Skip to main content
In this lesson we cover how to configure Backstage to use a persistent PostgreSQL database instead of the default ephemeral stores used in many local or development setups. By default Backstage often runs with an in-memory database (or a local SQLite file in some templates). That means any entities or state you create while Backstage runs are temporary — they are lost when the process stops or restarts. For production and long-lived environments, use a persistent database such as Postgres to retain entities, settings, and application state across restarts.
A slide titled "Managing Data in Backstage" comparing two environments: a Development Environment using an in-memory database (stacked server icon) and a Production Environment using a Postgres database (elephant logo). The slide notes the in-memory DB is temporary and lost on restart, while Postgres provides persistent storage.
Overview — steps to configure Backstage with Postgres:
  1. Provision a Postgres instance (local container, Docker Compose, or a managed cloud database).
  2. Update Backstage’s app-config.yaml to point to the Postgres instance.
  3. Initialize the database schema by running Backstage database migrations.
  4. Start Backstage with the environment variables or configuration in place so it can connect to Postgres.
Configuration example Add a backend.database section under your backend configuration in app-config.yaml. This tells Backstage to use the pg client (node-postgres) and to read connection details from environment variables:
Common connection options explained: You can supply a single connection string instead of individual fields:
Or use an environment variable for the connection string:
After configuring the connection, run Backstage’s database migrations to create required tables and schemas. The exact migration command depends on your repository (check package.json scripts or README). Run migrations before starting Backstage in production to avoid runtime schema errors.
Best practices and operational notes
  • Use strong credentials and store them in a secrets manager or environment variables — do not commit credentials to source control.
  • Restrict network access to the database (VPCs, security groups, or private networks).
  • Enable SSL/TLS for connections when using remote or managed Postgres services.
  • Regularly back up your Postgres data and test restore procedures.
  • For production, prefer a managed or highly available Postgres offering (for example, AWS RDS, Google Cloud SQL, or a clustered deployment).
Do not run production Backstage against an ephemeral or in-memory database. Data loss can occur on process restarts. Also ensure your migration strategy is part of your deployment pipeline to avoid schema drift.
Quick reference — example environment variable names Links and references With the database configured and migrations applied, Backstage will persist entities and other state to Postgres instead of using an ephemeral in-memory store.

Watch Video