JIYIK CN >

PostgreSQL , also known as Postgres, is a leading object-relational database system. It is popular because it is highly compliant with the SQL standard and includes additional features that simplify processing complex data sets at scale.

PostgreSQL uses a traditional client-server architecture, so you need to run it independently from your application code. In this post, we will deploy a PostgreSQL server instance as a Docker container. This avoids adding packages to your host and helps isolate the database from the rest of your stack. Before continuing, make sure you have Docker installed.

PostgreSQL has an official image on Docker Hub, which comes in several different variants. Tags allow us to choose between major PostgreSQL versions from v9 to v14, and choose the operating system to use as the base image. Alpine , Debian Stretch , and Debian Bullseye are provided .

For the purpose of this tutorial, we will use postgres:14the PostgreSQL 14 tag, which is available on Bullseye. We are also free to choose a different version to suit our requirements.

docker runStart the PostgreSQL container using the command:

$ docker run -d \
    --name postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD=<password> \
    -v postgres:/var/lib/postgresql/data \
    postgres:14

We must provide a value for the POSTGRES_PASSWORD environment variable. This defines the password that will be assigned to the default superuser account of Postgres. The username defaults to postgres but can be changed by setting the POSTGRES_USER environment variable.

-vThe option is used to mount a Docker volume to the PostgreSQL container's data directory. This references a named volume called postgres; Docker will create it or reattach the volume if it already exists. We should use volumes to store our database outside of the container. If not, our data will be used when the container is stopped.

By default, PostgreSQL listens on port 5432. The container port is bound to port 5432 on the Docker host using the -p option. The -d flag is used to start the container in detached mode, effectively making it a background service that runs until stopped by docker stop.

Provide password as a file

If you are uncomfortable with providing the superuser password as a plain text CLI flag, we can inject it as a file via a volume. The POSTGRES_PASSWORD_FILE environment variable should then be set to indicate the path to that file to Postgres:

$ docker run -d \
    --name postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres-password \
    -v ./postgres-password.txt:/run/secrets/postgres-password
    -v postgres:/var/lib/postgresql/data \
    postgres:14

This also works for POSTGRES_USER and other supported environment variables.

Connect to your database

Since PostgreSQL is bound to port 5432 above, we can connect to the database at localhost:5432 from any compatible client using the credentials assigned when launching the container as environment variables.

The Docker image also includes the psql binary that we can call using docker exec. This allows us to quickly interact with our database from a PostgreSQL shell inside the container.

$ docker exec -it postgres psql -U postgres

Connecting from other Docker containers

Creating a Docker network is the preferred way to access PostgreSQL from other containers on the same host. This avoids binding the Postgres server's ports and potentially exposing the service to the host's wider network.

Create a Docker network:

$ docker network create my-app

Use docker run with the --network option to start the Postgres container and connect to the network:

$ docker run -d \
    --name postgres \
    --network my-app \
    -e POSTGRES_PASSWORD=<password> \
    -v postgres:/var/lib/postgresql/data \
    postgres:14

Now join your application container to the same network:

$ docker run -d
    --name api
    --network my-app
    my-api:latest

Containers in the network can access Postgres using the postgres hostname, because this is the name assigned to the Postgres container. The connection is made using port 5432.

Configure PostgreSQL

We can pass PostgreSQL server options using the -c option after the image name in the docker run command:

$ docker run -d \
    --name postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD=<password> \
    -v postgres:/var/lib/postgresql/data \
    postgres:14 -c max_connections=100

Everything after the image name is passed to the command started in the container. For the Postgres image, this command will be the PostgreSQL server binary.

When you set values ​​for multiple options, you can use a custom configuration file. You need to mount the file into the container using another Docker volume, and then provide a -c option to instruct Postgres where to look:

$ docker run -d \
    --name postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD=<password> \
    -v ./postgres.conf:/etc/postgresql/postgresql.conf \
    -v postgres:/var/lib/postgresql/data \
    postgres:14 -c config_file=/etc/postgresql/postgresql.conf

This example uses a Docker bind mount to mount the postgres.conf file in the working directory into the container's /etc/postgresql directory.

Initialize the database

The Docker image supports seed files placed in the /docker-entrypoint-initdb.d directory. Any of the /etc/initdb.d or /etc/initdb.d files will be executed .sqlto .sql.gzinitialize the database. This happens after the default user account and postgres database are created. You can also add /etc/initdb.d .shfiles to run arbitrary shell scripts. All scripts are executed in alphabetical order.

This mechanism means that you only need a set of SQL or shell scripts named in the correct order to initialize the database. Install them into a new container using the docker run command with the -v option:

$ docker run -d \
    --name postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD=<password> \
    -v ./db-seed-files/:/etc/docker-entrypoint-initdb.d \
    -v postgres:/var/lib/postgresql/data \
    postgres:14

The init scripts will only be used if the Postgres data directory is empty. For practical purposes, this means that they will be run the first time the container starts, and a new, empty volume will be attached.

Creating a custom database mirror

You can choose to package the configuration files and initialization scripts in your own Docker image. This will let anyone with access to the image start a new PostgreSQL instance pre-configured for your application. Here is a simple Dockerfile that can be used:

Dockerfile

FROM postgres:14
COPY postgres.conf /etc/postgresql/postgresql.conf
COPY db-seed-files/ /etc/docker-entrypoint-initdb.d/
CMD ["-c", "config_file=/etc/postgresql/postgresql.conf"]

Build a custom image:

$ docker build -t custom-postgres:latest .

The build instructions in the Dockerfile will copy the PostgreSQL configuration files and initialization scripts from your working directory and embed them into the container image. Now you can start the database container without manually providing the resources:

$ docker run -d \
    --name custom-postgres \
    -p 5432:5432
    -e POSTGRES_PASSWORD=<password> \
    -v postgres:/var/lib/postgresql/data \
    custom-postgres:latest

Should You Containerize Your Production Database?

Deciding whether to run your database in Docker can be difficult. Containerizing PostgreSQL makes the setup experience easier, but sometimes more challenging to maintain. Care needs to be taken when managing containers to avoid losing data in the future. Docker also adds a modest performance overhead, which is worth considering when the database is expected to handle very large data volumes.

The benefits of Docker are increased portability, ease of scalability, and developer efficiency. Containerizing your database allows anyone to launch a new instance using Docker without having to manually install and configure PostgreSQL first. Therefore, writing a Dockerfile for your PostgreSQL database to add your configuration files and SQL seed scripts is a great way to help developers quickly launch new environments.

Summarize

PostgreSQL is an advanced SQL-based database engine that adds object-relational capabilities. While you can choose to run a traditional deployment in production, using a containerized instance simplifies setup and helps developers quickly spin up their own infrastructure.

The most critical aspect of a Dockerized deployment is to ensure that you use volumes to store your data. This will allow you to stop, replace, and update your containers to higher versions of the image without losing your database. In addition to storage, you should also evaluate how you will connect to Postgres and avoid binding ports to your host unless necessary. When connecting from another container, it is best to use a shared Docker network for easy access.