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)
Release archive (after publication)
Download the archive for your platform and verify it against the published
SHA256SUMS before adding dsql to PATH:
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.
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.
# Open an interactive shell. A cluster selector is a cluster ID, cluster ARN,
# or canonical Aurora DSQL endpoint.
# Run SQL without prompts. Noninteractive use requires both a cluster selector
# and a database role.
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:ListClustersanddsql:GetClusterare needed only for discovery.dsql:DbConnectAdminis required for the elevatedadmindatabase role.dsql:DbConnectand an IAM-to-database-role association are required for a custom database role.cloudwatch:GetMetricDatais 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
- CLI reference
- IAM least-privilege policies
- Interactive shell
- Output formats and JSON Lines schema
- Security and privacy
- Troubleshooting
- Testing and live-test policy
- Manual QA plan
- Release checklist
Contributing and testing
Contributions should preserve the terminology in CONTEXT.md, update public
documentation with behavior changes, and run the local gates:
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.