Backstage Database
You set up a backstage database by pointing the portal app to a relational store. Most teams pick PostgreSQL for production and keep local file storage only for testing. Platform teams often start with one shared superuser login for all portal plugins. That broad role makes setup fast, but it gives every plugin full write power. One bad query or human mistake can wipe catalog records across the whole app. How the backstage database architecture works Backstage serves as a central developer po
Database Access Proxy + Backstage Security Plugins: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up a backstage database by pointing the portal app to a relational store. Most teams pick PostgreSQL for production and keep local file storage only for testing. Platform teams often start with one shared superuser login for all portal plugins. That broad role makes setup fast, but it gives every plugin full write power. One bad query or human mistake can wipe catalog records across the whole app.
How the backstage database architecture works
Backstage serves as a central developer portal for software catalogs, templates, and docs. Under the hood, the portal relies on a modular backend architecture. Each core feature or custom plugin runs as its own isolated backend module. The catalog, scaffolder, search index, and auth modules all need state storage. They store service metadata, job history, user tokens, and index records in tables.
When the portal starts up, its database manager reads the main config file. The manager connects to the host and checks the logical database for each plugin. By default, the app creates a separate logical database or schema per plugin. The catalog module gets its own space, and the scaffolder gets another space. Each module then runs schema migrations to build its own tables and indexes. This separation stops plugins from overwriting each other during normal daily runs.
For local work, developers often run an in-memory store that resets on restart. Production setups require a durable PostgreSQL server to hold state across pod restarts. Teams pass the host address, port, and login keys through secret variables. The backend then opens a pool of network connections to handle user traffic.
Choosing a database separation strategy for plugins
Platform engineers must choose how to split data across the database server. You can isolate plugins at the logical database level or the schema level. Logical database isolation gives each plugin its own database on the PostgreSQL cluster. This approach requires a startup role with rights to create new databases. Many managed cloud database services restrict that high-level role by default.
Schema isolation keeps all plugins inside one single database on the server. Each plugin gets a dedicated named schema for its own tables and views. This method works well when cloud teams pre-build one database per app. Engineers can then assign narrower roles that only manage schemas inside that database.
Backups and upgrades also depend on this separation choice. Restoring one broken plugin is easier when its tables sit in a clean schema. Teams should test migration scripts in staging before running a portal version upgrade. A bad migration can lock tables and block the portal from starting up.
Database Access Proxy + Backstage Security Plugins: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Where native database roles fall short in daily ops
Native PostgreSQL roles and network rules solve the basic app connection problem. You can lock down network ports so only portal pods reach the server. You can also split app roles from human admin roles on the cluster. These steps decide who can log in to the database server.
Still, native setup does not control what happens during live human debugging sessions. On-call engineers still need direct database access to fix stuck scaffolder jobs. Sometimes a broken catalog entity needs a manual row update or state check. When an engineer logs in with a shared role, native controls step back. The database allows any query that matches the broad table permissions of that role.
Standard roles cannot inspect individual SQL statements in flight before they run. They also fail to tie shared role queries back to a specific person. If a table holds user emails or phone numbers, raw queries return everything. Masking tools must rewrite matched fields in results to protect those emails and phone numbers. Without query-level checks, one wrong delete statement can drop core catalog state.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Which database engine works best for a production Backstage setup?
PostgreSQL is the standard choice for production deployments of the developer portal. Local file stores work for quick laptop tests, but they fail under real team load.
Does each Backstage plugin need its own separate database server?
No, all plugins can share one PostgreSQL server instance without any issue. The app isolates each plugin by creating separate logical databases or schemas on that server.
Why do engineers ever need direct access to the portal database?
Engineers sometimes query the store to clear stuck catalog items or inspect failed jobs. They also check schema state when a plugin migration fails during an upgrade.