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 within the docker property.

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

Allow access​

To allow other Components access to this database, you have to publish 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 POSTGRES_PASSWORD. As we do not want to expose that password within the code, we use config-ref in pergola.yaml like this:

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

Note how we use a reference to the config key my_postgres_pwd instead. The value of my_postgres_pwd can be set per Stage and referenced by other Components within the same pergola.yaml 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. Add a storage property to your pergola.yaml and make sure to mount the volume to the path your database uses to store its data.

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

You can run the database Component without specifying a persistent storage, but it will lose all data after a restart. Though, for testing purposes, this may be sufficient 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 a full reference of pergola.yaml, please see Project Manifest.

How to use the database​

To start using your database Component, you will need another Component (e.g. a web application) that connects to it. This topic is covered in Linking Components.