`start`

Descrição

Inicia a sincronização entre um cluster de origem e destino.

Requisitos

Estado

Para usar o endpoint start , mongosync deve estar no estado IDLE .

Permissões

O usuário especificado na string de conexão mongosync deve ter as permissões necessárias nos clusters de origem e destino. Consulte Permissões do usuário para garantir que o usuário tenha as permissões corretas para iniciar a sincronização.

`mongosync` Várias instâncias de

Certifique-se de usar o usuário mongosync configurado nas connection strings para as configurações cluster0 ou cluster1 ao iniciar mongosync.

Observação

Ao configurar várias instâncias mongosync para sincronizar entre clusters fragmentados, você deve enviar comandos de ponto de conexão da API idênticos para cada instância mongosync .

Para obter mais informações, consulte Iniciar vários Mongosyncs.

Solicitar

POST /api/v1/start

Parâmetros do corpo da solicitação

Parâmetro

Tipo

necessidade

Descrição

source

string

Obrigatório

Nome do cluster de origem.

destination

string

Obrigatório

Nome do cluster de destino.

buildIndexes

string

Opcional

Configura compilações de índice durante a sincronização.

Opções suportadas:

beforeDataCopy (o padrão) faz com que mongosync crie índices no cluster de destino durante a inicialização. Isso inclui índices que existem no cluster de origem no ponto de inicialização e índices que são criados durante a migração.
afterDataCopy faz com que mongosync crie índices no cluster de destino após a cópia da coleção. Isso inclui índices que existem no cluster de origem no ponto de inicialização e índices que são criados durante a migração. Isso resulta em uma migração mais rápida para bancos de dados indexados.
Se você definir buildIndexes como afterDataCopy e definir createSupportingIndexes como false ao migrar para um cluster fragmentado, mongosync criará um índice fictício para dar suporte à chave de shard. mongosync tenta eliminar esse índice fictício depois que commit é chamado. Se não houver índices criados pelo usuário para oferecer suporte à chave de fragmentação, a eliminação do índice fictício falhará. Os usuários são aconselhados a descartar o índice fictício e criar seu próprio índice após a conclusão da migração.
excludeHashed faz com que mongosync pule a criação de índices com hash durante a sincronização. Isso pode melhorar o desempenho de grandes collections.
excludeHashedAfterCopy faz com que mongosync crie índices sem hash no cluster de destino após a cópia da coleção. excludeHashedAfterCopy também ignora a criação de índices com hash. Isso resulta em uma migração mais rápida para bancos de dados indexados, devido à criação de índices após a cópia inicial de dados e à ignorar a criação de índices com hash.
Se você definir buildIndexes como excludeHashedAfterCopy e definir createSupportingIndexes como false ao migrar para um cluster fragmentado, mongosync criará um índice fictício para dar suporte à chave de shard. mongosync tenta eliminar esse índice fictício depois que commit é chamado. Se não houver índices criados pelo usuário para oferecer suporte à chave de fragmentação, a eliminação do índice fictício falhará. Os usuários são aconselhados a descartar o índice fictício e criar seu próprio índice após a conclusão da migração.
never faz com que mongosync pule a criação de índices desnecessários durante a sincronização. Isso pode melhorar o desempenho da migração, especialmente com volumes de trabalho pesados de índice.
Se você iniciar a sincronização com a verificação ativada e buildIndexes definido como never, a migração falhará se mongosync encontrar uma coleção TTL no cluster de origem. Isso pode acontecer depois de chamar o endpoint /start ou muito mais tarde, como quando um usuário cria um índice TTL no cluster de origem enquanto uma migração está em andamento.
Para sincronizar coleções TTL sem construir índices no cluster de destino, você deve iniciar a sincronização com o verificador desabilitado.
AVISO: não construa índices manualmente no agrupamento de destino enquanto o mongosync estiver executando uma migração. Aguarde até que a migração esteja totalmente confirmada.
Para obter mais informações sobre os índices que ele cria,consulte Índices necessários.

/start retorna um erro quando buildIndexes está definido como never e reversible está definido como true.

Se você chamar /start sem especificar a opção buildIndexes , o mongosync construirá índices no agrupamento de destino.

Novidade na versão 1,3,0.

enableUserWriteBlocking

string ou boolean

Opcional

IMPORTANTE: se você estiver migrando de um pré-6.0 cluster de origem, não é possível definir este parâmetro.

Opções suportadas:

