Database migrations
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_historytable, 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 port3306unless 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, andDELETEgrants on the database. Flyway needs the data grants to record applied versions. By default, the migration user is the runtime user inFABRIC_GW_MYSQL_USER, which needsSELECT,INSERT,UPDATE, andDELETEto run. - The app Secret exists and holds the correct
FABRIC_GW_MYSQL_PASS. See 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.
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:
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:
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.
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:
-
Create a MySQL user with
CREATE,ALTER,INDEX,SELECT,INSERT,UPDATE, andDELETEgrants on the data plane database. -
Create a Secret with that user’s password:
-
Point the Job at them in your values file:
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.
- For every migration value, see Helm values.
- To upgrade the chart, see Upgrade the data plane.

