sql-script.adoc atomicity note is inaccurate for DDL, and Schema.bulkChange() is undocumented (arcadedb#6990, v26.10.1)

[robfrank]

ArcadeData/arcadedb#6990 (PR #7210, v26.10.1) added a public Schema method and, in doing so, made an existing statement in the SQL Script page inaccurate for DDL.

1. reference/sql/sql-script.adoc - the atomicity note is wrong for DDL

The [NOTE] A script is a transaction callout (around L22) currently reads:

The atomicity guarantee -- "all-or-nothing" -- applies to every script: if any statement fails (and is not caught by a retry/else clause), every change made by the script is rolled back.

Schema DDL has never had rollback, and PR #7210 makes that explicit and configurable: when a batched DDL script fails part way, the bulk scope publishes the prefix the batch completed and then rethrows the original exception, so leader and followers agree on the same partially-applied state. The statements before the failure stay applied.

The note needs a carve-out saying so. It is a correctness issue, not a wording nit: someone reading the page today would reasonably write a migration script that assumes a failed run leaves the schema untouched.

While editing, it is worth naming the statements excluded from batching because they touch records rather than definitions, since a script containing any of them keeps the old per-statement behaviour: REBUILD INDEX / REBUILD TYPE / REBUILD GRAPH ANALYTICAL VIEW, TRUNCATE TYPE / TRUNCATE BUCKET, REFRESH MATERIALIZED VIEW / REFRESH CONTINUOUS AGGREGATE, COMPACT INDEX, CREATE MATERIALIZED VIEW, CREATE CONTINUOUS AGGREGATE, the graph-analytical-view statements, ALTER TYPE ... WITH repartition = true, and CREATE INDEX on a type that already exists.

2. reference/java-api/java-schema.adoc - Schema.bulkChange(Runnable) is undocumented

New public API on the Schema interface. It groups several schema builder calls (createType / createProperty / createIndex ...) into a single schema change, so under HA the whole block replicates as one Raft entry instead of one per call.

Suggested as a new == Batching schema changes section after == Database Configuration (currently the last section, L156), wrapping a few of the calls the page already shows. Three things belong in it:

• What it buys: one persisted schema save, and under HA one Raft entry for the block.
• RemoteSchema inherits a plain pass-through, so the method is safe to call from a remote client and simply has no batching effect there.
• No rollback on failure. The calls that already succeeded stay applied and are published, then the exception is rethrown. This is the same carve-out as item 1 and should read consistently with it.

The escape hatch for the SQL-script path, arcadedb.schemaBulkDDLScript (DATABASE scope, default true), is covered by #452.

---

Filed from the post-merge pass over ArcadeData/arcadedb#6990.