Cómo migrar a Scopes y Collections en Couchbase 7.0

Ya sea que seas nuevo en Couchbase o como un veterano experimentado, probablemente hayas oído hablar de los Scopes y Collections. Si estás listo para probarlos por ti mismo, este artículo te ayuda a hacerlo realidad.

Scopes y Collections son una nueva característica introducida en la versión 7.0 de Couchbase Server que le permite organizar lógicamente los datos dentro de Couchbase. Para obtener más información, lee la siguiente introducción a Ámbito y colecciones.

Deberías aprovechar Scopes y Collections si quieres mapear tu RDBMS heredado a una base de datos de documentos o si estás intentando consolidar cientos de microservicios y/o inquilinos en un solo Couchbase clúster (lo que resulta en un TCO mucho menor).

En este artículo, repasaré cómo puedes planificar tu migración desde una versión anterior de Couchbase al uso de Ámbito y Colecciones en Couchbase 7.0.

Pasos de migración de alto nivel

Los siguientes son los pasos de alto nivel para migrar a Ámbitos y Colecciones en Couchbase 7.0.

No todos los pasos son esenciales: todo depende de su caso de uso y de sus requisitos tecnológicos particulares. Lo guiaré a través de los detalles de cada uno de estos pasos en las siguientes secciones.

1. Actualizar a Couchbase Server 7.0
2. Planifica tu estrategia de Scopes y CollectionsDetermine qué Buckets, Scopes, Collections e índices necesita. Determine el mapeo del o los Buckets antiguos a los nuevos Buckets/Scopes/Collections. Escriba scripts para crear Scopes, Collections e índices.
3. Migre el código de su aplicación: Este código de aplicación es su código de SDK de Couchbase, incluidas las consultas N1QL.
4. Migración de datos: Determine si una estrategia sin conexión funciona para su implementación o si necesita una migración en línea. Tome medidas en consecuencia.
5. Planifica e implementa tu estrategia de seguridad de bases de datos: Determine los usuarios y las asignaciones de roles que necesita. Cree scripts para administrar estas asignaciones.
6. Transmite en vivo con tu nueva aplicación compatible con Colecciones
7. Configurar XDCR y configurar la copia de seguridad para su base de datos Couchbase

Actualizar a Couchbase 7

Esto es lo que necesita saber sobre la actualización a Servidor Couchbase 7.0:

• Cada Bucket en 7.0+ tiene un _default Alcance con un _default Colección en él.
• Actualizar a Couchbase 7.0 mueve todos los datos del Bucket al _default Colección del Cubo.
• Hay sin impacto en las aplicaciones existentes. Por ejemplo, una referencia del SDK 2.7 a Bucket B se resuelve automáticamente B._default._default (haciendo referencia a _default Alcance y Recopilación, respectivamente).

El siguiente diagrama ilustra cómo se organizan los datos en Buckets, Scopes y Collections después de migrar datos de Couchbase 6 a Couchbase 7.

Si no desea utilizar Scopes y Collections con nombre, deténgase aquí mismo.

Pero si estás listo para usar esta nueva función de organización de datos, sigue leyendo.

Planifique su estrategia de ámbitos y colecciones

A continuación se encuentran los escenarios de migración de bases de datos más comunes con los que me he encontrado. Tu escenario de migración podría ser diferente y los resultados pueden variar.

Consolidación: De múltiples buckets a colecciones en un solo bucket

Un escenario común es cuando intentas reducir tu costo total de propiedad (TCO) consolidando múltiples buckets en un solo bucket.

Un clúster solo puede tener hasta 30 buckets, mientras que puedes tener 1000 colecciones por clúster, lo que permite una densidad mucho mayor. Este es un escenario común para la consolidación de microservicios.

El diagrama anterior muestra todas las Colecciones de destino pertenecientes al mismo Ámbito. Pero también podría darse el caso de que las Colecciones de destino pertenecieran a diferentes Ámbitos.

División: De un solo depósito a múltiples colecciones en un depósito

