gem-hunter

Official postgres plugin for dokku. Currently defaults to installing postgres 18.6.

• dokku 0.35.x+
• docker 1.8.x

# on 0.35.x+
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git --name postgres

postgres:app-links [<app>]                         # list all Postgres service links for a given app
postgres:backup <service> <bucket-name> [--id <id>] [-u|--use-iam] # create a backup of the Postgres service to an existing s3 bucket
postgres:backup-auth <service> <aws-access-key-id> <aws-secret-access-key> <aws-default-region> <aws-signature-version> <endpoint-url> [--id <id>] # set up authentication for backups on the Postgres service
postgres:backup-deauth <service> [--id <id>]       # remove backup authentication for the Postgres service
postgres:backup-logs <service> [-t|--tail [<tail-num>]] # print the most recent output of the scheduled backups of the service
postgres:backup-schedule <service> <schedule> <bucket-name> [--id <id>] [-u|--use-iam] # schedule a backup of the Postgres service
postgres:backup-schedule-cat <service> [--id <id>] # cat the crontab line of a scheduled backup for the service
postgres:backup-set-encryption <service> <passphrase> [--id <id>] # set encryption for all future backups of Postgres service
postgres:backup-set-public-key-encryption <service> <public-key-id> [--id <id>] # set GPG Public Key encryption for all future backups of Postgres service
postgres:backup-unschedule <service> [--id <id>|--all] # unschedule the backup of the Postgres service
postgres:backup-unset-encryption <service> [--id <id>] # unset encryption for future backups of the Postgres service
postgres:backup-unset-public-key-encryption <service> [--id <id>] # unset GPG Public Key encryption for future backups of the Postgres service
postgres:certificate <service>                     # print the certificate the Postgres service encrypts connections with
postgres:clone <service> <new-service> [--clone-flags...] # create container <new-name> then copy data from <name> into <new-name>
postgres:connect <service>                         # connect to the service via the postgres connection tool
postgres:create <service> [--create-flags...]      # create a Postgres service
postgres:destroy <service> [-f|--force]            # delete the Postgres service/data/container if there are no links left
postgres:enter <service>                           # enter or run a command in a running Postgres service container
postgres:exists <service>                          # check if the Postgres service exists
postgres:export <service> [-f|--file <path>] [--force] [--all-databases] [-- <export-args...>] # export a dump of the Postgres service database
postgres:expose <service> <ports...>               # expose a Postgres service on custom host:port if provided (random port on the 0.0.0.0 interface if otherwise unspecified)
postgres:import <service> [-f|--file <path>] [--all-databases] [-- <import-args...>] # import a dump into the Postgres service database
postgres:info [<service>] [--info-flags...]        # print the service information
postgres:link <service> [<app>] [--link-flags...]  # link the Postgres service to the app
postgres:linked <service> [<app>]                  # check if the Postgres service is linked to an app
postgres:links <service>                           # list all apps linked to the Postgres service
postgres:list                                      # list all Postgres services
postgres:logs <service> [-t|--tail [<tail-num>]]   # print the most recent log(s) for this service
postgres:mount [--replace] <service> <source:container-dir[:options]>... # mount a host path or docker volume into the service container
postgres:pause <service>                           # pause a running Postgres service
postgres:promote <service> [<app>]                 # promote service <service> as DATABASE_URL in <app>
postgres:reexpose <service>                        # reexpose a Postgres service, applying its expose settings
postgres:reset <service> [-f|--force]              # delete all data in the Postgres service, keeping the service and its links
postgres:restart <service>                         # graceful shutdown and restart of the Postgres service container
postgres:set <service> <key> [<value>] [--id <id>] # set or clear a property for a service
postgres:start <service>                           # start a previously stopped Postgres service
postgres:stop <service>                            # stop a running Postgres service
postgres:unexpose <service>                        # unexpose a previously exposed Postgres service
postgres:unlink <service> [<app>] [-n|--no-restart] # unlink the Postgres service from the app
postgres:unmount [--all] <service> [<source:container-dir>...] # remove one or all mounts from the service container
postgres:upgrade <service> [--upgrade-flags...]    # upgrade service <service> to the specified versions
postgres:upgrade-cleanup <service>                 # remove the data an upgrade across a major version kept aside

