Skip to content

Replace CLI_ASYNC_DDL with DDL_EXECUTION_MODE and DDL_ASYNC_WAIT_TIMEOUT #974

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
apstndb merged 6 commits into from
Sep 14, 2026
Merged

Replace CLI_ASYNC_DDL with DDL_EXECUTION_MODE and DDL_ASYNC_WAIT_TIMEOUT #974

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ab9affc
Merge origin/main (f10a4da, #972) into cursor/ddl-execution-modes-485…
cursoragent Sep 14, 2026
1ad9423
Replace CLI_ASYNC_DDL with DDL_EXECUTION_MODE and DDL_ASYNC_WAIT_TIMEOUT
cursoragent Sep 14, 2026
72718d8
Apply ASYNC_WAIT budget to in-flight GetOperation polls
cursoragent Sep 14, 2026
81c15ff
Merge origin/main (92f986d, #975) into cursor/ddl-execution-modes-485…
cursoragent Sep 14, 2026
744f217
Preserve completed LRO failures under a zero ASYNC_WAIT budget
cursoragent Sep 14, 2026
a3577f7
Retrigger CI after readme-sync module proxy flake
cursoragent Sep 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ There are differences between spanner-mycli and spanner-cli that include not onl
* GenAI support(`GEMINI` statement).
* BigQuery support (`BIGQUERY` statement).
* Interactive DDL batching
* Async DDL execution support (`--async` flag and `CLI_ASYNC_DDL` system variable)
* Async DDL execution support (`--async` flag and `DDL_EXECUTION_MODE` / `DDL_ASYNC_WAIT_TIMEOUT` system variables)
* Experimental Cassandra interface support as `CQL <cql>` statement.
* Support split points.
* Run as MCP (Model Context Protocol) server (EXPERIMENTAL, `--mcp`). See [Model Context Protocol](https://modelcontextprotocol.io/introduction) for more information.
Expand Down Expand Up @@ -1019,6 +1019,8 @@ For how these and other connection properties map to the official Spanner driver
| MAX_PARTITIONED_PARALLELISM | READ_WRITE | `4` |
| DEFAULT_ISOLATION_LEVEL | READ_WRITE | `REPEATABLE_READ` |
| STATEMENT_TIMEOUT | READ_WRITE | `"10m"` |
| DDL_EXECUTION_MODE | READ_WRITE | `"SYNC"` |
| DDL_ASYNC_WAIT_TIMEOUT | READ_WRITE | `"10s"` |
| DIRECTED_READ | READ_WRITE | `"us-central1:READ_ONLY"` |
| PROTO_DESCRIPTORS_FILE_PATH | READ_WRITE | `"order_descriptors.pb"` |

Expand Down
2 changes: 1 addition & 1 deletion docs/spanner-driver-compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ says otherwise; `java-spanner` versions are given where known.
| `autocommit_dml_mode` (`Transactional`/`PartitionedNonAtomic`) | yes | yes | `AUTOCOMMIT_DML_MODE` implemented |
| `auto_batch_dml` | yes | yes | `AUTO_BATCH_DML` implemented |
| `auto_batch_dml_update_count` / `auto_batch_dml_update_count_verification` | yes (v1.11.0) | yes | not implemented, tracked #401 |
| `ddl_execution_mode` (`SYNC`/`ASYNC`/`ASYNC_WAIT`) + `ddl_async_wait_timeout` | yes (v1.24.0) | n/a | `CLI_ASYNC_DDL` (bool) approximates; enum rename tracked #485 |
| `ddl_execution_mode` (`SYNC`/`ASYNC`/`ASYNC_WAIT`) + `ddl_async_wait_timeout` | yes (v1.24.0) | n/a | `DDL_EXECUTION_MODE` (`SYNC` default / `ASYNC` / `ASYNC_WAIT`) + `DDL_ASYNC_WAIT_TIMEOUT` (default 10s). `--async` selects `ASYNC`. The remaining wait budget bounds in-flight GetOperation polls as well as the between-poll wait. Wait-budget expiry is a successful handoff of the still-running operation ID and cancels only the polling RPC, not the server operation; caller/statement cancellation remains an error with that ID; a completed failing LRO remains a failure. `CLI_ASYNC_DDL` was removed (#485). |
| `directed_read` | yes (v1.26.0) | Connection API Directed Read since the 6.52.x era | `DIRECTED_READ` (session SET/SHOW, location[:READ_ONLY\|READ_WRITE] shorthand plus DirectedReadOptions protobuf JSON, empty clears). SHOW uses shorthand when lossless. SET rejected while a transaction is pending or active. Not applied to RW/DML/heartbeat/PDML. |
| `transaction_timeout` | yes (v1.22.0) | v6.101.0 | not implemented, tracked #482 |
| `statement_timeout` | yes (v1.22.0) | connection URL support v6.102.0 | `STATEMENT_TIMEOUT` implemented |
Expand Down
39 changes: 38 additions & 1 deletion docs/system_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ both `SHOW` and `SET`.
| `AUTO_BATCH_DML` | read,write | A BOOL indicating whether DML in an explicit read-write transaction is buffered until COMMIT, a later execute-now statement, or RUN BATCH. SET only changes future buffering. The default is false. |
| `AUTO_PARTITION_MODE` | read,write | A property of type BOOL indicating whether the connection automatically uses partitioned queries for all queries that are executed. |
| `CLI_ANALYZE_COLUMNS` | read,write | Go template for analyzing column data. |
| `CLI_ASYNC_DDL` | read,write | A boolean indicating whether DDL statements should be executed asynchronously. The default is false. |
| `CLI_AUTOWRAP` | read,write | Enable automatic line wrapping. |
| `CLI_AUTO_CONNECT_AFTER_CREATE` | read,write | A boolean indicating whether to automatically connect to a database after CREATE DATABASE. The default is false. |
| `CLI_BIGQUERY_LOCATION` | read,write | BigQuery location for queries (e.g. US, EU). |
Expand Down Expand Up @@ -116,6 +115,8 @@ both `SHOW` and `SET`.
| `COMMIT_RESPONSE` | read | The most recent response for a read-write transaction. SHOW VARIABLE COMMIT_RESPONSE returns COMMIT_TIMESTAMP and MUTATION_COUNT columns; SHOW VARIABLES includes those values as COMMIT_TIMESTAMP and MUTATION_COUNT. |
| `COMMIT_TIMESTAMP` | read | The commit timestamp of the last read-write transaction that Spanner committed. |
| `DATA_BOOST_ENABLED` | read,write | A property of type BOOL indicating whether this connection should use Data Boost for partitioned queries. The default is false. |
| `DDL_ASYNC_WAIT_TIMEOUT` | read,write | Maximum time ASYNC_WAIT spends waiting for a DDL operation before returning the still-running operation ID as a successful asynchronous submission. The remaining budget bounds in-flight GetOperation polls as well as the time between polls. Expiry cancels only the polling RPC and does not cancel the server operation. The default is 10s. Unused in SYNC and ASYNC modes. |
| `DDL_EXECUTION_MODE` | read,write | How DDL statements wait for the Admin long-running operation. SYNC (default) waits for the actual result. ASYNC returns the accepted operation ID immediately. ASYNC_WAIT waits up to DDL_ASYNC_WAIT_TIMEOUT and, on wait-budget expiry, returns the still-running operation ID as a successful asynchronous submission without canceling the server operation. --async selects ASYNC. Replaces CLI_ASYNC_DDL. |
| `DEFAULT_ISOLATION_LEVEL` | read,write | The transaction isolation level that is used by default for read/write transactions. |
| `DIRECTED_READ` | read,write | Directed read options for supported read-only queries. Accepts replica_location or replica_location:READ_ONLY\|READ_WRITE shorthand, or DirectedReadOptions protobuf JSON. SHOW uses shorthand when that form is lossless; otherwise protobuf JSON. Empty string clears. SET is rejected while a transaction is pending or active; SET LOCAL is not supported. Not applied to read-write queries, DML, heartbeat, or partitioned DML. |
| `EXCLUDE_TXN_FROM_CHANGE_STREAMS` | read,write | Controls whether to exclude recording modifications in current transaction from the allowed tracking change streams(with DDL option allow_txn_exclusion=true). |
Expand Down Expand Up @@ -408,6 +409,42 @@ more explanation than the reference table above.
- Styling only applies when output supports ANSI escape codes (interactive terminal with styled formats)
- Inspired by `LS_COLORS`, `GCC_COLORS`, and `JQ_COLORS` environment variable patterns

### DDL_EXECUTION_MODE

How DDL statements wait for the Admin long-running operation. This is a
type/behavior replacement for the removed boolean `CLI_ASYNC_DDL`.

- **Type**: STRING (`SYNC` / `ASYNC` / `ASYNC_WAIT`)
- **Default**: `SYNC`
- **Access**: Read/Write
- **Values**:
- `SYNC` waits until the LRO completes and reports its actual result
(including a completed failing LRO).
- `ASYNC` returns the accepted operation ID immediately. Later DDL failure
remains visible through `SHOW OPERATION`. `--async` selects this mode.
- `ASYNC_WAIT` waits until completion or `DDL_ASYNC_WAIT_TIMEOUT`. The
remaining wait budget bounds the initial GetOperation poll, later polls,
and the time between polls. When that separate wait budget expires, the
still-running operation ID is returned as a successful asynchronous
submission. Expiry cancels only the polling RPC; the server operation is
not canceled. Caller or `STATEMENT_TIMEOUT` cancellation remains an error
that includes the operation ID.
- **Migration**: `SET CLI_ASYNC_DDL = TRUE` becomes
`SET DDL_EXECUTION_MODE = 'ASYNC'`. `FALSE` is the `SYNC` default.

### DDL_ASYNC_WAIT_TIMEOUT

- **Type**: duration string (for example `10s`, `1m`)
- **Default**: `10s`
- **Access**: Read/Write
- **Description**: Maximum time `ASYNC_WAIT` spends waiting before handing off
the still-running operation ID. Unused in `SYNC` and `ASYNC`. Must be >= 0.
The remaining budget applies to in-flight GetOperation polls as well as the
between-poll wait. Zero expires the wait budget immediately for a
still-pending operation, including before the first GetOperation poll. A
terminal result already received from UpdateDatabaseDdl or a preceding poll
is reported as-is.

### CLI_SAVEPOINT_SUPPORT

Client-emulated SAVEPOINT for explicit transactions. `DISABLED` (default) leaves
Expand Down
82 changes: 82 additions & 0 deletions enums/ddlexecutionmode_enumer.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions enums/enums.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,17 @@ const (
SavepointSupportEnabled
)

// DDLExecutionMode determines how DDL statements wait for the Admin LRO.
//
//go:generate go tool enumer -type=DDLExecutionMode -trimprefix=DDLExecutionMode -transform=snake_upper
type DDLExecutionMode int

const (
DDLExecutionModeSync DDLExecutionMode = iota
DDLExecutionModeAsync
DDLExecutionModeAsyncWait
)

// IsSQLExport returns true if the display mode is one of the SQL export formats
func (d DisplayMode) IsSQLExport() bool {
return d == DisplayModeSQLInsert || d == DisplayModeSQLInsertOrUpdate || d == DisplayModeSQLInsertOrIgnore
Expand Down
4 changes: 3 additions & 1 deletion internal/mycli/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -456,7 +456,9 @@ func createSystemVariablesFromOptions(opts *spannerOptions, features ...Feature)
sysVars.Feature.LogLevel = l
sysVars.Config.ImpersonateServiceAccount = opts.ImpersonateServiceAccount
// --vertexai-project application moved to the GEMINI feature's ApplyFlags (#778).
sysVars.Feature.AsyncDDL = opts.Async
if opts.Async {
sysVars.Feature.DDLExecutionMode = enums.DDLExecutionModeAsync
}

// Handle system command options
// Priority: --skip-system-command takes precedence over --system-command
Expand Down
Loading