postgresql

Overview based on postgres

Chainguard Container for postgres

Minimal image for PostgreSQL, an advanced object-relational database management system.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/postgres:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard postgres container image is comparable to the official PostgreSQL Image from Docker Hub. However, the Chainguard image contains only the minimum set of tools and dependencies needed to function; for example, it does not include a package manager. Unlike many other Chainguard images, though, the postgres image does include a shell, allowing you to manage databases interactively.

Chainguard's postgres container image also provides a -slim variant that is even more minimal than the standard variant and contains only the critical files necessary to run PostgreSQL. As such, it doesn't include a shell, package manager, debuggers, or utility tools.

The -slim variant is best suited for advanced users who want maximum security and the smallest possible footprint. They're ideal for locked-down production environments or cases with strict compliance requirements, but users give up conveniences like shell access or running shell-based entrypoint scripts.

Migrating to the Chainguard postgresql container image

When migrating an existing PostgreSQL database to use the Chainguard postgres image it is likely that the collation version in the Chainguard container image will be different from the collation version in the original image that created the database. This may be due to different glibc versions, use of a different implementation of the C standard library (musl in Alpine for example), or the use of different locale configuration.

Chainguard recommends that you re-index and refresh the collation version when migrating to this image before the database is put back into production.

Additionally, note that Chainguard's postgres container image uses a different data directory than the official PostgreSQL image. The following commands show data directory for Chainguard's postgres image:

docker run -it --entrypoint sh cgr.dev/ORGANIZATION/postgres
/home/postgres # echo $PGDATA
/var/lib/postgresql/data

And these show the public image's data directory:

docker run -it --entrypoint sh postgres
# echo $PGDATA
/var/lib/postgresql/18/docker

As this output shows, the $PGDATA directory path in the public image includes the version number of PostgreSQL that's used by the image. If you've hardcoded this directory anywhere in your application, you will need to update it when you upgrade to a newer version of PostgreSQL. The data directory in Chainguard's postgres image remains consistent across versions.

In most cases it's recommended that you use the $PGDATA environment variable instead of hardcoding the path, as this will work regardless of what version of PostgreSQL you're using.

Getting Started

This section provides a high-level overview of how you can use Chainguard's postgres image. For a more in-depth walkthrough of how you can use the image in practice, please refer to our guide on getting started with the PostgreSQL Chainguard Image. This getting started guide outlines how to set up and run a PHP application that stores its data in a PostgreSQL database running within a containerized environment.

You can test the postgres image by running the following command:

docker run --rm -e POSTGRES_PASSWORD=password -ti --name postgres-test cgr.dev/ORGANIZATION/postgres:latest

Note that the only mandatory environment variable needed by the postgres image is POSTGRES_PASSWORD.

This command will run the container image, but no data within the PostgreSQL database will persist after the Image stops running. To persist PostgreSQL data you can mount a volume mapped to the container's data folder:

docker run --rm -d -v $PWD/data:/var/lib/postgresql/data -e POSTGRES_PASSWORD=password -ti --name postgres-test cgr.dev/ORGANIZATION/postgres:latest

This command includes the -d flag, which causes the container to run in the background and keeps it from taking over your terminal like the previous example.

Following that you can exec into the running container:

docker exec -ti postgres-test bash

Then switch to using the postgres user:

su postgres

As the postgres user, run the createdb wrapper to create a test database:

createdb test

Then use the PostgreSQL client to connect to the new database:

psql test

From there you can interact with the database as you would with any other PostgreSQL database. For instance, you can create a sample table:

CREATE TABLE accounts (
	user_id serial PRIMARY KEY,
	username VARCHAR ( 50 ) UNIQUE NOT NULL,
	password VARCHAR ( 50 ) NOT NULL,
	email VARCHAR ( 255 ) UNIQUE NOT NULL,
	created_on TIMESTAMP NOT NULL,
	last_login TIMESTAMP
);

With the table created you can then insert data into it:

