Skip to main content
By default, Backstage uses an in-memory database that resets on every restart—ideal for demos and local testing but unsuitable for production workloads. Switching to PostgreSQL provides persistent storage for all your catalog entities, ensuring data remains intact across restarts and upgrades.
The image compares data management in development and production environments, showing an in-memory database for development (temporary, lost on restart) and a Postgres database for production (persistent storage).
If you continue using the default in-memory database in production, all of your tracked applications and metadata will be lost whenever the Backstage instance restarts.

​
1. Provision a PostgreSQL Instance

You can provision PostgreSQL in several environments:
EnvironmentDescriptionExample Command
Local (Docker)Run a container on your machinedocker run -d --name backstage-pg -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:13
AWS RDSManaged PostgreSQL in AWSCreate via AWS Console or aws rds create-db-instance ...
GCP Cloud SQLGoogle-managed SQL serviceProvision with Cloud Console or gcloud sql instances create ...
Azure Database for PostgreSQLAzure-managed serviceProvision via Azure Portal or az postgres flexible-server create ...
After deployment, note the following connection details:
  • Host
  • Port (default: 5432)
  • Database name
  • Username
  • Password

​
2. Configure app-config.yaml

Update your Backstage configuration to use the PostgreSQL client. In app-config.yaml, replace the in-memory settings under backend.database with your PostgreSQL credentials: 
backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: ${POSTGRES_DB}
Field reference:
  • host: Hostname or IP address of the PostgreSQL server
  • port: TCP port (default 5432)
  • user: Database user with read/write permissions
  • password: Password for the specified user
  • database: Name of the target PostgreSQL database
Using environment variables keeps sensitive data out of your config file and allows you to manage credentials securely with tools like Vault.

​
3. Set Environment Variables

Before starting Backstage, export the connection parameters: 
export POSTGRES_HOST=your-postgres-host
export POSTGRES_PORT=5432
export POSTGRES_USER=backstage_user
export POSTGRES_PASSWORD=secretpassword
export POSTGRES_DB=backstage
Ensure these variables are loaded in your shell or container environment.

​
4. Launch Backstage

With configuration and environment variables in place, start the Backstage backend: 
yarn workspace backend start
Backstage will now connect to PostgreSQL, persisting all your catalog metadata and application data.

Watch Video