Official Repository

Last pushed: a day ago
Short Description
The PostgreSQL object-relational database system provides reliability and data integrity.
Full Description

Supported tags and respective Dockerfile links

Quick reference

What is PostgreSQL?

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, as requested by other software applications, be it those on the same computer or those running on another computer across a network (including the Internet). 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.

PostgreSQL implements the majority of the SQL:2011 standard, is ACID-compliant and transactional (including most DDL statements) avoiding locking issues using multiversion concurrency control (MVCC), provides immunity to dirty reads and full serializability; handles complex SQL queries using many indexing methods that are not available in other databases; has updateable views and materialized views, triggers, foreign keys; supports functions and stored procedures, and other expandability, and has a large number of extensions written by third parties. In addition to the possibility of working with the major proprietary and open source databases, PostgreSQL supports migration from them, by its extensive standard SQL support and available migration tools. And if proprietary extensions had been used, by its extensibility that can emulate many through some built-in and third-party open source compatibility extensions, such as for Oracle.

wikipedia.org/wiki/PostgreSQL

How to use this image

start a postgres instance

$ docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres

This image includes EXPOSE 5432 (the postgres port), so standard container linking will make it automatically available to the linked containers. The default postgres user and database are created in the entrypoint with initdb.

The postgres database is a default database meant for use by users, utilities and third party applications.
postgresql.org/docs

connect to it from an application

$ docker run --name some-app --link some-postgres:postgres -d application-that-uses-postgres

... or via psql

$ docker run -it --rm --link some-postgres:postgres postgres psql -h postgres -U postgres
psql (9.5.0)
Type "help" for help.

postgres=# SELECT 1;
 ?column? 
----------
        1
(1 row)

... via docker stack deploy or docker-compose

Example stack.yml for postgres:

# Use postgres/example user/password credentials
version: '3.1'

services:

    db:
        image: postgres
        environment:
            POSTGRES_PASSWORD: example

    adminer:
        image: adminer
        ports:
            - 8080:8080

Run docker stack deploy -c stack.yml postgres (or docker-compose -f stack.yml up), wait for it to initialize completely, and visit http://swarm-ip:8080, http://localhost:8080, or http://host-ip:8080 (as appropriate).

Environment Variables

The PostgreSQL image uses several environment variables which are easy to miss. While none of the variables are required, they may significantly aid you in using the image.

POSTGRES_PASSWORD

This environment variable is recommended for you to use the PostgreSQL image. This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the POSTGRES_USER environment variable. In the above example, it is being set to "mysecretpassword".

Note: 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.

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.

PGDATA

This optional environment variable can be used to define another location - like a subdirectory - for the database files. The default is /var/lib/postgresql/data, but if the data volume you're using is a fs mountpoint (like with GCE persistent disks), Postgres initdb recommends a subdirectory (for example /var/lib/postgresql/data/pgdata ) be created to contain the data.

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_XLOGDIR

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.

Arbitrary --user Notes

As of docker-library/postgres#253, this image supports running as a (mostly) arbitrary user via --user on docker run.

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 postgres
The files belonging to this database system will be owned by user "www-data".
...

$ docker run -it --rm --user 1000:1000 postgres
initdb: could not look up effective user ID 1000: user does not exist

The two easiest ways to get around this:

  1. bind-mount /etc/passwd read-only from the host (if the UID you desire is a valid user on your host):

    $ docker run -it --rm --user "$(id -u):$(id -g)" -v /etc/passwd:/etc/passwd:ro postgres
    The files belonging to this database system will be owned by user "jsmith".
    ...
    
  2. initialize the target directory separately from the final runtime (with a chown in between):

    $ docker volume create pgdata
    $ docker run -it --rm -v pgdata:/var/lib/postgresql/data postgres
    The files belonging to this database system will be owned by user "postgres".
    ...
    ( once it's finished initializing successfully and is waiting for connections, stop it )
    $ docker run -it --rm -v pgdata:/var/lib/postgresql/data bash chown -R 1000:1000 /var/lib/postgresql/data
    $ docker run -it --rm --user 1000:1000 -v pgdata:/var/lib/postgresql/data postgres
    LOG:  database system was shut down at 2017-01-20 00:03:23 UTC
    LOG:  MultiXact member wraparound protections are now enabled
    LOG:  autovacuum launcher started
    LOG:  database system is ready to accept connections
    

How to extend this image

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 and source any *.sh scripts found in that directory to do further initialization before starting the service.

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" <<-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.

Additionally, as of docker-library/postgres#253, these initialization scripts are run as the postgres user (or as the "semi-arbitrary user" specified with the --user flag to docker run; see the section titled "Arbitrary --user Notes" for more details).

You can also extend the image with a simple Dockerfile to set a different locale. The following example will set the default locale to de_DE.utf8:

FROM postgres:9.4
RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8
ENV LANG de_DE.utf8

Since database initialization only happens on container startup, this allows us to set the language before it is created.

Caveats

If there is no database when postgres starts in a container, then postgres will create the default database for you. While this is the expected behavior of postgres, this means that it will not accept incoming connections during that time. This may cause issues when using automation tools, such as docker-compose, that start several containers simultaneously.

Image Variants

The postgres images come in many flavors, each designed for a specific use case.

postgres:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.

postgres:alpine

This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.

This variant is highly recommended when final image size being as small as possible is desired. The main caveat to note is that it does use musl libc instead of glibc and friends, so certain software might run into issues depending on the depth of their libc requirements. However, most software doesn't have an issue with this, so this variant is usually a very safe choice. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.

To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar).

