Postgres

You might consider a managed Postgres for your application.

This page shows how to self-host it as a service.

Isolating the Database Layer

The database in SuperStack isn’t bundled inside the main app/ stack. Instead, it lives in its own directory — db/ — and is started separately.

By isolating the database layer, you gain several benefits:

• Avoid data corruption
• Run multiple app stacks safely
• Upgrade and experiment freely
• Cleaner separation of concerns

In short — keep your data persistent and your app stacks disposable. The db/ project handles the durable data, while each app/ project can come and go freely.

1. Add the Postgres Service

From the root of the repository, create a db directory:

mkdir db

Create a Compose file:

db/compose.yaml

name: myapp-db

services:
  postgres:
    image: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data:rw
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
      POSTGRES_DB: ${POSTGRES_DB:?}
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}", "-d", "app"]
      interval: 0.5s
      timeout: 3s
      retries: 10

volumes:
  postgres_data:

Optionally, increase healtcheck intervals in development:

db/compose.override.yaml

services:
  postgres:
    # Set faster healthcheck intervals for the development server
    healthcheck:
      interval: 0.5s
      timeout: 1s
      retries: 10

Add an environment file:

db/.env

POSTGRES_USER=admin
POSTGRES_PASSWORD=pass
POSTGRES_DB=app

2. Start Postgres

From the db/ directory:

docker compose up -d

3. Connect to Postgres in your application

In your app, connect to the db network in services that need it:

app/compose.yaml

services:
  # Add db_default network to services that need db access
  postgrest:
    networks:
      - default
      - myapp-db_default

networks:
  myapp-db_default:
    external: true

See also:

• Configure Psql – Customize psql for interacting with Postgres
• Convenience Script – Add a convenience script for interacing with PG
• Postgres Extensions – Add Extensions
• Postgres Migrations – Add a simple migrations system
• PostgREST – Add a REST API to Postgres