Accessing a Parallel Environment Database

How to connect to a database running in a parallel-services environment, whether it's running locally under Docker Compose or on AWS (EKS). See the Parallel services guide for the model.

Credentials and the database name come from the compose service's own environment (e.g. POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB, or the ${VAR} secrets resolved from your .env). Substitute your service's values for ‹user› / ‹password› / ‹db› below.

Managed database (the postgres default). With the durable-storage feature, a postgres service defaults to a platform-managed database on RDS, not an in-cluster pod — so it is not in the wbsp-svc-‹tenant›-‹env› namespace and the port-forward below does not apply to it. The app reaches it via the injected ‹SERVICE›_DB_HOST/_PORT/_NAME/_USER + ‹SERVICE›_DB_PASSWORD env. To connect directly, use the platform RDS connection (see the operator's RDS access in useful-commands.md). The steps below apply to a postgres run in-namespace (storage: persistent / run_parallel) or any other in-cluster datastore.

Locally (Docker Compose)

When you run the app's docker-compose services on your machine, the database is reachable on the host port the compose file maps to its container port (5432). For a ports: ["5433:5432"] mapping:

PGPASSWORD=‹password› psql -h localhost -p 5433 -U ‹user› -d ‹db›

A GUI client (TablePlus, DBeaver, pgAdmin, …) can connect to localhost:5433.

On AWS (parallel namespace)

On AWS the database runs in the isolated namespace wbsp-svc-‹tenant›-‹env› and is internal-only (no public endpoint; reachable only by the allow-listed apps). Port-forward the cluster service to a local port — this tunnels through the Kubernetes API server, so the NetworkPolicy does not block it:

export AWS_PROFILE=<profile>
aws eks update-kubeconfig --name <cluster> --region <region>   # once

kubectl -n wbsp-svc-‹tenant›-‹env› port-forward svc/‹db-service› 5544:5432

Then, in another shell:

PGPASSWORD=‹password› psql -h localhost -p 5544 -U ‹user› -d ‹db›

A GUI client can connect to localhost:5544 while the port-forward is running.

Applying a schema / migrations

Point your migration tool at whichever database your connection variables resolve to. For example, with Prisma through the AWS port-forward above:

POSTGRES_HOST=localhost POSTGRES_PORT=5544 \
POSTGRES_USER=‹user› POSTGRES_PASSWORD=‹password› POSTGRES_DB=‹db› \
  npx prisma migrate deploy

Re-run after a restart with ephemeral storage. If the environment definition sets ephemeral_storage: true, the database data — including any migrated schema — is lost when the pod restarts. Re-apply the schema to restore it.