> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data planes and Superblocks Database

> How data planes and data tags decide where each application's Aurora PostgreSQL database is created

export const Alert = ({type, title, children}) => {
  const variant = ["info", "success", "warning", "danger", "note"].includes(type) ? type : "note";
  return <div className={`alert alert--${variant}`}>
      <div className="alert-icon" />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

[Superblocks Database](/admin/superblocks-on-aws/database) gives every app its own Aurora PostgreSQL database inside your AWS account. The data plane provisions and connects to those databases, and the data tag decides which data plane, and therefore which database, an app talks to. The setup procedure is in [Set up Superblocks Database](/admin/superblocks-on-aws/database-setup); this page covers the decisions that come before it.

## Database work is routed by exact data tag

Ordinary API execution accepts a data plane whose agent tags are `profile:*`. Database work does not: a data plane with Superblocks Database enabled must list exact tags, such as `profile:dev`, and the data plane, Terraform module, and Helm chart all reject the wildcard. If your data planes run with `profile:*` today, decide your tags and switch to them before you enable databases.

## One database per app, per data tag

Superblocks creates one logical database for each combination of application and data tag, inside the Aurora pool owned by the data plane that serves that tag.

```mermaid theme={null}
flowchart TB
  App["Application"]

  subgraph prodAccount [AWS account: production]
    ProdPlane["Production data plane<br/>profile:production"]
    ProdPool[("Aurora pool<br/>always on")]
    ProdDb["App database<br/>production"]
  end

  subgraph devAccount [AWS account: pre-production]
    DevPlane["Development data plane<br/>profile:dev"]
    DevPool[("Aurora pool<br/>scale to zero")]
    DevDb["App database<br/>dev"]
  end

  App -->|"Production<br/>production tag"| ProdPlane
  App -->|"Edit and Preview<br/>dev tag"| DevPlane
  ProdPlane --> ProdPool
  ProdPool --- ProdDb
  DevPlane --> DevPool
  DevPool --- DevDb
```

With the recommended two-data-plane setup, an app built in Edit gets its development database from the development data plane, and publishing creates its production database through the production data plane and applies the same migrations there; see [How it works](/admin/superblocks-on-aws/database#how-it-works). Because the two data planes are separate, the development pool can scale to zero while the production pool stays always on; see [Cluster autoscaling](/admin/superblocks-on-aws/database-reference#cluster-autoscaling).

## One database-enabled data plane per data tag

Superblocks recommends a separate data plane for each data tag you enable databases for, each in its own VPC and ideally its own AWS account. The recommended two-account layout already satisfies this. If you run one of the [less common layouts](/enterprise/hybrid-architecture/plan/architectures#less-common-layouts), check it against these rules:

* **A data plane can serve databases for more than one tag**, but every tag it serves shares that data plane's pool, capacity shape, and IAM role. Keep tags with different requirements (dev vs production, or different regions) on different data planes.
* **Each data tag should be served by exactly one database-enabled data plane.** Replicas of that data plane are fine, because they share one configuration. A second, independently configured data plane serving the same tag makes routing ambiguous.
* **Two data planes in one account and region** must be declared together with distinct agent names so they share a state bucket without colliding. See [Multiple data planes in one account and region](/admin/superblocks-on-aws/database-reference#multiple-data-planes-in-one-account-and-region).
* **Each region needs its own tag** and its own prerequisite stack. An app's database in `us-east` and its database in `eu-west` are different databases. See [Additional AWS regions](/admin/superblocks-on-aws/database-reference#additional-aws-regions).

<Alert type="warning" title="Data tag keys are permanent once databases exist">
  Database and role names are derived from a hash of the data tag, and the connector role's permissions are scoped to that pattern. Renaming a data tag orphans every database and role created under the old name. See <a href="/admin/superblocks-on-aws/database-reference#data-tag-names">Data tag names</a>.
</Alert>

## Why keep it simple

Every layout in [Reference architectures](/enterprise/hybrid-architecture/plan/architectures) works with Superblocks Database, but each extra data tag means another database per app, and each extra database-enabled data plane means another Aurora pool with its own cost floor, capacity settings, IAM roles, and state to protect. One data tag and data plane for Edit and Preview, and one for Production, give builders a development database and a production database per app with no further decisions to make. Add more only when one of the less common layouts describes a requirement you have, and involve your Superblocks account manager before you enable databases on it.

## Next steps

<CardGroup cols={2}>
  <Card title="Set up Superblocks Database" icon="wrench" href="/admin/superblocks-on-aws/database-setup">
    The Terraform and Helm walkthrough, one data plane at a time.
  </Card>

  <Card title="Superblocks Database reference" icon="book" href="/admin/superblocks-on-aws/database-reference">
    Naming, IAM policies, pool and autoscaling options, and multi-region setup.
  </Card>
</CardGroup>