Otro escenario común es migrar los datos que residen dentro de un solo Bucket y dividirlos en múltiples Colecciones (dentro del mismo Bucket).

Es posible que antes hayas calificado diferentes tipos de datos con un tipo = foo campo o con un prefijo de clave como foo_key. Ahora cada uno de estos tipos de datos puede residir en su propia colección, lo que le brinda las ventajas del aislamiento lógico, el aislamiento de seguridad, la replicación y el control de acceso.

Este escenario puede ser un poco más complejo que el escenario de “consolidación” anterior, especialmente si desea deshacerse del prefijo de clave o del campo de tipo. Para una migración más sencilla, es posible que prefiera dejar los prefijos de clave y los campos de datos de tipo tal como están, aunque puedan ser algo redundantes con las Colecciones.

Creación de Scopes, Collections e Indexes

Una vez que hayas planeado qué Scopes, Collections e índices deseas tener, necesitas crear scripts para la creación de estas entidades. Puedes usar el SDK de Couchbase de tu elección, el couchbase-cli, las API REST directamente, o incluso scripts de N1QL para hacerlo.

A continuación se muestra un ejemplo de cómo utilizar la CLI (couchbase-cli y la terminal cbq) para crear un Scope, un Collection y un índice.

Tenga en cuenta que creación de índice la declaración hace no requiero que califiques los datos con un tipo = foo o cláusula de calificación de prefijo de clave.

Migre el código de su aplicación

Para utilizar Scopes y Collections con nombre, el código de su aplicación (incluido Consultas N1QL) necesita ser migrado.

Si anteriormente usaba campos de tipo o prefijos de clave (como en el escenario de división), no los necesito más.

Ejemplo de código de SDK

En el código de su SDK, debe conectarse a un clúster, abrir un Bucket y obtener una referencia a un objeto Collection para almacenar y recuperar documentos. Antes de Collections, todas las operaciones de clave-valor se realizaban directamente en el Bucket.

Nota: Si ha migrado a Couchbase SDK 3.0, ya ha realizado parte del trabajo para comenzar a usar Colecciones (aunque hasta ahora solo podía usar la Colección predeterminada).

Lo siguiente es un simple SDK de Java fragmento de código para almacenar y recuperar un documento en una Colección:

Consultas N1QL

Ahora, si quieres correr una consulta N1QL en la Collection del ejemplo de Java anterior, haga lo siguiente:

Note que puede consultar directamente en un Scope. La consulta anterior en el objeto Scope se asigna automáticamente a select * from bucket-name.scope-name.collection-name.

Otra forma de proporcionar contexto de ruta a N1QL es establecerlo en OpcionesDeConsulta. Por ejemplo:

Un ámbito puede tener múltiples colecciones, y puedes unirlas directamente haciendo referencia al nombre de la colección dentro del ámbito. Si necesitas hacer consultas entre ámbitos (o entre cubos), entonces es mejor usar el objeto clúster para realizar la consulta.

Tenga en cuenta que las consultas N1QL ya no necesitan calificar un tipo = foo campo (o prefijo_de_clave calificador), si corresponde.

Por ejemplo, esta antigua consulta N1QL...

...ahora se convierte en:

Migración de datos a Colecciones

A continuación, debe migrar los datos existentes a sus nuevos ámbitos y colecciones con nombre.

Lo primero que debes determinar es si puedes permitirte hacer una migración desconectada (donde tu aplicación está desconectada durante unas horas), o si necesitas hacer una migración mayormente en línea con un tiempo de inactividad mínimo de la aplicación.

Una migración sin conexión podría ser más rápida en general y requerir menos recursos adicionales en términos de espacio en disco o nodos adicionales.

Migración sin conexión

Si decides hacer una migración fuera de línea, puedes usar N1QL o Respaldo/Restauración. Analizaremos ambas opciones con más detalle.

Using N1QL for an Offline Migration

Prerequisite: Your cluster must have spare disk space and be using the Query Service.

Following this approach, your migration would look something like the following:

