# Run Postgres from Docker
On a Mac but similar to other platforms

I'll keep this fairly succinct as there's really not much more to blab about than what's in the title.

Installing Postgres directly on your machine is fine, but having the flexibility to quickly switch between the version you are running for development is beautiful. Running Postgres from a docker container, not installing with Brew or [insert tool of choice] gives you that beauty, and also lets you turn it off when you don't need it, saving your battery. Beautiful, right?

# Installing

Ok let's get going. Obviously you need Docker installed. If you don't have that, you're probably reading the wrong article. I use Docker Desktop, it's nice, but I'm more into the CLI, and LazyDocker too which is cool.

One quick thing to note is on a Mac (especially if you haven't installed Postgres manually on your machine), you will need libpq to give you the wonderful psql tool. Install it by running this command in your terminal.

brew install libpq

Check the version to verify it worked

ls /usr/local/Cellar/libpq

Next, create a symlink for psql (you could also add it to your path instead if you prefer)

ln -s /usr/local/Cellar/libpq/13.2/bin/psql /usr/local/bin/psql

Now grab the latest version of the Postgres container

docker pull postgres

Or a specific version to match your deployment env

docker pull postgres:[version_tag]

Now make a directory for your persistent volume to store the database on your machine

mkdir -p $HOME/docker/volumes/postgres

If you install multiple versions for various projects/environments, I find it useful for cleanup if you set the persistent volume directory to be version specific. Something like

mkdir -p $HOME/docker/10.17/volumes/postgres

Fire up the Postgres container adding the volume flag to your newly created directory

docker run --rm --name pg-docker \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e PG_TRUST_LOCALNET=true -d \
  -p 5432:5432 \
  -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres

You can set POSTGRES_USER and POSTGRES_PASSWORD to whatever you want, but “postgres” makes it simple for local dev. Obviously don't do that in prod, you're not silly.
Now you should be able to connect with psql

Enter your password “postgres” and you should see something like this

psql (13.2)
Type "help" for help.

postgres=#

Boom! You connected.
If you are unable to login with psql and you get an error like psql: error: FATAL: role “root” does not exist, you may need to set the Postgres user password manually from within the running container. To do this, get the container id running “docker ps -a” then exec into the container

docker exec -it  bash

Then run psql and this SQL command to set your password

ALTER ROLE postgres WITH PASSWORD 'postgres'

Quit with “\q” and “exit”. Then try connecting with psql again.

# Little extra

That was painless. Now, if you're a GUI kind of person, you may be asking, “yeah but can I still connect to my database using TablePlus?” Happily the answer is yes. Just fire it up, set host as localhost, or the default local IP and port, enter “postgres” as user and password, the name of a database you created, and test it out.

Development is tough enough as it is. I like it when things make my life easier.

Enjoy 👋



Back to articles
Back to home

# Links