Repository files navigation

A PostgreSQL command-line client with built-in AWS DSQL authentication support. Connect to AWS DSQL databases with automatic token generation - no manual token management required.

Installpdsql with a single command:

curl -sSL https://raw.githubusercontent.com/marcbowes/postgres/refs/heads/master/scripts/install.sh| sh

This installer automatically detects your platform (macOS/Linux) and architecture, downloads the appropriate package, and installspdsql to your local environment.

If you prefer to download manually:

1. Visit theGitHub Releases page
2. Download the appropriate package for your platform:
   • macOS Intel:postgres-dsql-macos-x64.zip
   • macOS Apple Silicon:postgres-dsql-macos-arm64.zip
   • Linux x64:postgres-dsql-linux-x64.zip
   • Linux ARM64:postgres-dsql-linux-arm64.zip
3. Extract and run:

   unzip postgres-dsql-*.zipcd postgres-dsql./bin/pdsql --version

For Linux users, we also provide native packages:

Debian/Ubuntu (.deb):

wget https://github.com/marcbowes/postgres/releases/latest/download/postgres-dsql_1.0.0-1_amd64.debsudo apt install ./postgres-dsql_1.0.0-1_amd64.deb

RHEL/Fedora (.rpm):

wget https://github.com/marcbowes/postgres/releases/latest/download/postgres-dsql-1.0.0-1.x86_64.rpmsudo dnf install postgres-dsql-1.0.0-1.x86_64.rpm

Connect to an AWS DSQL database:

pdsql --host=your-dsql-endpoint.example.com --user=admin --port=5432 --dbname=postgres

You can also use PostgreSQL connection strings:

pdsql"host=your-dsql-endpoint.example.com user=admin port=5432 dbname=postgres"

• Automatic Authentication: No need to manually generate or manage tokens
• Secure by Default: Automatically enforces SSL connections
• Token Auto-Renewal: Handles token expiration transparently
• Standard psql Interface: All familiar psql commands and features work

When you connect withpdsql:

1. SSL Required: Automatically enforces secure connections
2. Token Generation: Generates temporary AWS authentication tokens automatically
3. Admin Privileges: When connecting asadmin user, full admin privileges are granted
4. Auto-Renewal: New tokens are generated for each connection attempt
5. Short-Lived Tokens: Tokens expire after 5 seconds for enhanced security

pdsql uses your existing AWS credentials. Ensure you have credentials configured through one of these methods:

aws configure

export AWS_ACCESS_KEY_ID=your_access_keyexport AWS_SECRET_ACCESS_KEY=your_secret_keyexport AWS_REGION=us-east-1# Optional

Create~/.aws/credentials:

[default]aws_access_key_id = your_access_keyaws_secret_access_key = your_secret_key

If running on AWS infrastructure,pdsql will automatically use IAM roles.

# Start an interactive sessionpdsql --host=workgroup.123456789012.us-east-1.dsql.amazonaws.com --user=admin# Once connected, you can run SQL commands:postgres=>\lpostgres=> CREATE TABLE users (id serial, name text);postgres=> INSERT INTO users (name) VALUES ('Alice');postgres=> SELECT* FROM users;

# Execute a single querypdsql --host=your-endpoint.dsql.amazonaws.com --user=admin -c"SELECT version();"# Execute SQL from a filepdsql --host=your-endpoint.dsql.amazonaws.com --user=admin -f queries.sql

# Connect with specific database and additional optionspdsql --host=your-endpoint.dsql.amazonaws.com \      --user=admin \      --port=5432 \      --dbname=postgres \      --echo-queries \      --no-password

Error: "could not connect to server"

• Verify your DSQL endpoint URL is correct
• Ensure your security group allows connections on port 5432
• Check that your AWS credentials are properly configured

Error: "authentication failed"

• Verify your AWS credentials have the necessary DSQL permissions
• Ensure you're connecting to the correct DSQL workgroup
• Check that your IAM user/role hasdsql:DbConnect permissions

Error: "Unable to locate credentials"

• Runaws configure to set up credentials
• Or setAWS_ACCESS_KEY_ID andAWS_SECRET_ACCESS_KEY environment variables
• Verify your credentials work:aws sts get-caller-identity

For troubleshooting authentication and connection issues, enable detailed AWS SDK logging:

• AWS_LOG_LEVEL: Controls verbosity (NONE, FATAL, ERROR, WARN, INFO, DEBUG, TRACE)
• AWS_LOG_FILE: Controls output destination (stdout, stderr, or file path)

Enable debug logging to stderr (default):

AWS_LOG_LEVEL=DEBUG pdsql --host=your-endpoint.dsql.amazonaws.com --user=admin

Enable maximum verbosity for deep debugging:

AWS_LOG_LEVEL=TRACE pdsql --host=your-endpoint.dsql.amazonaws.com --user=admin

Save logs to a file for analysis:

AWS_LOG_LEVEL=DEBUG AWS_LOG_FILE=/tmp/dsql-debug.log pdsql --host=your-endpoint.dsql.amazonaws.com --user=admin

Send logs to stdout (useful for piping):

AWS_LOG_LEVEL=INFO AWS_LOG_FILE=stdout pdsql --host=your-endpoint.dsql.amazonaws.com --user=admin

The debug logs will reveal:

• Token Generation: Process of creating DSQL authentication tokens
• AWS Region Detection: How the region is determined from hostname or environment
• Credentials Provider Chain: Which credential sources are tried (environment, files, IAM roles, IMDS)
• HTTP Infrastructure: Event loops and network setup for IMDS on EC2
• Error Details: Specific AWS SDK errors with error codes

[INFO] [2025-06-28T03:33:55Z] Starting DSQL token generation for endpoint: your-endpoint.dsql.amazonaws.com[DEBUG] [2025-06-28T03:33:55Z] Using AWS_REGION from environment: us-west-2[DEBUG] [2025-06-28T03:33:55Z] Creating credentials provider chain with bootstrap for IMDS[INFO] [2025-06-28T03:33:55Z] Token generation successful

To disable all logging:

AWS_LOG_LEVEL=NONE pdsql --host=your-endpoint.dsql.amazonaws.com --user=admin

For additional help:

pdsql --help

To update to the latest version, simply run the installation command again:

curl -sSL https://raw.githubusercontent.com/marcbowes/postgres/refs/heads/master/scripts/install.sh| sh

If you need to build from source or contribute to development, see ourDevelopment Guide for detailed build instructions.

git clone https://github.com/marcbowes/postgres.gitcd postgresgit submodule update --init --recursive./scripts/build-dsql.sh

This project is based on PostgreSQL and maintains compatibility with the PostgreSQL license.

Contributions are welcome! Please see our contributing guidelines and feel free to submit issues or pull requests.

Note: This tool is specifically designed for AWS DSQL connections. For regular PostgreSQL connections, use the standardpsql client.