postgres

PostgreSQL, often simply "Postgres", is an object-relational database management system (ORDBMS) with an emphasis on extensibility and standards-compliance. As a database server, its primary function is to store data, securely and supporting best practices, and retrieve it later. It can handle workloads ranging from small single-machine applications to large Internet-facing applications with many concurrent users. Recent versions also provide replication of the database itself for security and scalability.

See postgresql.org for more information

This image is built by IBM to run on the IBM Z architecture and is not affiliated with any other community that provides a version of this image.

License

View license information here

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Versions

Use the pull string below for the version of this image you require.

14.5-bullseye	docker pull icr.io/ibmz/postgres@sha256:cdc8f153e40bfd843af72e7d6e964752961a557df3ac3ad8229cedc371640cd3	Vulnerability Report	09-09-2022
13	docker pull icr.io/ibmz/postgres@sha256:48d6a5ca101fea65ff8ff4e6a99167a3ce317d395178abf4b5a39644b593873b	Vulnerability Report	11-22-2024
15.2-bullseye	docker pull icr.io/ibmz/postgres@sha256:3ac7ab6516a8980968d5881ab6a3a19d5841a58cf1298e82fd0ecfbca3d10eaf	Vulnerability Report	03-13-2023
12	docker pull icr.io/ibmz/postgres@sha256:1816067071431202ac8aede4dc3e0e2b4314492818b079064ae211350f5551cb	Vulnerability Report	11-22-2024
Version	Pull String	Security (IBM Cloud)	Created

Usage Notes

Create user defined network (useful for connecting to other services attached to the same network (e.g. Kibana)):

docker network create somenetwork

Start a postgres instance:

docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword 
        -d icr.io/ibmz/postgres:[version]

The default postgres user and database are created in the entrypoint with initdb.

Note you can also use -u psql in your docker run statement to enter the container as user psql

Environment Variables:

The PostgreSQL image uses several environment variables which are easy to miss. The only variable required is POSTGRES_PASSWORD, the rest are optional.

Warning: the Docker specific variables will only have an effect if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup.

POSTGRES_PASSWORD:

This environment variable is required for you to use the PostgreSQL image.

It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the POSTGRES_USER environment variable.

Note 1: The PostgreSQL image sets up trust authentication locally so you may notice a password is not required when connecting from localhost (inside the same container). However, a password will be required if connecting from a different host/container.

Note 2: This variable defines the superuser password in the PostgreSQL instance, as set by the initdb script during initial container startup. It has no effect on the PGPASSWORD environment variable that may be used by the psql client at runtime, as described at https://www.postgresql.org/docs/10/static/libpq-envars.html. PGPASSWORD, if used, will be specified as a separate environment variable.

POSTGRES_USER:

This optional environment variable is used in conjunction with POSTGRES_PASSWORD to set a user and its password. This variable will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of postgres will be used.

Be aware that if this parameter is specified, PostgreSQL will still show The files belonging to this database system will be owned by user "postgres" during initialization. This refers to the Linux system user (from /etc/passwd in the image) that the postgres daemon runs as, and as such is unrelated to the POSTGRES_USER option. See the section titled "Arbitrary --user Notes" for more details.

POSTGRES_DB:

This optional environment variable can be used to define a different name for the default database that is created when the image is first started. If it is not specified, then the value of POSTGRES_USER will be used.

POSTGRES_INITDB_ARGS:

This optional environment variable can be used to send arguments to postgres initdb. The value is a space separated string of arguments as postgres initdb would expect them. This is useful for adding functionality like data page checksums:

-e POSTGRES_INITDB_ARGS="--data-checksums".

POSTGRES_INITDB_WALDIR:

This optional environment variable can be used to define another location for the Postgres transaction log. By default the transaction log is stored in a subdirectory of the main Postgres data folder (PGDATA). Sometimes it can be desireable to store the transaction log in a different directory which may be backed by storage with different performance or reliability characteristics.

Note: on PostgreSQL 9.x, this variable is POSTGRES_INITDB_XLOGDIR (reflecting the changed name of the --xlogdir flag to --waldir in PostgreSQL 10+).

POSTGRES_HOST_AUTH_METHOD:

This optional variable can be used to control the auth-method for host connections for all databases, all users, and all addresses. If unspecified then md5 password authentication is used. On an uninitialized database, this will populate pg_hba.conf via this approximate line:

echo "host all all all $POSTGRES_HOST_AUTH_METHOD" >> pg_hba.conf

See the PostgreSQL documentation on pg_hba.conf for more information about possible values and their meanings.

Note 1: It is not recommended to use trust since it allows anyone to connect without a password, even if one is set (like via POSTGRES_PASSWORD). For more information see the PostgreSQL documentation on Trust Authentication.