"sourceAndDestination": bloqueia gravações no cluster de destino enquanto a migração está em andamento e desbloqueia gravações pouco antes de o endpoint /progress relatar que canWrite está true. Os blocos gravam no cluster de origem após mongosync chamar o endpoint /commit.
Você também pode usar true para compatibilidade com versões anteriores.
"none": não ocorre bloqueio de gravação. Você também pode usar false para compatibilidade com versões anteriores.
"destinationOnly": bloqueia gravações no cluster de destino enquanto a migração está em andamento e desbloqueia gravações logo antes de canWrite ser true.

Para reverter a sincronização, o campo enableUserWriteBlocking deve ser configurado para "sourceAndDestination". Para permitir que o cluster de origem aceite gravações novamente, por exemplo , depois de executar testes de migração, execute o seguinte comando:

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

O valor padrão é "destinationOnly".

includeNamespaces

array

Opcional

Filtra o reconhecimento de data center ou as collection para incluir na sincronização.

Se você configurar um filtro em um cluster de origem que tenha vários reconhecimento de data center, o mongosync sincronizará somente os reconhecimento de data center especificados na definição de filtro. mongosync não sincronizará os outros reconhecimento de data center existentes.

Se você quiser modificar o filtro para adicionar um reconhecimento de data center recém-criado, será necessário reiniciar a sincronização filtrada desde o início.

Para obter mais detalhes, consulte Sincronização filtrada.

Para limitações atuais, consulte Sincronização filtrada.

Novidade na versão 1.1.

excludeNamespaces

array

Opcional

Filtra o reconhecimento de data center ou as collection a serem excluídas da sincronização.

Se você quiser modificar o filtro para adicionar um reconhecimento de data center recém-criado, será necessário reiniciar a sincronização filtrada desde o início.

Para obter mais detalhes, consulte Sincronização filtrada.

Para limitações atuais, consulte Sincronização filtrada.

Novidade na versão 1.6.

copyInNaturalOrder

matriz de documentos

Opcional

Copia uma lista de bancos de dados e coleções em sua ordem natural para o cluster de destino. A ordem natural é a ordem em que você inseriu anteriormente os documentos no banco de dados. Você deve passar uma array de documentos que cada um represente um banco de dados e suas coleções. Para obter um exemplo de sintaxe, consulte Capacidade de verificação natural.

IMPORTANTE: Use somente a opção copyInNaturalOrder para collections que definam explicitamente um campo de _id aleatório. O uso dessa opção para collections de tamanho 30GB ou maior reduz significativamente o tempo que a fase de cópia da collection leva.

AVISO: se você /resume uma migração mongosync após um /pause ou interrupção que tenha a opção copyInNaturalOrder habilitada para collections maiores que 500GB de tamanho, a migração poderá levar várias horas para ser concluída.

preExistingDestinationData

booleano

Opcional

IMPORTANTE: este recurso está atualmente em pré-visualização pública. Revise o comportamento e as limitações nesta seção para usar esse recurso em ambientes de produção.

O valor padrão é false.

Se definido como true:

mongosync permite namespaces preexistentes no cluster de destino.
Você deve especificar um filtro de namespace utilizando um ou ambos os parâmetros includeNamespaces e excludeNamespaces em sua solicitação.
Se a verificação incorporada estiver habilitada, o filtro de namespace deverá filtrar todas as coleções ou índices pré-existentes no cluster de destino, mesmo que eles não existam no cluster de origem. Caso contrário, a verificação incorporada falha.
Certifique-se de seguir todas as instruções no processo de substituição para garantir que nenhuma gravação insegura ocorra no cluster de origem ou de destino. mongosync não ativa o bloqueio de gravação quando você ativa esse recurso, portanto, você deve garantir manualmente que essas gravações não ocorram.
mongosync não garante que existam recursos suficientes, como espaço em disco, computação e oplog, no cluster de destino para acomodar a carga adicional da migração. Monitore o cluster de destino para garantir que ele tenha recursos suficientes.
mongosync não migra visualizações quando você usa esse recurso. Ele ignora visualizações no cluster de origem durante a migração. Você deve migrar as visualizações separadamente após a transição.
O nível de carga padrão é alterado de 3 para 2.
Você pode deixar o balanceador habilitado para um cluster de destino fragmentado durante a migração.
O modo de bloqueio de gravação padrão é alterado de "destinationOnly" para "none". Não é possível definir o bloqueio de gravação em collections individuais no cluster de origem ou de destino, porque o bloqueio de gravação só está disponível no nível do cluster. Além disso, a filtragem de namespace não é compatível com o bloqueio duplo de gravação.
mongosync não permite a migração reversa.

