AWS aurora-dsql documentation change
Summary
Updated documentation for the Aurora DSQL Connector for Go, replacing 'Token generation and caching' section with 'OCC retry' content and updating token generation descriptions from cached tokens to per-connection generation.
Security assessment
The changes primarily update operational details about token generation (changing from cached tokens refreshed at 80% lifetime to per-connection generation) and add documentation for optimistic concurrency control (OCC) retry mechanisms. There is no evidence of addressing a security vulnerability or weakness. The token generation changes describe a different implementation approach but don't indicate a security fix. The OCC retry documentation is about handling concurrency conflicts, not security.
Diff
diff --git a/aurora-dsql/latest/userguide/SECTION_program-with-go-pgx-connector.md b/aurora-dsql/latest/userguide/SECTION_program-with-go-pgx-connector.md index 0ccc4f05b..ec268bc04 100644 --- a//aurora-dsql/latest/userguide/SECTION_program-with-go-pgx-connector.md +++ b//aurora-dsql/latest/userguide/SECTION_program-with-go-pgx-connector.md @@ -5 +5 @@ -About the connectorKey featuresPrerequisitesInstallationQuick startConfiguration optionsConnection string formatAdvanced usageToken generation and cachingExamples +About the connectorKey featuresPrerequisitesInstallationQuick startConfiguration optionsConnection string formatAdvanced usageOCC retryExamples @@ -21 +21 @@ In Aurora DSQL, **authentication** involves: - * **Token Generation** : Authentication tokens are generated using AWS credentials and have configurable lifetimes + * **Token Generation** : The connector generates authentication tokens using AWS credentials, and these tokens have configurable lifetimes @@ -32 +32 @@ The Aurora DSQL Connector for Go allows you to continue using your existing pgx - * **Automatic Token Generation** : IAM tokens are generated automatically with smart caching (refreshes at 80% of token lifetime) + * **Automatic Token Generation** : The connector generates IAM tokens automatically for each connection @@ -34 +34 @@ The Aurora DSQL Connector for Go allows you to continue using your existing pgx - * **Connection Pooling** : Built-in support for pgxpool with token caching for efficient connection creation + * **Connection Pooling** : Built-in support for `pgxpool` with automatic token generation per connection @@ -48 +48 @@ Automatic Token Management -IAM tokens are generated and cached automatically. Tokens are refreshed at 80% of their lifetime to ensure they remain valid. +The connector generates IAM tokens automatically for each new connection using pre-resolved credentials. @@ -53 +53 @@ Connection Pooling -Connection pooling via pgxpool with token caching for efficient connection creation. +Connection pooling via `pgxpool` with automatic token generation per connection. @@ -243 +243 @@ Specify an AWS profile for credentials: -## Token generation and caching +## OCC retry @@ -245 +245 @@ Specify an AWS profile for credentials: -The connector automatically generates and caches IAM authentication tokens for optimal performance: +Aurora DSQL uses optimistic concurrency control (OCC). When two transactions modify the same data, the first to commit wins and the second receives an OCC error. @@ -247 +247 @@ The connector automatically generates and caches IAM authentication tokens for o - * **Connection pools** : Tokens are cached and reused across connections. The BeforeConnect hook retrieves tokens from the cache, generating new ones only when the cached token has used 80% of its lifetime. +The `occretry` package provides helpers for automatic retry with exponential backoff and jitter. Install it with: @@ -249 +248,0 @@ The connector automatically generates and caches IAM authentication tokens for o - * **Single connections** : A token is generated at connection time using pre-resolved credentials. @@ -251 +250 @@ The connector automatically generates and caches IAM authentication tokens for o - * **Credentials resolution** : AWS credentials are resolved once when the pool/connection is created and reused for all token generations. + go get github.com/awslabs/aurora-dsql-connectors/go/pgx/occretry @@ -252,0 +252 @@ The connector automatically generates and caches IAM authentication tokens for o +Use `WithRetry` for transactional writes: @@ -254,0 +255,16 @@ The connector automatically generates and caches IAM authentication tokens for o + err := occretry.WithRetry(ctx, pool, occretry.DefaultConfig(), func(tx pgx.Tx) error { + _, err := tx.Exec(ctx, "UPDATE accounts SET balance = balance - $1 WHERE id = $2", 100, fromID) + if err != nil { + return err + } + _, err = tx.Exec(ctx, "UPDATE accounts SET balance = balance + $1 WHERE id = $2", 100, toID) + return err + }) + +For DDL or single statements, use `ExecWithRetry`: + + + err := occretry.ExecWithRetry(ctx, pool, occretry.DefaultConfig(), + "CREATE TABLE IF NOT EXISTS users (id UUID PRIMARY KEY, name TEXT)") + +###### Important @@ -256 +272 @@ The connector automatically generates and caches IAM authentication tokens for o -Token duration defaults to 900 seconds (15 minutes). +`WithRetry` manages `BEGIN`/`COMMIT`/`ROLLBACK` internally. Your callback receives a transaction and should contain only database operations and be safe to retry.