Note 2: If you set POSTGRES_HOST_AUTH_METHOD to trust, then POSTGRES_PASSWORD is not required.

PGDATA:

This optional variable can be used to define another location - like a subdirectory - for the database files. The default is /var/lib/postgresql/data. If the data volume you're using is a filesystem mountpoint (like with GCE persistent disks) or remote folder that cannot be chowned to the postgres user (like some NFS mounts), Postgres initdb recommends a subdirectory be created to contain the data.

On ZCX, we will need to create a volume instead, and mount said volume within the created container.

docker volume create yourvol

docker run -d \
    --name some-postgres \
    -e POSTGRES_PASSWORD=mysecretpassword \
    -e PGDATA=/var/lib/postgresql/data/pgdata \
    -v {your_volume}:/var/lib/postgresql/data \
    icr.io/ibmz/postgres:xx

This is an environment variable that is not Docker specific. Because the variable is used by the postgres server binary (see the PostgreSQL docs), the entrypoint script takes it into account.

Docker Secrets:

As an alternative to passing sensitive information via environment variables, _FILE may be appended to some of the previously listed environment variables.

This causes the initialization script to load the values for those variables from files present in the container.

In particular, this can be used to load passwords from Docker secrets stored in /run/secrets/secret_name files. Again, it's important to note that the contents of this directory will be blank by default and that bind mounts do not work presently in ZCX.

Please place password/environmental values within a volume using docker cp, and mount said volume within the container.

Map this volume to the path /run/secrets/name_of_file.

docker volume create psgrs

mkdir -p run/secrets

then place any environmental values as their own named files within /run/secrets/

We will point to this file during our docker run statement, and pass it as an environment variable to be used by postgres.

Now move the contents of /run/secrets* over to the volume you've created by using a temporary container to populate the volume.

Keep in mind that tail -f /dev/null can be replaced with any command that doesn't return an exit code.

docker run -d --rm --name temp -v your_volume:/root/ icr.io/ibmz/alpine:3.12 tail -f /dev/null

docker cp run/. temp:/root

docker stop temp

docker run --name some-postgres -v {your_volume}:/run/ \
    -e POSTGRES_PASSWORD_FILE=/run/secrets/ -d icr.io/ibmz/postgres:xx

docker run -d --rm --name temp -v {your_volume}:/root/ icr.io/ibmz/alpine:3.12 tail -f /dev/null

docker cp data/. temp:/root

docker stop temp

Start your postgres container like this:

docker run --name some-postgres -v {your_volume}:/var/lib/postgresql/data \
         -e POSTGRES_PASSWORD=mysecretpassword -d icr.io/ibmz/postgres:xx

The -v your_volume:/var/lib/postgresql/data part of the command mounts your (volume)data directory from the underlying host system as /var/lib/postgresql/data inside the container, where PostgreSQL by default will write its data files. Initialization scripts

If you would like to do additional initialization in an image derived from this one, add one or more *.sql, *.sql.gz, or *.sh scripts under /docker-entrypoint-initdb.d (creating the directory if necessary). After the entrypoint calls initdb to create the default postgres user and database, it will run any *.sql files, run any executable *.sh scripts, and source any non-executable *.sh scripts found in that directory to do further initialization before starting the service.

Warning: scripts in /docker-entrypoint-initdb.d are only run if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup. One common problem is that if one of your /docker-entrypoint-initdb.d scripts fails (which will cause the entrypoint script to exit) and your orchestrator restarts the container with the already initialized data directory, it will not continue on with your scripts.

For example, to add an additional user and database, add the following to /docker-entrypoint-initdb.d/init-user-db.sh:

#!/bin/bash
set -e

psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
    CREATE USER docker;
    CREATE DATABASE docker;
    GRANT ALL PRIVILEGES ON DATABASE docker TO docker;
EOSQL

These initialization files will be executed in sorted name order as defined by the current locale, which defaults to en_US.utf8. Any *.sql files will be executed by POSTGRES_USER, which defaults to the postgres superuser. It is recommended that any psql commands that are run inside of a *.sh script be executed as POSTGRES_USER by using the --username "$POSTGRES_USER" flag. This user will be able to connect without a password due to the presence of trust authentication for Unix socket connections made inside the container. Arbitrary --user Notes

The main caveat to note is that postgres doesn't care what UID it runs as (as long as the owner of /var/lib/postgresql/data matches), but initdb does care (and needs the user to exist in /etc/passwd):

docker run -it --rm --user www-data -e POSTGRES_PASSWORD=mysecretpassword icr.io/ibmz/postgres:13

The files belonging to this database system will be owned by user "www-data".

docker run -it --rm --user 1000:1000 -e POSTGRES_PASSWORD=mysecretpassword \
        icr.io/ibmz/postgres:xx
initdb: could not look up effective user ID 1000: user does not exist