1. Create new Scopes, Collections and indexes.
2. Take old application offline.
3. For each named Collection:
   • Insert-Select from _default Collection to named Collection (using appropriate filters).
   • Delete data from _default Collection that was migrated in above step (to save space; or if space is not an issue, you can do this at the end).
4. Verify your migrated data.
5. Drop old Buckets.
6. Online your new application.

Using Backup/Restore for an Offline Migration

Prerequisite: You need disk space to store backup files.
With this approach, your migration would look like this:

1. Create new Scopes, Collections and indexes
2. Take application offline
3. Take backup (cbbackupmgr) of 7.0 cluster
4. Restore using explicit mapping to named Collections. Use --filter-keys y --map-data (see examples 1 and 2 below).
5. Online your new application.

Example 1: No Filtering during Restore

This example moves the entire _default Collection to a named Collection. (This is the likely case for the consolidation scenario).

Example 2: Restore with Filtering

This example moves portions of _default Collection to different named Collections (This is the likely case for the splitting scenario).

Online Migration Using XDCR

In order to do a mostly online migration, you need to use cross data center replication (XDCR).

Depending on your spare capacity in the existing cluster, you can do self-XDCR (where the source and destination Bucket are on the same cluster), or you can set up a separate cluster to replicate to.

Here are the steps you need to follow:

1. Setup XDCR from yoursource cluster to your target cluster (you can do self-XDCR if you have spare disk space and compute resources on the original cluster).
2. Create new Buckets, Scopes and Collections.
3. Set up replications either directly from a Bucket to a bucket.scope.collection or using Migration Mode (details shown below) if a single Bucket’s default Collection has to be split into multiple Collections.
4. Explicit mapping rules are specifiable for each destination to specify subset of the data.
5. Once replication destinations are caught up, offline your old application.
6. Online your new application directing it to the new cluster (or new Bucket if using self-XDCR).
7. Delete your old cluster (or your old Bucket if using self-XDCR).

Using XDCR to Migrate from Multiple Buckets to a Single Bucket

These steps are for the consolidation scenario.

The XDCR set up will look something like the following:

• For each source Bucket, set up a replication to the named Collection in the destination Bucket and Scope

The following screenshot shows the XDCR set up for one source Bucket:

Using XDCR to Split to Multiple Collections from within a Single Bucket

These steps are for the splitting scenario.

In order to map the source _default Collection to multiple target Collections, you should use the Migration Mode provided by XDCR.

The XDCR screens below show Migration Mode being used:

There are four filters you need to set up: (Travel-sample._default._default is the source. A new Bucket called Viajar is the target.)

• filter type="airport", replicate to Inventory:Airport
• filter type="airline", replicate to Inventory:Airline
• filter type="hotel", replicate to Inventory:Hotel
• filter type="route", replicate to Inventory:Route

Plan & Implement Your Database Security Strategy

Now that you have all your data in named Scopes and Collections, you have finer control over what data you can assign privileges to. Previously you could do so only at Bucket level.

For more information on role-based access control (RBAC) security for Scopes and Collections, read this article: Introducing RBAC Security for Collections or consult the documentation on RBAC.

The following roles are available at Scope and Collection level in Couchbase 7.

Admin Roles:

• Scope Admin role is available at the Scope level. A Scope admin can administer Collections in their Scope.

Data Reader Roles:

• Data Reader
• Data Writer
• Data DCP Reader
• Data Monitoring

Query Roles:

• FTS Searcher
• Query Select
• Query Update
• Query Insert
• Query Delete
• Query Manage Index
• Query Manage Functions
• Query Execute Functions

Conclusión

I hope this guide helps you successfully migrate to Scopes and Collections in Couchbase 7.

For more information on the 7.0 release, check out the What’s New documentation o peruse the release notes.

What do you think of the new Scopes and Collections feature? I look forward to hearing your feedback on the Couchbase Forums.

Ready to try out Scopes and Collections for yourself?
Dig into Couchbase 7 today