Guides

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:

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

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

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

The output shows the instance URL and other details:

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

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

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

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

Code
 
kraft cloud instance list

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

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

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

Then start the PostgreSQL instance and mount that volume:

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

Code
 
kraft cloud --help

Or visit the CLI Reference.