CLI del generador de esquemas SQL de MongoDB

Casos de uso

Utilice la CLI de MongoDB SQL Schema Builder cuando ejecute la interfaz SQL en una implementación autogestionada de EA y necesite generar o actualizar el esquema de sus colecciones. La CLI es la ruta de gestión de esquemas compatible para este tipo de implementación.

La CLI no toma muestras de sus datos. En su lugar, analiza cada documento de cada colección que procesa, de modo que el esquema generado refleja con precisión los datos exactos de las colecciones. Incluso los campos que aparecen en solo una pequeña fracción de los documentos se incluyen en el esquema.

La regeneración del esquema siempre la inicia el usuario. La CLI no actualiza un esquema automáticamente ni según un cronograma. Debe regenerar un esquema cada vez que cambie la forma de los datos subyacentes, de modo que la interfaz SQL opere con la información del esquema proporcionada.

Requisitos previos

Antes de ejecutar la CLI de MongoDB SQL esquema desarrollador, asegúrese de cumplir los siguientes requisitos:

• Su implementación es un clúster de MongoDB Enterprise. La CLI no es compatible con los clúster de MongoDB Community.

• Puede conectarse al clúster desde la máquina donde ejecuta la CLI, ya sea con una cadena de conexión (--uri) o un archivo de configuración (--file).

• El usuario de base de datos con el que se autentica la CLI tiene, como mínimo:

  • El privilegio read en cada base de datos que desee procesar. Este privilegio permite a la CLI enumerar y analizar sus colecciones.

  • Los privilegios find, insert y update en la colección __sql_schemas de cada base de datos que se procesa, o el rol readWrite en la base de datos. La CLI guarda cada esquema con una inserción, por lo que el privilegio update es necesario incluso en la primera ejecución.

Puede proporcionar credenciales con las marcas --username y --password o incluirlas en la cadena de conexión. Si no proporciona credenciales, la CLI intenta conectarse sin autenticación y registra una advertencia.

Invocar la CLI

Ejecuta la CLI de MongoDB SQL Schema Builder desde la línea de comandos en tu clúster para generar o actualizar un esquema. El binario se denomina mongodb-schema-manager.

El siguiente ejemplo analiza cada colección de la base de datos sales y guarda los registros de seguimiento en un directorio logs:

mongodb-schema-manager \
   --uri "mongodb://<host>:<port>" \
   --ns-include "sales.*" \
   --logpath ./logs \
   --verbosity info

Cuando se completa la ejecución, la CLI imprime las bases de datos y los namespaces para los que creó o modificó un esquema. Si algún namespace tiene un nivel de polimorfismo demasiado grande para un uso significativo, se considera inestable. La CLI enumera esos namespaces. Para obtener más información, consulte Esquemas inestables.

Conectar con TLS

La CLI de MongoDB SQL Schema Builder no proporciona indicadores de línea de comandos para TLS. Para conectarse a un clúster habilitado para TLS, especifique las opciones de TLS en la cadena de conexión que pase a --uri.

Codifique en porcentaje cualquier valor de opción que contenga caracteres reservados, incluidos los caracteres / en una ruta de archivo. Por ejemplo, la ruta /etc/certs/ca.pem se convierte en %2Fetc%2Fcerts%2Fca.pem.

El siguiente ejemplo habilita TLS y especifica un archivo de autoridad de certificación:

mongodb-schema-manager \
   --uri "mongodb://<host>:<port>/?tls=true&tlsCAFile=%2Fetc%2Fcerts%2Fca.pem" \
   --ns-include "sales.*"

Si su implementación requiere certificados de cliente, también establezca tlsCertificateKeyFile y tlsCertificateKeyFilePassword si el archivo de clave está cifrado. Para obtener la lista completa de opciones de cadena de conexión TLS, consulte Opciones de TLS.

Cómo se almacenan los esquemas

La CLI guarda un documento de esquema por namespace en una colección __sql_schemas en cada base de datos que procesa.

db.__sql_schemas.aggregate([
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } },
   { $sort: { namespace: 1 } }
])

db.__sql_schemas.aggregate([
   { $match: { _id: "<collection-name>" } },
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } }
])

Referencia de indicadores de CLI

