Skip to content

Deploy PostgreSQL

This guide shows you how to use PostgreSQL, a powerful, open source object-relational database system.

To run it, follow these steps:

  1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

  2. Clone the examples repository and cd into the examples/postgres/ directory:

Terminal window
git clone https://github.com/kraftcloud/examples
cd examples/postgres/

Make sure to log into Unikraft Cloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

Terminal window
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

When done, invoke the following command to deploy this application on Unikraft Cloud:

Terminal window
kraft cloud deploy -e POSTGRES_PASSWORD=unikraft -p 5432:5432/tls -M 1024 .

The output shows the instance URL and other details:

Terminal window
[] Deployed successfully!
────────── name: postgres-saan9
────────── uuid: 3a1371f2-68c6-4187-84f8-c080f2b028ca
───────── state: starting
────────── fqdn: young-thunder-fbafrsxj.fra0.kraft.host
───────── image: postgres@sha256:2476c0373d663d7604def7c35ffcb4ed4de8ab231309b4f20104b84f31570766
──────── memory: 1024 MiB
─────── service: young-thunder-fbafrsxj
── private fqdn: postgres-saan9.internal
──── private ip: 172.16.3.1
────────── args: wrapper.sh docker-entrypoint.sh postgres -c shared_preload_libraries='pg_ukc_scaletozero'

In this case, the instance name is postgres-saan9 and the service young-thunder-fbafrsxj. They are different for each run.

If you use port 5432/tls as per the example above you can now directly connect to postgres:

Terminal window
psql -U postgres -h young-thunder-fbafrsxj.fra0.kraft.host

Use the unikraft password at the password prompt. You should see output similar to:

Terminal window
Password for user postgres:
psql (15.5 (Ubuntu 15.5-0ubuntu0.23.04.1), server 16.2)
WARNING: psql major version 15, server major version 16.
Some psql features might not work.
Type "help" for help.
postgres=#

Use SQL and psql commands for your work.

At any point in time, you can list information about the instance:

Terminal window
kraft cloud instance list
NAME FQDN STATE CREATED AT IMAGE MEMORY ARGS BOOT TIME
postgres-saan9 young-thunder-fbafrsxj.fra0.kraft.host running 6 minutes ago postgres@sha256:2476c0373d663d7604d... 1.0 GiB wrapper.sh docker-entrypoint.sh postgres 603.42 ms

When done, you can remove the instance:

Terminal window
kraft cloud instance remove postgres-saan9

Using Volumes

You can use volumes for data persistence for you PostgreSQL instance.

For that you would first create a volume:

Terminal window
kraft cloud volume create --name postgres --size 200

Then start the PostgreSQL instance and mount that volume:

Terminal window
kraft cloud deploy -e POSTGRES_PASSWORD=unikraft -e PGDATA=/volume/postgres -v postgres:/volume -p 5432:5432/tls -M 1024 .

Customize Your Deployment

Your deployment is a standard PostgreSQL installation. Customizing the deployment generally means providing a different environment.

An obvious one is to use a different database password when starting PostgreSQL. For that you use a different POSTGRES_PASSWORD environment variable when starting the PostgreSQL instance.

You could also a different location to mount your volume or set additional configuration options.

And, of course, you can use the PostgreSQL instance in conjunction with a frontend service, see the guide here. However, in that case make sure to disable scale-to-zero if you plan to use the DB internally.

Learn More

Use the --help option for detailed information on using Unikraft Cloud:

Terminal window
kraft cloud --help

Or visit the CLI Reference.