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:

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:

# 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:

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

The output shows the instance URL and other details:

[●] 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:

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

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

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.

Idle Scale-to-Zero

This example uses the idle scale-to-zero policy by default (see the labels section in the Kraftfile). It means that the instance will scale-to-zero even in the presence of psql connections. To ensure that the instance is not put into standby even for long running queries (during which the connections are also idle), the PostgreSQL example makes use of scale-to-zero application support. To this end, we load the pg_ukc_scaletozero module into PostgreSQL, which suspends scale-to-zero during query processing. You can see this in action by running SELECT pg_sleep(10); and verifying that the instance keeps on running.

Note

If you’d like to use a port other than 5432/tls you’ll need to use the kraft cloud tunnel command to connect to PostgreSQL. See the tunneling guide for more information. In addition, you need to explicitly disable scale-to-zero by either changing the label in the Kraftfile or use --scale-to-zero off in the deploy command.

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

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:

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:

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

Then start the PostgreSQL instance and mount that volume:

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.

Note

Support for scale-to-zero for internal instances is coming soon.

Learn More

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

kraft cloud --help

Or visit the CLI Reference.