mongosync gera a seguinte mensagem de registro no início da migração:

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/pt-br/docs/cluster-to-cluster-sync/current/reference/api/start/
for important requirements and limitations.

Consulte Limitações de sincronização filtradas.

reversible

booleano

Opcional

Se definido para true, permite que a operação de sincronização seja revertida.

Para fazer a sincronização reversa, o campo enableUserWriteBlocking deve ser definido como sourceAndDestination.

Esta opção não é suportada para as seguintes configurações:

Sincronizar de um conjunto de réplicas para um cluster fragmentado
Sincronizar clusters fragmentados que têm números diferentes de shards
Sincronização reversível quando buildIndexes está definido como never.

IMPORTANTE: se você estiver migrando de um pré-6.0 cluster de origem, não é possível definir reversible como true.

Para obter mais informações, consulte o endpoint inverso .

O valor padrão é false.

sharding

documento

Opcional

Configura a sincronização entre um conjunto de réplicas e um cluster fragmentado. A sincronização de um conjunto de réplicas para um cluster fragmentado requer esta opção.

Para obter mais informações, consulte Parâmetros de fragmentação.

Novidade na versão 1.1.

verification

Documento

Opcional

Configura o verificador incorporado.

Para obter mais informações, consulte Verificador incorporado.

Novidades na versão 1.9.

verification.enabled

Bool

Opcional

Habilita o verificador incorporado. O verificador executa uma série de verificações nas collections suportadas no cluster de destino para confirmar que a migração foi bem-sucedida.

Se o verificador não encontrar erros, mongosync fará a transição para o estado COMMITTED. Se encontrar erros, haverá falha na migração.

O verificador está habilitado por padrão.

AVISO: o verificador não verifica todas as collections ou dados. Para obter detalhes, consulte Verificador incorporado.

Novidades na versão 1.9.

Parâmetros de fragmentação

Novidade na versão 1.1.

Para sincronizar de um conjunto de réplicas para um cluster fragmentado, defina a opção sharding para fragmentar coleções no cluster de destino.

mongosync exibe um erro se a opção sharding não estiver definida ao sincronizar de um conjunto de réplicas para um cluster fragmentado. mongosync também apresenta um erro se a opção sharding estiver definida com qualquer outra configuração.

A opção sharding tem os seguintes parâmetros:

Parâmetro	Tipo	Descrição
`createSupportingIndexes`	booleano	Opcional. Define se a sincronização cria um índice de suporte para a chave de shard, se não existir nenhum. O padrão é `false`. Se você definir `buildIndexes` como `"afterDataCopy"` ou `"excludeHashedAfterCopy"` e definir createSupportingIndexes como `false` ao migrar para um cluster fragmentado, `mongosync` criará um índice fictício para dar suporte à chave de shard. `mongosync` tenta eliminar esse índice fictício depois que `commit` é chamado. Se não houver índices criados pelo usuário para oferecer suporte à chave de fragmentação, a eliminação do índice fictício falhará. Os usuários são aconselhados a descartar o índice fictício e criar seu próprio índice após a conclusão da migração. Se você definir esse parâmetro como `true` e definir `buildIndexes` como `"excludeHashed"` ou `"excludeHashedAfterCopy"`, `mongosync` não criará índices de hash de suporte para chaves de shard de hash no cluster de destino. `mongosync` ainda cria índices de suporte sem hash para chaves de shard sem hash. Para obter mais informações e limitações,consulte Índices de suporte.
`shardingEntries`	matriz de documentos	Obrigatório. Define o namespace e a chave das collection para fragmentar durante a sincronização. As coleções não incluídas nesta array são sincronizadas com coleções não fragmentadas no cluster de destino. Se definido com uma array vazia, nenhuma collection será fragmentada.
`shardingEntries` `.collection`	string	Define a collection como shard.
`shardingEntries` `.database`	string	Define o reconhecimento de data center da collection como shard.
`shardingEntries` `.shardCollection`	documento	Define a chave de shard para gerar no cluster de destino.
`shardingEntries` `.shardCollection` `.key`	array	Define os campos a serem usados para a chave de shard. Para obter mais informações, consulte Chaves de fragmento.

Resposta

Campo	Tipo	Descrição
`success`	booleano	Quando a solicitação é bem-sucedida, esse valor é `true`.
`error`	string	Se ocorreu um erro, indica o nome do erro. Este campo é omitido da resposta quando `success` é `true`.
`errorDescription`	string	Descrição detalhada do erro que ocorreu. Este campo é omitido da resposta quando `success` é `true`.