Docker Pull Command

Comments (121)
subliminalpanda
7 days ago

Everything seems to be working fine when starting up

docker run -p 8432:5432 -e POSTGRES_PASSWORD=password-v testvol:/var/lib/postgresql/data postgres:latest -d postgres

However recently during startup i've been seeing the following errors:

LOG:  database system was interrupted; last known up at 2017-06-16 15:56:23 UTC
LOG:  database system was not properly shut down; automatic recovery in progress
LOG:  invalid record length at 1/9D4B9B70: wanted 24, got 0
LOG:  redo is not required
LOG:  MultiXact member wraparound protections are now enabled
LOG:  database system is ready to accept connections
LOG:  autovacuum launcher started

How would I go about fixing this kind of error?

Also when the container is running with the -d flag, how do I perform a clean shutdown?

Thanks!

zegratman
19 days ago

Problem with 9.3 version at docker run stage (no problem with 9.4 version) :

LOG: unrecognized configuration parameter "dynamic_shared_memory_type" in file "/var/lib/postgresql/data/postgresql.conf" line 126
FATAL: configuration file "/var/lib/postgresql/data/postgresql.conf" contains errors

briandoran
19 days ago

Is there a quick way to add additional -D parameters for when postgres starts up? for instance -Dconfig_file =/some_location

juanb
a month ago

Hi there,

How could I change the default listen port? that because there's another server using 5432, and I need to be able to run several containers with different ports while using --net=host.

Thanks in advance.

srlopez
a month ago

About connection to a running container ...
After run first time a container like this
$ docker run --name db -e POSTGRES_PASSWORD=1234 -d postgres

The 'normal' way to connect to database and run psql is
$ docker run -it --rm --link db:postgres postgres psql -h postgres -U postgres
But it create another contair

If i want run bash without create other container i can 'exec' and then psql

$ docker exec -it db bash
incontainer$ psql -U postgres -h postgres
psql: could not translate host name "postgres" to address: Name or service not known
but
$incontainer $ psql -U postgres
run ok.
¿why -h postgres doesn't work?
¿Which is best option to run a bash?

greenfish77
a month ago

is there anyone know how to change POSTGRES_PASSWORD on using volume?

$ sudo docker run --name ccc -d -p 5432:5432 -v /aaa:/var/lib/postgresql/data -e POSTGRES_PASSWORD=admin -e POSTGRES_USER=admin postgres
$ psql -h 127.0.0.1 -U admin
... input password "admin"
$ sudo docker rm -vf ccc

and now just change POSTGRES_PASSWORD.
$ sudo docker run --name ccc -d -p 5432:5432 -v /aaa:/var/lib/postgresql/data -e POSTGRES_PASSWORD=admin111 -e POSTGRES_USER=admin postgres

$ psql -h 127.0.0.1 -U admin
... input password "admin111" was failed.
... input password old "admin" was passed.

i want to change password to admin111, how ?

muralikg
2 months ago

@johnnywell postgres-contrib-$VERSION is part of the image hence the extensions should available for use.

If you want to enable the extension globally for any database you create it has to be enabled on "template1" database
For example:
\c template1
CREATE EXTENSION pg_trgm;

johnnywell
2 months ago

How do I install extensions to the default database?

huggla
3 months ago

You can also extend the image with a simple Dockerfile to set a different locale. The following example will set the default locale to de_DE.utf8:

FROM postgres:9.4
RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8
ENV LANG de_DE.utf8"

You should mention that this example doesn't work with alpine tags. How change locale on Alpine?

gambitwebservice
4 months ago

Beware the current suggestion to use '--link' when running this container. Docker is deprecating this command explained here, they are now using docker networking.