Starting from v1.9.0, RisingWave has introduced support for using a SQL backend as a meta store for managing metadata. This marks a significant shift as RisingWave fully deprecates the etcd meta backend starting with v2.1.0. To ensure continued support and access to new features, please follow this guide on migrating from etcd to the SQL backend. The SQL backend currently supports these databases:
  • PostgreSQL (Recommended for production environments.)
  • SQLite (Limited to testing and pilot deployments.)
  • MySQL (Limited to testing and pilot deployments.)
Transitioning to a SQL backend offers numerous benefits, including enhanced stability, performance, and observability. In this guide, we will walk through the process of migrating an existing cluster from the etcd backend to a SQL backend.

​
Prerequisite

Ensure the following before starting the migration:

​
Start a SQL backend service

You need to have a SQL backend service running and accessible. Depending on your choice of SQL backend, here are the general requirements:
  • SQLite
    • Provide a writable directory where the SQLite database file can be stored.
    • SQLite operates directly from a file, so no separate service needs to be started.
  • PostgreSQL
    • Ensure that a PostgreSQL server is running and a database is prepared for use with RisingWave.
  • MySQL
    • Ensure that a MySQL server is running and a database is prepared for use with RisingWave.
Make sure the SQL backend service is operational and you have the necessary credentials and access configurations to connect to it from the server where RisingWave is deployed.

​
Back up etcd data

The migration process from etcd to a SQL backend is performed offline, so we recommend taking a backup of your current etcd data to avoid any data loss before the migration. Refer to the meta-backup for detailed instructions.

​
Procedure

Follow the steps below to migrate an existing cluster from the etcd backend to a SQL backend.
  1. Upgrade the cluster to version 2.0.5, which includes important migration fixes.
  2. Stop all components except etcd To safely migrate your metadata, stop all running components of the RisingWave cluster, except the etcd service. This ensures that no new data is written to etcd during the migration process.
  3. Run the migration command Execute the RisingWave migration command to transfer metadata from etcd to the SQL backend. You need to provide the necessary options, including the addresses for both the etcd source and the SQL backend target.
risingwave ctl meta migration --etcd-endpoints <etcd_address> --sql-endpoint <sql_address> -f
Replace <etcd_address> with the address of your etcd service and <sql_address> with the address of your SQL backend. 3. Update meta configuration After the migration, update the RisingWave meta configuration to point to the new SQL backend and remove the etcd configs. 
--sql-endpoint [endpoint address]
--backend sql
  1. Start the RisingWave cluster and stop etcd Start the RisingWave cluster with the updated configuration to enable SQL backend. Once the cluster is confirmed to be running correctly, you can safely stop the etcd service.

​
Post-migration

After completing the migration, monitor your cluster to ensure it is functioning as expected with the new SQL backend. Pay attention to the following key areas:

​
Performance monitoring

Keep an eye on the performance metrics to identify any changes or improvements in stability and response times. Monitoring tools and dashboards can help track the performance of your SQL backend and RisingWave cluster.

​
Backup management

After running the system for a while, if you confirm that everything is working correctly, don’t forget to delete the backup if you made one.

​
Troubleshooting

If the migration command fails, check the following:
  • Ensure that the target SQL backend service is running and healthy.
  • Verify that the target database exists and is accessible.
  • Confirm that the user has sufficient permissions to write to the database.
  • If the migration process was interrupted, re-run the migration command with the -f (force) parameter to overwrite all metadata.
Familiarize yourself with the SQL backend’s diagnostic tools and error messages. To seek help from the community, you can join our Slack workspace and post your questions in the #troubleshooting channel. You may also file an issue in GitHub.