KodeKloud Notes

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

Warning

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:

Environment	Description	Example Command
Local (Docker)	Run a container on your machine	`docker run -d --name backstage-pg -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:13`
AWS RDS	Managed PostgreSQL in AWS	Create via AWS Console or `aws rds create-db-instance ...`
GCP Cloud SQL	Google-managed SQL service	Provision with Cloud Console or `gcloud sql instances create ...`
Azure Database for PostgreSQL	Azure-managed service	Provision 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

Note

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.

Links and References

Watch Video