Run Percona Distribution for PostgreSQL in a Docker container¶

Docker images of Percona Distribution for PostgreSQL are hosted publicly on Docker Hub .

For more information about using Docker, see the Docker Docs .

Note

Make sure that you are using the latest version of Docker . The ones provided via apt and yum may be outdated and cause errors.

By default, Docker pulls the image from Docker Hub if it is not available locally.

1. Start the container¶

Start a Percona Distribution for PostgreSQL container as follows:

docker run --name container-name -e POSTGRES_PASSWORD=secret -d percona/percona-distribution-postgresql:18.3

Where:

container-name is the name you assign to your container
POSTGRES_PASSWORD is the superuser password
18.3 is the tag specifying the version you need. Docker identifies the architecture (x86_64 or ARM64) and pulls the respective image. See the full list of tags .

Note

Some extensions require server startup configuration and must be loaded via shared_preload_libraries before PostgreSQL starts.

Tip

You can secure the password by exporting it to the environment file and using that to start the container.

Export the password to the environment file:

echo "POSTGRES_PASSWORD=secret" > .my-pg.env

Start the container:

docker run --name container-name --env-file ./.my-pg.env -d percona/percona-distribution-postgresql:18.3

2. Enable extensions¶

Extensions must be explicitly loaded when starting the container using the shared_preload_libraries parameter, then enabled per database:

Start the container with the extensions you want to load:

docker run --name container-name -e POSTGRES_PASSWORD=secret -d percona/percona-distribution-postgresql:18.3 -c shared_preload_libraries=example_extension

Connect to the container’s interactive terminal:

docker exec -it container-name bash

The `container-name` is the name of the container that you started in the previous step.

Create the extension in the desired database:
```
CREATE EXTENSION example_extension;
```

You can specify multiple extensions as a comma-separated list in shared_preload_libraries.

For extension-specific setup, see:

3. Update the image¶

Pull the new tag explicitly:

docker pull percona/percona-distribution-postgresql:18.3

Or pull the latest image for a major version:

docker pull percona/percona-distribution-postgresql:18

4. Docker image contents¶

The Docker image of Percona Distribution for PostgreSQL includes the following components:

Component name	Description
`percona-postgresql18`	A metapackage that installs the latest version of PostgreSQL
`percona-postgresql18-server`	The PostgreSQL server package.
`percona-postgresql-common`	PostgreSQL database-cluster manager. It provides a structure under which multiple versions of PostgreSQL may be installed and/or multiple clusters maintained at one time.
`percona-postgresql-client-common`	The manager for multiple PostgreSQL client versions.
`percona-postgresql18-contrib`	A collection of additional PostgreSQLcontrib extensions
`percona-postgresql18-libs`	Libraries for use with PostgreSQL.
`percona-pg-stat-monitor18`	A Query Performance Monitoring tool for PostgreSQL.
`percona-pgaudit18`	Provides detailed session or object audit logging via the standard PostgreSQL logging facility.
`percona-pgaudit18_set_user`	An additional layer of logging and control when unprivileged users must escalate themselves to superuser or object owner roles in order to perform needed maintenance tasks.
`percona-pg_repack18`	rebuilds PostgreSQL database objects.
`percona-wal2json18`	a PostgreSQL logical decoding JSON output plugin.
`percona-pgvector`	A vector similarity search for PostgreSQL

Connect to Percona Distribution for PostgreSQL from an application in another Docker container¶

This image exposes the standard PostgreSQL port (5432), so container linking makes the instance available to other containers. Start other containers like this in order to link it to the Percona Distribution for PostgreSQL container:

docker run --name app-container-name --network container:container-name -d app-that-uses-postgresql

where:

app-container-name is the name of the container where your application is running,
container name is the name of your Percona Distribution for PostgreSQL container, and
app-that-uses-postgresql is the name of your PostgreSQL client.

Connect to Percona Distribution for PostgreSQL from the `psql` command line client¶

The following command starts another container instance and runs the psql command line client against your original container, allowing you to execute SQL statements against your database:

docker run -it --network container:db-container-name --name container-name percona/percona-distribution-postgresql:18.3 psql -h address -U postgres