Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Migration depuis Couchbase Server

Introduction

Ce guide présente les principaux points à prendre en compte lors de la migration de Couchbase Server vers Amazon DocumentDB. Il explique les considérations relatives aux phases de découverte, de planification, d'exécution et de validation de votre migration. Il explique également comment effectuer des migrations hors ligne et en ligne.

Comparaison avec Amazon DocumentDB

Découverte

La migration vers Amazon DocumentDB nécessite une compréhension approfondie de la charge de travail de base de données existante. La découverte de la charge de travail consiste à analyser la configuration et les caractéristiques opérationnelles de votre cluster Couchbase (ensemble de données, index et charge de travail) afin de garantir une transition fluide avec un minimum de perturbations.

Configuration du cluster

Couchbase utilise une architecture centrée sur les services où chaque fonctionnalité correspond à un service. Exécutez la commande suivante sur votre cluster Couchbase pour déterminer quels services sont utilisés (voir Obtenir des informations sur les nœuds) :

curl -v -u <administrator>:<password> \
  http://<ip-address-or-hostname>:<port>/pools/nodes | \
  jq '[.nodes[].services[]] | unique'

Exemple de sortie :

[
  "backup",
  "cbas",
  "eventing",
  "fts",
  "index",
  "kv",
  "n1ql"
]

Les services de Couchbase incluent les éléments suivants :

Service de données (kv)

Le service de données permet read/write d'accéder aux données en mémoire et sur disque.

Amazon DocumentDB prend en charge les K/V opérations sur les données JSON via l'API MongoDB.

Service de requêtes (n1ql)

Le service de requête prend en charge l'interrogation de données JSON via SQL++.

Amazon DocumentDB prend en charge l'interrogation de données JSON via l'API MongoDB.

Service d'indexation (index)

Le service d'index crée et gère des index sur les données, ce qui permet d'accélérer les requêtes.

Amazon DocumentDB prend en charge un index principal par défaut et la création d'index secondaires sur des données JSON via l'API MongoDB.

Service de recherche (fts)

Le service de recherche prend en charge la création d'index pour la recherche en texte intégral.

La fonction de recherche en texte intégral native d'Amazon DocumentDB vous permet d'effectuer des requêtes de texte de base sur de grands ensembles de données textuelles à l'aide d'index de texte spécifiques à l'aide de l'API. MongoDB Pour bénéficier de fonctionnalités avancées telles que la recherche floue, la recherche multilingue et la recherche entre collections, utilisez l'intégration d'Amazon DocumentDB Zero-ETL à Amazon Service. OpenSearch

Service d'analyse (cbas)

Le service d'analyse prend en charge l'analyse des données JSON en temps quasi réel.

Amazon DocumentDB prend en charge les requêtes ad hoc sur les données JSON via l'API MongoDB. Vous pouvez également exécuter des requêtes complexes sur vos données JSON dans Amazon DocumentDB à l'aide d'Apache Spark exécuté sur Amazon EMR.

Service de concours complet (concours complet)

Le service d'événementiel exécute une logique métier définie par l'utilisateur en réponse aux modifications des données.

Amazon DocumentDB automatise les charges de travail pilotées par des événements en invoquant des AWS Lambda fonctions chaque fois que des données changent dans votre cluster Amazon DocumentDB.

Service de sauvegarde (sauvegarde)

Le service de sauvegarde planifie des sauvegardes complètes et incrémentielles des données et fusionne les sauvegardes de données précédentes.

Amazon DocumentDB sauvegarde en continu vos données sur Amazon S3 avec une période de conservation de 1 à 35 jours afin que vous puissiez les restaurer rapidement à tout moment pendant la période de conservation des sauvegardes. Amazon DocumentDB prend également des instantanés automatiques de vos données dans le cadre de ce processus de sauvegarde continu. Vous pouvez également gérer la sauvegarde et la restauration d'Amazon DocumentDB avec AWS Backup. .

Caractéristiques opérationnelles

