AWS aurora-dsql documentation change
Summary
Updated documentation to clarify how DDL operations cause concurrency control responses (OC001) due to distributed catalog versioning, added example scenario, and included note about idle sessions encountering stale catalog versions.
Security assessment
This change improves documentation about distributed transaction behavior and schema change handling in Aurora DSQL. It explains technical details of catalog version management and retry scenarios. No security vulnerabilities or security features are mentioned or addressed in this documentation update.
Diff
diff --git a/aurora-dsql/latest/userguide/working-with-ddl.md b/aurora-dsql/latest/userguide/working-with-ddl.md index 25ab34ac6..fc1deadbe 100644 --- a//aurora-dsql/latest/userguide/working-with-ddl.md +++ b//aurora-dsql/latest/userguide/working-with-ddl.md @@ -13 +13 @@ Specifically, DDL behaves differently in Aurora DSQL as follows: -**Concurrency control errors** +**Concurrency control responses** @@ -16 +16 @@ Specifically, DDL behaves differently in Aurora DSQL as follows: -Aurora DSQL returns a concurrency control violation error if you run one transaction while another transaction updates a resource. For example, consider the following sequence of actions: +Because the database catalog is distributed, Aurora DSQL manages DDL schema changes as distributed transactions that update the catalog version. Sessions that have a cached copy of the catalog at an earlier version can receive a concurrency control response with SQLSTATE code `40001` and OCC code `OC001` when they next interact with storage. @@ -18 +18 @@ Aurora DSQL returns a concurrency control violation error if you run one transac - 1. In session 1, a user adds a column to the table `mytable`. +For example, consider the following sequence of actions: @@ -20 +20 @@ Aurora DSQL returns a concurrency control violation error if you run one transac - 2. In session 2, a user attempts to insert a row into `mytable`. + 1. In session 1, a user adds a column to the table `mytable`. This updates the catalog version. @@ -22 +22 @@ Aurora DSQL returns a concurrency control violation error if you run one transac -Aurora DSQL returns the error `SQL Error [40001]: ERROR: schema has been updated by another transaction, please retry: (OC001).` + 2. In session 2, a user attempts to insert a row into `mytable`. This session still has the previous catalog version cached. @@ -23,0 +24 @@ Aurora DSQL returns the error `SQL Error [40001]: ERROR: schema has been updated +Aurora DSQL returns `SQL Error [40001]: ERROR: schema has been updated by another transaction, please retry: (OC001)`. @@ -26,0 +28,5 @@ Aurora DSQL returns the error `SQL Error [40001]: ERROR: schema has been updated + +###### Note + +An OC001 response can also occur when the schema change has already completed before the affected transaction starts. Aurora DSQL query processors discover catalog changes reactively during query execution, so a session that has been idle might still be operating with a stale catalog version. On retry, the session refreshes its catalog cache and the transaction typically succeeds. +