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.md 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.