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
cd examples/postgres/

Make sure to log into KraftCloud by setting your token and a metro close to you. We use fra0 (Frankfurt, πŸ‡©πŸ‡ͺ) in this guide:

Terminal window
# Set KraftCloud access token
# Set metro to Frankfurt, DE

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

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:
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€ image: postgres@sha256:2476c0373d663d7604def7c35ffcb4ed4de8ab231309b4f20104b84f31570766
β”œβ”€β”€β”€β”€β”€β”€β”€β”€ memory: 1024 MiB
β”œβ”€ service group: young-thunder-fbafrsxj
β”œβ”€β”€ private fqdn: postgres-saan9.internal
β”œβ”€β”€β”€β”€ private ip:
└────────── args: postgres

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

To test the deployment, first forward the port with the kraft cloud tunnel command. Be sure to use the service group returned by the kraft cloud deploy command:

Terminal window
kraft cloud tunnel young-thunder-fbafrsxj 5432:5432

Now, on a separate console, you can query PostgreSQL using psql. We assume the username is postgres and the password is unikraft:

Terminal window
psql -U postgres -h localhost

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.

Use SQL and psql commands for your work.

To disconnect, simply kill the tunnel command with ctrl-C

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

Terminal window
kraft cloud instance list
postgres-saan9 running 6 minutes ago 1.0 GiB 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 use a different port or a different location to mount your volume.

And, of course, you can use the PostgreSQL instance in conjunction with a frontend service, see the guide here.

Learn More

Use the --help option for detailed information on using KraftCloud:

Terminal window
kraft cloud --help

Or visit the CLI Reference.