How To Set Up TimescaleDB On macOS Effortlessly [Using Docker]

Installing TimescaleDB on mac is easy. Simply install Timescale via Homebrew and you're all set up.

Except you're not. If you need multiple local Timescale versions or you already have installed Postgres before, you're out of luck.

There's an easier way to set up PostgreSQL with Timescale on Mac and to manage multiple versions: by using Docker.

In this article, we'll set up Timescale with Postgres 12 on macOS Big Sur with Docker.

TL;DR:

# create folder for docker volume
mkdir -p $HOME/docker/volumes/timescale-pg-12

# create and start timescale postgres 12 docker container
docker run --rm --name timescale-pg-12 -p 127.0.0.1:5112:5432 -v $HOME/docker/volumes/timescale-pg-12:/var/lib/postgresql/data -e POSTGRES_PASSWORD=postgres -d timescale/timescaledb:latest-pg12

# connect
psql -h localhost -p 5112 -U postgres

# stop
docker stop timescale-pg-12

Prerequisites

Before we get to TimescaleDB, we need two things installed before we start.

Installing Docker

First, we need to install Docker on macOS. Follow the instructions on docker.com to install the official Docker for Mac.

Also, start the Docker application and go through their Getting Started guide to make sure everything works.

You may need to restart your shell for the docker cli command to work.

Installing Postgres CLI

If you haven't already, install the Brew package manager.

Then, update Brew and install libpq:

brew update
brew install libpq

As a last step, symlink psql and the other libpq tools to your local binaries (/usr/local/bin):

brew link --force libpq

Installing Timescale

Now we can install Timescale with PostgreSQL 12.

We'll start by creating a folder for our persistent Docker volume:

mkdir -p $HOME/docker/volumes/timescale-pg-12

Next, we'll create and start a Docker container with Postgres 13:

docker run --rm --name timescale-pg-12 -p 127.0.0.1:5112:5432 -v $HOME/docker/volumes/timescale-pg-12:/var/lib/postgresql/data -e POSTGRES_PASSWORD=postgres -d timescale/timescaledb:latest-pg12

TODO from here. Command works!

Let's unpack this command:

• docker run is the command to start a container (and download it if it isn't cached locally)
• --rm makes Docker delete this container when it is stopped
• --name timescale-pg-12 gives the container its name
• -p 127.0.0.1:5112:5432 exposes port 5432 (Postgres standard port) from the container to our local interface (127.0.0.1) on port 5112
• -v $HOME/docker/volumes/timescale-pg-12:/var/lib/postgresql/data mounts the data directory we created earlier into the correct place inside the Timescale Docker container
• -e POSTGRES_PASSWORD=postgres sets the connection password for the postgres user to postgres
• -d makes the container run in detached mode (in the background)
• timescale/timescaledb:latest-pg12 describes the Docker image we want to use

I like port 5112 because this makes it easy to distinguish different Postgres versions. 5113 for Timescale with PG 13, 5112 for Timescale with PG 12 and so on. This allows us to also use other ports for Postgres versions without Timescale, like port 5012 for Postgres 12.

And because we exposed to the local 127.0.0.1 interface only, nobody can connect to this Postgres instance from outside our own Mac.

We can now connect to the container with the following psql command:

psql -h localhost -p 5112 -U postgres

Just type in the password postgres when required.

The connection string for this Postgres instance is postgres://postgres:postgres@127.0.0.1:5112.

Don't worry If you get an error like the following, that means Postgres is setting itself up for the first time. This may take a minute or two:

➜  ~ psql -h localhost -p 5112 -U postgres
psql: error: server closed the connection unexpectedly
	This probably means the server terminated abnormally
	before or while processing the request.

This works fabulously with other timescale / postgres versions, too! Here's an example for timescale on postgres 11:

mkdir -p $HOME/docker/volumes/timescale-pg-11

docker run --rm --name timescale-pg-11 -p 127.0.0.1:5111:5432 -v $HOME/docker/volumes/timescale-pg-11:/var/lib/postgresql/data -e POSTGRES_PASSWORD=postgres -d timescale/timescaledb:latest-pg11

psql -h localhost -p 5111 -U postgres

docker stop timescale-pg-11