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, for example Docker.

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

Code(bash)
 
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. This guide uses fra (Frankfurt, 🇩🇪):

Code(bash)
 
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra

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

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

The output shows the instance address and other details:

Code(ansi)
 
[●] Deployed successfully!
 │
 ├────────── name: postgres-saan9
 ├────────── uuid: 3a1371f2-68c6-4187-84f8-c080f2b028ca
 ├───────── state: starting
 ├────────── fqdn: young-thunder-fbafrsxj.fra.unikraft.app
 ├───────── 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're different for each run.

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

Code
 
psql -U postgres -h young-thunder-fbafrsxj.fra.unikraft.app

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

Code(ansi)
 
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.

You can list information about the instance by running:

Code(bash)
 
kraft cloud instance list

Code(text)
 
NAME            FQDN                                     STATE    CREATED AT     IMAGE                                   MEMORY   ARGS                                      BOOT TIME
postgres-saan9  young-thunder-fbafrsxj.fra.unikraft.app  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(bash)
 
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 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 extra configuration options.

You can use the PostgreSQL instance in conjunction with a frontend service, see the guide here. But 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(bash)
 
kraft cloud --help

Or visit the CLI Reference.