Exemplos

Iniciar um trabalho de sincronização

O exemplo a seguir inicia um tarefa de sincronização entre o cluster de origem cluster0 e o cluster de destino cluster1.

Solicitação:

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

Resposta:

{"success":true}

Iniciar um trabalho de sincronização reversível

O exemplo a seguir inicia um tarefa de sincronização entre o cluster de origem cluster0 e o cluster de destino cluster1.

Os campos reversible e enableUserWriteBlocking permitem que a sincronização seja revertida. Para reverter a direção de sincronização, consulte: reverter.

Solicitação:

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

Resposta:

{"success":true}

Iniciar um trabalho de sincronização filtrado

O exemplo a seguir inicia um tarefa de sincronização entre o cluster de origem cluster0 e o cluster de destino cluster1.

cluster0 contém o reconhecimento de data center sales, marketing e engineering.

O banco de dados sales contém as coleções EMEA, APAC e AMER.

O array includeNamespaces neste exemplo define um filtro em dois dos bancos de dados: sales e marketing.

O banco de dados sales também filtra as coleções EMEA e APAC.

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

Depois de chamar a API /start com este filtro em vigor, mongosync:

Sincroniza todas as coleções no banco de dados do marketing
Filtra o banco de dados engineering
Sincroniza as coleções EMEA e APAC a partir do banco de dados do sales
Filtra a coleção AMER

A opção includeNamespaces cria um filtro. Para filtrar a sincronização, consulte: Sincronização filtrada

Solicitação:

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

Resposta:

{"success":true}

Iniciar sincronização do conjunto de réplicas para cluster fragmentado

O exemplo a seguir inicia um tarefa de sincronização entre o conjunto de réplicas de origem cluster0 e o cluster fragmentado de destino cluster1. A array key neste exemplo define a chave de shard {"location": 1, "region": 1 }.

Solicitação:

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 }
                   ]
                }
            }
         ]
      }
   } '

Resposta:

{"success":true}

Comece com o Verificador Desativado

A partir de 1.9, o verificador incorporado é executado por padrão quando você inicia uma migração. Se você precisar desativá-lo, defina verification.enabled como false.

Solicitação:

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

Resposta:

{"success":true}

Você deve verificar se uma migração foi bem-sucedida antes de transferir a carga do aplicação para o cluster de destino. Se você precisar desativar o verificador por qualquer motivo, use um método alternativo para verificar a sincronização.

Comportamento

Verificador incorporado

A partir de 1.9, mongosync fornece um verificador embarcado para determinar se a transferência de dados do cluster de origem para o de destino foi bem-sucedida.

Quando ativado, o verificador realiza uma série de verificações no cluster de destino. Se alguma dessas verificações retornar um erro, o verificador falhará na migração. Se todas as verificações forem bem-sucedidas, mongosync fará a transição para o estado COMMITTED.

Para desabilitar o verificador, consulte Iniciar com o verificador desabilitado.

O endpoint /start retorna um erro se você habilitar verificações de verificação que não são suportadas pelo cluster de origem ou destino ou se não houver memória suficiente.

Estado

Se a solicitação start for bem-sucedida, mongosync entrará no estado RUNNING .

Fragmentar conjuntos de réplicas

A sincronização de um conjunto de réplicas para um cluster fragmentado requer a opção sharding . Esta opção configura como mongosync fragmenta a collection.

A matriz sharding.shardingEntries especifica as coleções a serem fragmentadas. As collection que não estão listadas nesta matriz replicam como não fragmentadas.

Para obter mais informações, consulte Comportamento de cluster fragmentado.

Índices de apoio

mongosync sincroniza índices do cluster de origem para o cluster de destino. Ao sincronizar de um conjunto de réplicas para um cluster fragmentado, mongosync pode exigir um índice adicional para suportar a chave de shard, que pode não existir no cluster de origem.

mongosync pode criar índices de suporte para collection fragmentadas durante a sincronização. Isso é feito definindo a opção sharding.createSupportingIndexes .

Quando sharding.createSupportingIndexes é false (o padrão):

