O MongoDB SQL Schema Builder CLI é a ferramenta de gerenciamento de esquema para implantação autogerenciada do Enterprise Advanced (EA) da interface SQL. Você baixa e executa o CLI no cluster para produzir o JSON schema. A interface SQL usa esse esquema para traduzir query SQL em operação MongoDB.
Esta página explica o que é a ferramenta, o que você precisa para executá-la, como você a invoca e os sinalizadores que ela aceita. Para a visão geral do gerenciamento de esquemas e os outros tipos de implantação suportados, consulte Gerenciamento de esquemas.
Casos de uso
Use a CLI do MongoDB SQL Schema Builder ao executar a interface SQL em uma implantação autogerenciada de EA e precisar gerar ou atualizar o esquema para suas coleções. A CLI é o caminho de gerenciamento de esquemas compatível para este tipo de implantação.
A CLI não amostra seus dados. Em vez disso, ele analisa cada documento em cada coleção que processa, para que o esquema gerado reflita com precisão os dados exatos nas coleções. Até mesmo os campos que aparecem em apenas uma pequena fração de documentos são incluídos no esquema.
A regeneração do esquema é sempre iniciada pelo usuário. A CLI não atualiza um esquema automaticamente ou em um agendamento. Você deve regenerar um esquema sempre que a forma dos seus dados subjacentes mudar, para que a interface SQL opere nas informações do esquema fornecidas.
Pré-requisitos
Antes de executar o MongoDB SQL Schema Builder CLI, certifique-se de atender aos seguintes requisitos:
Sua implantação é um cluster do MongoDB Enterprise. A CLI não oferece suporte a clusters do MongoDB Community.
Você pode se conectar ao cluster a partir da máquina onde executa a CLI, seja com uma string de conexão (
--uri) ou um arquivo de configuração (--file).O usuário de banco de dados que a CLI autentica tem, no mínimo:
O privilégio
readem cada banco de dados que você deseja processar. Esse privilégio permite que a CLI enumere e analise suas coleções.Os privilégios
find,inserteupdatena coleção__sql_schemasem cada banco de dados que você processa, ou a funçãoreadWriteno banco de dados. A CLI grava cada esquema com um upsert, portanto, o privilégioupdateé necessário mesmo ao executar pela primeira vez.
Você pode fornecer credenciais com os sinalizadores --username e --password ou incluí-las na string de conexão. Se você não fornecer credenciais, a CLI tentará se conectar sem autenticação e registrará um log de aviso.
Invocar a CLI
Você executa o MongoDB SQL Schema Builder CLI na linha de comando em seu cluster para gerar ou atualizar um esquema. O binário é chamado mongodb-schema-manager.
O exemplo a seguir analisa cada coleção no banco de dados sales e grava logs de rastreamento em um diretório logs:
mongodb-schema-manager \ --uri "mongodb://<host>:<port>" \ --ns-include "sales.*" \ --logpath ./logs \ --verbosity info
Quando a execução for concluída, a CLI imprime os bancos de dados e os namespaces para os quais criou ou modificou um esquema. Se algum namespace tiver um nível de polimorfismo grande demais para uso significativo, ele será considerado instável. A CLI lista esses namespaces. Para mais informações, consulte Esquemas instáveis.
Conectar com TLS
O MongoDB SQL Schema Builder CLI não fornece sinalizadores de linha de comando para TLS. Para conectar-se a um cluster habilitado para TLS, especifique as opções TLS na string de conexão que você passa para --uri.
Codifique em porcentagem qualquer valor de opção que contenha caracteres reservados, incluindo os caracteres / em um caminho de arquivo. Por exemplo, o caminho /etc/certs/ca.pem se torna %2Fetc%2Fcerts%2Fca.pem.
O exemplo a seguir habilita o TLS e especifica um arquivo de autoridade de certificação:
mongodb-schema-manager \ --uri "mongodb://<host>:<port>/?tls=true&tlsCAFile=%2Fetc%2Fcerts%2Fca.pem" \ --ns-include "sales.*"
Se seu sistema exigir certificados de cliente , defina também tlsCertificateKeyFile e tlsCertificateKeyFilePassword se o arquivo de chave estiver criptografado. Para obter a lista completa de opções de string de conexão TLS, consulte Opções de TLS.
Como os esquemas são armazenados
A CLI grava um documento de esquema por namespace em uma coleção __sql_schemas em cada banco de dados que processa.
Importante
Trate a coleção __sql_schemas como um namespace reservado para a Interface SQL. Não o modifique manualmente. Use a CLI para criar e atualizar os esquemas que ele contém.
Inspecionar esquemas armazenados
Para revisar os esquemas gerados pela CLI, execute um pipeline de agregação na coleção __sql_schemas no banco de dados que você deseja inspecionar. Cada documento relata os seguintes metadados:
lastUpdated: A data e a hora da gravação de esquema mais recente.unstable: Se o esquema é instável. Para mais informações, consulte Esquemas instáveis.
Para listar o status de cada esquema em um banco de dados sem imprimir o corpo completo do esquema, execute o seguinte pipeline em mongosh:
db.__sql_schemas.aggregate([ { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } }, { $sort: { namespace: 1 } } ])
Para visualizar o esquema completo de uma coleção específica, corresponda ao seu nome:
db.__sql_schemas.aggregate([ { $match: { _id: "<collection-name>" } }, { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } } ])
Por padrão, a CLI exclui implicitamente qualquer banco de dados ou coleção cujo nome comece com dois sublinhados (__), incluindo a própria coleção __sql_schemas. Para incluir esses namespaces, você deve especificá-los explicitamente com --ns-include. Por exemplo, --ns-include "*.__*" inclui coleções que começam com __ em bancos de dados que não começam com __.
A CLI deriva o esquema de uma visualização do pipeline de visualização e dos esquemas das coleções de origem que o pipeline referencia. Em condições normais, a CLI não visualiza amostras. Para garantir que o esquema derivado de uma visualização seja preciso, primeiro gere esquemas atualizados para as coleções de origem.
Se não houver esquema para uma coleção de origem ou se a CLI não puder derivar o esquema dos esquemas de coleção de origem disponíveis, a CLI voltará a executar a visualização e amostrar seus documentos de saída.
Referência de sinalizador CLI
A CLI do MongoDB SQL Schema Builder aceita os seguintes sinalizadores. Você deve fornecer --uri ou --file para que a CLI possa se conectar ao seu cluster.
-f, --file <CONFIG_FILE>- O caminho para um arquivo de configuração. Os argumentos da linha de comando têm precedência sobre os valores no arquivo de configuração.
--uri <URI>- A string de conexão para o seu cluster.
-u, --username <USERNAME>- O nome de usuário para autenticação. Você também pode especificar o nome de usuário na string de conexão.
-p, --password <PASSWORD>- A senha para autenticação. Você também pode especificar a senha na string de conexão.
--ns-include <NS_INCLUDE>- Os bancos de dados e as coleções a serem incluídos, no formato
<database_pattern>.<collection_pattern>. A sintaxe Glob é compatível, comomydb.*. Repita o sinalizador para especificar vários padrões. Se você omitir esse sinalizador, a CLI incluirá todos os bancos de dados e coleções. Namespaces que começam com__são implicitamente excluídos, a menos que você os especifique explicitamente. --ns-exclude <NS_EXCLUDE>- Os bancos de dados e coleções a serem excluídos, no mesmo formato que
--ns-include. Repita o sinalizador para especificar vários padrões. Este sinalizador tem precedência sobre--ns-include. --quiet- Ativa o modo silencioso para menos saída. Padrão:
false. -o, --logpath <LOGPATH>- O diretório onde a CLI grava arquivos de log. Os arquivos de log são nomeados
mongodb-schema-manager.log.{date}. Se você omitir este sinalizador, a CLI não gravará arquivos de log. -v, --verbosity <VERBOSITY>- O nível de log a ser capturado no arquivo de log. Requer
--logpath. Aceitatrace,debug,info,warnouerror. Padrão:warn. -a, --action <SCHEMA_ACTION>A ação a ser executada no esquema. Padrão:
merge. Aceita os seguintes valores:merge: Mescla o novo esquema com o esquema existente. Se nenhum esquema existir, esta ação criará um. Esta ação não atualiza esquemas instáveis.overwrite: Ignora e substitui o esquema existente. Se nenhum esquema existir, esta ação criará um. Use esta ação para atualizar um esquema instável.clear: Remove o camposchemado documento de esquema existente. Se não houver esquema, esta ação captura apenas metadados.
--dry-run- Executa uma execução de teste sem analisar esquemas ou gravar no banco de dados. Use este sinalizador para testar seus padrões
--ns-includee--ns-exclude. Padrão:false. --resolver <RESOLVER>- O resolvedor de DNS a ser usado se a resolução de DNS falhar ou for lenta. Aceita
cloudflare,googleouquad9. -j, --jobs <JOBS>- O número máximo de tarefas de esquema em processamento simultâneas. Deve ser um número inteiro maior que
0. Padrão: duas vezes o número de núcleos físicos.
Esquemas instáveis
Quando os documentos de uma coleção variam muito em forma, como coleções que usam nomes de campo como chaves de mapa, a CLI marca o esquema derivado como instável. Um esquema instável define unstable como true no documento do esquema, limita o número de campos capturados e define additionalProperties como true. Um esquema instável pode não representar totalmente os dados no namespace.
Quando uma ação de executar produz um ou mais esquemas instáveis, a CLI imprime os namespace afetados:
The following namespaces have unstable schemas. They may not fully represent the data in the namespace. Unstable schemas are not updated by the schema-manager by default. To update them, use the 'overwrite' action.
A ação merge padrão não atualiza um esquema instável. Para atualizar um esquema instável, execute a CLI com --action overwrite.
Quando gerar novamente um esquema
Regenere um esquema quando a forma dos dados subjacentes for alterada, como quando você adiciona campos, remove campos ou altera o tipo de dados de um campo existente. O CLI não detecta alterações na forma dos dados por conta própria, portanto, a regeneração é sempre iniciada pelo usuário. Um esquema desatualizado pode fazer com que a interface SQL mapeie coleções para as tabelas e colunas erradas.