Help for any commands can be displayed by specifying the command as an argument to postgres:help. Plugin help output in conjunction with any files in the docs/ folder is used to generate the plugin documentation. Please consult the postgres:help command for any undocumented commands.

# usage
dokku postgres:create <service> [--create-flags...]

flags:

• -c|--config-options <string>: extra arguments for the process the service container runs, not docker flags; use mount for mounts
• -C|--custom-env <string>: semi-colon delimited environment variables to start the service with
• --definition <string>: the definition to run the service on, instead of the one its image and version resolve to
• -i|--image <string>: the image name to start the service with
• -I|--image-version <string>: the image version to start the service with
• -N|--initial-network <string>: the initial network to attach the service to
• --log-driver <string>: the docker logging driver to run the service container with (default: the daemon's own)
• --log-opt <strings>: a comma-separated list of key=value docker log options for the service container
• -m|--memory <int>: container memory limit in megabytes (default: unlimited)
• -p|--password <string>: override the user-level service password, for datastores that have one
• -P|--post-create-network <strings>: a comma-separated list of networks to attach the service container to after service creation
• -S|--post-start-network <strings>: a comma-separated list of networks to attach the service container to after service start
• --restart <string>: the docker restart policy to run the service container with (default: always)
• -r|--root-password <string>: override the root-level service password, for datastores that have one
• --service-memory <string>: memory in megabytes the datastore itself is told to use, such as a cache size or a heap, for datastores that support it (default: the datastore's own)
• -s|--shm-size <string>: override shared memory size for the service docker container
• --volume <stringArray>: a host path or docker volume to mount into the service container, as :[:], repeatable
• --volume-target <stringArray>: mount one of the definition's volumes at another container path, as =, repeatable
• --wait-timeout <string>: seconds to wait for the service to become ready (default: the datastore's own)

Create a postgres service named lollipop:

dokku postgres:create lollipop

You can also specify the image and image version to use for the service. It must be compatible with the postgres image.

export POSTGRES_IMAGE="postgres"
export POSTGRES_IMAGE_VERSION="18.6"
dokku postgres:create lollipop

An image other than postgres has no version to fall back on, because the version this plugin pins belongs to postgres, so name one alongside it.

dokku postgres:create lollipop --image <image> --image-version <version>

These images each have definitions of their own, one per major version, so a service on one is placed by the major its tag carries and has a version to fall back on.

dokku postgres:create lollipop --image pgvector/pgvector --image-version 0.8.7-pg18
dokku postgres:create lollipop --image postgis/postgis --image-version 18-3.6
dokku postgres:create lollipop --image timescale/timescaledb --image-version 2.31.0-pg18

The definition a service runs on decides where its data is mounted, and is otherwise worked out from the image and version. An image whose tags do not carry the major version can name one outright, and --image and --image-version are laid over the image and version it ships. The definitions are: postgres-14, postgres-15, postgres-16, postgres-17, postgres-18, postgres-pgvector-pg17, postgres-pgvector-pg18, postgres-postgis-pg17, postgres-postgis-pg18, postgres-timescaledb-pg17, postgres-timescaledb-pg18.

export POSTGRES_DEFINITION="postgres-14"
dokku postgres:create lollipop --definition postgres-14 --image <image> --image-version <version>

You can also specify custom environment variables to start the postgres service in semicolon-separated form.

export POSTGRES_CUSTOM_ENV="USER=alpha;HOST=beta"
dokku postgres:create lollipop

The container log is bounded by whatever dokku logs:set --global max-size says, and by dokku's own default where it says nothing, which a service may override for itself.

dokku postgres:create lollipop --log-opt max-size=20m,max-file=3

The container is restarted by docker whenever it stops, which a service may change for itself.

dokku postgres:create lollipop --restart unless-stopped

The service is waited on until it answers, for as long as the datastore's own default, which a slow host may raise for every service with POSTGRES_WAIT_TIMEOUT or a service may raise for itself.

dokku postgres:create lollipop --wait-timeout 120

The config options are handed to the process the container runs, not to docker, so a host path or docker volume is mounted with --volume, which may be repeated.

dokku postgres:create lollipop --volume /var/lib/dokku/data/storage/lollipop:/opt/extra:ro

The definition's own volumes can be mounted at another path in the container, for an image that keeps its data somewhere else, with --volume-target, which may be repeated.

export POSTGRES_VOLUME_TARGETS="data=/srv/postgres"
dokku postgres:create lollipop --volume-target data=/srv/postgres

The service passwords are generated unless they are given. A datastore without a root password refuses --root-password rather than dropping it.

dokku postgres:create lollipop --password <password> --root-password <root-password>

Official Postgres "$DOCKER_BIN" image ls does not include postgis extension (amongst others). The following example creates a new postgres service using postgis/postgis:13-3.1 image, which includes the postgis extension.

# use the appropriate image-version for your use-case
dokku postgres:create postgis-database --image "postgis/postgis" --image-version "13-3.1"

To use pgvector instead, run the following:

# use the appropriate image-version for your use-case
dokku postgres:create pgvector-database --image "pgvector/pgvector" --image-version "pg17"

# usage
dokku postgres:destroy <service> [-f|--force]

flags:

• -f|--force: force the destruction of the service

Destroy the service, it's data, and the running container:

dokku postgres:destroy lollipop

A service that is still linked to an app is not destroyed, and the apps it is linked to are named. Unlink them first.

# usage
dokku postgres:info [<service>] [--info-flags...]

flags:

• --backend: show the execution backend the service was created with
• --backup-access-key-id-fingerprint: show a sha256 fingerprint of the stored backup access key id
• --backup-auth-fingerprint: show a sha256 fingerprint of the stored backup access key id and secret
• --backup-authenticated: show whether backup credentials are stored for the service
• --backup-bucket: show the bucket scheduled backups are shipped to
• --backup-default-region: show the region backups authenticate against
• --backup-encrypted: show whether scheduled backups are encrypted with a passphrase
• --backup-encryption-fingerprint: show a sha256 fingerprint of the stored backup passphrase
• --backup-endpoint-url: show the s3-compatible endpoint backups are shipped to
• --backup-keyserver: show the keyserver backup public keys are fetched from
• --backup-mailto: show who cron mails the output of scheduled backups to in place of the global MAILTO
• --backup-object-name: show the name backups are uploaded under in place of the default
• --backup-public-key-id: show the gpg public key id backups are encrypted with
• --backup-schedule: show the cron schedule backups run on
• --backup-schedules: show every scheduled backup, as id, schedule, bucket and use-iam
• --backup-secret-access-key-fingerprint: show a sha256 fingerprint of the stored backup secret access key
• --backup-signature-version: show the signature version backups authenticate with
• --backup-storage-class: show the s3 storage class backups are uploaded with
• --backup-timestamp: show whether backups are uploaded under a key ending in the time they started
• --backup-use-iam: show whether scheduled backups authenticate with an instance role
• --config-dir: show the service configuration directory
• --config-options: show the config options the service container is run with
• --custom-env: show the custom environment the service container is run with
• --data-dir: show the service data directory
• --database-name: show the name of the database inside the service
• --definition: show the definition the service was created with
• --dsn: show the service DSN
• --export-args: show the extra arguments every export of the service is run with
• --expose-host: show the host the exposed DSN names
• --expose-mode: show whether exposed ports are published through an ambassador or directly by the service container
• --exposed-dsn: show the DSN the service is reached at through its exposed ports
• --exposed-ports: show service exposed ports
• --id: show the service container id
• --image: show the image the service runs
• --image-version: show the image version the service was created with
• --import-args: show the extra arguments every import into the service is run with
• --initial-network: show the initial network being connected to
• --internal-ip: show the service internal ip
• --links: show the service app links
• --log-driver: show the docker logging driver the service container is run with
• --log-opt: show the docker log options the service container is run with
• --memory: show the memory limit the service container is run with
• --mounts: show the host paths and docker volumes mounted into the service container
• --password-fingerprint: show a sha256 fingerprint of the service password
• --port-bind-address: show the address exposed ports without one of their own are bound on
• --port-source-range: show the only range of client addresses the exposed ports accept
• --post-create-network: show the networks to attach to after service container creation
• --post-start-network: show the networks to attach to after service container start
• --restart-policy: show the restart policy the service container is run with
• --root-password-fingerprint: show a sha256 fingerprint of the service root password
• --service: show the name of the service
• --service-memory: show the memory in megabytes the datastore itself is told to use
• --service-root: show the service root directory
• --shm-size: show the shared memory size the service container is run with
• --status: show the service running status
• --version: show the service image version
• --volume-targets: show the container paths the service's volumes are mounted at in place of the definition's
• --wait-timeout: show the seconds the service is waited on to become ready

Get connection information as follows:

dokku postgres:info lollipop

Alongside the connection information this reports the properties set on the service, the state it was created with, and its backup settings. A property that was never set, or that was unset, reports as empty. Omit the service to report on every postgres service:

dokku postgres:info

The information can be read by machine, one json object per service:

dokku postgres:info lollipop --format json

You can also retrieve a specific piece of service info via a flag, which prints it on its own:

dokku postgres:info lollipop --dsn
dokku postgres:info lollipop --status
dokku postgres:info lollipop --internal-ip
dokku postgres:info lollipop --initial-network

NOTE: a flag cannot be combined with --format, and only one may be given

The exposed dsn is the one a client off the host connects with. It names the expose-host, or the first global domain without one, and is empty until the service is exposed and there is a host to name:

dokku postgres:info lollipop --exposed-dsn

The properties postgres:set writes are reported under the names it takes, so a value read here can be written back:

dokku postgres:set lollipop initial-network my-network

The stored backup credentials and passphrase are never printed. Each is reported as a lowercase hex sha256 fingerprint of that stored value, with surrounding whitespace trimmed, so a copy of one value can be compared against it:

dokku postgres:info lollipop --backup-access-key-id-fingerprint
dokku postgres:info lollipop --backup-secret-access-key-fingerprint
dokku postgres:info lollipop --backup-encryption-fingerprint

A fingerprint is empty when that value is not stored. The access key id and the secret are also reported as one fingerprint of the pair, which is empty until both are stored and is what backup-auth writes in one call:

dokku postgres:info lollipop --backup-auth-fingerprint

The service's passwords are reported the same way, and are empty for a password the datastore does not have:

dokku postgres:info lollipop --password-fingerprint

The same fingerprints can be computed from the values that were passed to set, backup-auth and backup-set-encryption:

printf '%s' "$AWS_ACCESS_KEY_ID" | sha256sum
printf '%s' "$AWS_SECRET_ACCESS_KEY" | sha256sum
printf '%s\n%s' "$AWS_ACCESS_KEY_ID" "$AWS_SECRET_ACCESS_KEY" | sha256sum
printf '%s' "$PASSPHRASE" | sha256sum
printf '%s' "$PASSWORD" | sha256sum

# usage
dokku postgres:list

List all services:

dokku postgres:list

# usage
dokku postgres:logs <service> [-t|--tail [<tail-num>]]

flags:

• -t|--tail <int>: tail the logs, optionally showing this many lines

You can tail logs for a particular service:

dokku postgres:logs lollipop

By default, logs will not be tailed, but you can do this with the --tail flag:

dokku postgres:logs lollipop --tail

By default the last 100 lines are shown, but a different count can be specified:

dokku postgres:logs lollipop --tail=5

# usage
dokku postgres:link <service> [<app>] [--link-flags...]

flags:

• -a|--alias <string>: the prefix of the config variable the service url is set as on the app, which is suffixed with _URL
• -e|--env-var <string>: the full name of the config variable the service url is set as on the app, used instead of an alias and not suffixed with _URL
• -n|--no-restart: whether to skip restarting the app
• -q|--querystring <string>: ampersand delimited querystring arguments to append to the service url after a ?

A postgres service can be linked to a container. This will use native docker links via the docker-options plugin. Here we link it to our playground app.

NOTE: this will restart your app

dokku postgres:link lollipop playground

The following environment variables will be set automatically by docker (not on the app itself, so they won’t be listed when calling dokku config):

DOKKU_POSTGRES_LOLLIPOP_NAME=/lollipop/DATABASE
DOKKU_POSTGRES_LOLLIPOP_PORT=tcp://172.17.0.1:5432
DOKKU_POSTGRES_LOLLIPOP_PORT_5432_TCP=tcp://172.17.0.1:5432
DOKKU_POSTGRES_LOLLIPOP_PORT_5432_TCP_PROTO=tcp
DOKKU_POSTGRES_LOLLIPOP_PORT_5432_TCP_PORT=5432
DOKKU_POSTGRES_LOLLIPOP_PORT_5432_TCP_ADDR=172.17.0.1

The following will be set on the linked application by default:

DATABASE_URL=postgres://:SOME_PASSWORD@dokku-postgres-lollipop:5432

The host exposed here only works internally in docker containers. If you want your container to be reachable from outside, you should use the expose subcommand. Another service can be linked to your app:

dokku postgres:link other_service playground

The url can be set under another name with the --alias flag. The value given is the prefix of the config variable, which is suffixed with _URL and holds the same url:

dokku postgres:link lollipop playground --alias BLUE_DATABASE

This will set the following on the linked application instead of DATABASE_URL:

BLUE_DATABASE_URL=postgres://:SOME_PASSWORD@dokku-postgres-lollipop:5432

An alias whose variable is already set on the app is refused, and unlink removes the variable whatever alias it was set under. An app that expects the url under a name that does not end in _URL can be given that name in full with the --env-var flag, which cannot be combined with --alias:

dokku postgres:link lollipop playground --env-var MB_DB_CONNECTION_URI

This will set the following on the linked application instead of DATABASE_URL:

MB_DB_CONNECTION_URI=postgres://:SOME_PASSWORD@dokku-postgres-lollipop:5432

A name already set on the app is refused. Arguments can be appended to the url as a querystring with the --querystring flag:

dokku postgres:link lollipop playground --querystring "foo=bar&baz=qux"

This will cause DATABASE_URL to be set as:

postgres://:SOME_PASSWORD@dokku-postgres-lollipop:5432?foo=bar&baz=qux

It is possible to change the protocol for DATABASE_URL by setting the environment variable POSTGRES_DATABASE_SCHEME on the app. Link records the variable it set, so unlink still removes it after the scheme or querystring on it changes. A link made by an earlier version of the plugin is recorded the next time link or promote runs for it, and until then we advise you to unlink before changing the scheme.

dokku config:set playground POSTGRES_DATABASE_SCHEME=postgres2
dokku postgres:link lollipop playground

This will cause DATABASE_URL to be set as:

postgres2://:SOME_PASSWORD@dokku-postgres-lollipop:5432

# usage
dokku postgres:unlink <service> [<app>] [-n|--no-restart]

flags:

• -n|--no-restart: whether to skip restarting the app

You can unlink a postgres service:

NOTE: this will restart your app and unset related environment variables

dokku postgres:unlink lollipop playground

An app is still linked after its DATABASE_URL is changed to point elsewhere, and is unlinked the same way. The variable it now holds is not the service's, so it is left alone, nothing is unset, the app is not restarted, and a warning says so. A variable link set that has only had its scheme or querystring changed still points at the service, and is unset.

# usage
dokku postgres:set <service> <key> [<value>] [--id <id>]

flags:

• --allow-restart: restart or reexpose the service when the property only takes effect that way and its value changed
• --id <string>: record the property on this backup schedule instead of on the service
• --no-restart: do not restart the linked apps when a password change updates the url they hold

Set the network to attach after the service container is started:

dokku postgres:set lollipop post-create-network custom-network

Set multiple networks:

dokku postgres:set lollipop post-create-network custom-network,other-network

Unset the post-create-network value:

dokku postgres:set lollipop post-create-network

Limit the container to 512 megabytes of memory, or go back to no limit with 0:

dokku postgres:set lollipop memory 512

Give the container a shared memory size of its own:

dokku postgres:set lollipop shm-size 256m

Start the container with semi-colon delimited environment variables of your own:

dokku postgres:set lollipop custom-env "TZ=UTC;LANG=C.UTF-8"

Pass extra arguments to the process the service container runs. These are not docker flags, so use mount for mounts. The value follows -- so that its leading dash is not read as a flag:

dokku postgres:set lollipop config-options -- "<config-options...>"

Go back to running the process with the datastore's own arguments alone:

dokku postgres:set lollipop config-options

Change the password in the datastore and in the url every linked app holds, restarting the apps. The value is never printed back, and info reports a fingerprint of it:

dokku postgres:set lollipop password "<new-password>"

Give the linked apps the new url without restarting them:

dokku postgres:set --no-restart lollipop password "<new-password>"

Change one of the settings backup-auth stores, such as the endpoint of an s3 compatible service, without passing the rest again:

dokku postgres:set lollipop backup-endpoint-url https://nyc3.digitaloceanspaces.com

Rotate the credentials backups are shipped with one at a time. The value is never printed back, and info reports a fingerprint of that value:

dokku postgres:set lollipop backup-access-key-id AKIAIOSFODNN7EXAMPLE
dokku postgres:set lollipop backup-secret-access-key "<secret-access-key>"

Encrypt backups with a passphrase, or with a gpg public key:

dokku postgres:set lollipop backup-encryption-passphrase "<passphrase>"
dokku postgres:set lollipop backup-public-key-id "<public-key-id>"

Ship the default scheduled backup to another bucket, or have it authenticate with an instance role, when that is the only schedule. Both rewrite the crontab entry. With more than one schedule, change a schedule with backup-schedule --id:

dokku postgres:set lollipop backup-bucket other-bucket
dokku postgres:set lollipop backup-use-iam true

Record a backup setting on one schedule. An empty value clears that schedule's own value and leaves the service's. The bucket and the instance role cannot be set this way:

dokku postgres:set lollipop backup-storage-class STANDARD_IA --id monthly

Give one schedule its own endpoint. The access key and the secret are set with backup-auth --id, and set rotates one of them once both are stored:

dokku postgres:set lollipop backup-endpoint-url https://nyc3.digitaloceanspaces.com --id monthly

Set the keyserver a public key for backup encryption is fetched from:

dokku postgres:set lollipop backup-keyserver hkp://keys.example.com

Set the s3 storage class backups are uploaded with, one of STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, INTELLIGENT_TIERING, GLACIER, DEEP_ARCHIVE or GLACIER_IR:

dokku postgres:set lollipop backup-storage-class STANDARD_IA

Go back to uploading backups with the bucket's default storage class:

dokku postgres:set lollipop backup-storage-class

Upload backups under a name of your own rather than postgres-lollipop:

dokku postgres:set lollipop backup-object-name db/latest

Upload every backup to the same key, without a timestamp, so bucket versioning and lifecycle rules can keep and rotate them:

dokku postgres:set lollipop backup-timestamp false

Go back to timestamped backups:

dokku postgres:set lollipop backup-timestamp

Mail the output of scheduled backups to a comma-separated list of email addresses or local users rather than to the global cron MAILTO. Requires a dokku version that reads json entries from the cron-entries plugin trigger, and a mail transfer agent on the host:

dokku postgres:set lollipop backup-mailto ops@example.com,dba@example.com

Go back to mailing scheduled backup output to the global cron MAILTO:

dokku postgres:set lollipop backup-mailto

Cap the container log at a size of your own rather than the one it inherits:

dokku postgres:set lollipop log-opt max-size=20m,max-file=3

Keep the log unbounded, which is what a service had before there was anything to say here:

dokku postgres:set lollipop log-opt max-size=unlimited

Send the container log somewhere other than the daemon's own driver:

dokku postgres:set lollipop log-driver journald

Restart the container unless it was stopped on purpose, including across a docker restart:

dokku postgres:set lollipop restart-policy unless-stopped

Go back to always restarting the container:

dokku postgres:set lollipop restart-policy

Wait up to two minutes for the service to answer, used the next time it is started:

dokku postgres:set lollipop wait-timeout 120

Go back to the wait timeout the host or the datastore sets:

dokku postgres:set lollipop wait-timeout

Publish exposed ports that have no address of their own on one address rather than on every interface:

dokku postgres:set lollipop port-bind-address 10.0.0.5

Only accept connections to the exposed ports from clients in one IP address or CIDR:

dokku postgres:set lollipop port-source-range 10.0.0.0/8

Go back to accepting every client:

dokku postgres:set lollipop port-source-range

Name the host the exposed dsn points clients at, when they reach the server by a name or address other than its global domain. It does not change where the ports are bound:

dokku postgres:set lollipop expose-host db.example.com

Go back to naming the first global domain:

dokku postgres:set lollipop exp