El CLI de MongoDB SQL esquema Builder acepta las siguientes marcas. Debe proporcionar --uri o --file para que la CLI pueda conectarse a su clúster.

-f, --file <CONFIG_FILE>

La ruta a un archivo de configuración. Los argumentos de la línea de comandos tienen prioridad sobre los valores del archivo de configuración.

--uri <URI>

La cadena de conexión de su clúster.

-u, --username <USERNAME>

El nombre de usuario para la autenticación. También puedes especificar el nombre de usuario en la cadena de conexión.

-p, --password <PASSWORD>

La contraseña para la autenticación. También puede especificar la contraseña en la cadena de conexión.

--ns-include <NS_INCLUDE>

Las bases de datos y colecciones que se incluirán, en el formato <database_pattern>.<collection_pattern>. Se admite la sintaxis Glob, como mydb.*. Repita la marca para especificar varios patrones. Si omite esta marca, la CLI incluye todas las bases de datos y colecciones. Los namespaces que comienzan con __ se excluyen implícitamente a menos que los especifique explícitamente.

--ns-exclude <NS_EXCLUDE>

Las bases de datos y colecciones a excluir, en el mismo formato que --ns-include. Repita la bandera para especificar varios patrones. Esta bandera tiene prioridad sobre --ns-include.

--quiet

Habilita la moda silenciosa para menos resultados. Por defecto: false.

-o, --logpath <LOGPATH>

El directorio donde la CLI guarda entrada de registro. entrada de registro se denominan mongodb-schema-manager.log.{date}. Si omite esta marca, la CLI no guarda entrada de registro.

-v, --verbosity <VERBOSITY>

El nivel de registro que se capturará en la entrada de registro. Requiere --logpath. Acepta trace, debug, info, warn o error. Por defecto: warn.

-a, --action <SCHEMA_ACTION>

La acción que se realizará en el esquema. Por defecto: merge. Acepta los siguientes valores:

• merge: Combina el nuevo esquema con el esquema existente. Si no existe un esquema, esta acción crea uno. Esta acción no actualiza los esquemas inestables.

• overwrite: Ignora y sobrescribe el esquema existente. Si no existe un esquema, esta acción crea uno. Utilice esta acción para actualizar un esquema inestable.

• clear: Remueve el campo schema del documento de esquema existente. Si no existe ningún esquema, esta acción solo captura metadatos.

--dry-run

Realiza una ejecución de prueba sin analizar esquemas ni escribir en la base de datos. Utilice esta marca para probar sus patrones --ns-include y --ns-exclude. Por defecto: false.

--resolver <RESOLVER>

El solucionador de DNS que se utilizará si la resolución de DNS falla o es lenta. Acepta cloudflare, google o quad9.

-j, --jobs <JOBS>

El número máximo de tareas de procesamiento de esquemas simultáneas. Debe ser un número entero mayor que 0. Por defecto: dos veces el número de núcleos físicos.

Esquemas inestables

Cuando los documentos de una colección varían mucho en su forma, como las colecciones que utilizan nombres de campo como claves de mapa, la CLI marca el esquema derivado como inestable. Un esquema inestable establece unstable en true en el documento del esquema, limita el número de campos capturados y establece additionalProperties en true. Un esquema inestable puede no representar completamente los datos en el namespace.

Cuando una ejecución produce uno o más esquemas inestables, la CLI imprime los namespace afectados:

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.

La acción merge por defecto no actualiza un esquema inestable. Para actualizar un esquema inestable, ejecute la CLI con --action overwrite.

Cuándo regenerar un esquema

Regenere un esquema cuando cambie la forma de los datos subyacentes, como cuando agrega campos, remueve campos o cambia el tipo de dato de un campo existente. La CLI no detecta los cambios en la forma de los datos por sí sola, por lo que la regeneración siempre la inicia el usuario. Un esquema obsoleto puede hacer que la interfaz SQL asigne colecciones a las tablas y columnas incorrectas.

Obtén más información

• Gestión de esquemas
• Instalar la Interfaz SQL de MongoDB
• Query con Interfaz SQL
• Descripción general de la interfaz SQL de MongoDB

• Descripción general del administrador de esquemas de MongoDB (PDF): Referencia técnica completa para los desarrolladores de esquemas SQL de MongoDB.