Utilisez l'outil de découverte pour Couchbase pour obtenir les informations suivantes sur votre ensemble de données, vos index et votre charge de travail. Ces informations vous aideront à dimensionner votre cluster Amazon DocumentDB.

Jeu de données

L'outil extrait les informations suivantes relatives au compartiment, à l'étendue et à la collection :

Index

L'outil extrait les statistiques d'index suivantes et toutes les définitions d'index pour tous les compartiments. Notez que les index principaux sont exclus car Amazon DocumentDB crée automatiquement un index principal pour chaque collection.

Charge de travail

L'outil récupère les métriques K/V des requêtes N1QL. K/V les valeurs des métriques sont collectées au niveau du bucket et les métriques SQL++ sont collectées au niveau du cluster.

Les options de ligne de commande de l'outil sont les suivantes :

python3 discovery.py \
  --username <source cluster username> \
  --password <source cluster password> \
  --data_node <data node IP address or DNS name> \
  --admin_port <administration http REST port> \
  --kv_zoom <get bucket statistics for specified interval> \
  --tools_path <full path to Couchbase tools> \
  --index_metrics <gather index definitions and SQL++ metrics> \
  --indexer_port <indexer service http REST port> \
  --n1ql_start <start time for sampling> \
  --n1ql_step <sample interval over the sample period>

Voici un exemple de commande :

python3 discovery.py \
  --username username \
  --password ******** \
  --data_node "http://10.0.0.1" \
  --admin_port 8091 \
  --kv_zoom week \
  --tools_path "/opt/couchbase/bin" \
  --index_metrics true \
  --indexer_port 9102 \
  --n1ql_start -60000 \
  --n1ql_step 1000

