/ /

`start`

Descripción

Inicia la sincronización entre un clúster de origen y un clúster de destino.

Requisitos

Estado

Para utilizar el endpoint start, mongosync debe estar en el estado IDLE.

Permisos

El usuario especificado en la cadena de conexión mongosync debe tener los permisos requeridos en los clústeres de origen y destino. Consultar Permisos de usuario para asegurar que el usuario tenga los permisos correctos para iniciar la sincronización.

Instancias múltiples de `mongosync`

Asegura que uses el usuario mongosync configurado en las cadenas de conexión para la configuración de cluster0 o cluster1 cuando inicies mongosync.

Nota

Cuando configures múltiples instancias de mongosync para sincronizarse entre clústeres fragmentados, debes enviar comandos idénticos de puntos finales API a cada instancia de mongosync.

Para obtener más información, consulte Iniciar múltiples Mongosyncs.

Solicitud

POST /api/v1/start

Parámetros del cuerpo de la solicitud

Parameter

Tipo

Necesidad

Descripción

source

string

Requerido

Nombre del clúster de origen.

destination

string

Requerido

Nombre del clúster de destino.

buildIndexes

string

Opcional

Configura la creación de índices durante la sincronización.

Opciones admitidas:

afterDataCopy (por defecto en los clústeres de origen que ejecutan MongoDB 6.0 o una versión posterior) permite que mongosync construya índices en el clúster de destino después de la copia de colección. Esto incluye los índices que existen en el clúster de origen en el momento de la inicialización y los índices que se crean durante la migración. Esto resulta en una migración más rápida para las bases de datos indexadas.
Si el valor de buildIndexes es afterDataCopy y se configura createSupportingIndexes en false al migrar a un clúster, mongosync crea un índice ficticio para soportar la clave de partición. mongosync intenta descartar este índice ficticio después de que se llama commit. Si no existen índices creados por el usuario para soportar la clave de partición, se producirá un error al eliminar el índice ficticio. Se recomienda a los usuarios descartar el índice ficticio y crear su propio índice después de completar la migración.
IMPORTANTE: este parámetro solo es compatible con clústeres de origen que ejecutan MongoDB 6.0 o posterior.
beforeDataCopy (el por defecto en los clústeres de origen que ejecutan una versión anterior a6.0) hace que mongosync genere índices en el clúster de destino durante la inicialización. Esto incluye los índices que existen en el clúster de origen en el momento de la inicialización y los índices que se crean durante la migración.
excludeHashed hace que mongosync omita la creación de índices hasheados durante la sincronización. Esto puede mejorar el rendimiento para grandes colecciones.
excludeHashedAfterCopy hace que mongosync compile índices que no se encriptada en el clúster de destino después de la copia de la colección. excludeHashedAfterCopy también omite la construcción de índices encriptados. Esto se traduce en una migración más rápida para las bases de datos indexadas, tanto por la creación de índices después de la copia inicial de datos como por la omisión de la creación de índices encriptada.
Si el valor de buildIndexes es excludeHashedAfterCopy y se configura createSupportingIndexes en false al migrar a un clúster, mongosync crea un índice ficticio para soportar la clave de partición. mongosync intenta descartar este índice ficticio después de que se llama commit. Si no existen índices creados por el usuario para soportar la clave de partición, se producirá un error al eliminar el índice ficticio. Se recomienda a los usuarios descartar el índice ficticio y crear su propio índice después de completar la migración.
IMPORTANTE: este parámetro solo es compatible con clústeres de origen que ejecutan MongoDB 6.0 o posterior.
never hace que mongosync omita la creación de índices innecesarios durante la sincronización. Esto puede mejorar el rendimiento de la migración, especialmente con cargas de trabajo pesadas de índices.
Si inicias la sincronización con la verificación habilitada y buildIndexes configurado en never, la migración fallará si mongosync encuentra una colección TTL en el clúster de origen. Esto puede suceder después de que llames al endpoint /start o mucho más tarde, como cuando un usuario crea un índice TTL en el clúster de origen mientras una migración está en curso.
Para sincronizar colecciones TTL sin crear índices en el clúster de destino, debes iniciar la sincronización con el verificador deshabilitado.
ADVERTENCIA: No construya manualmente índices en el clúster de destino mientras mongosync esté realizando una migración. Espere hasta que la migración esté completamente comprometida.
Para obtener más información sobre los índices que sí compila, consulta Índices obligatorios.

