Migrate Control Plane datastore to MySQL

This page describes how to migrate Control Plane' datastore from MongoDB to MySQL.

Since PipeCD release v0.9.8 which introduces MySQL as PipeCD control-plane datastore, we plan to drop the support for MongoDB datastore in the near future. Consider the supports of cloud providers (GCP, AWS, Azure, etc), MySQL has a higher status over MongoDB is one of the most reasons for this support-dropping conclusion.

If you are using MongoDB as your PipeCD control-plane datastore, the following guide is manipulation to migrate your datastore to MySQL.

Before start

You need to install the pipectl version v0.9.10-1-4ab28c0 command-line tool.

Validate your installed pipectl command

$ pipectl datastore -h
Manage control-plane datastore resource.

  pipectl datastore [command]

Available Commands:
  migrate     Migrate data to MySQL datastore.


Step by step guide for migration

1. Prepare your MySQL datastore instance.


  • MySQL v8.0 or later is required.
  • To enable pipectl to migrate data to the new MySQL datastore, your new MySQL data instance has to be connected from pipectl running environment.
    The current implementation of pipectl datastore subcommand connects directly to datastore, you do not need to authenticate your pipectl binary with API Key as for other subcommands. Just make sure pipectl running environment is in the same network with your MySQL instance is enough.
  • Your MySQL instance has to be initialized with the going to be used database, make sure you create it before move to the next step.

For example, if you use docker to create your new MySQL instance, the command should be

$ docker run -d \
    --name test-db \
    -e MYSQL_DATABASE=*database-name* \

2. Stop PipeCD control-plane

In case your PipeCD control-plane is installed by helm, simply run helm uninstall command would help.

3. Migrate using pipectl

Migrate using the following command (replace upstream-data-src, downstream-data-src and database with your corresponding values)

$ pipectl datastore migrate \
    --upstream-data-src="mongodb://" \
    --downstream-data-src="root:test@tcp(" \


  • Make sure your data-srcs value are formatted as same as the above example.
  • If you want to migrate only specific data models (not all at once), use the --models flag as follow --models=Application,Project. (Use pipectl datastore migrate -h to get the list of migratable models)

4. Start PipeCD control-plane with the new configuration

Your new control-plane’s configuration should be updated as follow:

 apiVersion: ""
 kind: ControlPlane
-    type: MONGODB
+    type: MYSQL
-      url: mongodb://
+      url: root:test@tcp(
       database: quickstart

See ConfigurationReference for the full configuration.

Restart PipeCD control-plane as same as you start it before, your PipeCD should be ready 🚀.