K/V les valeurs métriques seront basées sur des échantillons toutes les 10 minutes de la semaine dernière (voir méthode HTTP et URI). Les valeurs des métriques SQL++ seront basées sur des échantillons toutes les 1 seconde au cours des 60 dernières secondes (voir Étiquettes https://docs.couchbase.com/server/current/rest-api/rest-statistics-single.html#general-labels générales). La sortie de la commande se trouvera dans les fichiers suivants :

collection-stats.csv — informations sur le compartiment, la portée et la collection

bucket,bucket_type,scope_name,collection_name,total_size,total_items,document_size
beer-sample,membase,_default,_default,2796956,7303,383
gamesim-sample,membase,_default,_default,114275,586,196
pillowfight,membase,_default,_default,1901907769,1000006,1902
travel-sample,membase,inventory,airport,547914,1968,279
travel-sample,membase,inventory,airline,117261,187,628
travel-sample,membase,inventory,route,13402503,24024,558
travel-sample,membase,inventory,landmark,3072746,4495,684
travel-sample,membase,inventory,hotel,4086989,917,4457
...

index-stats.csv — noms et tailles des index

bucket,scope,collection,index-name,index-size
beer-sample,_default,_default,beer_primary,468144
gamesim-sample,_default,_default,gamesim_primary,87081
travel-sample,inventory,airline,def_inventory_airline_primary,198290
travel-sample,inventory,airport,def_inventory_airport_airportname,513805
travel-sample,inventory,airport,def_inventory_airport_city,487289
travel-sample,inventory,airport,def_inventory_airport_faa,526343
travel-sample,inventory,airport,def_inventory_airport_primary,287475
travel-sample,inventory,hotel,def_inventory_hotel_city,497125
...

kv-stats.csv — obtenir, définir et supprimer des métriques pour tous les compartiments

bucket,gets,sets,deletes
beer-sample,0,0,0
gamesim-sample,0,0,0
pillowfight,369,521,194
travel-sample,0,0,0

n1ql-stats.csv — SQL++ sélectionne, supprime et insère des métriques pour le cluster

selects,deletes,inserts
0,132,87

indexes- <bucket-name>.txt — définitions d'index de tous les index du bucket. Notez que les index principaux sont exclus car Amazon DocumentDB crée automatiquement un index principal pour chaque collection.

CREATE INDEX `def_airportname` ON `travel-sample`(`airportname`)
CREATE INDEX `def_city` ON `travel-sample`(`city`)
CREATE INDEX `def_faa` ON `travel-sample`(`faa`)
CREATE INDEX `def_icao` ON `travel-sample`(`icao`)
CREATE INDEX `def_inventory_airport_city` ON `travel-sample`.`inventory`.`airport`(`city`)
CREATE INDEX `def_inventory_airport_faa` ON `travel-sample`.`inventory`.`airport`(`faa`)
CREATE INDEX `def_inventory_hotel_city` ON `travel-sample`.`inventory`.`hotel`(`city`)
CREATE INDEX `def_inventory_landmark_city` ON `travel-sample`.`inventory`.`landmark`(`city`)
CREATE INDEX `def_sourceairport` ON `travel-sample`(`sourceairport`)
...

Planification

Au cours de la phase de planification, vous allez déterminer les exigences du cluster Amazon DocumentDB et le mappage des compartiments, des étendues et des collections Couchbase avec les bases de données et les collections Amazon DocumentDB.

Exigences relatives au cluster Amazon DocumentDB

Utilisez les données collectées lors de la phase de découverte pour dimensionner votre cluster Amazon DocumentDB. Consultez la section Dimensionnement des instances pour plus d'informations sur le dimensionnement de votre cluster Amazon DocumentDB.

Mappage de compartiments, d'étendues et de collections avec des bases de données et des collections

Déterminez les bases de données et les collections qui existeront dans vos clusters Amazon DocumentDB. Envisagez les options suivantes en fonction de la façon dont les données sont organisées dans votre cluster Couchbase. Ce ne sont pas les seules options, mais elles vous fournissent des points de départ à prendre en compte.

Couchbase Server 6.x ou version antérieure

Compartiments Couchbase vers les collections Amazon DocumentDB

Migrez chaque compartiment vers une collection Amazon DocumentDB différente. Dans ce scénario, la valeur du document Couchbase sera utilisée comme id valeur Amazon _id DocumentDB.

Couchbase Server 7.0 ou version ultérieure

Collections Couchbase vers collections Amazon DocumentDB

Migrez chaque collection vers une collection Amazon DocumentDB différente. Dans ce scénario, la valeur du document Couchbase sera utilisée comme id valeur Amazon _id DocumentDB.

Migration

Migration des index

La migration vers Amazon DocumentDB implique le transfert non seulement de données, mais également d'index afin de maintenir les performances des requêtes et d'optimiser les opérations de base de données. Cette section décrit le processus détaillé étape par étape pour migrer les index vers Amazon DocumentDB tout en garantissant la compatibilité et l'efficacité.

Utilisez Amazon Q (disponible dans AWS Management Console ou dans votre IDE) pour convertir les CREATE INDEX instructions SQL++ en commandes Amazon createIndex() DocumentDB.

Amazon Q générera des createIndex() commandes Amazon DocumentDB équivalentes. Notez que vous devrez peut-être mettre à jour les noms des collections en fonction de la façon dont vous avez mappé les compartiments, les étendues et les collections Couchbase aux collections Amazon DocumentDB.

Par exemple :

indexes-beer-sample.txt

CREATE INDEX `beerType` ON `beer-sample`(`type`)
CREATE INDEX `code` ON `beer-sample`(`code`) WHERE (`type` = "brewery")

Exemple de sortie Amazon Q (extrait) :

db.beerSample.createIndex(
  { "type": 1 },
  {
    "name": "beerType",
    "background": true
  }
)

db.beerSample.createIndex(
  { "code": 1 },
  {
    "name": "code",
    "background": true,
    "partialFilterExpression": { "type": "brewery" }
  }
)

Pour les index qu'Amazon Q n'est pas en mesure de convertir, consultez la section Gestion des index et des propriétés d'index Amazon DocumentDB pour plus d'informations.

Refactorisez le code pour utiliser les API MongoDB

Les clients utilisent les SDK Couchbase pour se connecter au serveur Couchbase. Les clients Amazon DocumentDB utilisent des pilotes MongoDB pour se connecter à Amazon DocumentDB. Toutes les langues prises en charge par les SDK Couchbase sont également prises en charge par les pilotes MongoDB. Consultez la section Pilotes MongoDB pour plus d'informations sur le pilote correspondant à votre langue.

Les API étant différentes entre Couchbase Server et Amazon DocumentDB, vous devrez refactoriser votre code pour utiliser les API MongoDB appropriées. Vous pouvez utiliser Amazon Q pour convertir les appels d' K/V API et les requêtes SQL++ en API MongoDB équivalentes :

À l'aide de l'exemple de code Python de Hello Couchbase, Amazon Q génère les éléments suivants (extrait) :

from pymongo import MongoClient

# Connection parameters
database_name = "travel-sample"

# Connect to Amazon DocumentDB cluster
client = MongoClient('<Amazon DocumentDB connection string>',
                     tls=True,
                     tlsCAFile='global-bundle.pem')

# Get reference to database and collection
db = client['travel-sample']
airline_collection = db['airline']

# upsert document function
def upsert_document(doc):
    print("\nUpsert Result: ")
    try:
        # key will equal: "airline_8091"
        key = doc["type"] + "_" + str(doc["id"])
        doc['_id'] = key # Amazon DocumentDB uses _id as primary key
        result = airline_collection.update_one(
            {'_id': key},
            {'$set': doc},
            upsert=True
        )
        print(f"Modified count: {result.modified_count}")
    except Exception as e:
        print(e)

# get document function
def get_airline_by_key(key):
    print("\nGet Result: ")
    try:
        result = airline_collection.find_one({'_id': key})
        print(result)
    except Exception as e:
        print(e)

# query for document by callsign
def lookup_by_callsign(cs):
    print("\nLookup Result: ")
    try:
        result = airline_collection.find(
            {'callsign': cs},
            {'name': 1, '_id': 0}
        )
        for doc in result:
            print(doc['name'])
    except Exception as e:
        print(e)

# Test document
airline = {
    "type": "airline",
    "id": 8091,
    "callsign": "CBS",
    "iata": None,
    "icao": None,
    "name": "Couchbase Airways",
}

upsert_document(airline)
get_airline_by_key("airline_8091")
lookup_by_callsign("CBS")

Reportez-vous à la section Connexion par programmation à Amazon DocumentDB pour des exemples de connexion à Amazon DocumentDB en Python, PHP, Go Node.js, Java, C#/.NET, R et Ruby.

Sélectionnez l'approche de migration

Lorsque vous migrez des données vers Amazon DocumentDB, deux options s'offrent à vous :

Migration hors ligne

Envisagez une migration hors ligne lorsque :

Couchbase Server 6.x ou version antérieure

Compartiment Couchbase vers la collection Amazon DocumentDB

Exportez des données à l'aide de cbexport json pour créer un dump JSON de toutes les données du bucket. Pour l'--formatoption, vous pouvez utiliser lines oulist.

cbexport json \
  --cluster <source cluster endpoint> \
  --bucket <bucket name> \
  --format <lines | list> \
  --username <username> \
  --password <password> \
  --output export.json \
  --include-key _id

Importez les données dans une collection Amazon DocumentDB à l'aide de mongoimport avec l'option appropriée pour importer les lignes ou la liste :

lignes :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --file export.json

liste :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --jsonArray \
  --file export.json

Couchbase Server 7.0 ou version ultérieure

Pour effectuer une migration hors ligne, utilisez les outils cbexport et mongoimport :

Bucket Couchbase avec étendue et collection par défaut

Exportez des données à l'aide de cbexport json pour créer un dump JSON de toutes les collections du bucket. Pour l'--formatoption, vous pouvez utiliser lines oulist.

cbexport json \
  --cluster <source cluster endpoint> \
  --bucket <bucket name> \
  --format <lines | list> \
  --username <username> \
  --password <password> \
  --output export.json \
  --include-key _id

Importez les données dans une collection Amazon DocumentDB à l'aide de mongoimport avec l'option appropriée pour importer les lignes ou la liste :

lignes :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --file export.json

liste :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --jsonArray \
  --file export.json

Collections Couchbase vers collections Amazon DocumentDB

Exportez les données à l'aide de cbexport json pour créer un dump JSON de chaque collection. Utilisez l'--include-dataoption pour exporter chaque collection. Pour l'--formatoption, vous pouvez utiliser lines oulist. Utilisez les --collection-field options --scope-field et pour stocker le nom de l'étendue et de la collection dans les champs spécifiés de chaque document JSON.

cbexport json \
  --cluster <source cluster endpoint> \
  --bucket <bucket name> \
  --include-data <scope name>.<collection name> \
  --format <lines | list> \
  --username <username> \
  --password <password> \
  --output export.json \
  --include-key _id \
  --scope-field "_scope" \
  --collection-field "_collection"

Comme cbexport a ajouté les _collection champs _scope et à chaque document exporté, vous pouvez les supprimer de chaque document du fichier d'exportation par le biais de la fonction de recherche et de remplacementsed, ou de la méthode de votre choix.

Importez les données de chaque collection dans une collection Amazon DocumentDB à l'aide de mongoimport avec l'option appropriée pour importer les lignes ou la liste :

lignes :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --file export.json

liste :

mongoimport \
  --db <database> \
  --collection <collection> \
  --uri "<Amazon DocumentDB cluster connection string>" \
  --ssl \
  --sslCAFile global-bundle.pem \
  --jsonArray \
  --file export.json

Migration en ligne

Envisagez une migration en ligne lorsque vous devez minimiser les temps d'arrêt et que les modifications en cours doivent être répliquées sur Amazon DocumentDB en temps quasi réel.

Consultez Comment effectuer une migration en direct de Couchbase vers Amazon DocumentDB pour savoir comment effectuer une migration en direct vers Amazon DocumentDB. La documentation explique comment déployer la solution et effectuer une migration en direct d'un bucket vers un cluster Amazon DocumentDB.

Couchbase Server 6.x ou version antérieure

Compartiment Couchbase vers la collection Amazon DocumentDB

L'utilitaire de migration pour Couchbase est préconfiguré pour effectuer une migration en ligne d'un bucket Couchbase vers une collection Amazon DocumentDB. En ce qui concerne la configuration du connecteur récepteur, le document.id.strategy paramètre est configuré pour utiliser la valeur de la clé de message comme valeur de _id champ (voir Propriétés de la stratégie de l'identifiant du connecteur récepteur) :

ConnectorConfiguration:
  document.id.strategy: 'com.mongodb.kafka.connect.sink.processor.id.strategy.ProvidedInKeyStrategy'
      

Couchbase Server 7.0 ou version ultérieure

Bucket Couchbase avec étendue et collection par défaut

L'utilitaire de migration pour Couchbase est préconfiguré pour effectuer une migration en ligne d'un bucket Couchbase vers une collection Amazon DocumentDB. En ce qui concerne la configuration du connecteur récepteur, le document.id.strategy paramètre est configuré pour utiliser la valeur de la clé de message comme valeur de _id champ (voir Propriétés de la stratégie de l'identifiant du connecteur récepteur) :

ConnectorConfiguration:
  document.id.strategy: 'com.mongodb.kafka.connect.sink.processor.id.strategy.ProvidedInKeyStrategy'
      

Collections Couchbase vers collections Amazon DocumentDB

Configurez le connecteur source pour diffuser chaque collection Couchbase de chaque domaine vers une rubrique distincte (voir Options de configuration de la source). Par exemple :

ConnectorConfiguration:
  # add couchbase.collections configuration
  couchbase.collections: '<scope 1>.<collection 1>, <scope 1>.<collection 2>, ...'
      

Configurez le connecteur récepteur pour diffuser depuis chaque rubrique vers une collection Amazon DocumentDB distincte (voir Propriétés de configuration du connecteur récepteur). Par exemple :

ConnectorConfiguration:
  # remove collection configuration  
  #collection: 'test'
  
  # modify topics configuration
  topics: '<bucket>.<scope 1>.<collection 1>, <bucket>.<scope 1>.<collection 2>, ...'

  # add topic.override.%s.%s configurations for each topic 
  topic.override.<bucket>.<scope 1>.<collection 1>.collection: '<collection>'
  topic.override.<bucket>.<scope 1>.<collection 2>.collection: '<collection>'
      

Validation

Cette section décrit un processus de validation détaillé pour vérifier la cohérence et l'intégrité des données après la migration vers Amazon DocumentDB. Les étapes de validation s'appliquent quelle que soit la méthode de migration.

Vérifiez que toutes les collections existent dans la cible

Source : Couchbase

option 1 : pupitre de requêtes

SELECT RAW `path`
  FROM system:keyspaces
  WHERE `bucket` = '<bucket>'

option 2 : outil cbq

cbq \
  -e <source cluster endpoint> \
  -u <username> \
  -p <password> \
  -q "SELECT RAW `path`
       FROM system:keyspaces
       WHERE `bucket` = '<bucket>'"

Cible Amazon DocumentDB

mongosh (voir Connexion à votre cluster Amazon DocumentDB) :

db.getSiblingDB('<database>')
db.getCollectionNames()

Vérifier le nombre de documents entre les clusters source et cible

Source : Couchbase

Couchbase Server 6.x ou version antérieure

option 1 : pupitre de requêtes

SELECT COUNT(*)
FROM `<bucket>`

option 2 : cbq

cbq \
  -e <source cluster endpoint> \
  -u <username> \
  -p <password> \
  -q "SELECT COUNT(*)
       FROM `<bucket>`"

Couchbase Server 7.0 ou version ultérieure

option 1 : pupitre de requêtes

SELECT COUNT(*)
FROM `<bucket>`.`<scope>`.`<collection>`

option 2 : cbq

cbq \
  -e <source cluster endpoint> \
  -u <username> \
  -p <password> \
  -q "SELECT COUNT(*)
       FROM `<bucket>`.`<scope>`.`<collection>`"

Cible Amazon DocumentDB

mongosh (voir Connexion à votre cluster Amazon DocumentDB) :

db = db.getSiblingDB('<database>')
db.getCollection('<collection>').countDocuments()

Comparez les documents entre les clusters source et cible

Source : Couchbase

Couchbase Server 6.x ou version antérieure

option 1 : pupitre de requêtes

SELECT META().id as _id, *
FROM `<bucket>`
LIMIT 5

option 2 : cbq

cbq \
  -e <source cluster endpoint> \
  -u <username> \
  -p <password> \
  -q "SELECT META().id as _id, *
       FROM `<bucket>`
       LIMIT 5"

Couchbase Server 7.0 ou version ultérieure

option 1 : pupitre de requêtes

SELECT META().id as _id, *
FROM `<bucket>`.`<scope>`.`<collection>`
LIMIT 5

option 2 : cbq

cbq \
  -e <source cluster endpoint> \
  -u <username> \
  -p <password> \
  -q "SELECT META().id as _id, *
       FROM `<bucket>`.`<scope>`.`<collection>`
       LIMIT 5"

Cible Amazon DocumentDB

mongosh (voir Connexion à votre cluster Amazon DocumentDB) :

db = db.getSiblingDB('<database>')
db.getCollection('<collection>').find({
  _id: {
    $in: [
      <_id 1>, <_id 2>, <_id 3>, <_id 4>, <_id 5>
    ]
  }
})