Connect to PostgreSQL in Docker from your Mac

What you need

• Docker running on your Mac (Docker Desktop or similar).
• A container from the official postgres image with its port published to your Mac. Without -p, nothing outside Docker can reach it.

A minimal start:

docker run --name pg -e POSTGRES_PASSWORD=<password> -p 5432:5432 -d postgres:18

If something on your Mac already uses 5432 (Postgres.app, Homebrew’s PostgreSQL, another container), publish a different host port, such as -p 5433:5432, and connect to 5433.

Find your connection details

To see which host port a running container uses, ask Docker. For a container started with -p 55470:5432:

docker port pg 5432

0.0.0.0:55470
[::]:55470

The environment variables only work once. The image uses them only when it starts with an empty data directory; with an existing database, it leaves everything as it was. If you change POSTGRES_PASSWORD and restart with the same volume, the old password still applies. Change it with ALTER ROLE postgres PASSWORD '<new>' instead, or start with a fresh volume (losing the data).

Volumes changed in PostgreSQL 18. From the 18 image on, the data lives in /var/lib/postgresql/18/docker, and you mount the volume at /var/lib/postgresql. For 17 and earlier, mount at /var/lib/postgresql/data; a volume at the wrong path doesn’t keep your data when the container is re-created.

docker run --name pg -e POSTGRES_PASSWORD=<password> -p 5432:5432 -v pgdata:/var/lib/postgresql -d postgres:18

Connection string

postgresql://postgres:<password>@localhost:5432/postgres

Inside the container, the image’s pg_hba.conf trusts connections over the Unix socket and from 127.0.0.1 and ::1, but requires a scram-sha-256 password from every other address. Connections from your Mac arrive through Docker’s network, so they need the password. On a PostgreSQL 18.6 container:

 type  |   database    | user_name |  address  |  auth_method
-------+---------------+-----------+-----------+---------------
 local | {all}         | {all}     |           | trust
 host  | {all}         | {all}     | 127.0.0.1 | trust
 host  | {all}         | {all}     | ::1       | trust
…
 host  | {all}         | {all}     | all       | scram-sha-256

See PostgreSQL connection strings.

TLS

The official image doesn’t turn TLS on: SHOW ssl returns off. Traffic to a container on your Mac stays on your Mac, so leave TLS off or at prefer. Asking for it fails:

psql: error: connection to server at "localhost" (::1), port 55470 failed: server does not support SSL, but SSL was required

That’s server does not support SSL.

Connect with Inlet

1. Choose New Connection and enter localhost, the published port, user postgres (or your POSTGRES_USER) and the database. Or paste postgresql://postgres:<password>@localhost:5432/postgres and Inlet fills in the form.
2. Leave TLS off or at prefer.
3. Save the password in the Keychain, or have Inlet ask each time.
4. Tag the connection local (or development) so it’s easy to tell apart from production.

Connect from the command line

You don’t need psql on your Mac: the container has one, and inside it the socket is trusted, so no password is asked for.

docker exec -it pg psql -U postgres

From your Mac, with psql from Homebrew’s libpq package (keg-only, so /opt/homebrew/opt/libpq/bin/psql). On a test container published on port 55470:

PGPASSWORD=<password> psql -h localhost -p 55470 -U postgres -c 'select version();'

                                                         version
--------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
(1 row)

Troubleshooting

All of these were reproduced with postgres:18 (PostgreSQL 18.6) on a Mac.

• Port already taken. Starting a second container on the same host port fails before it runs:

  docker: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint … Bind for 0.0.0.0:55470 failed: port is already allocated
  

  Pick another host port with -p. A server outside Docker is sneakier: in a test, a container published on a port that another program on the Mac already listened on (on 127.0.0.1 and ::1) started without complaint, and a connection to localhost reached the other program instead. If a Homebrew or Postgres.app server might be running, publish another port, and check what you’re connected to with select version();.

• password authentication failed after you changed POSTGRES_PASSWORD: the volume already had a database, so the variable was ignored (the log says PostgreSQL Database directory appears to contain a database; Skipping initialization). Connecting with the new password fails, and the old one still works:

  psql: error: connection to server at "localhost" (::1), port 55471 failed: FATAL:  password authentication failed for user "postgres"
  

• no password supplied: connections from your Mac need the password, even though docker exec doesn’t.

  psql: error: connection to server at "localhost" (::1), port 55470 failed: fe_sendauth: no password supplied
  

• Connection refused: the container isn’t running, the port isn’t published, or it’s still initialising (check docker logs pg for database system is ready to accept connections).

  psql: error: connection to server at "localhost" (::1), port 55479 failed: Connection refused
  	Is the server running on that host and accepting TCP/IP connections?
  connection to server at "localhost" (127.0.0.1), port 55479 failed: Connection refused
  	Is the server running on that host and accepting TCP/IP connections?
  

• FATAL: role "<name>" does not exist: the user is postgres unless you set POSTGRES_USER when the data directory was first created.