Skip to navigation

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_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.

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:

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:

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.

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:

    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:

    migrations:
    existingSecret: fabric-dp-migrations
    passwordKey: FLYWAY_PASS
    dbUser: fabric_ddl
ValueDefaultDescription
migrations.existingSecret""Secret with the migration password. Empty means the app Secret.
migrations.passwordKeyFABRIC_GW_MYSQL_PASSKey in that Secret.
migrations.enabledtrueSet to false to run migrations from your own pipeline.
migrations.backoffLimit2How 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