INSERT INTO accounts (username, password, email, created_on, last_login)
VALUES (
'Linky',
'p@$$w0rD',
'linky@example.com',
'2017-07-23',
'2017-07-23'
);

You can also use all of PostgreSQL's internal meta-commands. For example, \dt will list all the tables stored within the database:

\dt

          List of relations
 Schema |   Name   | Type  |  Owner
--------+----------+-------+----------
 public | accounts | table | postgres
(1 row)

Customizing PostgreSQL with environment variables

You can extend Chainguard's Postgres image with environment variables. Chainguard's Postgres image is compatible with the environment variables available in the official PostgreSQL image, including the following:

• PGDATA: This variable allows you to define another location for database files. The default data directory is /var/lib/postgresql/data.
• POSTGRES_PASSWORD: This environment variable sets the superuser password for PostgreSQL. This variable is required to use the Postgres image.
• POSTGRES_USER: This is used with the POSTGRES_PASSWORD variable to set a superuser for the database and its password. If not specified, you can use the default postgres user.
• POSTGRES_DB: Using this variable allows you to set a different name for the default database. If not specified, the default database will be postgres or the value set by POSTGRES_USER.
• POSTGRES_INITDB_ARGS: This variable allows you to send arguments to postgres initdb.
• POSTGRES_INITDB_WALDIR: You can set this variable to define the location for the PostgreSQL transaction log. By default, the transaction log is stored in a subdirectory of the main postgresql data folder, which you can define with PGDATA.
• POSTGRES_HOST_AUTH_METHOD: This variable allows you to control the auth-method used to authenticate when connecting to the database.

Note that if you set the POSTGRES_HOST_AUTH_METHOD variable to trust, then the POSTGRES_PASSWORD variable is no longer required:

docker run --rm -e POSTGRES_HOST_AUTH_METHOD=trust -e POSTGRES_DB=linky -ti --name postgres-test cgr.dev/ORGANIZATION/postgres:latest

Additionally, be aware that the Docker specific variables will only have an effect if you start the container with an empty data directory; pre-existing databases won't be affected on container startup.

Running PostgreSQL with a custom configuration file

You can also run the Chainguard postgres image with a custom configuration file. The following example will mount a PostgreSQL configuration file named my-postgres.conf to the container.

docker run --rm -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=password -ti --name postgres-test cgr.dev/ORGANIZATION/postgres:latest -c 'config_file=/etc/postgresql/postgresql.conf'

This command also uses the PostgreSQL server's -c flag to set the config_file runtime parameter.

Initial SQL script

The path for initial load sql script should be same as per application docs /docker-entrypoint-initdb.d/init.sql for versions up to and including PostgreSQL 13. For PostgreSQL 14 and above, the initial load script needs to be mounted at /var/lib/postgres/initdb/init.sql.

Using the Slim Variant

The -slim variant is designed for production environments where security and minimal footprint are priorities. You'll need to use a two-step approach to set up and run PostgreSQL.

Initializing the Database with the Slim Dev Variant

Use the -slim-dev variant to initialize the database, then use the -slim variant to run the PostgreSQL server.

Step 1: Initialize the database

Create a Docker volume for persistent data:

docker volume create postgres-data

Initialize the database using the -slim-dev image:

docker run --rm \
  -v postgres-data:/var/lib/postgresql/data \
  --user 65532:65532 \
  --entrypoint initdb \
  cgr.dev/ORGANIZATION/postgres:18-slim-dev \
  -D /var/lib/postgresql/data --locale=C --encoding=UTF8

Step 2: Start the PostgreSQL server

Run the PostgreSQL server using the -slim image:

docker run -d \
  --name postgres-slim \
  -v postgres-data:/var/lib/postgresql/data \
  --user 65532:65532 \
  --entrypoint postgres \
  cgr.dev/ORGANIZATION/postgres:18-slim \
  -D /var/lib/postgresql/data

Documentation and Resources

• Getting Started with the PostgreSQL Chainguard Container
• Vulnerability Comparison: postgres
• Blog: How to Use the Postgres Docker Official Image

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.