Skip to main content

Database Component

Create a database Component in Project Manifest

The easiest way to create a database Component is to use a plain preconfigured Docker image.

An example with PostgreSQL could use the image 'postgres:16.2' and look like this:

version: v1

components:
- name: my-db-component
docker:
image: postgres:16.2
resources:
cpu: 500m
memory: 2Gi

Note, how we refer to the standard image in the 'docker' - property.

This is a runnable configuration, but it is so far not even accessible.

Allow access

To allow other Components access to this database, you have to open the corresponding port. For PostgreSQL, the standard port is 5432. You need to specify the port by adding a 'ports' property to your pergola.yaml:

[...]
ports:
- 5432

For reference please see Ports in Project Manifest.

Configure database

Usually, database docker images come with a variety of config options. As an absolute minimum, one should override the standard password.

In case of the PostgreSQL docker image, this is done by defining an environment variable with a config-ref in pergola.yaml like this:

[...]
env:
- name: POSTGRES_PASSWORD
config-ref: my_postgres_pwd

Note how we use a config - reference to the config key my_postgres_pwd. The value of my_postgres_pwd can be set per Stage and accessed by other Components as well.

For reference, please see Environment variables in Project Manifest and Configuration Management.

Provide storage

A database needs a persistent storage to store its data to. Add a storage property to your pergola.yaml and make sure to mount the volume to the path your database uses to store data.

[...]
storage:
- name: pgdata
path: /var/lib/postgresql/data
size: 50Gi

Note: You can run the database Component without specifying persistent storage, but it will lose all data after restart. For testing purpose, this might suffice or even be beneficial.

Final pergola.yaml

Putting it all together, a fully working pergola.yaml could look like this:

version: v1

components:
- name: my-db-component
docker:
image: postgres:16.2
resources:
cpu: 500m
memory: 2Gi
ports:
- 5432
env:
- name: POSTGRES_PASSWORD
config-ref: my_postgres_pwd
storage:
- name: pgdata
path: /var/lib/postgresql/data
size: 50Gi

For full reference of pergola.yaml please see Project Manifest.

How to use the database

To start using your database Component, you need to have another Component (e.g. a web application) that connects to it.

This topic is covered in Linking Components