Why running Backstage on PostgreSQL in production needs its own plan
Backstage needs a production database plan as soon as the portal stops being a single developer's sandbox. The architecture overview names PostgreSQL as the production database and SQLite as the development option, and Backstage gives each backend plugin its own logical database through Knex. In practice, the catalog, scaffolder and plugin state all live in PostgreSQL, so the database becomes the place where your portal's data is actually held. Choosing how that database is run, backed up and upgraded is a decision about the portal itself, not a detail to settle after the Helm chart is written.
That choice shapes four things at once. Backups decide what you can restore after a bad catalog import or an accidental deletion. Failover decides how long sign-in and template runs stay unavailable when a node fails. Upgrade planning decides which PostgreSQL major version you run and when you move off it. Search adds its own constraint: the search plugin needs a PostgreSQL version that the Backstage documentation specifies, so the version you pick today must satisfy both the portal and the support window of your database. Confirm the current minimum version in the search plugin documentation for your Backstage release before you fix a database version.
You need this plan once more than one backend replica reads the same database, when several teams depend on a shared catalog, or when an auditor asks you to show that the portal's data can be recovered within a stated objective. At that point, ask your team to confirm the recovery requirements in writing, the managed or operator option, the replication mode, and who performs major upgrades. Treat the database as part of the portal's change record, because every later decision in this topic depends on it.
Choosing between managed PostgreSQL and an in-cluster operator
A managed PostgreSQL service moves most database operations to the cloud provider. The provider runs the instances, applies patches, takes backups and handles hardware replacement, while your team owns schemas, roles, parameters and the Backstage connection settings. For a Backstage deployment this often means one fewer stateful system inside your cluster, but it also means your recovery options are bounded by what the provider exposes.
- Failover: Ask whether failover is automatic, how long the provider states it takes, and whether it is within a single zone or across zones.
- Backups and restore: Confirm retention period, whether point-in-time recovery is included, and whether you can restore to a new instance for testing.
- Upgrades: Ask who schedules minor and major version upgrades, whether you can defer them, and how long the provider supports each major version.
- Cost drivers: Instance size, storage, backup retention, cross-zone replicas and network egress usually recur monthly, so request an itemized quote for each.
- Data location: Confirm the region and whether the service runs in an account and network you control.
Before you commit, confirm each item in writing with the provider and check it against your own recovery time and data-loss requirements.",
CloudNativePG is an Apache-2.0 operator that runs PostgreSQL inside your Kubernetes cluster. It manages persistent volume claims directly rather than through StatefulSets, and it integrates with the Kubernetes API server to perform failover without an external tool such as Patroni. Your team gets declarative cluster definitions and keeps the database in infrastructure you control, but the operator becomes a platform component your team must monitor, upgrade and understand.
- Failover: The operator promotes a standby through the Kubernetes API. It also supports quorum-based failover and synchronous replication, which you must configure and test.
- Backups: Object storage backups use the Barman Cloud plugin, volume snapshots are supported, and WAL archiving enables point-in-time recovery. Your team owns the bucket, credentials and restore drills.
- Upgrades: The operator manages supported PostgreSQL versions, but your team still plans the rollout, the Kubernetes version compatibility and the operator upgrade itself.
- Connection pooling: Built-in PgBouncer pooling is available, which affects how Backstage connections are counted against limits.
- Cost drivers: Node capacity, storage classes, object storage and the engineering time to run the operator usually dominate.
Confirm with your platform team which operator release line you will follow and whether your Kubernetes distribution is on the operator's supported list.",
Self-run PostgreSQL on virtual machines or bare metal, with Patroni coordinating high availability, gives you full control over the database host, the distributed configuration store and the failover policy. Patroni is MIT licensed and runs PostgreSQL 9.3 to 18. It needs a distributed configuration store such as etcd, Consul, ZooKeeper or Kubernetes, so the coordination layer becomes another service to run. PostgreSQL itself does not detect a failed primary or notify a standby, so this external tooling is required for automatic failover.
- Failover: Patroni handles leader election and promotion using the configuration store. Your team must test fencing and split-brain behavior.
- Backups: Backup tooling, retention, storage and restore testing are all yours to select and operate.
- Upgrades: Minor updates replace executables and restart, while major upgrades use pg_upgrade, dump and restore, or logical replication. Each path needs a rehearsed runbook.
- Skills: Expect the team to need PostgreSQL, Patroni and configuration store expertise on call.
- Cost drivers: Hardware or virtual machine capacity, the configuration store cluster, backup storage and staff time recur, and the staff time is often the largest line.
Confirm which Patroni release line you will track and who owns the on-call rotation before you select this model.",
Connection, database and deployment options and when each fits
This table compares the main database layouts for Backstage, from one shared server with per-plugin databases to in-cluster operators and managed services. Read each row against your team's operating skills, your availability target and the upgrade calendar you can commit to. The main takeaway is that the cheapest layout to start with is rarely the cheapest to run through failover, backups and major upgrades.
| Option | When it fits | Operations cost and what to confirm |
|---|---|---|
| One server with per-plugin logical databases | Single Backstage instance with a modest catalog and a team that wants the simplest layout | One database to back up, patch and upgrade. Backstage creates one logical database per backend plugin through Knex, so confirm the role can create and access them. |
| Separate clusters per plugin or per environment | Teams that need different maintenance windows, storage or access boundaries per plugin | Multiplies backup, patch and failover work. Confirm each cluster has its own recovery test and monitoring. |
| Synchronous replication | Recovery targets where a committed catalog or scaffolder write must survive loss of the primary | Commits wait for standbys, so write latency rises and a standby outage can block writes. Confirm the standby count and behavior when one is unavailable. |
| Asynchronous replication | Read scaling or a warm standby where a small window of lost commits is acceptable | Faster commits, but failover can lose recent writes. Confirm the acceptable loss window with the platform owner before choosing it. |
| PgBouncer connection pooling | Several Backstage replicas or backend deployments that open many connections to one server | An extra component to run and monitor. Confirm pool mode and connection limits against the Backstage pool settings in your configuration. |
| SSL and credentials handling | Any deployment where database traffic crosses a network segment you do not fully control | Certificate issuance, rotation and secret delivery recur. Confirm your client authentication method matches your PostgreSQL version and security policy. |
| CloudNativePG operator | Kubernetes-based teams that want PostgreSQL managed as Kubernetes resources with built-in failover | Requires Kubernetes operator skills and recurring operator upgrades. Failover uses the Kubernetes API server, so confirm your cluster design supports it. |
| Patroni with a distributed configuration store | Teams running PostgreSQL on virtual machines that need automated failover with an existing etcd, Consul or ZooKeeper service | Adds a configuration store to operate alongside PostgreSQL. Confirm which store your team already runs and who owns its upgrades. |
| Managed PostgreSQL service | Teams that prefer the provider to handle patching, backups and failover within the provider's options | Recurring provider fees and less control over versions and extensions. Ask the provider for its supported PostgreSQL versions, backup retention and failover behavior in writing. |
How per-plugin logical databases change backup and restore
Backstage gives each backend plugin its own logical database through Knex, so catalog, scaffolder, auth and search state are separate units. That separation is useful for recovery: a team can restore one plugin's data after a bad write or a failed migration without rolling back the others. It also means a backup is no longer a single database dump. Before relying on this, confirm which plugins are enabled in your app-config.yaml and backend setup, because each enabled plugin adds a database you must include in backup jobs, retention rules and restore runbooks. A plugin you forgot to list is a plugin you may not be able to recover.
The same design multiplies operational load. Every plugin database adds to the connection count the backend opens, and each plugin's credentials add to the set your team must rotate, store and scope. Managed PostgreSQL services and in-cluster operators both need these connection and role settings reviewed as the portal grows. Ask whether your platform's connection limits and connection pooler configuration still hold after you add plugins, and whether each database role has only the privileges its plugin needs. Keep an inventory of databases, owners and roles so that a credential change or a new plugin does not break restore paths unnoticed.
Test restores per database, not only once for the cluster. Restore each plugin database into a scratch instance, start a Backstage backend against it, and check that the catalog loads, scaffolder tasks are visible and sign-in still resolves to the expected identities. Repeat this after every plugin change and after each PostgreSQL minor update. Record the restore order you used, since some plugin data may depend on catalog entities being present. If you rely on a managed service's point-in-time recovery, confirm with the provider whether it restores all databases in an instance to one consistent time or lets you restore individual databases, because that answer decides how you handle a single-plugin incident.
Setup sequence for a production Backstage database
This sequence takes a PostgreSQL instance from a version decision to a documented, tested database that Backstage plugins can use with separate logical databases, backups and recovery.
Confirm the supported PostgreSQL major version
Check the PostgreSQL versioning policy before choosing a major version, because the supported windows differ by release. PostgreSQL 18 is supported until November 14, 2030, while 14 is supported until November 12, 2026, so a new deployment should start on a version with a long remaining window. Record the chosen version and its end-of-support date in the runbook. Done when the platform owner signs off on the version and the date is written down.
Pick the operator or managed service
Decide between a managed PostgreSQL service in your cloud account and an in-cluster operator such as CloudNativePG, which manages persistent volume claims directly, integrates with the Kubernetes API for failover, and includes PgBouncer pooling. Compare who patches the database, who holds the backup keys, how failover is triggered and what each option costs in your environment. Ask vendors to confirm backup, PITR and failover behavior in writing. Done when the choice and its owner are recorded.
Provision roles and per-plugin databases
Create one login role for Backstage with the minimum privileges it needs, then create a separate logical database for each backend plugin that uses PostgreSQL, since Backstage gives each plugin its own database through Knex. Use strong, generated passwords, and set the authentication method to SCRAM rather than the deprecated MD5 option. Check that the role can connect to each plugin database and cannot read the others. Done when a connection test succeeds for every database and the access check fails for a cross-database query.
Set Backstage connection settings
Add the PostgreSQL host, port, database and credential references to the backend configuration, and inject the password from a Kubernetes Secret or your secrets manager instead of the image or a committed file. Set connection pool limits so the total across replicas stays below the server's connection capacity, and enable TLS if the database is reached over a network. Confirm the settings in a non-production environment by starting the backend and loading the catalog. Done when the backend starts cleanly and logs show successful database migrations.
Enable backups and WAL archiving
Configure base backups and continuous WAL archiving so you can restore to a point in time. With CloudNativePG this means object storage backups through the Barman Cloud plugin or volume snapshots, plus WAL archiving; with a managed service, enable its point-in-time recovery feature. Set retention to match your recovery requirements and store backups outside the cluster that runs the database. Done when a backup completes and WAL segments are visibly arriving in the archive.
Test failover and restore
Simulate a primary failure in a staging copy and confirm the standby is promoted, that Backstage reconnects without a rebuild, and that the catalog still loads. Then restore a backup to a new instance at a chosen point in time and compare row counts and recent catalog changes against the source. PostgreSQL does not detect primary failure itself, so verify the failover tool you chose. Done when both drills complete and the measured recovery behavior is written into the results.
Document the runbook
Write a runbook covering the PostgreSQL version and end-of-support date, the connection settings location, backup schedules, the restore and failover procedures from the drills, and the owner for each. Add a plan for minor updates, which replace executables and need a restart, and for major upgrades, which use pg_dumpall with restore, pg_upgrade, or logical replication. Assign a review date. Done when the runbook is reviewed by the platform and security owners and linked from your Backstage operations documentation.
Which PostgreSQL versions Backstage and your upgrade plan support
Backstage runs on PostgreSQL, but the supported database version is only one input to your plan. The cards below cover the PostgreSQL support window, the search requirement, and the Node.js and Backstage release lines that your upgrade schedule must follow together.
PostgreSQL 14 to 18 are supported
PostgreSQL currently supports major versions 14 through 18. Version 18 was first released on September 25, 2025 and is supported until November 14, 2030, while version 14 reaches end of support on November 12, 2026. Choose a version that will still be supported for the full life of the Backstage release you deploy, and confirm the version your Backstage release line expects before provisioning.
Versions 13 and earlier are unsupported
PostgreSQL 13 and earlier no longer receive fixes from the community. A database that old is a security and compliance finding in its own right, so treat any existing instance on those versions as a migration task before the Backstage upgrade starts. Ask your managed PostgreSQL provider or operator which major versions it offers and how quickly it adopts new ones.
PostgreSQL 12 cited for search
The Backstage documentation has cited PostgreSQL 12 as the version required by the search engine setup. Search plugin requirements change between releases, so confirm the current minimum with the Backstage documentation before you choose a PostgreSQL version. If the search requirement and the supported-version window disagree, plan around the newer constraint and record the decision.
Match the Node.js release line
Backstage supports two adjacent even-numbered Node.js releases. As of Backstage 1.46.0 these were Node.js 22 and 24. Your PostgreSQL client libraries and base images inherit that choice, so a Node.js change can force a rebuild and a driver check at the same time as a database change. Schedule the Node.js and database changes so each can be tested separately.
Follow the Backstage release cadence
The main release line ships monthly and the next release line ships weekly on Tuesdays. High and critical vulnerabilities are backported to releases from the last six months where feasible. Staying within that window keeps you on a line that receives security fixes, and every upgrade includes database migrations that must be tested against your chosen PostgreSQL version.
Plan database and portal upgrades together
Move Backstage to a current release line first, confirm it runs against your current PostgreSQL version, and then schedule the database major upgrade in its own change window. Record the PostgreSQL version, the Node.js version and the Backstage version in one compatibility matrix that your team reviews at each release. Ask your partner to include this matrix in the upgrade runbook.
Planning PostgreSQL major upgrades without losing catalog state
A PostgreSQL major upgrade for Backstage is a data migration, not a package update, because the catalog, scaffolder history and plugin state all live in the database. PostgreSQL documents three paths: dump and restore with pg_dumpall, pg_upgrade, and logical replication. Dump and restore is the simplest to reason about but needs the longest outage window, since the portal's backends must stop writing while the data is copied. pg_upgrade converts the data directory in place and is faster on large databases. Logical replication works across major versions and can keep the cutover to several seconds of downtime, but it requires you to plan the replication setup, verify row counts and handle sequences before switching the Backstage connection settings over.
PostgreSQL 18 changes the calculation for pg_upgrade. Its release announcement states that pg_upgrade retains planner statistics across major upgrades, so the new cluster does not start cold, and it adds parallel jobs and a --swap option. Confirm the exact flags against the upgrade documentation for the version you are moving to before writing a runbook. Minor releases are a different operation: PostgreSQL states they never change the internal storage format, so you replace the executables and restart. That is routine maintenance you can schedule alongside Backstage patch releases, while a major upgrade needs its own change record and rollback plan.
Tie the database change to the Backstage release cadence. Backstage ships a main release line monthly and a next line weekly, and its upgrade guidance moves all @backstage packages together with yarn backstage-cli versions:bump. Do not change the database version and the Backstage version in the same window, because a failure then has two possible causes. Instead, rehearse the chosen path on a copy of production: restore a recent snapshot, run the Backstage migrations, confirm the catalog refreshes and the scaffolder history is intact, then time the cutover. Confirm with your platform team which PostgreSQL versions your Backstage release and plugins support, and keep the rehearsal results as the evidence for the change.
Questions buyers ask about running Backstage on PostgreSQL
What drives the cost of running Backstage on PostgreSQL?
The cost is driven mainly by who operates the database and how many environments you need. Backstage itself is open source under the Apache License 2.0, so there is no license fee from the project. The spend falls on infrastructure (database nodes, storage, backups, and any managed service charges), on internal staff time for on-call and patching, and on the implementation work to design per-plugin databases, connection settings, high availability and backup restore tests. Recurring costs include hosting, backup storage and upgrade effort. Ask any quote to split one-time build work from recurring operations, and to state which PostgreSQL versions and HA design it assumes.
How long does a PostgreSQL setup for Backstage take?
Duration depends on the target design, not on Backstage alone. A single managed instance with per-plugin logical databases is a smaller job than a highly available cluster with tested point-in-time recovery, connection pooling and a restore drill. The main drivers are the number of environments, whether the database runs in a managed service or in Kubernetes, how many Backstage backend deployments share it, the depth of backup testing and the approval steps in your change process. Ask for a timeline tied to a written scope with named milestones, and confirm which environments and failover tests are included.
Can our team run Backstage on PostgreSQL without outside help?
Yes, if your team already operates PostgreSQL and Kubernetes or a similar platform. The work that usually strains internal teams is not the first install but the ongoing parts: choosing a version that matches Backstage's search requirements (PostgreSQL 12 or later for search), setting up replication and a failover tool, testing restores, and planning major upgrades. Assess your skills in those areas before deciding. A partner can cover the build and hand over runbooks, while your team keeps the operating role. Request a handover plan that lists the tasks, owners and training included.
What do we need to provide for a PostgreSQL implementation?
You provide the environment and the decisions. Expect to supply access to the infrastructure where PostgreSQL will run, whether that is a cloud account, a data center or a Kubernetes cluster, along with storage classes, network rules, secrets management and DNS. You also need to name owners for the database, backup retention targets, recovery time and recovery point expectations, and the identity setup that Backstage uses for sign-in. Early decisions include whether to use a managed service or an in-cluster operator and how many Backstage backend deployments will connect. Ask the quote to list these inputs so gaps are found before work starts.
Does a managed PostgreSQL service remove the need for a database operator?
A managed service removes some operating work, such as host patching and some backup mechanics, but it does not remove design or ownership. You still decide database layout, per-plugin logical databases, connection limits, access roles, maintenance windows and restore testing. Managed services also vary in which PostgreSQL versions they offer and how they handle failover, so confirm those details with the provider. In-cluster operators such as CloudNativePG shift more work to your Kubernetes team but give more control. Ask for a comparison that states which tasks move to the provider and which stay with you.
How do Backstage upgrades affect the PostgreSQL database?
Backstage upgrades and PostgreSQL upgrades are separate changes that can collide. Backstage moves its @backstage packages together with yarn backstage-cli versions:bump, and the Backstage Upgrade Helper shows template changes between versions. Backstage supports two adjacent even-numbered Node.js releases, and its versioning policy says high and critical vulnerabilities are backported to recent releases where feasible. PostgreSQL releases a new major version about once a year and supports each for five years. PostgreSQL 14 is supported until November 12, 2026, and PostgreSQL 18 until November 14, 2030. Plan minor updates routinely, and schedule major PostgreSQL upgrades with a tested rollback. Ask the quote how upgrades to both stacks are sequenced and tested.
What should we request in a quote for Backstage PostgreSQL work?
Ask for a written scope that names the PostgreSQL version and the reason for it, the database topology (single instance, primary with standbys, or operator-managed cluster), how each Backstage plugin's logical database is created and owned, connection pooling and limits, backup method and retention, and the restore test you will see. Also request the failover approach, the upgrade plan for both Backstage and PostgreSQL, the documentation and training included, and the support period after handover. Confirm what is one-time and what is recurring, and which third-party costs, such as cloud or managed service fees, are excluded. Fixed-scope quotes make these items easy to compare.
How DeployOpen scopes and delivers a Backstage database build
DeployOpen builds the PostgreSQL layer for Backstage inside infrastructure you control, with the database design agreed in writing before any work starts. The cards below follow the path from scoping to handover and the ongoing support that comes after, and each one names a decision your team should make or check.
Written scope before any build
The scope fixes which Backstage plugins get their own logical database, which PostgreSQL major version is targeted, and whether the database runs in a managed service or in-cluster. It also records connection settings, backup expectations and the upgrade path. Ask for the scope in writing before work starts, because it becomes the basis of the quote. Confirm which plugins are in use today, since each one adds a database to manage.
Work in your infrastructure
DeployOpen plans and implements the database inside your cloud accounts, data centers or air-gapped networks, so credentials, backups and data never leave your control. Confirm where the database will run, who holds administrative access, and which network paths the Backstage backend needs to reach it. Agree these boundaries in the scope so that access requests do not stall the build.
Version targets and upgrade planning
The build targets a supported PostgreSQL major version and records its end-of-support date, so the upgrade window is known from the start. Major upgrades can use dump and restore, pg_upgrade or logical replication, and the choice affects downtime. Confirm the target major version and its support end date with your platform team before the database is provisioned.
Backup and recovery testing
A backup that has never been restored is not evidence of recovery. The delivered design covers backup method, retention and point-in-time recovery, and includes a restore test that the client observes and signs off. Ask whether restores are tested on a schedule and who owns the runbook after handover.
Ongoing support and upgrades as retainers
Minor PostgreSQL updates, Backstage version bumps that touch database migrations, and major upgrades recur over the life of the portal. DeployOpen offers these as retainers, separate from the fixed-scope build. Ask what a retainer covers, how upgrades are scheduled, and how urgent security patches are handled before you sign.
Evidence without audit claims
DeployOpen prepares configuration records, access controls, backup evidence and runbooks that an auditor can review. It does not issue audit reports, attestations or certifications, and independent auditors or certification bodies make those determinations. Confirm which evidence your assessor expects, and ask for it to be listed in the scope.
