Migrate Existing Self-Managed Couchbase Mobile Clusters to App Services


      If you are an existing user of Couchbase Mobile, have set up a Couchbase Server cluster, and have attached Sync Gateway, then you may wish to migrate your data and users from your existing self-managed servers to Couchbase Capella. Once the data and users are migrated, you will have to configure the App Services and set it up for remote sync.


      • You are running a self-hosted Couchbase Server with a Sync Gateway 2.0 or higher with shared bucket access enabled.

      • You have signed up for access to Capella Cloud.


      Step 1. Set up Capella server for replication

      Step 2. Set up XDCR replication.

      Set up an XDCR one way data replication from the self-managed cluster bucket to the Capella bucket.

      If you are replicating from a 3.x version of Sync Gateway deployment using persistent configuration mode then you MUST SETUP the following XDCR filter

      NOT REGEXP_CONTAINS(META().id, "^_sync:dbconfig:| _sync:registry")

      Step 3. Wait for replication to complete

      The following figure shows the setup of the components at this point. XDCR is copying the data from the on-prem bucket into Capella.

      During this period, clients are still connected to the original Sync Gateway, and their updates will be captured by the XDCR replication.


      Step 4. Detach replication

      Once the XDCR replication is complete:

      • Stop Sync Gateway cluster on source self-managed cluster.

      • Stop XDCR replication from source self-managed cluster.

      This ensures that no new data is written from Couchbase Mobile clients without being migrated to the Capella database.

      Step 5. Set up Capella App Services

      Now launch App Services on the target Capella Cluster.

      Then create an App Endpoint and configure it via Capella UI. Here are key aspects of the App Endpoint creation that you will have to handle:

      • Import Filter: If your existing setup uses a custom Import Filter function, you can write the filter function using the inline editor on Capella or import an existing Import Filter function file.

      • Access Control: You can write the sync function using the inline editor on Capella or import existing sync filter function file.

      • Authentication Provider: If your existing app uses basic authentication, then there are no changes required. Otherwise, if your existing setup was using OIDC then you will need to reconfigure the OIDC provider on Capella.

      Step 6. Direct Couchbase Mobile clients to the new Capella App Services.

      Direct Couchbase Lite clients to App Endpoint URL. There are couple of options here:

      • You can roll out a new version of the app to point to App Services URL endpoint. There will be downtime as the new app is rolled out.

      • You can configure the load balancer available in the source cluster to redirect existing clients to new App Services target.

      The following figure shows the setup of the components now that the migration is complete.