PostgreSQL
This guide shows you how to use PostgreSQL, a powerful, open source object-relational database system.
To run it, follow these steps:
- Install the CLI. Use the unikraft CLI or the legacy kraft 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.
The unikraft CLI is the current standard, while kraft is the legacy version. Choose one of the CLIs below and only run the commands associated with it for the rest of this guide.
- Clone the
examplesrepository andcdinto theexamples/postgres/directory:
Code
Make sure to log into Unikraft Cloud and pick a metro close to you.
This guide uses fra (Frankfurt, 🇩🇪):
When done, invoke the following command to deploy this app on Unikraft Cloud:
The output shows the instance address and other details:
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
Use the unikraft password at the password prompt.
You should see output like:
Code
Use SQL and psql commands for your work.
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 isn't put into standby even for long running queries
(during which the connections are also idle).
The PostgreSQL example makes use of scale-to-zero app support.
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.
If you'd like to use a port other than 5432/tls you'll need to use the socat command to connect to PostgreSQL.
See the MariaDB example for a guide on how to use it.
Additionally, 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.
You can list information about the instance by running:
When done, you can remove the instance:
Using volumes
You can use volumes for data persistence for your PostgreSQL instance. For that you would first create a volume:
Then start the PostgreSQL instance and mount that volume:
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.
Support for scale-to-zero for internal instances is coming soon.
Learn more
Use the --help option for detailed information on using Unikraft Cloud:
Or visit the CLI Reference or the legacy CLI Reference.