> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Database migrations

> How the data plane chart migrates its MySQL schema, and how to adopt an existing database, run migrations yourself, or use a separate migration user.

This page applies to the Enterprise plan, where you run the data plane in your own VPC with the MySQL secret store. The Helm chart keeps the data plane's MySQL schema current with a Flyway migration Job that runs before every install and upgrade. This page explains the default behavior, what must be true before it runs, and how to adopt a database that already has data, run migrations yourself, or give migrations their own user.

If you use the distributed secret store, the data plane needs no MySQL, and the chart skips the migration Job.

## Default behavior

With `migrations.enabled: true` (the default), every `helm install` and `helm upgrade` runs the `fabric-gateway-chart-dp-migrate` Job before the gateway rolls out. It applies the chart's SQL files to the database named by `FABRIC_GW_MYSQL_HOST` and `FABRIC_GW_MYSQL_DATABASE`.

* **Runs once per release.** It's a Job, not an init container, so it doesn't run for every pod.
* **Gated.** If a migration fails, the Helm operation stops before any gateway pod rolls. The failed Job stays in the namespace so you can read its logs.
* **Upgrade-safe.** Flyway records applied versions in the `flyway_schema_history` table, and applies only newer files on a later upgrade. Running the same chart version again changes nothing.

The gateway never migrates its own schema, whatever this setting is.

## Prerequisites

The Job runs as part of `helm install` and `helm upgrade`, so these must be true before you run either:

* MySQL is reachable from the cluster at `FABRIC_GW_MYSQL_HOST`. The Job uses port `3306` unless you add `:<port>` to the host.
* The database exists. The chart creates the tables, not the database or the user.
* The migration user has `CREATE`, `ALTER`, `INDEX`, `SELECT`, `INSERT`, `UPDATE`, and `DELETE` grants on the database. Flyway needs the data grants to record applied versions. By default, the migration user is the runtime user in `FABRIC_GW_MYSQL_USER`, which needs `SELECT`, `INSERT`, `UPDATE`, and `DELETE` to run.
* The app Secret exists and holds the correct `FABRIC_GW_MYSQL_PASS`. See [Secrets and keys](/run/secrets-and-keys).

The Job retries its connection 10 times by default (`migrations.connectRetries`), so a database that's still starting doesn't fail the install right away.

> **Note**
>
> The migration Job connects to MySQL without TLS options. With MySQL 8 and its default `caching_sha2_password` authentication over a connection without TLS, the Job fails with `RSA public key is not available client side`. Reach MySQL over TLS, create the user with `mysql_native_password`, or run migrations yourself. You can also override the connection string with `migrations.extraEnv`, for example with `FLYWAY_URL` set to `jdbc:mysql://<host>:3306/<db>?sslMode=REQUIRED`. Entries in `extraEnv` win over the chart's values.

## Adopt a pre-populated database

If the database already has the data plane schema, for example a restored snapshot, keep the defaults:

```yaml
migrations:
  baselineOnMigrate: true
  baselineVersion: "0"
```

Flyway marks the database as baselined at version `0`, and then applies every migration above it. Don't raise `baselineVersion`. Flyway's own default is `1`, which treats the first migrations as already applied and silently skips them.

## Run migrations yourself

To manage schema changes with your own tooling, such as an existing CI/CD pipeline, turn the Job off:

```yaml
migrations:
  enabled: false
```

Then, before you install or upgrade, apply the SQL files in the chart's `files/sql/dp/` folder in version order (`V000`, `V001`, `V002`, and any later files). You can use the `mysql` CLI, Flyway, golang-migrate, or your own pipeline. Apply the new files from each chart version before you upgrade to it.

> **Warning**
>
> If you turn the Job off and skip this step, the gateway starts against a schema that was never created, and credential and OAuth operations fail.

## Use a least-privilege migration user

By default, the Job connects with the runtime user and the password from the app Secret, so the runtime user needs DDL grants as well as data grants. To keep the runtime user to `SELECT`, `INSERT`, `UPDATE`, and `DELETE`, give migrations their own user and Secret:

1. Create a MySQL user with `CREATE`, `ALTER`, `INDEX`, `SELECT`, `INSERT`, `UPDATE`, and `DELETE` grants on the data plane database.

2. Create a Secret with that user's password:

   ```bash
   kubectl -n pm-fabric-dp create secret generic fabric-dp-migrations \
     --from-literal=FLYWAY_PASS='<migration-user-password>'
   ```

3. Point the Job at them in your values file:

   ```yaml
   migrations:
     existingSecret: fabric-dp-migrations
     passwordKey: FLYWAY_PASS
     dbUser: fabric_ddl
   ```

| Value                       | Default                | Description                                                                    |
| --------------------------- | ---------------------- | ------------------------------------------------------------------------------ |
| `migrations.existingSecret` | `""`                   | Secret with the migration password. Empty means the app Secret.                |
| `migrations.passwordKey`    | `FABRIC_GW_MYSQL_PASS` | Key in that Secret.                                                            |
| `migrations.enabled`        | `true`                 | Set to `false` to run migrations from your own pipeline.                       |
| `migrations.backoffLimit`   | `2`                    | How many times Kubernetes retries a failed migration Pod before the Job fails. |
| `migrations.dbUser`         | `""`                   | MySQL user for migrations. Empty means `FABRIC_GW_MYSQL_USER`.                 |

## Hand the steps to an AI agent

An agent can read this topic and prepare the migration, but a failed migration affects your data, so run it yourself against production. Use an agent to run it only in a staging or throwaway environment.

#### Prepare a database migration

Read [https://docs.fabricgateway.ai/run/database-migrations.md](https://docs.fabricgateway.ai/run/database-migrations.md). Tell me which of the three cases applies to my database: default behavior, a pre-populated database, or migrations that I run myself. Then list the exact commands I should run and the output that shows each one worked. Don't run any command that changes the database.

## Next steps

* To install with migrations in place, see [Install with Helm](/run/install).
* For every migration value, see [Helm values](/run/helm-values#database-migrations).
* To upgrade the chart, see [Upgrade the data plane](/run/upgrade).