Example apps

Serverless Databases: PostgreSQL

Serverless databases scale up the moment a query arrives and cost nothing while idle, instead of keeping a provisioned instance running around the clock.

This guide shows you how to use PostgreSQL, a powerful, open source object-relational database system, in exactly that fashion. The database runs in a lightweight virtual machine that scales to zero when not in use and resumes in milliseconds on the next connection.

To run it, follow these steps:

Install the unikraft CLI. You need a BuildKit builder. The easiest way to get one is via Docker. Alternatively, you can also directly set up and use BuildKit, see the quick start.

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

Code
git clone https://github.com/unikraft-cloud/examples
cd examples/postgres/

Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

Code
unikraft login

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

Code
unikraft build . --output <my-org>/postgres:latest
unikraft run --metro fra \
  -m 1G \
  -p 5432:5432/tls \
  --scale-to-zero policy=idle,cooldown-time=1000,stateful=true \
  -e POSTGRES_PASSWORD=unikraft \
  --image <my-org>/postgres:latest

The output shows the instance address and other details:

Code
metro:        fra
name:         postgres-saan9
uuid:         3a1371f2-68c6-4187-84f8-c080f2b028ca
state:        starting
image:        <my-org>/postgres
resources:
  memory:     1024MiB
  vcpus:      1
service:
  uuid:       8e9d810b-b1da-a30b-fd42-5c30c1900cb5
  name:       young-thunder-fbafrsxj
  domains:
  - fqdn:     young-thunder-fbafrsxj.fra.unikraft.app
networks:
- uuid:       f1fab4c9-7951-75e3-ea1c-d87e47b4c9e2
  private-ip: 10.0.3.1
  mac:        12:b0:31:34:b1:96
timestamps:
  created:    just now

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
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.

This example uses the idle scale-to-zero policy by default. It means that the instance will scale-to-zero even in the presence of psql connections.

The PostgreSQL example makes use of scale-to-zero app support. This ensures that the instance isn't put into standby even for long running queries (during which the connections are also idle). To this end, the example loads 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.

You can list information about the instance by running:

Code
unikraft instances list

Code
METRO  NAME            STATE    IMAGE              ARGS  MEMORY  VCPUS  FQDN                                     CREATED
fra    postgres-saan9  running  <my-org>/postgres        1.0GiB  1      young-thunder-fbafrsxj.fra.unikraft.app  2 minutes ago

When done, you can remove the instance:

Code
unikraft instance remove postgres-saan9

Using volumes

You can use volumes for data persistence for your PostgreSQL instance. For that you would first create a volume:

Code
unikraft volume create --set metro=fra --set name=postgres --set size=200M

Then start the PostgreSQL instance and mount that volume:

Code
unikraft build . --output <my-org>/postgres:latest
unikraft run --metro fra \
  -m 1G \
  -p 5432:5432/tls \
  --scale-to-zero policy=idle,cooldown-time=1000,stateful=true \
  -e POSTGRES_PASSWORD=unikraft \
  -e PGDATA=/volume/postgres \
  --volume postgres:/volume \
  --image <my-org>/postgres:latest

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 use 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.

Learn more

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

Code
unikraft --help

Or visit the CLI Reference.

Edit this page

Last modified on October 5, 2026

Sandboxes: OpenClaw Serverless Functions: Node.js Code Execution with ROMs