/start devuelve un error cuando buildIndexes se establece en never y reversible se establece en true.

Si llamas a /start sin especificar la opción buildIndexes, mongosync crea índices en el clúster de destino.

Novedad en la versión 1.3.0.

enableUserWriteBlocking

string o booleano

Opcional

IMPORTANTE: este parámetro solo es compatible con clústeres de origen que ejecutan MongoDB 6.0 o posterior.

Opciones admitidas:

"sourceAndDestination": bloquea las escrituras en el clúster de destino mientras la migración está en curso, y desbloquea las escrituras justo antes de que el endpoint /progress informe que canWrite está true. Bloquea las escrituras en el clúster de origen después de que mongosync llama al endpoint /confirmación.
También puedes usar true para la compatibilidad retroactiva.
"none": no se produce bloqueo de guardado. También puedes usar false para la compatibilidad con versiones anteriores.
"destinationOnly"bloquea las escrituras en el clúster de destino mientras la migración está en progreso y desbloquea las escrituras justo antes de que canWrite esté true.

Para la sincronización inversa, el campo enableUserWriteBlocking debe configurarse en "sourceAndDestination". Para permitir que el clúster de origen acepte escrituras nuevamente, por ejemplo, después de ejecutar pruebas de migración, ejecute el siguiente comando:

db.adminCommand( { setUserWriteBlockMode: 1, global: false } )

El valor por defecto es "destinationOnly".

includeNamespaces

arreglo

Opcional

Filtra las bases de datos o colecciones para incluir en la sincronización.

Si configuras un filtro en un clúster de origen que tiene varias bases de datos, mongosync solo sincroniza las bases de datos especificadas en la definición del filtro. mongosync no sincronizará las otras bases de datos existentes.

Si deseas modificar el filtro para añadir una base de datos recién creada, debes reiniciar la sincronización filtrada desde el principio.

Para más detalles, consulte Sincronización Filtrada.

Para ver las limitaciones actuales, consulta Sincronización filtrada.

Novedad en la versión 1.1.

excludeNamespaces

arreglo

Opcional

Filtra las bases de datos o colecciones que se deben excluir de la sincronización.

Si deseas modificar el filtro para añadir una base de datos recién creada, debes reiniciar la sincronización filtrada desde el principio.

Para más detalles, consulte Sincronización Filtrada.

Para ver las limitaciones actuales, consulta Sincronización filtrada.

Novedad en la versión 1.6.

copyInNaturalOrder

arreglo de documentos

Opcional

Copia una lista de bases de datos y colecciones en su orden natural al clúster de destino. El orden natural es el orden en el que previamente se insertaron los documentos en la base de datos. Debe pasar un arreglo de documentos que representen cada uno una base de datos y sus colecciones. Para un ejemplo de sintaxis, consulte Capacidad de escaneo natural.

IMPORTANTE: Solo utiliza la opción copyInNaturalOrder para conjuntos de elementos que explícitamente configuren un campo aleatorio _id. Usar esta opción para colecciones de tamaño 30GB o mayor reduce significativamente el tiempo que toma la fase de copia de colecciones.

ADVERTENCIA: Si /resume una mongosync migración después de /pause o una interrupción que tenga la opción copyInNaturalOrder activada para colecciones de más de 500GB de tamaño, la migración puede llevar varias horas en completarse.

preExistingDestinationData

booleano

Opcional

IMPORTANTE: Esta funcionalidad se encuentra actualmente en Vista Previa Pública. Por favor revisa el comportamiento y las limitaciones en esta sección para utilizar esta funcionalidad en entornos de producción.

El valor por defecto es false.

Si se configura en true:

mongosync permite espacios de nombres preexistentes en el clúster de destino.
Debes especificar un filtro de espacio de nombres mediante uno o ambos de los parámetros includeNamespaces y excludeNamespaces en tu solicitud.
Si la verificación embebida está habilitada, el filtro de namespace debe filtrar cualquier colección o índice preexistente en el clúster de destino, incluso si no existen en el clúster de origen. De lo contrario, se produce un error en la verificación incrustada.
Asegúrate de seguir todas las instrucciones en el proceso de cambio para garantizar que no se produzcan guardados inseguros en el clúster de origen o de destino. mongosync no habilita el bloqueo de escritura cuando activas esta funcionalidad, por lo que debes asegurarte manualmente de que estos guardados no se produzcan.
mongosync no garantiza que existan los recursos suficientes, como espacio en disco, capacidad de cómputo y oplog, en el clúster de destino para acomodar la carga adicional de la migración. Supervisa tu clúster de destino para asegurarte de que disponga de recursos suficientes.
mongosync no migra vistas cuando se usa esta funcionalidad. Ignora las vistas en el clúster de origen durante la migración. Debes migrar las visualizaciones por separado después del cambio.
El nivel de carga por defecto cambió de 3 a 2.
Puede dejar el balanceador habilitado para un clúster de destino particionado durante la migración.
El modo de bloqueo de escritura por defecto se cambió de "destinationOnly" a "none". No puede establecer el bloqueo de escritura en colecciones individuales, ya sea en el clúster de origen o en el de destino, porque el bloqueo de escritura solo está disponible a nivel de clúster. Además, el filtrado por espacio de nombres no es compatible con el doble bloqueo de escritura.
mongosync no permite la migración inversa.

mongosync muestra el siguiente mensaje de registro al inicio de la migración:

ATTENTION! Data migration to a non-empty cluster is allowed
with the preExistingDestinationData set to true in the
request to start migration. This feature is currently in
preview. Please see https://www.mongodb.com/es/docs/cluster-to-cluster-sync/current/reference/api/start/
for important requirements and limitations.

Consulta Limitaciones de sincronización filtrada.

reversible

booleano

Opcional

Si se establece en true, permite que la operación de sincronización se revierta.

Para realizar la sincronización inversa, el campo enableUserWriteBlocking debe estar establecido en sourceAndDestination.

Esta opción no está soportada para las siguientes configuraciones:

Sincronización desde un set de réplicas a un clúster particionado
Sincroniza clústeres fragmentados que tengan diferentes números de particiones.
Sincronización reversible cuando buildIndexes está configurado en never.

IMPORTANTE: la configuración de reversible a true solo es compatible para clústeres de origen que ejecutan MongoDB 6.0 o posterior.

Para obtener más información, consulta el endpoint reverse.

El valor por defecto es false.

sharding

Documento

Opcional

Configura la sincronización entre un set de réplicas y un clúster. La sincronización de un set de réplicas a un clúster requiere esta opción.

Para obtener más información, vea Parámetros de particionado.

Novedad en la versión 1.1.

verification

Documento

Opcional

Configura el verificador embebido.

Para obtener más información, consulte Validador embebido.

Nuevo en la versión 1.9.

verification.enabled

bool

Opcional

Habilita el verificador integrado. El verificador realiza una serie de comprobaciones de verificación en las colecciones admitidas en el clúster de destino para confirmar que la migración fue exitosa.

Si el verificador no encuentra errores, mongosync pasa al estado COMMITTED. Si encountera errores, falla la migración.

El verificador está habilitado por defecto.

ADVERTENCIA: El verificador no revisa todas las colecciones o datos. Para más detalles, consulta Embedded Verifier.

Nuevo en la versión 1.9.

Parámetros de partición

Novedad en la versión 1.1.

Para sincronizar desde un set de réplicas a un clúster, configura la opción sharding para particionar las colecciones en el clúster de destino.

mongosync lanza un error si la opción sharding no está configurada cuando se sincroniza desde un set de réplicas a un clúster fragmentado. mongosync también lanza un error si la opción sharding se configura con cualquier otra configuración.

La opción sharding tiene los siguientes parámetros:

