Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Export and Migrate Data from Capella

  • Capella Operational
    Learn how to export data from Capella to other Capella clusters, to self-managed Couchbase Server, or to third-party databases.

    Couchbase Capella provides flexible data export and migration capabilities to support your evolving infrastructure needs. The methods to export data from Capella include:

    • Cross datacenter replication (XDCR)

    • Cluster backups

    • Bucket backups for full or granular migrations

    • Command-line tools

    Capella supports the following data export and migration scenarios:

    Assistance with data export and migration for those with paid plans is available from Couchbase Support. If you’re using a free tier cluster, you can find community support through the Couchbase forums and the Couchbase discord channel.

    What You Can Export by Method

    The following table summarizes what you can export using each method and tool:

    Data Type XDCR Cluster Backup Bucket Backup cbbackupmgr cbexport

    Documents (JSON)

    Scopes & Collections

    1

    2

    Indexes (GSI)

    3

    4

    4

    Search Indexes

    Eventing Functions

    Cluster Configuration

    5

    6

    6

    User Accounts & Roles

    Allowed IP addresses

    1 XDCR replicates data only and does not create scopes or collections on the destination bucket. If matching scopes and collections exist in the destination bucket, XDCR automatically maps data to them unless you choose the explicit mapping option for the replication.

    2 cbexport does not preserve the scope and collection hierarchy. You can optionally embed the scope and collection names as fields within the exported JSON documents, but they do not restore as scopes and collections on import.

    3 You must recreate indexes on the destination cluster. You can extract index definitions using the Capella UI. For more information about exporting index definitions, see Migrating Indexes and Functions.

    4 Bucket backups and cbbackupmgr restore GSIs in a deferred state (Created), so you must manually build them after restore to get them into the Ready state. For more information, see Migrating Indexes and Functions.

    5 Cluster backups include cluster configuration settings, but may need adjustment based on the destination environment.

    6 When restoring bucket backups, the bucket configuration only restores if you allow the restore to create the bucket. If the bucket already exists, the restore does not change the configuration of the pre-existing bucket.

    Prerequisites

    Before exporting or migrating data, make sure you have the following common prerequisites where applicable. Each export option may have additional specific requirements, so make sure to review the documentation for your chosen option.

    Export to Another Capella Cluster

    You can migrate data between Capella clusters using several options, depending on your requirements.

    Option 1: Cross Datacenter Replication (XDCR)

    XDCR replicates data in near-real-time from a source bucket to a destination bucket. When directly migrating to another Capella cluster, you can replicate data between clusters in the same or different regions, but they must share the same cloud service provider (CSP).

    When to use XDCR:

    • When you need to migrate data between operational Capella clusters in the same CSP with minimal downtime.

    • When you need continuous data synchronization and can accept eventual consistency.

    • When you need to verify data on the destination cluster before cutover.

    What XDCR migrates:

    Data Type Included

    Documents (JSON)

    Scopes & Collections

    1

    Indexes (GSI)

    2

    Full-Text Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    1 XDCR replicates data only and does not create scopes or collections on the destination bucket. If matching scopes and collections exist in the destination bucket, XDCR automatically maps data to them unless the explicit mapping option was chosen for the replication. If you explicitly map source and destination scopes and collections, the scope and collections must exist on the destination bucket or the mapped data does not replicate. To copy the scopes and collections from 1 bucket to another, use cbbackupmgr to back up and restore only the scopes and collections without the documents using the --disable-data option.

    2 XDCR replicates data only and does not create indexes on the destination bucket. If matching indexes already exist in the destination bucket, they index replicated data automatically.

    Limitations:

    • Cannot replicate data between clusters on different CSPs.

    • Requires both source and destination clusters to be running simultaneously.

    • Not available for free tier clusters.

    For more information about using XDCR and for detailed procedures, see:

    Option 2: Cloud Snapshot Cluster Backup

    Cloud snapshots create a snapshot of your entire cluster and allow you to restore it to the same or a different cluster.

    Using a cloud snapshot, you can back up and restore a cluster and all of its buckets in a single backup. For AWS and Azure clusters, you can restore a cloud snapshot backup to a different region on the same CSP. For GCP clusters, you cannot restore a cloud snapshot backup to a different region.

    When to use cluster backups:

    • Migrating an entire cluster to another Capella cluster.

    • Moving to a different region or Availability Zone.

    • Creating a copy of a production cluster for testing.

    What cluster backups include:

    Data Type Included

    Documents (JSON)

    Scopes & Collections

    Indexes (GSI)

    Search Indexes

    Eventing Functions

    Cluster Settings

    1

    Cluster access credentials

    Allowed IP addresses

    1 If the number of nodes differs between the backup and restore, Capella scales your cluster configuration up or down to the number of nodes in the backup.

    Before you restore a cluster backup, use the Couchbase Capella Management API to get a list of all available cluster access credentials and get a list of all allowed IP addresses on your cluster.

    Limitations:

    • Not available for free tier clusters.

    • Cannot restore to a different CSP.

    • GCP clusters cannot restore to a different region.

    • Restoring to a cluster with a different node count may cause performance issues until the cluster stabilizes after restore.

    • Cluster backups do not capture buckets that use the Memory Only bucket type.

    For more information about cluster backups, and detailed instructions for creating and restoring cluster backups, see:

    Option 3: Individual Bucket Backups Using the UI

    Bucket backups allow you to back up and restore individual buckets, providing more granular control over your migration.

    In the Capella UI, you can restore a bucket backup to a cluster in the same or different region, but it must be on the same cloud service provider (CSP). To restore a bucket to a different CSP, download the backup and use cbbackupmgr to restore it to a cluster on a different CSP.

    When to use bucket backups:

    • Migrating specific buckets rather than entire clusters.

    • Restoring data to a cluster with a different configuration in the same organization and CSP.

    • Creating test environments with data subsets.

    What bucket backups include:

    Data Type Included

    Documents (JSON)

    Scopes & Collections

    Indexes (GSI)

    Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    Limitations:

    • Not available for free tier clusters.

    • When using the UI, you can restore to a bucket only to the same cloud service provider (CSP) as the 1 used to create the backup — such as from Azure to Azure.

    • You can restore bucket backups only to a cluster running the same or later version of Couchbase Server.

    • Bucket backups provide per-item consistency but do not guarantee consistency across items; the consistency window is typically within a few seconds under normal conditions.

    • Limited to migrating documents, scopes and collections, indexes, and eventing functions.

    • Global Secondary Indexes (GSIs) restore in a deferred state (Created). You must manually build them after the restore to make them active (Ready).

    For more information about bucket backups, and detailed instructions for creating and restoring bucket backups using the UI, see:

    Option 4: Command-Line Tools (cbbackupmgr)

    Use cbbackupmgr for flexible, automated migrations between Capella clusters when you need more control over the backup and restore process. This method allows for migration between CSPs in Capella, but data transfer costs may apply.

    When to use cbbackupmgr:

    • Migrating from free tier clusters.

    • When you need to migrate across CSPs.

    What cbbackupmgr migrates:

    Data Type Included

    Documents (JSON)

    1

    Scopes & Collections

    1

    Indexes (GSI)

    2

    Full-Text Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    1 Supports filtering to migrate specific subsets of data.

    2 GSI indexes restore in a deferred state (Created). You must manually build them after the restore to make them active (Ready). For more information, see Build Indexes.

    Limitations:

    • Limited to migrating data, scopes, collections, indexes, and eventing functions.

    • You can restore backups only to a cluster running the same or later version of Couchbase Server.

    • GSIs restore in a deferred state (Created), so you must manually build them after restore to get them into the Ready state.

    • You must create buckets manually.

    • You must configure cluster settings manually.

    For more information about using cbbackupmgr and for detailed instructions, see:

    Export to Self-Managed Couchbase Server

    You can export data from Capella to self-managed Couchbase Server deployments using several options, depending on your requirements.

    Option 1: Cross Datacenter Replication (XDCR)

    XDCR can replicate data from a Capella operational cluster to a self-managed Couchbase Server cluster in near-real-time. Self-managed clusters can be on-premises or in a cloud environment. The clusters do not need to be on the same CSP (AWS, GCP, or Azure), but they must have network connectivity and run compatible Couchbase Server versions.

    When to use XDCR for self-managed migration:

    • Migrating with minimal downtime while maintaining an active Capella cluster.

    • When you need continuous data synchronization during a phased migration.

    • Moving data to on-premises or non-Capella cloud deployments.

    What XDCR migrates:

    Data Type Included

    Documents (JSON)

    Scopes & Collections

    1

    Indexes (GSI)

    2

    Full-Text Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    1 XDCR replicates data only and does not create scopes or collections on the destination bucket. If matching scopes and collections exist in the destination bucket, XDCR automatically maps data to them unless the explicit mapping option was chosen for the replication. If you explicitly map source and destination scopes and collections, the scope and collections must exist on the destination bucket or the mapped data does not replicate. To copy the scopes and collections from 1 bucket to another, use cbbackupmgr to back up and restore only the scopes and collections without the documents using the --disable-data option.

    2 XDCR replicates data only and does not create indexes on the destination bucket. If matching indexes already exist in the destination bucket, they index replicated data automatically.

    Limitations:

    • Not available for free tier clusters.

    • Requires both source and destination clusters to be running simultaneously.

    For more information about using XDCR and for detailed procedures, see:

    Option 2: cbbackupmgr

    Use cbbackupmgr to create backups that you can restore to self-managed Couchbase Server installations.

    When to use cbbackupmgr:

    • Moving data to self-managed Couchbase Server environments.

    • Migrating from free tier clusters.

    • Creating portable backups for disaster recovery.

    What cbbackupmgr migrates:

    Data Type Included

    Documents (JSON)

    1

    Scopes & Collections

    1

    Indexes (GSI)

    2

    Full-Text Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    1 Supports filtering to migrate specific subsets of data.

    2 GSI indexes restore in a deferred state (Created). You must manually build them after the restore to make them active (Ready). For more information, see Build Indexes.

    Limitations:

    • You can restore bucket backups only to a cluster running the same or later version of Couchbase Server.

    • Limited to migrating data, scopes/collections, indexes, and eventing functions.

    • Global Secondary Indexes (GSIs) restore in a deferred state (Created), so you must manually build them after restore to get them into the Ready state.

    For more information about using cbbackupmgr and for detailed instructions, see:

    Option 3: Download Bucket Backups Using the UI

    The Capella UI allows you to download bucket backups as cbbackupmgr archives. You can restore these downloads only to Couchbase systems (Capella or self-managed Server), not to third-party databases.

    When to use bucket backup downloads:

    • Restoring to a Capella cluster in a different CSP.

    • Moving data to self-managed Couchbase Server environments.

    • Creating portable backups for disaster recovery.

    • Offline storage of bucket data.

    Limitations:

    • Not available for free tier clusters.

    • You can restore downloaded bucket backups only to Couchbase systems (Capella or self-managed Server), not to third-party databases.

    • You can restore bucket backups only to a cluster running the same or later version of Couchbase Server.

    • Bucket backups provide per-item consistency but do not guarantee consistency across items; the consistency window is typically within a few seconds under normal conditions.

    • Limited to migrating documents, scopes and collections, indexes, and eventing functions.

    • Global Secondary Indexes (GSIs) restore in a deferred state (Created). You must manually build them after the restore to make them active (Ready).

    For more information about downloading bucket backups using the UI, see:

    Export to Third-Party Systems

    When migrating data from Capella to third-party systems, cbexport is the recommended option.

    cbexport

    The cbexport json command-line tool exports data from Capella to JSON format (lines or list format) for import into other systems.

    When to use cbexport:

    • Exporting data for import into third-party databases.

    • Exporting data for compliance or archival purposes.

    • Migrating from free tier clusters.

    What cbexport can export:

    Data Type Included

    Documents (JSON)

    1

    Scopes & Collections

    1

    Indexes (GSI)

    Search Indexes

    Eventing Functions

    Cluster Settings

    Cluster access credentials

    Allowed IP addresses

    1 Supports filtering to export specific subsets of data.

    Limitations:

    • You cannot export data from multiple buckets with a single command. You must run separate export commands for each bucket or scope/collection.

    For more information about using cbexport and for detailed instructions, see:

    Partial Dataset Migration

    If you need to migrate only specific subsets of your data, you can use filtering options available in some export options.

    Filter by Scope and Collection

    All migration methods support migrating specific scopes and collections:

    • XDCR: Use scope and collection mapping to replicate specific data subsets

    • cbbackupmgr: Use --include-data and --exclude-data flags

    • cbexport: Specify scope and collection in export command

    • Bucket backups: Restore to specific scopes/collections

    Migrate Indexes and Functions

    If you’re using bucket backups or cbbackupmgr for migration, Global Secondary Indexes (GSI) do not automatically restore to an active state. Bucket backups and cbbackupmgr restore GSIs in a deferred state, so you must manually build them after restore to get them into the Ready state. For more information, see Restore Indexes and Build Indexes.

    For migration methods that do not include indexes and functions, you need to export and then manually recreate these components on your destination cluster.

    Export GSI Definitions

    To export GSI definitions from the Capella UI:

    1. In the navigation breadcrumbs in the Capella UI, do 1 of the following:

      • Click your organization name and go to Operational.

      • Click your current project name or search for a project and go to Operational.

      • Expand the cluster breadcrumb and search for a cluster.

    2. Select the cluster where you want to work with the Index Service.

    3. Go to Data Tools  Indexes.

    4. Expand the listing for the index you want to export.

    5. Copy the definition by clicking .

      You can then paste the definition into a query editor on your destination cluster.

    For more information about indexes, see:

    Export Search Index Definitions

    You can export and import full Search index definitions from Capella using the Capella UI. For instructions, see:

    Recreate Eventing Functions

    XDCR and cbexport do not include Eventing functions; you must manually recreate them on the destination cluster. If you’re using bucket backups or cbbackupmgr, backups include Eventing functions, which restore automatically.

    For more information, see Add Eventing Functions.

    Migrate Query User-Defined Functions (UDF)

    Each migration method handles UDFs in the following way:

    • Cluster backup (Cloud snapshots): Include both SQL++ UDF definitions and JavaScript UDF library files, which restore automatically.

    • Bucket backups and cbbackupmgr: Include SQL++ UDF definitions, which restore automatically. JavaScript UDF library files do not back up and you must manually recreate them on the destination cluster.

    • XDCR and cbexport: Do not include either SQL++ UDF definitions or JavaScript UDF library files and you must manually recreate them on the destination cluster.

    To manually recreate JavaScript UDF libraries on the destination cluster, use the library management tools in the Capella UI.

    For more information, see JavaScript Functions for Query Reference.

    See Also