The database wouldn’t let me in. I had AWS credentials, the VPC was locked down, and the RDS instance was running. Still, pgcli just wouldn’t connect.
Most people hit this wall the first time they try to use pgcli with an AWS-hosted PostgreSQL database. It’s not pgcli’s fault. The trouble comes from mixing AWS’s security layers—IAM authentication, networking, and TLS certificates—with a CLI client that isn’t aware of them out of the box. The fix is simple once you see all the moving parts.
First, pgcli needs the right connection string. If you’re using IAM authentication for your RDS or Aurora PostgreSQL instance, AWS doesn’t give you a static password. You must generate an auth token. The AWS CLI can do this in one line:
aws rds generate-db-auth-token \
--hostname mydb.abc123xyz.us-east-1.rds.amazonaws.com \
--port 5432 \
--username db_user \
--region us-east-1
This token works only for 15 minutes. That’s why automation matters. You can wrap pgcli with a shell script that runs this command, stores the token in a variable, and then passes it into the pgcli call via PGPASSWORD.
Second, ensure your local pgcli can establish a TLS connection with the RDS instance. AWS requires an SSL connection by default. Download the Amazon RDS root certificate and add sslmode=require or sslrootcert=/path/to/rds-combined-ca-bundle.pem to your pgcli command. Without this, the connection will fail even if the token is correct.
Third, open the right network path. Your RDS instance must be accessible from your current environment. For many setups, that means using an EC2 instance as a bastion host or connecting your local machine through a VPN or AWS Direct Connect. If the hostname is private, you must be in the right VPC or peered network. Publicly accessible instances still need strict inbound rules for port 5432.
Once these three steps are in place—auth token generation, TLS configuration, and network access—pgcli will connect to AWS-hosted PostgreSQL as cleanly as psql does, but with richer features like auto-completion and syntax highlighting.
The real power here is speed. With the right setup, you can make these connections on demand, without storing passwords, and with all AWS policies enforced. That means better security and faster iteration.
If you want to skip building and debugging this workflow yourself, you can see it running—live—in minutes. Take a look at hoop.dev and watch how quickly secure, CLI-based database access from AWS becomes part of your daily flow.