Parameter	Tipo	Descripción
`createSupportingIndexes`	booleano	opcional. Configura si la sincroniza crea un índice de soporte para la clave de partición, si no se ha creado ninguno previamente. El valor por defecto es `false`. Si el valor de `buildIndexes` es `"afterDataCopy"` o `"excludeHashedAfterCopy"` y estableces createSupportingIndexes en `false` mientras migras a un clúster particionado, `mongosync` crea un índice dummy para soportar la clave de partición. `mongosync` intenta descartar este índice ficticio después de que se haya llamado a `commit`. Si no existen índices creados por usuarios para respaldar la clave de partición, la eliminación del índice ficticio fallará. Se recomienda a los usuarios descartar el índice ficticio y crear su propio índice después de completar la migración. Si se establece este parámetro en `true` y se establece `buildIndexes` en `"excludeHashed"` o `"excludeHashedAfterCopy"`, entonces `mongosync` no crea índices hash de soporte para clave de partición con hash en el clúster de destino. `mongosync` aún crea índices de apoyo no encriptada para claves de fragmento no encriptada. Para obtener más información y limitaciones, consulta Índices de soporte.
`shardingEntries`	arreglo de documentos	Obligatorio. Establece el namespace y la clave de las colecciones a partición durante la sincronización. Las colecciones que no están incluidas en este arreglo se sincronizan con las colecciones no fragmentadas en el clúster de destino. Si se configura con un arreglo vacío, no se crean particiones de las colecciones.
`shardingEntries` `.collection`	string	Establece la partición de la colección.
`shardingEntries` `.database`	string	Establece la base de datos de la colección a partición.
`shardingEntries` `.shardCollection`	Documento	Establece la clave de partición que se generará en el clúster de destino.
`shardingEntries` `.shardCollection` `.key`	arreglo	Establece los campos que se utilizarán para la clave de partición. Para obtener más información, consulte Claves de partición.

Respuesta

Campo	Tipo	Descripción
`success`	booleano	Cuando la solicitud es exitosa, este valor es `true`.
`error`	string	Si se produce un error, se indicará el nombre del error. Este campo se omite de la respuesta cuando `success` es `true`.
`errorDescription`	string	Descripción detallada del error que ocurrió. Este campo se omite en la respuesta cuando `success` es `true`.

Ejemplos

Iniciar una tarea de sincronización

El siguiente ejemplo inicia un trabajo de sincronización entre el clúster de origen cluster0 y el clúster de destino cluster1.

solicitud:

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1"
   } '

Respuesta:

{"success":true}

Inicia una tarea de sincronización reversible

El siguiente ejemplo inicia un trabajo de sincronización entre el clúster de origen cluster0 y el clúster de destino cluster1.

Los campos reversible y enableUserWriteBlocking permiten que la sincronización sea reversible. Para invertir la dirección de la sincronización, consulta: inverso.

solicitud:

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "reversible": true,
      "enableUserWriteBlocking": "sourceAndDestination"
   } '

Respuesta:

{"success":true}

Iniciar una tarea de sincronización filtrada

El siguiente ejemplo inicia un trabajo de sincronización entre el clúster de origen cluster0 y el clúster de destino cluster1.

cluster0 contiene las bases de datos sales, marketing y engineering.

La base de datos sales contiene las colecciones EMEA, APAC y AMER.

El arreglo includeNamespaces en este ejemplo define un filtro en dos de las bases de datos, sales y marketing.

La base de datos sales también filtra en las colecciones EMEA y APAC.

"includeNamespaces" : [
      {
          "database" : "sales",
          "collections": [ "EMEA", "APAC" ]
      },
      {
          "database" : "marketing"
      }
   ]

Después de que llames a la API /start con este filtro activado, mongosync:

Sincroniza todas las colecciones en la base de datos marketing
Filtra la base de datos engineering
Sincroniza las colecciones EMEA y APAC de la base de datos sales
Se filtra la colección AMER

La opción includeNamespaces crea un filtro. Para filtrar la sincronización, consulta: Sincronización filtrada

solicitud:

