Skip to content

Service: PostgreSQL

Jump to bottom
Claude Agent edited this page Nov 3, 2026 · 3 revisions

Getting Started

PostgreSQL is the world's most advanced open source relational database, trusted for reliability, feature robustness, and performance. Available as an open web service in Eyevinn Open Source Cloud, you can spin up a PostgreSQL instance in seconds and use it as the database backend for your applications, analytics tools, or OSC services that require a relational database.

Storage: up to 20 GiB per instance.

Prerequisites

Step 1: Store the password as a secret

It is good practice to store your database password as a service secret so you can reference it safely in other services. Navigate to the PostgreSQL service page, go to the Service Secrets tab, and click New Secret. Enter a name such as postgrespwd and a strong password as the value.

Step 2: Create a PostgreSQL instance

Go to the My osc-postgresqls tab and click Create osc-postgresql. Fill in:

  • Name: a unique name for your instance (alphanumeric only, e.g. mydb)
  • PostgresPassword: {{secrets.postgrespwd}} (references the secret created in Step 1)
  • PostgresUser (optional): superuser username, defaults to postgres
  • PostgresDb (optional): default database name, defaults to the username if not set

Click Create and wait for the status indicator to turn green.

Step 3: Connect to your database

Once the instance is running, click it to see the connection details including the IP address and port. Connect using any PostgreSQL client:

psql "postgres://postgres:<password>@<IP>:<PORT>/postgres"

Or use the connection URL in your application:

DATABASE_URL=postgres://postgres:<password>@<IP>:<PORT>/postgres

Changing the password

PostgresPassword sets the superuser password only when the instance first creates its database. After that the password lives in the database. Changing the service secret, or restarting the instance, does not change it. This follows the upstream image behavior: the Docker Hub postgres page states that "the Docker specific variables will only have an effect if you start the container with a data directory that is empty".

Updating a service secret does not restart or reconfigure running instances either. A service reads its secret values when it starts.

To rotate the password:

  1. Connect with the current password.
  2. Run \password postgres in psql, using your PostgresUser instead of postgres if you set one. psql prompts for the new password twice and sends it as a hash, so the new password is not written to the server log.
  3. Immediately update the service secret (for example postgrespwd) to the same new value. The PostgreSQL instance needs no restart.

The secret must be updated too because backups connect with the current value of the secret that PostgresPassword references. When it differs from the real password, backups fail with an authentication error.

Any other service secret that embeds this password, such as the connection URLs described in "Using PostgreSQL with other OSC services", must be updated as well, and that service restarted so it reads the new value.

A secret name used by several instances is shared, so changing it changes what backups of every instance referencing it use. Use one secret per instance, or rotate all of them together.

Stored secret values cannot be read back. Keep the old value until the rotation is finished.

Using PostgreSQL with other OSC services

Many OSC services (Umami, Ghost, Formbricks, PostgREST, and others) accept a PostgreSQL connection URL. After creating your instance, store the full connection URL as a service secret on the target service and reference it with {{secrets.name}}.

CLI usage

osc create birme-osc-postgresql mydb \
  -o PostgresPassword="{{secrets.postgrespwd}}" \
  -o PostgresUser="postgres" \
  -o PostgresDb="myapp"

Resources

Clone this wiki locally