# El dialecto DDM Un archivo `.ddm` describe una base de datos relacional con la sintaxis declarativa de DKL: un **modelo** que contiene **abstracciones** (plantillas de columnas que no se crean) y **entidades** (tablas). Las herramientas [dbgen e install-model](/es/devkron/2.0/bibliotecas/ddm/herramientas.md) lo convierten en SQL. ## Primer modelo `crm.ddm`: ```dkl #include "ddm.dkh" model "CRM Demo" { #include "induxsoft.abstracts.ddm" entity "ciudad" : "TableModel" { @"nombre" string(80) required } entity "cliente" : "TableModel" { @"codigo" string(15) required unique @"nombre" string(150) required @"email" string(100) @"limite" decimal(14,2) @"notas" memo @"alta" date @"iciudad" ref:"ciudad" index "ix_cliente_nombre" { field "nombre" field "codigo" desc } } } ``` Generado con `dkl dbgen src=crm.ddm fmt=gen_mysql.dkl out=./crm.sql`: ```sql CREATE DATABASE IF NOT EXISTS crm_demo; USE crm_demo; CREATE TABLE `ciudad`( `sys_pk` INT NOT NULL AUTO_INCREMENT PRIMARY KEY, `sys_guid` VARCHAR(32) NOT NULL UNIQUE, `sys_dtcreated` DATETIME, `sys_timestamp` DATETIME NOT NULL, `sys_info` VARCHAR(32), `sys_user` VARCHAR(32), `sys_lastuser` VARCHAR(32), `sys_exported` BOOL, `sys_dtexported` DATETIME, `sys_recver` INT, `sys_deleted` BOOL, `sys_lock` INT, `nombre` VARCHAR(80) NOT NULL ); CREATE TABLE `cliente`( `sys_pk` INT NOT NULL AUTO_INCREMENT PRIMARY KEY, `sys_guid` VARCHAR(32) NOT NULL UNIQUE, `sys_dtcreated` DATETIME, `sys_timestamp` DATETIME NOT NULL, `sys_info` VARCHAR(32), `sys_user` VARCHAR(32), `sys_lastuser` VARCHAR(32), `sys_exported` BOOL, `sys_dtexported` DATETIME, `sys_recver` INT, `sys_deleted` BOOL, `sys_lock` INT, `codigo` VARCHAR(15) NOT NULL UNIQUE, `nombre` VARCHAR(150) NOT NULL, `email` VARCHAR(100), `limite` DECIMAL(14,2), `notas` TEXT, `alta` DATE, `iciudad` INT ); CREATE INDEX `ix_cliente_nombre` ON `cliente` (`nombre`, `codigo` DESC); ALTER TABLE `cliente` ADD FOREIGN KEY (`iciudad`) REFERENCES `ciudad`(`sys_pk`); ``` - `#include "ddm.dkh"` va al inicio: carga los patrones de sintaxis de DDM. - `#include "induxsoft.abstracts.ddm"` dentro de `model` trae las abstracciones `TableModel` y `EnumModel` del repositorio. - `ref:"ciudad"` creó la columna `iciudad INT` y su llave foránea a `ciudad(sys_pk)`. ## Conceptos | Elemento | Sintaxis | Qué es | |---|---|---| | Modelo | `model "nombre" { … }` | El conjunto de abstracciones y entidades. Su nombre (en minúsculas, con espacios y `.:;-/` cambiados por `_`) es el de la base que crea el script de `dbgen` | | Abstracción | `abstract "nombre" { … }` | Columnas e índices que heredan las entidades; no se crea como tabla | | Entidad | `entity "nombre" { … }` o `entity "nombre" : "abstracción1" "abstracción2" … { … }` | Una tabla. Puede descender de 0 a 5 abstracciones | | Columna | `@"nombre" tipo atributos…` | Una columna de la tabla | | Índice | `index "nombre" [unique] { field "col" [desc] … }` | Un índice de una o varias columnas | | Comentario | `// texto` | | ## Herencia y composición - Se heredan **columnas e índices** de cada abstracción ascendente. - Con varios ascendentes se aplican en orden; si dos definen la misma columna, gana el último. Las columnas propias de la entidad prevalecen sobre las heredadas (así se redefine el tamaño de una columna heredada). - Si una columna se declara **dos veces** en la misma entidad, prevalece la última definición; no es error. - Una abstracción **no** puede heredar de otra (el patrón `abstract` no admite ascendente), y una entidad **no** puede heredar de otra entidad: `El ascendente 'documento' no está definido`. - Las abstracciones pueden declararse en cualquier parte del modelo (se procesan antes que las entidades); el orden de las entidades tampoco importa. - `#include "otro.ddm"` dentro de `model` incorpora las abstracciones y entidades de otro modelo. Ejemplo con dos ascendentes, redefinición, alias de tipos, una columna repetida y un tipo que no es de DDM (`double`): ```dkl #include "ddm.dkh" model "Prueba herencia" { abstract "Auditoria" { @"creado_por" string(32) index "ix_creado" { field "creado_por" } } abstract "Base" { @"id" int key autoincrement @"nota" string(20) } entity "documento" : "Base" "Auditoria" { @"nota" string(200) @"folio" str(10) required unique @"activo" boolean @"hora" time @"cantidad" integer @"descripcion" text @"total" double @"folio" string(12) required unique } } ``` ```sql CREATE DATABASE IF NOT EXISTS prueba_herencia; USE prueba_herencia; CREATE TABLE `documento`( `id` INT NOT NULL AUTO_INCREMENT PRIMARY KEY, `nota` VARCHAR(200), `creado_por` VARCHAR(32), `folio` VARCHAR(12) NOT NULL UNIQUE, `activo` BOOL, `hora` TIME, `cantidad` INT, `descripcion` TEXT, `total` double ); CREATE INDEX `ix_creado` ON `documento` (`creado_por`); ``` ## Abstracciones incluidas `induxsoft.abstracts.ddm` define las del modelo de datos de Devkron (ver [Modelo de datos de Devkron](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md)): ```dkl #include "ddm.dkh" model "Induxsoft abstracts" { abstract "TableModel" { @"sys_pk" int key required autoincrement @"sys_guid" string(32) unique required @"sys_dtcreated" datetime @"sys_timestamp" datetime required @"sys_info" string(32) @"sys_user" string(32) @"sys_lastuser" string(32) @"sys_exported" bool @"sys_dtexported" datetime @"sys_recver" int @"sys_deleted" bool @"sys_lock" int } abstract "EnumModel" { @"id" int key @"const" string(150) } } ``` El repositorio trae también `induxsoft.sys_tables.ddm` (tablas de sistema: `tuser`, `usergroup`, `sys_batch`… necesarias para `dbr.login`) y `dbm.sys_tables.ddm` (bitácora de `install-model`). ## Tipos de columna | DDM | MySQL | SQL Server | |---|---|---| | `bool` | `BOOL` | `BIT` | | `int` | `INT` | `INT` | | `datetime` | `DATETIME` | `DATETIME` | | `date` | `DATE` | `DATE` | | `time` | `TIME` | `TIME` | | `decimal(p,s)` | `DECIMAL(p,s)` | `DECIMAL(p,s)` | | `string(n)` | `VARCHAR(n)`; si `n` > 4096, `TEXT` | `VARCHAR(n)` | | `memo` | `TEXT` | `VARCHAR(65535)` (ver nota) | | `mmemo` | `MEDIUMTEXT` | `VARCHAR(16777215)` (ver nota) | | `lmemo` | `LONGTEXT` | `VARCHAR(MAX)` | - **Alias:** `str` y `varchar` = `string`; `boolean` y `bit` = `bool`; `integer` = `int`; `text` = `memo`. - **Otros tipos** (`bigint`, `smallint`, `float`, `double`, `blob`) pasan tal cual al SQL, sin validarse. - `string` sin tamaño equivale a `string(32)`. - `decimal`: indique siempre `(precisión, escala)`; los valores por omisión previstos (12, 4) no se aplican. - **Nota SQL Server:** `VARCHAR(65535)` y `VARCHAR(16777215)` no son válidos en SQL Server (el máximo es 8000 o `MAX`). Para SQL Server use `lmemo` en lugar de `memo`/`mmemo`, o corrija el script generado. ## Atributos de columna Hasta **tres** por columna, en cualquier orden: | Atributo | Efecto | |---|---| | `key` (o `primarykey`) | Clave primaria. Implica `required` (no agrega `unique`, la clave ya es única) | | `required` | `NOT NULL`. Sin él la columna admite nulos | | `unique` | Restricción `UNIQUE` en la columna (el nombre del índice lo pone el motor) | | `autoincrement` | Valor incremental; la columna debe ser la clave | - **Clave compuesta:** no ponga `key` en dos columnas (cada una emitiría su `PRIMARY KEY`); use un `index … unique` con ambas. - Al comparar modelos, los nombres de columna no distinguen mayúsculas. - **Sin efecto:** `indexed` e `indexed_desc` se leen pero no se aplican; las sintaxis `list:`, `enum:` y los bloques `enum` existen en `ddm.dkh` pero el generador no las procesa. ## Llaves foráneas | Sintaxis | Resultado | |---|---| | `@"col" ref:"entidad"` | Columna del tipo de la clave de `entidad` y llave foránea a esa clave. La entidad debe tener una columna `key` | | `@"col" tipo ref:"entidad" ["columna"]` | Tipo y columna referida explícitos. Si se omite el tipo, se toma el de la columna referida | | Con atributos | `@"icategoria" int ref:"ctpersona" ["sys_pk"] required` | - Las llaves se crean después de todas las tablas (`ALTER TABLE … ADD FOREIGN KEY`), así que el orden de las entidades no importa. - Solo referencias de una columna, sin `ON DELETE`/`ON UPDATE`; el nombre de la restricción lo pone el motor. - Una columna `ref:` admite nulos salvo que lleve `required`. - Al actualizar una base existente, una columna `ref:` nueva en una tabla que ya existe se crea **sin** su llave foránea. ## Índices ```dkl index "indice1" unique { field "campo1" field "campo2" desc } ``` - De los modificadores de índice solo `unique` tiene efecto; `algorithm` se guarda en el JSON pero no se usa. - Se heredan de las abstracciones igual que las columnas. - En una instalación se crean después de las tablas y antes de las llaves foráneas. - Al actualizar, los índices de tablas existentes no se comparan (agregar o cambiar un `index` en una tabla que ya existe no hace nada); los de tablas nuevas sí se crean. ## Compatibilidad: wide y strict Las directivas `wide compatibility` (predeterminada) y `strict compatibility` controlan cómo compara `install-model` el modelo nuevo con el instalado. Se escriben solas en su línea dentro de `model`, y son **posicionales**: cada entidad toma la última directiva que aparece antes de ella. ```dkl #include "ddm.dkh" model "mi_modelo" { wide compatibility entity "a" { @"x" int } strict compatibility entity "b" { @"x" int } } ``` En el JSON de primer paso (`dkl dbgen src=comp.ddm out=./comp.json`) la entidad `a` queda con `"compatibility":"wide"` y `b` con `"strict"`. La única diferencia: si una columna `required` o `key` de una entidad existente **desaparece** del modelo nuevo, `wide` lo acepta (la columna sigue en la base) y `strict` lo marca como incompatible y aborta. En ninguno se borra la columna. `strict` sirve para avisar que una columna `NOT NULL` retirada del modelo seguirá existiendo y hará fallar los `INSERT` que no la llenen. La variante por entidad (`strict compatibility: 'entidad'`) está deshabilitada. Un modelo `.json` sin el campo `compatibility` se trata como `wide`. ## Modelo de ejemplo completo El modelo de un CRM, con abstracciones propias, entidades sin ascendente, enumeraciones, llaves foráneas con las dos sintaxis, un índice compuesto y referencias a entidades definidas después: ```dkl #include "ddm.dkh" model "CRM Sales" { abstract "induxsoftTableModel" { @"sys_pk" int key autoincrement @"sys_guid" string(32) unique required @"sys_dtcreated" datetime required @"sys_timestamp" datetime required @"sys_recver" int @"sys_deleted" bool @"sys_lock" int @"sys_info" string(32) @"sys_user" string(32) } abstract "induxsoftEnumModel" { @"id" int key @"const" string(150) } entity "tabla_solita" //Una tabla de que no desciende de ninguna abstracción { @"campo1" string(10) key @"campo2" int } entity "tuser" : "induxsoftTableModel" { @"userid" string required unique @"username" string(250) required } entity "domicilio" : "induxsoftTableModel" { @"codPos" string } entity "agente" : "induxsoftTableModel" { @"codigo" string(15) required unique @"nombre" string(150) required unique @"uf_iuser" int ref:"tuser" ["sys_pk"] unique @"codnomina" string(50) @"email" string(50) @"notas" string(2048) @"pcomision" decimal(18,8) @"telefono" string(150) @"domicilio1" int ref:"domicilio" ["sys_pk"] @"uf_sys_baja" bool index "indice1" unique { field "uf_iuser" field "nombre" desc } } entity "cmdedocivil" : "induxsoftEnumModel" { } entity "cmdsexo" : "induxsoftEnumModel" { } entity "ctpersona" : "induxsoftTableModel" { @"descripcion" string(50) } entity "ciudad" : "induxsoftTableModel" { @"codigo" string(8) } entity "pais" : "induxsoftTableModel" { @"codigo" string(8) } entity "persona" : "induxsoftTableModel" { @"nombre" string(150) required // @"telefono" string(15) @"email" string(100) @"apellido1" string(50) required @"apellido2" string(50) @"autoid" string(150) @"codigo" string(32) @"codpostal" string(10) @"colonia" string(100) @"domicilio" string(255) @"email2" string(100) @"fnacimiento" date @"msn" string(100) @"notas" memo @"skype" string(100) @"sys_guid_contacto" string(32) @"tel_casa" string(80) @"tel_movil" string(80) @"tel_trabajo" string(80) @"tratamiento" string(10) @"tel_movil" string(80) @"edocivil" int ref:"cmdedocivil" ["id"] @"sexo" int ref:"cmdsexo" ["id"] @"icategoria" int ref:"ctpersona" ["sys_pk"] required @"iciudad" int ref:"ciudad" ["sys_pk"] @"iejecutivo" int ref:"agente" ["sys_pk"] @"nacionalidad" int ref:"pais" ["sys_pk"] } entity "ctorganizacion" : "induxsoftTableModel" { @"descripcion" string(50) } entity "organizacion" : "induxsoftTableModel" { @"nombre" string(150) unique required @"codigo" string(32) @"codpostal" string(10) @"domicilio" string(255) @"email" string(100) @"fax" string(80) @"nomcomercial" string(150) @"notas" memo @"sys_guid_cliente" string(32) @"sys_guid_otro" string(32) @"sys_guid_proveedor" string(32) @"tel1" string(80) @"tel2" string(80) @"tel3" string(80) @"website" string(150) @"icategoria" int ref:"ctorganizacion" ["sys_pk"] required @"iciudad" int ref:"ciudad" ["sys_pk"] @"iejecutivo" int ref:"agente" ["sys_pk"] @"nacionalidad" int ref:"pais" ["sys_pk"] } entity "sales_pipeline_stage" : "induxsoftTableModel" { @"ref_pipeline" ref:"sales_pipeline" required @"sequence" int required //El número de secuencia de las etapas en el pipeline @"name" string(50) required @"probability" decimal(4,1) @"stuck_in_days" int } entity "sales_pipeline" : "induxsoftTableModel" { @"name" string(50) @"probability" bool } } ``` `dbgen` lo convierte en 14 tablas, un índice único compuesto y sus llaves foráneas. Observe que `persona` declara `tel_movil` dos veces (vale la última) y que `sales_pipeline_stage` referencia a `sales_pipeline`, definida después. ## Errores del modelo | Mensaje | Causa | |---|---| | `El ascendente 'X' no está definido` | Una entidad hereda de una abstracción inexistente (o de otra entidad) | | `La tabla 'X' a la que se hace referencia en 'Y' no existe en el modelo.` | `ref:` a una entidad inexistente | | `No se puede resolver o la columna referenciada de la tabla 'X' desde la tabla 'Y' porque no tiene una clave primaria indicada.` | `ref:` simplificado a una entidad sin `key` | | `La columna 'K' referenciada de la tabla 'X' desde la tabla 'Y' no existe.` | Sintaxis completa con una columna inexistente | | `No hay objetos de bases de datos definidos` | El archivo no define ningún modelo | ## Lo que DDM no tiene Valores por omisión (`DEFAULT`), restricciones `CHECK`, motor, juego de caracteres o intercalación (se usan los del servidor), acciones `ON DELETE`/`ON UPDATE`, llaves foráneas de varias columnas, clave primaria compuesta (use un índice único), renombrar o eliminar objetos, vistas, procedimientos y disparadores. [Regresar a DDM](/es/devkron/2.0/bibliotecas/ddm/)