curl -X POST "http://localhost:27182/api/v1/start" --data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "includeNamespaces": [
         {
             "database": "sales",
             "collectionsRegex": {
                "pattern": "^accounts_.+$",
                "options": "i"
             }
         }, {
            "database": "marketing"
         }
      ]
   } '

Respuesta:

{"success":true}

Iniciar sincronizar desde set de réplicas a clúster

El siguiente ejemplo inicia una tarea de sincronización entre el set de réplicas de origen cluster0 y el clúster fragmentado de destino cluster1. El arreglo key en este ejemplo define la clave de partición {"location": 1, "region": 1 }.

solicitud:

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "sharding": {
         "createSupportingIndexes": true,
         "shardingEntries": [
            {
                "database": "accounts",
                "collection": "us_east",
                "shardCollection": {
                   "key": [
                      { "location": 1 },
                      { "region": 1 }
                   ]
                }
            }
         ]
      }
   } '

Respuesta:

{"success":true}

Inicia con el Verificador deshabilitado

A partir de 1.9, el verificador incrustado se ejecuta por defecto cuando se inicia una migración. Si necesitas deshabilitarlo, configura verification.enabled a false.

solicitud:

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "verification": {
         "enabled": false
      }
   } '

Respuesta:

{"success":true}

Debes verificar que una migración fuera exitosa antes de transferir la carga de tu aplicación al clúster de destino. Si necesita desactivar el verificador por cualquier motivo, utilice un método alternativo para verificar la sincronización.

Comportamiento

Verificador Integrado

A partir de 1.9, mongosync proporciona un verificador integrado para determinar si la transferencia de datos del clúster de origen al de destino fue exitosa.

Cuando se activa, el verificador realiza una serie de comprobaciones de verificación en el clúster de destino. Si alguna de estas comprobaciones devuelve un error, el verificador falla la migración. Si todas las comprobaciones se realizan correctamente, mongosync pasa al estado COMMITTED.

Para desactivar el verificador, consulta Comenzar con el verificador desactivado.

El punto de enlace /start devuelve un error si se habilitan controles de verificación que no son compatibles con el clúster de origen o destino, o si no hay suficiente memoria.

Estado

Si la solicitud start es exitosa, mongosync entra en el estado RUNNING.

Partición Set de Réplicas

Sincronizar desde un set de réplicas a un clúster requiere la opción sharding. Esta opción configura cómo mongosync las colecciones de fragmentos.

El arreglo sharding.shardingEntries especifica las colecciones a particionar. Las colecciones que no se listan en este arreglo se replican como no fragmentadas.

Para obtener más información, consulta Comportamiento de clúster particionado.

Índices de soporte

mongosync sincroniza los índices del clúster de origen al clúster de destino. Cuando se sincroniza desde un set de réplicas a un clúster particionado, mongosync puede requerir un índice adicional para admitir la clave de partición, que puede no existir en el clúster de origen.

mongosync puedes crear índices auxiliares para colecciones particionadas durante la sincronización. Esto se realiza estableciendo la opción sharding.createSupportingIndexes.

Cuando sharding.createSupportingIndexes es false (el valor por defecto):

Cada clave de partición proporcionada para la opción sharding.shardingEntries debe tener un índice existente en el clúster de origen.
Uno de los índices utilizados para la clave de partición debe tener una intercalación simple si la colección utiliza cualquier otra intercalación.
Para usar un índice único en la clave de partición, debes especificar su unicidad cuando crees el índice en el clúster de origen.
Los índices únicos en el clúster de origen que son incompatibles con la clave de partición solicitada en el clúster de destino, como un índice único en el origen que no contiene la clave de partición solicitada como prefijo en el clúster de destino, pueden causar que mongosync falle.
Si el valor de buildIndexes es "afterDataCopy" o "excludeHashedAfterCopy" y configuras createSupportingIndexes en false durante la migración a un clúster, mongosync crea un índice dummy para soportar la clave de partición. mongosync intenta descartar este índice simulado después de que se llama a commit. Si no existen índices creados por el usuario para admitir la clave de partición, al eliminar el índice ficticio, la operación fallará. Se recomienda a los usuarios descartar el índice temporal y crear su propio índice después de que la migración se complete.

