# Herramientas de DDM: install-model, dbgen y dba Las herramientas de DDM son programas DKL del repositorio [`Induxsoft/dkl-ddm`](https://github.com/Induxsoft/dkl-ddm). Se ejecutan con `dkl` desde la consola y usan las conexiones del repositorio de conexiones (`connections.xml`, ver [dbr.dkh](/es/devkron/2.0/bibliotecas/motor/dbr/)). | Herramienta | Para qué | |---|---| | `install-model` | Instala un modelo en una base de datos **o actualiza** una base existente (incluso en producción) aplicando solo los cambios seguros. Solo MySQL | | `dbgen` | Genera el script SQL (MySQL o SQL Server) o el JSON de un modelo; compara dos modelos y genera el SQL de actualización; obtiene el modelo de una base existente | | `dba` | Administra conexiones desde la consola: listar, ver, crear y eliminar; crear bases de datos | ## Instalación Copie **todo** el contenido de la carpeta `src` del repositorio en la carpeta de `dkl` (o en la carpeta desde la que ejecutará las herramientas): | Archivo | Qué es | |---|---| | `ddm.dkh` | Patrones de sintaxis del dialecto | | `install-model.dkl` | Instalador de modelos | | `dbgen.dkl` | Generador | | `gen_mysql.dkl`, `gen_sqlserver.dkl` | Generadores de segundo paso (SQL) | | `gen_mysql_json.dkl`, `gen_sqlserver_json.dkl` | Variantes que entregan las sentencias como JSON | | `ddm.json.dkl` | Primer paso (modelo a JSON) y comparación de modelos | | `ddm.mysql.dkl`, `ddm.sqlserver.dkl` | Generación de SQL, incluido el de actualización | | `dbm.dkl` | Lógica de instalación y de la bitácora | | `dba.dkl` | Utilidad de conexiones | | `induxsoft.abstracts.ddm` | Abstracciones `TableModel` y `EnumModel` | | `induxsoft.sys_tables.ddm` | Tablas de sistema de Devkron (`tuser`, `usergroup`, `sys_batch`…) | | `dbm.sys_tables.ddm` | Tablas de bitácora de `install-model` | ```bash git clone https://github.com/Induxsoft/dkl-ddm.git sudo cp dkl-ddm/src/* /opt/devkron/ ``` Las herramientas funcionan con Devkron 2.0 sin cambios. Los ejemplos de esta página se ejecutaron con la distribución 2.0 contra MySQL 8.0. ## Cómo se genera 1. El `.ddm` se valida contra los patrones de `ddm.dkh`. 2. Se transforma a **JSON** (primer paso), independiente del motor. 3. El JSON produce SQL de MySQL o de SQL Server (segundo paso, `gen_mysql.dkl` / `gen_sqlserver.dkl`). ## install-model ```bash dkl install-model db=conexión@aplicación model=archivo.ddm ``` | Parámetro | Valor | |---|---| | `db` | Nombre cualificado de una conexión existente (MySQL) | | `model` | Archivo `.ddm` o `.json` (el JSON de primer paso de `dbgen`) | | `action` | En lugar de `model`: `infer-model`, `show-model` o `show-last-error` | Los parámetros con espacios van entre comillas completas: `"db=mi base@grupo"`. ### Ejemplo: instalar y evolucionar un modelo Sobre una base vacía `crm_demo` (conexión `crm@tienda`) con el `crm.ddm` del [dialecto](/es/devkron/2.0/bibliotecas/ddm/dialecto.md): ```bash dkl install-model db=crm@tienda model=crm.ddm ``` ```text Modelo obtenido. Iniciando lectura, espere un momento por favor. Modelo inferido exitosamente. -- ------------------------- -- Iniciando analisis. Analisis completado. tabla creada: ciudad tabla creada: cliente nuevo indice: ix_cliente_nombre en cliente nuevo fk: cliente.iciudad a ciudad.sys_pk Modelo instalado con éxito ``` `crm_v2.ddm` amplía `email` a `string(200)` y agrega `@"telefono" string(20)`: ```bash dkl install-model db=crm@tienda model=crm_v2.ddm ``` ```text Iniciando analisis. Analisis completado. campo modificado: email en cliente nuevo campo: telefono en cliente Modelo instalado con éxito ``` `crm_v3.ddm` agrega además `@"rfc" string(13) required`, que no puede crearse sobre filas existentes: ```bash dkl install-model db=crm@tienda model=crm_v3.ddm dkl install-model db=crm@tienda action=show-last-error ``` ```text Iniciando analisis. {"table":"cliente","column":"rfc","action":"incompatible","message":"No se puede a\u00F1adir el campo porque tiene establecido el atributo 'required' o es 'PrimaryKey'."} Analisis completado. {99} No es posible instalar el modelo, se encontraron incompatibilidades.[Ln= 217] No se encontraron errores. ``` La incompatibilidad aborta todo **antes** de ejecutar SQL (ni siquiera se aplica lo compatible), solo se informa en la consola y `show-last-error` no la muestra. El código de salida de `dkl` es 0 aun así: en ejecuciones desatendidas capture la salida y busque `{99}`. ### Funciones de action | `action` | Qué hace | |---|---| | `infer-model` | Lee la estructura real de la base y la **registra como el modelo vigente**. Es la forma de re-sincronizar después de un cambio hecho a mano | | `show-model` | Imprime el modelo vigente en JSON (si no hay bitácora, primero lo infiere y la salida trae mensajes antes del JSON) | | `show-last-error` | Muestra el último error al **ejecutar** sentencias DDL (de `sys_model_ddl_log`); no muestra incompatibilidades | Un `action` mal escrito no da un error propio: se interpreta como instalación y falla con `No existe el archivo de origen o no se ha indicado el parámetro (model).` ### Cómo trabaja - **Solo MySQL.** Con otro motor: `El motor de base de datos de la conexión no esta soportada.` - **Bitácora**: crea si no existen tres tablas: - `sys_model_log`: una fila por ejecución (`source`, `install`, `analisys`, `compatible`, `success` y `model`, el modelo vigente al terminar, que es contra el que compara la siguiente ejecución); - `sys_model_ddl_log`: una fila por sentencia DDL (`ref_model_log`, `action`: `create_table`, `create_index`, `create_reference`, `new_column`, `change_column`; `cmdsql`, `jsondef`, `success`, `message`); - `sys_packs`: versión de esquema por paquete (`pack`, `schema_ver`, `sys_timestamp`), para instaladores que llevan la versión del esquema por módulo. - **Primera ejecución sobre una base con datos**: infiere la base real y la registra como línea base; luego compara contra ella. - **Orden**: tablas nuevas → índices de tablas nuevas → llaves foráneas de tablas nuevas → columnas nuevas y modificadas de tablas existentes. Cada sentencia se registra y el modelo vigente se actualiza paso a paso. - **Fallo a la mitad**: MySQL confirma cada DDL; no hay transacción que deshaga. El estado parcial queda registrado y una nueva ejecución continúa desde ahí. - `sys_model_log` y `sys_model_ddl_log` se excluyen siempre del análisis. ### Reglas al actualizar una base existente `install-model` compara el modelo nuevo con el **último modelo registrado** (no con la base real) y aplica solo la diferencia. Principio: **en producción nunca se eliminan datos ni se reduce lo que existe.** | Situación (tabla que existe en ambos modelos) | Resultado | |---|---| | Columna nueva sin `required` ni `key` | Compatible: `ALTER TABLE … ADD` (con `unique` si lo tiene) | | Columna nueva con `required` o `key` | **Incompatible** en ambos modos (DDM no tiene valor por omisión para las filas existentes) | | Columna que sale del modelo | No se hace nada, la columna queda. Si era `required` o `key`: incompatible solo en `strict` | | Misma definición | Nada | | Mismo tipo y tamaño pero cambia `required`, `unique`, `key` o `autoincrement` | **Incompatible** en cualquier dirección, incluso quitar `required` | | Cambia tipo, tamaño, precisión o escala | `MODIFY COLUMN` si hay un tipo compatible; si no, incompatible | Si cambian varios atributos a la vez, el mensaje nombra uno (prevalece `key`, luego `required`, luego `unique`); si solo cambia `autoincrement`, el mensaje queda vacío. **Tipos compatibles** (el resultado es siempre el más amplio): | Par | Resultado | |---|---| | `char` + `varchar` | `varchar` | | `char` + `string` | `string` | | `string` + `memo` / `mmemo` / `lmemo` | `memo` / `mmemo` / `lmemo` | | `memo` + `mmemo`, `mmemo` + `lmemo`, `memo` + `lmemo` | el mayor | | `bit` + `tinyint` | `tinyint` | | `bit` + `bool` | `bool` | | `bool` + `int`, `tinyint` + `int`, `int` + `smallint` | `int` | | `tinyint` + `smallint`, `bool` + `smallint` | `smallint` | | `int` + `float` / `double` / `decimal` | `float` / `double` / `decimal` | | `float` + `decimal`, `double` + `decimal` | `decimal` | | `float` + `double` | `double` | | `date` + `datetime` | `datetime` | Cualquier otro par (`string`/`int`, `string`/`decimal`, `int`/`datetime`, `bigint`/`int`) es incompatible: `No se encontro una definición para los tipos de datos.` **Solo se amplía**: en `string` queda el tamaño mayor; en `decimal`, la mayor precisión y la mayor escala (si además cambia el tipo, la precisión pasa a 11 más la escala). Pedir un tamaño menor no falla, se conserva el mayor. Un `string` de más de 4096 pasa a `TEXT`. **Lo que una actualización nunca hace**: eliminar tablas o columnas ni reducir tipos o tamaños; comparar o cambiar índices de tablas existentes; crear la llave foránea de una columna `ref:` agregada a una tabla existente; cambiar valores por omisión, `CHECK`, motor, juego de caracteres o intercalación; detectar cambios hechos a mano. Todo eso se hace con SQL manual y después `infer-model`. ### Cómo se infiere un modelo `infer-model`, `show-model` sin bitácora y la primera instalación sobre una base existente deducen el modelo así: | En MySQL | En el modelo | |---|---| | `varchar(n)` | `string` de tamaño `n` | | `text`, `mediumtext`, `longtext` | `memo`, `mmemo`, `lmemo` | | `int` | `int` | | `tinyint`, `bit` | `bool` | | `decimal(p,s)` | `decimal` | | otro (`bigint`, `char`, `timestamp`…) | El nombre original, con tamaño o precisión | `required` sale de `IS_NULLABLE`, `unique` de `UNI`, `key` de `PRI` y `autoincrement` de `auto_increment`. Por eso un `bigint` de la base contra `int` en el `.ddm` es incompatible, y un `char` contra `string` genera un `MODIFY` a `VARCHAR`: el `.ddm` debe coincidir también en nulabilidad y unicidad. Los índices de más de una columna se deducen como índices del modelo. ### Mensajes de error | Mensaje | Causa | |---|---| | `No se ha indicado una cadena de conexión (db).` | Falta `db` | | `No se encontro el grupo de conexiones X` / `No se encontro la conexión X` | El nombre cualificado no existe en el repositorio | | `El motor de base de datos de la conexión no esta soportada.` | La conexión no es MySQL | | `No existe el archivo de origen o no se ha indicado el parámetro (model).` | El archivo no existe, falta `model` o el `action` está mal escrito | | `El tipo de archivo no esta soportado.` | `model` no es `.ddm` ni `.json` | | `El ascendente 'X' no está definido` | Entidad que hereda de una abstracción inexistente | | `La tabla 'X' a la que se hace referencia en 'Y' no existe en el modelo.` | `ref:` a una entidad inexistente | | `No hay objetos de bases de datos definidos` | El archivo no define un modelo | | `{99} No es posible instalar el modelo, se encontraron incompatibilidades.` | Ver arriba; el detalle está en las líneas JSON previas | ## dbgen `dbgen` elige su modo por los parámetros: | Modo | Parámetros | Resultado | |---|---|---| | Generar desde un modelo | `src` | Script SQL o JSON de primer paso | | Comparar dos modelos | `a` y `b` | Script SQL de actualización | | Generar desde una conexión | `db` | Modelo JSON de una base existente | Sin ninguno: `Debe indicar un origen (db, src, a, b).` > **`out` debe incluir una carpeta**: `out=./crm.sql`, no `out=crm.sql`. Con un nombre sin carpeta, `dbgen` responde `No existe la ruta de salida, o no se ha indicado el parámetro.` La carpeta debe existir. ### Generar desde un modelo ```bash dkl dbgen src=modelo.ddm fmt=gen_mysql.dkl out=./script.sql dkl dbgen src=modelo.ddm fmt=gen_sqlserver.dkl out=./script.sql dkl dbgen src=modelo.ddm out=./modelo.json ``` - `fmt` acepta `gen_mysql.dkl`, `gen_mysql`, `mysql`, `gen_sqlserver.dkl`, `gen_sqlserver`, `sqlserver` o `json`. Sin `fmt` se obtiene el JSON de primer paso. - Con SQL, `dbgen` escribe también, junto al script y con el mismo nombre base, el `.json` de primer paso (`script.json`), útil como `a` o `b` en una comparación posterior. - El script de MySQL empieza con `CREATE DATABASE IF NOT EXISTS ; USE ;`; el de SQL Server con el equivalente `IF NOT EXISTS … CREATE DATABASE`. Quite esas líneas para aplicar el script sobre otra base. - Orden del script: tablas, índices, llaves foráneas. El resultado de `crm.ddm` está en la página del [dialecto](/es/devkron/2.0/bibliotecas/ddm/dialecto.md). ### Comparar dos modelos ```bash dkl dbgen a=actual.json b=nuevo.json fmt=gen_mysql.dkl out=./cambio.sql dkl dbgen a=actual.json b=nuevo.json c=cliente,ciudad fmt=mysql out=./cambio.sql ``` - `a` es el modelo de partida y `b` al que se quiere llegar, ambos en JSON de primer paso. `c` (opcional) limita la comparación a esas tablas comunes (las tablas nuevas se incluyen siempre; si ningún nombre coincide, se comparan todas). - El script trae tablas nuevas (con índices y llaves) y columnas nuevas o modificadas, con las mismas reglas de `install-model`. - **Las incompatibilidades no abortan**: se imprimen y se omiten del script. Si `dbgen` imprime una incompatibilidad, `install-model` no instalaría ese modelo. - El script de comparación no incluye `CREATE DATABASE` ni `USE`. Comparando el modelo instalado de `crm_demo` (después de `crm_v2.ddm`) con un `crm_v4.ddm` que amplía `telefono` a 30 y agrega `rfc` opcional: ```bash dkl install-model db=crm@tienda action=show-model > a.json dkl dbgen src=crm_v4.ddm out=./b.json dkl dbgen a=a.json b=b.json fmt=mysql out=./cambio.sql ``` `cambio.sql`: ```sql ALTER TABLE `cliente` MODIFY COLUMN `telefono` VARCHAR(30); ALTER TABLE `cliente` ADD `rfc` VARCHAR(13); ``` ### Generar desde una conexión ```bash dkl dbgen db=miconexion@grupoapps fmt=json out=./modelo.json ``` | Parámetro | Valor | |---|---| | `db` | Conexión existente (obligatorio) | | `fmt` | `json` (ver nota sobre `ddm`) | | `out` | Archivo de salida (obligatorio) | | `schema` | Base de datos a leer; por omisión la de la conexión | > **`fmt=ddm` no funciona** en la versión actual del repositorio (rama `main`, commit `2770168`), ni con Devkron 1.x ni con 2.0: termina con `La variable 'output' ya fué inicializada con un tipo diferente al de la asignación [dbgen.dkl]`. Use `fmt=json`. Cuando se corrija, el `.ddm` generado será un punto de partida: reconstruye solo los índices de varias columnas, expresa las llaves foráneas en forma simplificada (`ref:"tabla"`) y conserva los tipos de MySQL que no son `varchar`/`text` (por ejemplo `tinyint(1)`, `bigint`), que hay que ajustar al vocabulario de DDM. ## dba Utilidad de consola para el repositorio de conexiones (usa las funciones [dba.*](/es/devkron/2.0/bibliotecas/motor/dbr/dba.md)): ```bash dkl dba show all dkl dba show qn=miconexion@grupoapps dkl dba delete qn=miconexion@grupoapps dkl dba create connection qn=miconexion@grupoapps "settings=Engine:MY_SQL,Host:127.0.0.1,Port:3306,UserName:mi_usuario,Password:MiClave#2026,SslMode:0,DefaultSchema:tienda" dkl dba create database qn=miconexion@grupoapps "settings=Engine:MY_SQL,Host:127.0.0.1,Port:3306,UserName:mi_usuario,Password:MiClave#2026,SslMode:0,DefaultSchema:tienda" ``` - `show all` lista aplicaciones y conexiones; `show` muestra los datos de `qn` (incluida la contraseña); `delete` elimina el registro (no la base); `create connection` registra una conexión a una base existente; `create database` además crea la base. - `settings` son pares `clave:valor` separados por comas, con las claves de los [datos de conexión](/es/devkron/2.0/bibliotecas/motor/dbr/). - Sin acción: `Debe indicar la acción en la línea de comando.` ```text $ dkl dba show all Repositorio de conexiones tienda (Grupo de aplicación) principal@tienda (Conexión) crm@tienda (Conexión) --------------------- $ dkl dba show qn=crm@tienda {"Host":"127.0.0.1","UserName":"bib_doc","Password":"MiClave#2026","DefaultSchema":"crm_demo","Port":"3307","SSLMode":"0","Engine":"MY_SQL"} ``` (En la salida real `show` imprime la contraseña guardada; aquí se sustituyó por el valor de ejemplo.) [Regresar a DDM](/es/devkron/2.0/bibliotecas/ddm/)