Add a database

This guide adds a PostgreSQL database to a landscape and hands its address to your app. Harthelm creates the database at the Sync, keeps its password in the workspace's vault and dumps it every night.

Add the managed serviceCopy Anchor Link

Add a managed service next to your app, and give the app the database's address:

schema: harthelm/v1

services:
  db:
    type: managed
    provider: postgres
    config:
      postgresVersion: "18"
      database: app
      user: app
    secrets:
      password: ${{ secrets.DB_PASSWORD }}

  web:
    type: steps
    steps: [{run: npm start}]
    needs: [db]
    env:
      DATABASE_URL: ${{ services.db.dsn }}
    ports:
      - port: 3000
        routes: [{path: /}]

• provider: postgres is the built-in PostgreSQL. The console's Managed services → Catalog shows what else your installation offers: MariaDB, Valkey, RabbitMQ and S3 object storage are built in (Managed services).
• config sets the version ("18" or "17"; it cannot change later), the database and the user.
• secrets.password names a vault key. The password itself never goes into the file.
• ${{ services.db.dsn }} becomes postgresql://app:<password>@<host>:5432/app when web starts.

Sync and give it a passwordCopy Anchor Link

The database is ready in about a minute; its row in the Run panel shows "Managed service: Synchronized". Run or restart web so it picks up DATABASE_URL.

Other ways to connectCopy Anchor Link

For libraries that read the PG* variables:

    env:
      PGHOST: ${{ services.db.host }}
      PGPORT: ${{ services.db.port }}
      PGDATABASE: app
      PGUSER: app
      PGPASSWORD: ${{ services.db.secret }}

${{ services.db.secret }} follows a password rotation by itself; ${{ secrets.DB_PASSWORD }} keeps the value of your last Sync until you sync again.

Size and storageCopy Anchor Link

  db:
    type: managed
    provider: postgres
    plan: small
    resources:
      storage: 2Gi

plan is tiny (the default: 0.25 vCPU, 256 MiB, 1 GiB) or small (0.5 vCPU, 512 MiB, 5 GiB). resources changes what the plan lets you change. Sizes are MiB as a number, or 2048Mi, 2Gi, 1.5Gi; decimal units like 2GB are refused. Storage can only grow, and only where your installation's storage class can grow volumes: otherwise the Sync refuses a plan that needs more storage with update-constraint.

Rotate the passwordCopy Anchor Link

Open the database in Managed services and click Rotate under Secrets. Harthelm generates a new value, stores it in the vault, and the services that read the connection restart with it.

Pause, resume and deleteCopy Anchor Link

• Teardown pauses the database; the data stays. The next Sync resumes it.
• Removing or renaming the service in harthelm.yml deletes the database and its data at the next Sync; the review warns first.

BackupsCopy Anchor Link

The database is dumped every night (backups: true is the default). The details drawer in Managed services shows the last dump and has Dump now.

MariaDB insteadCopy Anchor Link

A MariaDB works the same way, with provider: mariadb Since 1.3.0:

  db:
    type: managed
    provider: mariadb
    config:
      mariadbVersion: "11.8"
      database: shop
      user: shop
    secrets:
      password: ${{ secrets.DB_PASSWORD }}

${{ services.db.dsn }} is then mysql://shop:<password>@<host>:3306/shop, and ${{ services.db.details.jdbcUrl }} the JDBC URL without credentials. mariadbVersion is "12.3", "11.8" (the default) or "11.4". You can move to a newer series later by changing it; the server is upgraded in place and cannot go back, so click Dump now first.

Next stepsCopy Anchor Link