Cuando sharding.createSupportingIndexes es true:

Si los índices de soporte existen en el clúster de origen, mongosync sincroniza los índices con el clúster de destino y los utiliza como claves de partición.
Si los índices de soporte no existen, mongosync los crea en el clúster de destino.

La opción sharding.createSupportingIndexes afecta a todas las colecciones fragmentadas.

Renombrar Durante la Sincronización

Las colecciones listadas en el arreglo sharding.shardingEntries al sincronizarse de un set de réplicas a un clúster, se convierten en colecciones particionadas en el clúster de destino.

Renombrar una colección (como con el comando renameCollection) en el clúster de origen después de llamar a start pero antes de que mongosync comience a copiar la colección puede bloquear la partición de la colección en el destino.

Nota

No se admite renombrar colecciones para usar una base de datos diferente mientras se sincroniza desde un set de réplicas a un clúster fragmentado.

Para comprobar si es seguro renombrar colecciones, llama al endpoint progress y revisa el valor del campo collectionCopy.estimatedCopiedBytes en el documento de retorno.

Un valor de 0 indica que mongosync no ha comenzado a copiar la colección.
Renombrar una colección en este punto puede resultar en una colección no particionada en el clúster de destino, ya que la transición a la copia puede ocurrir antes de que el cambio de nombre surta efecto en el origen.
Un valor mayor que 0 indica que mongosync ha empezado a copiar. Renombrar la colección desde este punto en adelante no bloquea su particionado en el clúster de destino, incluso en el evento de un fallo.

Índices requeridos

Cuando se llama a /start con la opción buildIndexes configurada en never, mongosync omite crear índices innecesarios.

Los índices que siempre se compilan incluyen:

mongosync construye un índice en el campo _id de cada colección que copia.
mongosync construye índices ficticios para cada colección particionada que no tenga un índice para admitir la clave de partición en el clúster de destino. Cuando buildIndexes se establece en never, mongosync mantiene este índice después de la confirmación.

Protección de endpoints

mongosync no protege el punto de conexión start. Sin embargo, por defecto, la API se vincula únicamente a localhost y no acepta llamadas de otras fuentes. Además, la llamada start no expone credenciales de conexión ni datos de usuario.

Capacidad de escaneo natural

Cuando se llama a /start con la opción copyInNaturalOrder, se deben especificar las bases de datos y colecciones mediante documentos, como en el siguiente ejemplo.

solicitud:

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": "sales",
        "collections": [
          "accounts",
          "orders",
        ]
      },
      {
        "database": "marketing",
        "collections": [
          "offers",
        ]
      },
    ]
  }'

Respuesta:

{"success":true}

ADVERTENCIA: Si habilita la migración para colecciones con campos _id no aleatorios, la fase de copia de la colección puede requerir más tiempo para completarse cuando especifique copyInNaturalOrder.

Puedes utilizar copyInNaturalOrder para copiar todas las colecciones en varias bases de datos en su orden natural, como en el siguiente ejemplo.

solicitud:

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": "sales",
      },
      {
        "database": "marketing",
      },
    ]
  }'

Respuesta:

{"success":true}

Puede usar copyInNaturalOrder para copiar todas las bases de datos y sus colecciones en su orden natural.

solicitud:

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": ".",
      },
    ]
  }'

Respuesta:

{"success":true}

Volver

Configuración

progreso

Descripción

Requisitos

Estado

Permisos

Instancias múltiples de mongosync

Nota

Solicitud

Parámetros del cuerpo de la solicitud

Parámetros de partición

Respuesta

Ejemplos

Iniciar una tarea de sincronización

Inicia una tarea de sincronización reversible

Iniciar una tarea de sincronización filtrada

Iniciar sincronizar desde set de réplicas a clúster

Inicia con el Verificador deshabilitado

Comportamiento

Verificador Integrado

Estado

Partición Set de Réplicas

Índices de soporte

Renombrar Durante la Sincronización

Nota

Índices requeridos

Protección de endpoints

Capacidad de escaneo natural

Instancias múltiples de `mongosync`