# DB Branching

{% hint style="info" %}
This feature is available to users on the Team and Enterprise pricing plans.
{% endhint %}

The `db_branches` feature in mirrord lets developers spin up an isolated DB branch that mirrors the remote DB, while running safely in isolation. This allows schema changes, migrations, and experiments without impacting teammates or shared environments. Currently, the feature is limited to **MySQL, PostgreSQL, MSSQL, MongoDB** databases for remote usage, and **Redis** database for local development.

**When is this useful?**

1. **Running schema migrations safely**\
   Developers can test migrations and schema changes without risking corruption of the remote databases.
2. **Experimenting locally**\
   Developers get a branch of the remote DB connected to their local app automatically - no admin setup required.
3. **Collaborating with teammates**\
   If a branch already exists (with the same ID), mirrord reuses it. Developers can share branches as needed.
4. **Validating AI-generated database changes** If your AI coding agents need to generate migrations or schema updates, DB branching provides a safe environment to test those changes without risking the shared environment.

### Prerequisites

Before you start, make sure you have:

1. Minimum versions installed:

* MySQL: Operator `3.129.0`, mirrord CLI `3.160.0` and operator Helm chart `1.37.0` with `operator.mysqlBranching` value set to `true`.
* PostgreSQL: Operator `3.131.0`, mirrord CLI `3.175.0` and operator Helm chart `1.40.2` with `operator.pgBranching` value set to `true`.
* MSSQL: Operator `3.150.0`, mirrord CLI `3.195.0` and operator Helm chart `1.57.0` with `operator.mssqlBranching` value set to `true`.
* MongoDB: Operator `3.137.0`, mirrord CLI `3.183.0` and operator Helm chart `1.44.0` with `operator.mongoBranching` value set to `true`.
* Redis: mirrord CLI `3.180.0` (no operator or chart version requirements, since Redis is supported only via a local DB branch).

2. Your local application is using environment variables or Kubernetes Secrets to store DB connection strings or individual connection parameters.
3. mirrord installed and working.

### Configuring `db_branches`

Developers define branches in their `mirrord.json`:

```json
{
  "db_branches": [
    {
      "id": "users-mysql-db",             // Optional
      "location": "remote",               // Optional, default is "remote", Available options [remote | local]
      "type": "mysql",                    // Available options [mysql | pg | mssql | mongodb | redis]
      "version": "8.0",
      "name": "users-database-name",      // Optional
      "ttl_secs": 60,                     // Optional
      "creation_timeout_secs": 20,        // Optional, Defaults to 60 if not specified
      "connection": {
        "url": "DATABASE_URL"
      },
      "copy": {
        "mode": "empty"                   // Defaults to "empty" if not specified
      }
    }
  ]
}
```

#### Key Fields

1. `id`: When reused, mirrord reattaches to the same branch as long as the time-to-live (TTL) has not expired. This allows multiple sessions to share the same database branch. To prevent accidental reuse of another user's branch, it is recommended to assign a unique value (for example, a UUID) as the identifier. (The `id` field is not used for local Redis instances and has no effect on database selection or reuse)
2. `location`: Supported values are `remote` and `local`. The default is `remote`. `remote` applies only when the `type` field is set to `mysql`, `pg`, `mssql`, or `mongodb`, while `local` applies only when `type` is set to `redis`.
3. `type`: Supported values are `"mysql"`, `"pg"`, `"mssql"`, `"mongodb"`, and `"redis"`.
4. `version`: Database engine version.
5. `name`: Remote database name to clone, the override URL uses `name` so the connection URL looks like .../dbname. If name is ommited, the override URL just points to the database server; the application must select the DB manually in that case.
6. `ttl_secs`: Override for branch time-to-live (TTL). The default is 5 minutes. The maximum allowed is 15 minutes. If you set a value above 15, mirrord will automatically fall back to 15 minutes.
7. `connection`: Describes how to locate the source database connection details. Supports a full connection URL or individual connection parameters. See [Advanced Configuration](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching-advanced-config#connection-modes) for details.
8. `copy.mode`: Allows developers to control how the database is cloned when creating a branch, see [Advanced Configuration](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching/db-branching-advanced-config)
9. `creation_timeout_secs`: Override for branch creation timeout. The default is 60 seconds.
10. `iam_auth`: Optional IAM authentication for AWS RDS or GCP Cloud SQL. See [Advanced Configuration](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching-advanced-config#iam-authentication) for details.
11. `local.port`: Currently only for Local Redis. Sessions that use the same port share a single local Redis database. When a new session starts on that port, it creates a new database instance that replaces the existing one.

### Running With DB Branches

1. Run your app with mirrord and set the `db_branches` field in [the mirrord configuration file](https://metalbear.com/mirrord/docs/config).
2. mirrord will spin up a database branch according to the following rules:

* Reusing an existing branch: If you provide an ID that matches an existing branch and its TTL hasn’t expired, mirrord will reuse that branch. When this happens, mirrord will notify you:

  ```
  A branch with this ID already exists for the target database.
  You’re about to use it! 
  ```

  *This means you’re connecting to an existing branch, not a fresh isolated one.*
* Creating a new branch: If no ID is specified, or if you choose a new, non-existing ID, mirrord will create a fresh, empty database branch.

3. mirrord will override your DB environment variable with the branch's connection URL, so the app connects to the branch, not to the source db. This setup reduces the risk of accidental writes reaching the source database by directing activity toward an isolated branch.
4. The branch will be destroyed automatically when the TTL is reached and the branch is not in use (reconnecting to the same branch again extends its lifetime).

***

### Portforwards

When DB branching is enabled, mirrord will also automatically set up portforwards to the branch pod while the session is active. This can be used to, for example, access the branch database with a GUI SQL client like DBeaver or DataGrip. To list currently active DB branch portforwards, run `mirrord db-branches connections`.

### Local Redis

mirrord can spin up a local Redis instance, automatically redirecting your app's Redis traffic to it.

```json
{
  "db_branches": [
    {
      "type": "redis",
      "location": "local",                     // "local" spawns Redis, "remote" is no-op (default)
      "connection": {
        // Use "host" if your app reads Redis as host:port (e.g. REDIS_ADDR=redis:6379)
        // Use "url" if your app reads a full Redis URL (e.g. REDIS_URL=redis://user:pass@redis:6379/0)
        "host": { "type": "env", "variable": "REDIS_ADDR" }
      },
      "local": {                               // Optional runtime config
        "port": 6379,                          // Custom port (default: 6379)
        "runtime": "container",                // "container" (default), "redis_server", or "auto"
        "container_runtime": "docker"          // "docker" (default), "podman", or "nerdctl"
      }
    }
  ]
}
```

mirrord overrides the env variable to point to `localhost:<port>` and cleans up the Redis instance on exit.

***

### FAQ

**Q: Why does my connection time out?** A: By default, branch databases have SSL disabled. Check if your client is specifically requesting SSL.

**Q: How do I use IAM authentication instead of passwords?** A: mirrord supports IAM authentication for AWS RDS and GCP Cloud SQL. Just add `"iam_auth": { "type": "aws_rds" }` or `"iam_auth": { "type": "gcp_cloud_sql" }` — mirrord automatically uses standard env vars like `AWS_REGION` or `GOOGLE_APPLICATION_CREDENTIALS` from your target pod. See [IAM Authentication](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching-advanced-config#iam-authentication) for details.

### What's next?

Next, check out the [Advanced Configuration](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching/db-branching-advanced-config) and [DB Branch Management](https://metalbear.com/mirrord/docs/sharing-the-cluster/db-branching/db-branch-management) sections to learn more about customization and command options.