Short answer: set the Prefect server’s database URL via the

PREFECT_SERVER_DATABASE_CONNECTION_URL

environment variable inside your container. Use an async SQLAlchemy DSN with the asyncpg driver, e.g.

<postgresql+asyncpg://user:password@host:5432/dbname>

. Ensure the container can reach your Postgres host and that

asyncpg

is installed in the image. Example with docker run (same Docker network as Postgres):

# Network and Postgres
docker network create prefect-net
docker run -d --name pg --network prefect-net \
  -e POSTGRES_USER=prefect \
  -e POSTGRES_PASSWORD=prefect \
  -e POSTGRES_DB=prefect \
  -p 5432:5432 \
  postgres:16

# Prefect server pointing at Postgres
docker run -d --name prefect-server --network prefect-net \
  -p 4200:4200 \
  -e PREFECT_SERVER_DATABASE_CONNECTION_URL=<postgresql+asyncpg://prefect:prefect@pg:5432/prefect> \
  prefecthq/prefect:3.4.22 \
  prefect server start --host 0.0.0.0 --port 4200

Example docker-compose.yml:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: prefect
      POSTGRES_PASSWORD: prefect
      POSTGRES_DB: prefect
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  prefect:
    image: prefecthq/prefect:3.4.22
    depends_on:
      - postgres
    environment:
      PREFECT_SERVER_DATABASE_CONNECTION_URL: <postgresql+asyncpg://prefect:prefect@postgres:5432/prefect>
      PREFECT_UI_ENABLED: "true"
    command: ["prefect", "server", "start", "--host", "0.0.0.0", "--port", "4200"]
    ports:
      - "4200:4200"

volumes:
  pgdata:

Notes and tips: - Using Prefect 3.x,

PREFECT_SERVER_DATABASE_CONNECTION_URL

is the setting you want. Use the async DSN scheme

postgresql+asyncpg://...

. - The Prefect server will initialize/migrate the database on startup. If you prefer to run migrations manually (or CI/CD), you can run:

prefect server database upgrade

- If your Postgres is running on your Mac host (not in Docker), from a Mac Docker container you can connect via `host.docker.internal`:

PREFECT_SERVER_DATABASE_CONNECTION_URL=<postgresql+asyncpg://user:pass@host.docker.internal:5432/dbname>

- Make sure the image has the

asyncpg

driver installed. The official images typically include what’s needed; if you build your own image, add:

pip install asyncpg

- Switching from SQLite to Postgres will give you a new, empty Prefect database. There isn’t an automated cross-dialect migration of existing data; plan to recreate blocks/deployments or backfill as needed. References: - Self-hosted with Docker and Docker Compose - Database CLI commands (upgrade/reset/stamp)