How to connect to PostgreSQL or MySQL in Docker from your Mac

A database in a container listens inside Docker's network. Your Mac reaches it only through a port you publish. Once that port is published, the database is at localhost like any other local server, and any client connects the usual way.

Publish the port

#

docker run --name pg -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres:17
docker run --name mysql -e MYSQL_ROOT_PASSWORD=secret -p 3306:3306 -d mysql:8.4

-p 5432:5432 maps port 5432 on your Mac to port 5432 in the container. The left number is the one you connect to. If a PostgreSQL from Homebrew already holds 5432, publish on another port, -p 5433:5432, and connect to 5433.

-p 5432:5432 publishes on every network interface of your Mac. To keep the database off your local network, bind it to loopback: -p 127.0.0.1:5432:5432.

docker ps shows the mapping in its PORTS column, and docker port pg prints it for one container.

Connect from the command line

#

psql "postgresql://postgres:secret@localhost:5432/postgres"
mysql -h 127.0.0.1 -P 3306 -u root -p

The official images create these accounts:

Use 127.0.0.1 with the mysql client, not localhost. On a Mac it reads localhost as "use the Unix socket", and the container's socket is not on your Mac.

Without a client installed, run the one inside the container: docker exec -it pg psql -U postgres.

Connect in TablePro

#

1. Click New Connection… on the welcome window, or press Cmd+N, and pick PostgreSQL or MySQL.
2. On General, set Host to localhost and Port to the published port.
3. Fill in Username and Password from the table above. PostgreSQL also needs Database: postgres works on a fresh container. On MySQL you can leave Database empty and pick one later with Cmd+K.
4. Click Test Connection, then Save & Connect.

TablePro's MySQL driver connects over TCP only, so localhost works here where it fails in the mysql client. MySQL 8 accounts on caching_sha2_password connect without switching the auth plugin. On MySQL, an empty Username means your macOS login name, so type root.

If you already have a connection string, skip the fields. Click Import from URL… at the bottom of the database type sheet, paste the URL, check the preview and click Import. The form opens filled in. A password with @, # or % in it needs percent-encoding first: p@ss becomes p%40ss.

Read the settings from a Compose file

#

In a project, the same facts live in docker-compose.yml:

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    ports:
      - "5432:5432"

The service name db resolves only inside the Compose network. From your Mac the address is still localhost and the published port.

TablePro can read this file instead of you retyping it:

1. Choose File > Import > Open Project Folder… and pick the project folder.
2. The sheet lists one row per set of credentials it found, with the database type, host, port, user and database, and the file and key behind it. A Compose service appears with host 127.0.0.1 and its published port.
3. Select a row and click Continue. The connection form opens filled in. Nothing is saved and nothing connects until you click Save.

The scan reads docker-compose.yml and compose.yaml, and also .env, so a ${POSTGRES_PASSWORD} in the Compose file is filled from the project's .env. Passwords are never displayed. A row says Password found, and the value goes to your Keychain when you save.

Two notes on a row tell you it may not connect:

• No published port, may be unreachable: the service has no ports: mapping.
• Container service name, may be unreachable: the host came from a .env value such as DB_HOST=db, which only resolves inside Docker. Change Host to localhost in the form.

Where it stops

#

• One pass of Open Project Folder… imports one row. Run it again for the next service.
• Nothing is matched against the connections you already have, so importing the same row twice gives you two connections.
• Template files such as .env.example are skipped.
• TablePro does not start, stop or list containers. It connects to whatever is listening on the port.
• MySQL connections never use a Unix socket. Give the connection a host and a port.

If it does not connect

#

• Connection refused: nothing is listening on that port. Check that the container is running and the port is published with docker ps.
• Password authentication failed on PostgreSQL, or Access denied on MySQL, with the password from your docker run line: POSTGRES_PASSWORD and MYSQL_ROOT_PASSWORD apply only when the data directory is first created. A container started on an existing volume keeps the password that volume was created with.
• You connect, but to the wrong server: another PostgreSQL or MySQL on your Mac holds the port. Publish the container on a different one.

Field by field, the connection form is covered in the docs for PostgreSQL and MySQL, and the config files the scan reads are listed in Open Project Folder. On this site, see the PostgreSQL and MySQL pages and importing connections from a project.

With the container connected, the usual next step is loading data: see how to import a CSV file into PostgreSQL or MySQL.