Cada chave de shard fornecida para a opção sharding.shardingEntries deve ter um índice existente no cluster de origem.
Um dos índices usados para a chave de shard deve ter agrupamento simples se a collection usar qualquer outro agrupamento.
Para usar um índice único na chave de fragmento, você deve especificar sua exclusividade ao criar o índice no cluster de origem.
Índice único no cluster de origem que são incompatíveis com a chave de shard solicitada no cluster de destino, como um índice único na origem que não contém a chave de shard solicitada como prefixo no destino, podem fazer com que mongosync falhe.
Se você definir buildIndexes como "afterDataCopy" ou "excludeHashedAfterCopy" e definir createSupportingIndexes como false ao migrar para um cluster fragmentado, mongosync criará um índice fictício para dar suporte à chave de shard. mongosync tenta eliminar esse índice fictício depois que commit é chamado. Se não houver índices criados pelo usuário para oferecer suporte à chave de fragmentação, a eliminação do índice fictício falhará. Os usuários são aconselhados a descartar o índice fictício e criar seu próprio índice após a conclusão da migração.

Quando sharding.createSupportingIndexes é true:

Se os índices de suporte existirem no cluster de origem, o mongosync sincronizará os índices com o cluster de destino e os utilizará como chaves de shard.
Se os índices de suporte não existirem, o mongosync os criará no cluster de destino.

A opção sharding.createSupportingIndexes afeta todas as collection fragmentadas.

Renomear durante a sincronização

As collection listadas na matriz sharding.shardingEntries , quando sincronizadas de um conjunto de réplicas para um cluster fragmentado, tornam-se collection no cluster de destino.

Renomear uma coleção (como com o comando renameCollection ) no cluster de origem depois de chamar start , mas antes mongosync começar a copiar a coleção pode bloquear a fragmentação da coleção no destino.

Observação

Não é permitido renomear collection para usar um reconhecimento de data center diferente durante a sincronização de um conjunto de réplicas para um cluster fragmentado.

Para verificar se é seguro renomear as coleções, chame o endpoint progress e verifique o valor do campo collectionCopy.estimatedCopiedBytes no documento de retorno.

Um valor de 0 indica que mongosync não começou a copiar a collection.
Renomear uma coleção nesse ponto pode resultar em uma coleção não fragmentada no cluster de destino, pois a transição para a cópia pode acontecer antes que a renomeação entre em vigor na origem.
Um valor maior que 0 indica que mongosync iniciou a cópia. Renomear a collection a partir desse ponto não bloqueia sua fragmentação no cluster de destino, mesmo em caso de falha.

Índices exigidos

Quando você chama /start com a opção buildIndexes definida como never, mongosync ignora a criação de índices desnecessários.

Os índices que são sempre construídos incluem:

mongosync constrói um índice no campo _id de cada collection que copia.
mongosync cria índices fictícios para cada coleção fragmentada que não tem um índice para dar suporte à chave de shard no cluster de destino. Quando buildIndexes está definido como never, mongosync retém esse índice após o commit.

Proteção de endpoint

mongosync não protege o endpoint start . No entanto, por padrão, a API é vinculada apenas ao host local e não aceita chamadas de outras fontes. Além disso, a chamada start não expõe credenciais de conexão ou dados de usuário.

Capacidade de varredura natural

Ao chamar /start com a opção copyInNaturalOrder, você deve especificar os bancos de dados e as coleções usando documentos, como no exemplo a seguir.

Solicitação:

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

Resposta:

{"success":true}

AVISO: se você habilitar a migração para collections com campos _id não aleatórios, a fase de cópia da collection poderá levar mais tempo para ser concluída quando você especificar copyInNaturalOrder.

Você pode usar copyInNaturalOrder para copiar todas as collections em vários bancos de dados em sua ordem natural, como no exemplo a seguir.

Solicitação:

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

Resposta:

{"success":true}

Você pode usar copyInNaturalOrder para copiar todos os bancos de dados e suas coleções em sua ordem natural.

Solicitação:

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

Resposta:

{"success":true}

Voltar

Configuração

progresso

Descrição

Requisitos

Estado

Permissões

mongosync Várias instâncias de

Observação

Solicitar

Parâmetros do corpo da solicitação

Parâmetros de fragmentação

Resposta

Exemplos

Iniciar um trabalho de sincronização

Iniciar um trabalho de sincronização reversível

Iniciar um trabalho de sincronização filtrado

Iniciar sincronização do conjunto de réplicas para cluster fragmentado

Comece com o Verificador Desativado

Comportamento

Verificador incorporado

Estado

Fragmentar conjuntos de réplicas

Índices de apoio

Renomear durante a sincronização

Observação

Índices exigidos

Proteção de endpoint

Capacidade de varredura natural

`mongosync` Várias instâncias de