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 necesarios en los clústeres de origen y destino. Consulte
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 | |||||
|---|---|---|---|---|---|---|---|---|
| string | Requerido | Nombre del clúster de origen. | |||||
| string | Requerido | Nombre del clúster de destino. | |||||
| string | Opcional | Configura la creación de índices durante la sincronización. Opciones admitidas:
Si llama a Novedad en la versión 1.3.0. | |||||
| booleano | Opcional | Cuando Para especificar explícitamente las colecciones que Por defecto, ADVERTENCIA: Para las colecciones que | |||||
| 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:
Para la sincronización inversa, el campo El valor por defecto es | |||||
| 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, 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 obtener más detalles, consulte Sincronización filtrada. Para ver las limitaciones actuales, consulta Sincronización filtrada. Novedad en la versión 1.1. | |||||
| arreglo | Opcional | Filtra las bases de datos o colecciones que se excluirán de la sincronización. Si configuras un filtro en un clúster de origen que tiene varias bases de datos, 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 obtener más detalles, consulte Sincronización filtrada. Para ver las limitaciones actuales, consulta Sincronización filtrada. Novedad en la versión 1.6. | |||||
| 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: Use la ADVERTENCIA: La opción detectRandomId utiliza un umbral de tamaño de colección inferior, de 20 GiB, porque comprueba rigurosamente que las colecciones tengan un bajo grado de correlación entre los valores de | |||||
| 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 Si se configura en
| |||||
| booleano | Opcional | Si se establece en Para revertir la sincronización, el campo Esta opción no está soportada para las siguientes configuraciones:
IMPORTANTE: la configuración de reversible a Para obtener más información, consulte el punto final inverso. El valor por defecto es | |||||
| 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. | |||||
| Documento | Opcional | Configura el verificador embebido. Para obtener más información, consulte Verificador integrado. Nuevo en la versión 1.9. | |||||
| Booleano | 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, El verificador está habilitado de forma predeterminada. ADVERTENCIA: El verificador no verifica todas las colecciones ni todos los datos. Para más información, consulte Verificador integrado. 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 genera un error si la opción sharding no está configurada al sincronizar desde un conjunto de réplicas a un clúster fragmentado. mongosync también genera un error si la opción sharding está configurada con cualquier otra configuración.
La opción sharding tiene los siguientes parámetros:
Parameter | Tipo | Descripción |
|---|---|---|
| booleano | Opcional. Establece si la sincronización crea un índice de apoyo para la clave de fragmento, si no existe ninguno. El valor predeterminado es Si el valor de Si se establece este parámetro en Para obtener más información y conocer las limitaciones,consulte Índices de soporte. |
| arreglo de documentos | Obligatorio. Establece el namespace y la clave de las colecciones a partición durante la sincronización. Las colecciones no incluidas en esta matriz se sincronizan con las colecciones no fragmentadas del clúster de destino. Si se configura con una matriz vacía, no se fragmenta ninguna colección. |
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 fragmento. Para obtener más información, consulte Claves de partición. |
Respuesta
Campo | Tipo | Descripción |
|---|---|---|
| booleano | Cuando la solicitud es exitosa, este valor es |
| string | Si se produce un error, se indicará el nombre del error. Este campo se omite de la respuesta cuando |
| string | Descripción detallada del error ocurrido. Este campo se omite en la respuesta cuando |
Ejemplos
Iniciar un trabajo 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 un trabajo de sincronización filtrado
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 las colecciones EMEA y APAC.
"includeNamespaces" : [ { "database" : "sales", "collections": [ "EMEA", "APAC" ] }, { "database" : "marketing" } ]
Después de llamar a la API /start con este filtro implementado, mongosync:
Sincroniza todas las colecciones en la base de datos
marketingFiltra la base de datos
engineeringSincroniza las colecciones
EMEAyAPACde la base de datossalesSe 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 sincronización desde el conjunto de réplicas al clúster fragmentado
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 integrado se ejecuta de forma predeterminada al iniciar una migración. Si necesita desactivarlo, configure verification.enabled en 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 ingresa al 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 con el de destino. Al sincronizar desde un conjunto de réplicas a un clúster fragmentado, mongosync podría requerir un índice adicional para admitir la clave de fragmentación, que podría 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.shardingEntriesdebe 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 utilizar un índice único en la clave de fragmento, debe especificar su singularidad cuando crea el índice en el clúster de origen.
Los índices únicos en el clúster de origen que son incompatibles con la clave de fragmento solicitada en el clúster de destino, como un índice único en el origen que no contiene la clave de fragmento solicitada como prefijo en el destino, pueden provocar que
mongosyncfalle.Si el valor de
buildIndexeses"afterDataCopy"o"excludeHashedAfterCopy"y se establece createSupportingIndexes enfalseal migrar a un clúster fragmentado,mongosynccrea un índice ficticio compatible con la clave de fragmento.mongosyncintenta eliminar este índice ficticio trascommitllamar a. Si no existen índices creados por el usuario compatibles con la clave de fragmento, la eliminación del índice ficticio fallará. Se recomienda a los usuarios eliminar el índice ficticio y crear el suyo propio una vez finalizada la migración.
Cuando sharding.createSupportingIndexes es true:
Si los índices de soporte existen en el clúster de origen,
mongosyncsincroniza los índices con el clúster de destino y los utiliza como claves de partición.Si los índices de soporte no existen,
mongosynclos 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.
Cambiar el nombre de una colección (por ejemplo, con el comando) en el clúster de origen después de renameCollection llamar start a pero antes de que mongosync comience a copiar la colección puede impedir que la colección se fragmente en el destino.
Nota
No se admite cambiar el nombre de colecciones para usar una base de datos diferente mientras se sincroniza desde un conjunto 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
mongosyncno 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
mongosyncha iniciado la copia. Cambiar el nombre de la colección a partir de este momento no bloquea su fragmentación en el clúster de destino, incluso en caso de 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:
mongosyncconstruye un índice en el campo_idde cada colección que copia.mongosyncconstruye í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. CuandobuildIndexesse establece ennever,mongosyncmantiene 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 llama a /start con la opción copyInNaturalOrder, debe 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}