dsql-cli 1.0.0

Aurora DSQL command-line client
dsql-cli-1.0.0 is not a library.

Aurora DSQL CLI

dsql is a DSQL-native command-line client for Amazon Aurora DSQL. It helps you discover clusters, connect with IAM database authentication, run SQL, and use an interactive shell with a temporary metrics dashboard. It is inspired by PostgreSQL shell workflows, not a psql compatibility layer.

Status

This project is a release candidate. Local checks, packaging metadata, and release automation are present; live Aurora DSQL validation and publication remain manual, explicitly authorized release gates. The client never creates, updates, or deletes a cluster.

Install

crates.io (after publication)

cargo install dsql-cli --locked
dsql --version

Release archive (after publication)

Download the archive for your platform and verify it against the published SHA256SUMS before adding dsql to PATH:

sha256sum --check SHA256SUMS
tar -xzf dsql-*.tar.gz
./dsql --version

On macOS, use shasum -a 256 -c SHA256SUMS when GNU sha256sum is not available.

Build a checkout

Rust 1.94 or later is required. Building and viewing help do not contact AWS.

cargo build --locked --release
./target/release/dsql --help

Five-minute quickstart

dsql uses the AWS SDK default credential chain. Configure a Region through that chain or pass --region; use --profile for a shared SDK profile. Cached SDK-supported IAM Identity Center (SSO) credentials work, but dsql does not perform an SSO login flow.

# List clusters discoverable by the active AWS identity. Discoverability does
# not imply that the identity can connect.
dsql clusters --region us-east-1

# Open an interactive shell. A cluster selector is a cluster ID, cluster ARN,
# or canonical Aurora DSQL endpoint.
dsql 0123456789abcdefghijklmnop --region us-east-1

# Run SQL without prompts. Noninteractive use requires both a cluster selector
# and a database role.
dsql 0123456789abcdefghijklmnop --region us-east-1 -U app_role \
  -c 'SELECT current_user;'

Aurora DSQL has one built-in database, postgres, and dsql connects to it on port 5432. A database role is the PostgreSQL role supplied as the username; the predefined admin role is elevated. A custom role requires its IAM-to-database-role association as well as connection permission.

Common commands

dsql [OPTIONS] [CLUSTER]
dsql clusters [OPTIONS]
Command Use
dsql clusters --region REGION List discoverable clusters without connecting.
dsql CLUSTER -U ROLE -c 'SQL' Run SQL and exit. -c may be repeated.
dsql CLUSTER -U ROLE -f query.sql Run a UTF-8 SQL file and exit.
dsql CLUSTER -U ROLE < query.sql Run semicolon-terminated SQL from standard input.
dsql CLUSTER --format jsonl -U ROLE -c 'SQL' Emit machine-readable JSON Lines.
dsql CLUSTER --ssl-root-cert root.pem Add a PEM trust anchor without disabling normal TLS validation.

table is the default output format; csv, tsv, and jsonl are also available. See the CLI reference for input, exit-code, and format rules.

Interactive shell

Without -c, -f, or redirected standard input, dsql starts an interactive shell after connecting. It accepts SQL plus a small, explicit set of backslash commands:

0123456789abcdefghijklmnop/app_role=> SELECT 1 AS ready;
 ready
-------
 1
(1 row)

0123456789abcdefghijklmnop/app_role=> \conninfo
Cluster: 0123456789abcdefghijklmnop
Region: us-east-1
Database role: app_role

0123456789abcdefghijklmnop/app_role=> \metrics

Use \? for shell help, \d/\dt/\dn/\du for catalog inspection, \refresh to safely refresh completion metadata while idle, and \q to exit. \metrics opens the temporary metrics dashboard for the connected cluster; q or Esc returns to the shell. See Interactive shell.

IAM and security

Start with least privilege:

  • dsql:ListClusters and dsql:GetCluster are needed only for discovery.
  • dsql:DbConnectAdmin is required for the elevated admin database role.
  • dsql:DbConnect and an IAM-to-database-role association are required for a custom database role.
  • cloudwatch:GetMetricData is needed only for \metrics.

The client always verifies TLS certificate chains and hostnames. It has no plaintext or insecure mode, does not print credentials or authentication tokens, and does not send telemetry. Read IAM permissions and security and privacy before connecting.

Troubleshooting and documentation

Contributing and testing

Contributions should preserve the terminology in CONTEXT.md, update public documentation with behavior changes, and run the local gates:

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features

Ignored Docker and live Aurora DSQL tests are opt-in. Never run a live test without explicit authorization and an appropriate development cluster; see testing.

License

Licensed under Apache-2.0.