Descripción
Inicia la sincronización entre un clúster de origen y uno de destino.
Requisitos
Estado
Para utilizar el punto final 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 garantizar que el usuario tenga los permisos correctos para iniciar la sincronización.
Varias mongosync instancias
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 configura varias instancias mongosync para sincronizar entre clústeres fragmentados, debe enviar comandos de punto final de API idénticos a cada instancia 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 las compilaciones de índices durante la sincronización. Opciones admitidas:
Si llama a Nuevo en la versión 1.3.0. | |||||
| booleano | Opcional | Cuando, Para especificar explícitamente colecciones que Por defecto, ADVERTENCIA: Para las colecciones que | |||||
| cadena 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 revertir la sincronización, el campo El valor predeterminado es | |||||
| arreglo | Opcional | Filtra las bases de datos o colecciones para incluir en la sincronización. Si configura un filtro en un clúster de origen que tiene varias bases de datos, Si desea modificar el filtro para agregar una base de datos recién creada, deberá reiniciar la sincronización filtrada desde el principio. Para obtener más detalles, consulte Sincronización filtrada. Para conocer las limitaciones actuales, consulte Sincronización filtrada. Nuevo en la versión 1.1. | |||||
| arreglo | Opcional | Filtra las bases de datos o colecciones que se excluirán de la sincronización. Si configura un filtro en un clúster de origen que tiene varias bases de datos, Si desea modificar el filtro para agregar una base de datos recién creada, deberá reiniciar la sincronización filtrada desde el principio. Para obtener más detalles, consulte Sincronización filtrada. Para conocer las limitaciones actuales, consulte Sincronización filtrada. Nuevo en la versión 1.6. | |||||
| conjunto 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 se insertaron previamente los documentos en la base de datos. Debe pasar una matriz de documentos que representen cada una de las bases de datos y sus colecciones. Para ver 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 función se encuentra actualmente en versión preliminar pública. Revise el comportamiento y las limitaciones en esta sección para poder usarla en entornos de producción. El valor predeterminado es Si se establece en
| |||||
| booleano | Opcional | Si se establece en Para revertir la sincronización, el campo Esta opción no es compatible con las siguientes configuraciones:
IMPORTANTE: La configuración reversible en Para obtener más información, consulte el punto final inverso. El valor predeterminado es | |||||
| Documento | Opcional | Configura la sincronización entre un conjunto de réplicas y un clúster fragmentado. La sincronización desde un conjunto de réplicas a un clúster fragmentado requiere esta opción. Para obtener más información, consulte Parámetros de fragmentación. Nuevo 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. Este realiza una serie de comprobaciones en las colecciones compatibles del clúster de destino para confirmar que la migración se realizó correctamente. 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
Nuevo en la versión 1.1.
Para sincronizar desde un conjunto de réplicas a un clúster fragmentado, configure la opción sharding para fragmentar 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 establece este parámetro en Para obtener más información y conocer las limitaciones,consulte Índices de soporte. |
| conjunto de documentos | Obligatorio. Establece el espacio de nombres y la clave de las colecciones que se fragmentará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 colección como fragmento. |
shardingEntries.database | string | Establece la base de datos de la colección en fragmento. |
shardingEntries.shardCollection | Documento | Establece la clave de fragmento 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 fragmentos. |
Respuesta
Campo | Tipo | Descripción |
|---|---|---|
| booleano | Cuando la solicitud es exitosa, este valor es |
| string | Si se produjo un error, indica su nombre. Este campo se omite en 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.
Pedido:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1" } '
Respuesta:
{"success":true}
Iniciar un trabajo 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 reversible enableUserWriteBlocking campos y permiten invertir la sincronización. Para invertir la dirección de la sincronización, consulte: invertir.
Pedido:
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.
La matriz 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 datossalesFiltra la colección
AMER
La includeNamespaces opción crea un filtro. Para filtrar la sincronización, consulte: Sincronización filtrada
Pedido:
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 conjunto de réplicas de origen cluster0 y el clúster fragmentado de destino cluster1. La matriz key de este ejemplo define la clave de fragmentación {"location": 1, "region": 1 }.
Pedido:
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}
Comience 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.
Pedido:
curl localhost:27182/api/v1/start -XPOST \ --data ' { "source": "cluster0", "destination": "cluster1", "verification": { "enabled": false } } '
Respuesta:
{"success":true}
Debe verificar que la migración se haya realizado correctamente antes de transferir la carga de su aplicación al clúster de destino. Si necesita deshabilitar 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 desde el clúster de origen al destino fue exitosa.
Cuando está habilitado, el verificador realiza una serie de comprobaciones en el clúster de destino. Si alguna de estas comprobaciones devuelve un error, el verificador falla la migración. Si todas las comprobaciones son correctas, mongosync pasa al estado COMMITTED.
Para deshabilitar el verificador, consulte Comenzar con el verificador deshabilitado.
El punto final /start devuelve un error si habilita comprobaciones 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.
Conjuntos de réplicas de fragmentos
La sincronización desde un conjunto de réplicas a un clúster fragmentado requiere la opción sharding. Esta opción configura cómo mongosync fragmenta las colecciones.
La matriz sharding.shardingEntries especifica las colecciones que se fragmentarán. Las colecciones que no aparecen en esta matriz se replican como no fragmentadas.
Para obtener más información, consulta Comportamiento de clúster particionado.
Índices de apoyo
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 Se pueden crear índices de soporte para colecciones fragmentadas durante la sincronización. Esto se realiza configurando la opción sharding.createSupportingIndexes.
Cuando sharding.createSupportingIndexes es false (el valor predeterminado):
Cada clave de fragmento que proporcione para la opción
sharding.shardingEntriesdebe tener un índice existente en el clúster de origen.Uno de los índices utilizados para la clave del fragmento 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 fragmento.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.
Cambiar el nombre 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 progress cambiar el nombre de las colecciones, llame al punto final y verifique el valor del collectionCopy.estimatedCopiedBytes campo en el documento de retorno.
Un valor de 0 indica que
mongosyncno ha comenzado a copiar la colección.Cambiar el nombre de una colección en este punto puede generar una colección sin fragmentar en el clúster de destino, ya que la transición a la copia puede ocurrir antes de que el cambio de nombre tenga 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 llama a /start con la opción buildIndexes establecida en never, mongosync omite la creación de índices innecesarios.
Los índices que siempre se construyen incluyen:
mongosyncconstruye un índice en el campo_idde cada colección que copia.mongosyncCrea índices ficticios para cada colección fragmentada que no tenga un índice compatible con la clave de fragmento en el clúster de destino. CuandobuildIndexesse establece ennever,mongosyncconserva este índice después de la confirmación.
Protección de endpoints
mongosync No protege el punto final start. Sin embargo, por defecto, la API se vincula únicamente al host local y no acepta llamadas de otras fuentes. Además, la llamada start no expone las credenciales de conexión ni los datos del 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.
Pedido:
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.
Puede utilizar copyInNaturalOrder para copiar todas las colecciones en múltiples bases de datos en su orden natural, como en el siguiente ejemplo.
Pedido:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "copyInNaturalOrder": [ { "database": "sales", }, { "database": "marketing", }, ] }'
Respuesta:
{"success":true}
Puede utilizar copyInNaturalOrder para copiar todas las bases de datos y sus colecciones en su orden natural.
Pedido:
curl -X POST "http://localhost:27182/api/v1/start" --data ' { "source": "cluster0", "destination": "cluster1", "copyInNaturalOrder": [ { "database": ".", }, ] }'
Respuesta:
{"success":true}