# Modelo de datos de Devkron: sesiones, entidades y bloqueos El modelo de datos de Devkron es un **patrón de diseño** para bases de datos de aplicaciones: cada tabla (entidad) tiene los mismos campos de control, hay tablas de sistema para usuarios, sesiones y bloqueos, y las operaciones de guardado manejan la concurrencia. `dbr.dkh` trae funciones que aprovechan ese patrón para iniciar sesión, leer y guardar entidades sin escribir SQL, bloquear filas y borrarlas de forma lógica. Estas funciones necesitan una conexión abierta con **`dbr.login`** o **`dbr.reconnect`** (una sesión), no con `dbr.open`. ## Objetivos del patrón - **Confiabilidad**: claves primarias, foráneas, restricciones y transacciones obligatorias; control de concurrencia para que nadie sobrescriba sin darse cuenta los cambios de otro. - **Escalabilidad**: migrar los datos a otro motor con mínimos cambios en el código; respaldo, integración y replicación previstos desde el diseño. - **Adaptabilidad**: hacer crecer el sistema con poco esfuerzo, con la misma API para todos los motores, y que el programador se concentre en la funcionalidad, no en las previsiones de acceso a datos. ## Campos de control | Campo | Tipo | Para qué | |---|---|---| | `sys_pk` | Entero autoincremental | Clave primaria (alcance local: única en esa tabla y esa base) | | `sys_guid` | Texto(32) | Identificador global único (alcance global: único entre bases) | | `sys_dtcreated` | Fecha/hora | Creación de la fila | | `sys_timestamp` | Fecha/hora | Última actualización | | `sys_recver` | Entero | Versión de la fila: control de concurrencia optimista | | `sys_lock` | Entero, nulo, sin duplicados | Id del bloqueo pesimista vigente (`NULL` = sin bloquear) | | `sys_deleted` | Booleano | Marca de eliminación lógica | | `sys_exported`, `sys_dtexported` | Booleano, fecha | Exportación por las utilidades de transporte de datos | | `sys_info`, `sys_user`, `sys_lastuser` | Texto | Información y usuarios de auditoría (los llena su aplicación) | **Claves foráneas**: siempre enteras y con el valor del `sys_pk` de la tabla a la que apuntan. **¿Por qué un GUID además de `sys_pk`?** El autoincremental es lo más eficiente, pero solo es único dentro de su tabla y su base: el cliente con `sys_pk` 15 de la base A no es el 15 de la base B. Para saber si un registro ya existe en otra base, o para copiarlo, se usa `sys_guid`, que es único en cualquier lugar. Se guarda como texto de 32 caracteres (no con el tipo GUID de cada motor) para no depender de un motor en particular; `uuid()` genera valores en ese formato. **Tablas de sistema**: `tuser` (usuarios: `userid`, `username`, `pwd`, `pwdmd5`…), `sys_session` (sesiones), `sys_catalog` (catálogo de entidades: `objectname`) y `sys_lockinfo` (bloqueos: `sys_table`, `sys_row`, `sys_token`, `sys_active`). Para crearlas en una base use el modelo `induxsoft.sys_tables.ddm` de [DDM](/es/devkron/2.0/bibliotecas/ddm/). ## Funciones ### Sesiones | Función | Qué hace | |---|---| | `dbr.login(qname, usuario, contraseña)` | Valida el usuario contra `tuser`, crea una sesión en `sys_session` y devuelve la conexión abierta. **Cierra las sesiones anteriores del mismo usuario** (las marca con `sys_deleted=1`) | | `dbr.getSID(ses)` | Devuelve el id de la sesión (`sys_session.sys_guid`, 32 caracteres hexadecimales) | | `dbr.reconnect(qname, sid)` | Devuelve una conexión abierta para una sesión existente y vigente, sin pedir contraseña (así se mantiene la sesión entre peticiones web) | | `dbr.logout(ses)` | Cierra la sesión (`sys_deleted=1`) y la conexión. Un segundo `dbr.logout` no hace nada | | `dbr.setHashUnicode(v)` | Con `@true`, `dbr.login` compara el MD5 de la contraseña codificada en UTF-16; con `@false` (predeterminado), en ASCII. Afecta a todo el proceso | Cómo compara `dbr.login` en 2.0 (igual en los cuatro motores, con consulta parametrizada): - el usuario no distingue mayúsculas y se le quitan espacios; - con hash ASCII (predeterminado) acepta si `md5(contraseña)` coincide con `LOWER(pwd)` **o** con `LOWER(pwdmd5)`; con hash Unicode, solo contra `pwd`; - una columna `NULL` no coincide; si `tuser` no tiene `pwdmd5`, se compara solo `pwd`. En 1.x MySQL, PostgreSQL y Firebird comparaban siempre contra `pwd`, y SQL Server concatenaba usuario y hash en el SQL. Efecto práctico: una base que solo llenaba `pwdmd5` ahora permite entrar. Una base con contraseñas guardadas como MD5 en `pwd` o en `pwdmd5` funciona sin cambios. ### Entidades | Función | Qué hace | |---|---| | `dbr.get(ses, tabla, sys_pk)` | Registro de la fila con ese `sys_pk`; `@null` si no existe | | `dbr.getg(ses, tabla, guid)` | Registro de la fila con ese `sys_guid`; `@null` si no existe | | `dbr.getw(ses, tabla, filtro, params)` | Registro de la **primera** fila que cumple el filtro SQL (con parámetros); `@null` si ninguna | | `dbr.save(ses, tabla, registro)` | **Alta** si el registro no trae `sys_pk` (o es 0): asigna `sys_guid`, fechas y `sys_recver`=0. **Cambio** si trae `sys_pk`: hace `UPDATE … SET sys_recver=sys_recver+1 … WHERE sys_pk=… AND sys_recver=` y solo actualiza los campos que vienen en el registro. Devuelve el registro con los campos de control completos | | `dbr.erase(ses, tabla, sys_pk)` | Eliminación **lógica**: `sys_deleted=1` | El nombre de tabla no puede tener espacios ni comillas (`Nombre de entidad inválido`). **Concurrencia optimista con `sys_recver`.** Lea la entidad, guarde su `sys_recver` (en un formulario web, como campo oculto) y mándelo de vuelta al guardar. Si otro usuario guardó antes, el `sys_recver` ya no coincide y `dbr.save` falla con `No fue posible actualizar la entidad`: muestre los datos actuales y pida repetir el cambio. Ese número es lo que evita que un cambio se pierda en silencio. ### Bloqueo pesimista Impide que otra sesión modifique una fila mientras un usuario la edita (por ejemplo, un pedido abierto en una caja). | Función | Qué hace | |---|---| | `dbr.lock(ses, tabla, sys_pk)` | Bloquea la fila: inserta un registro en `sys_lockinfo`, pone su id en `sys_lock` de la fila y lo devuelve. La tabla debe estar en `sys_catalog`. Si la misma sesión ya la tenía bloqueada, devuelve el **mismo** id; si la tiene otra sesión, error | | `dbr.chklock(ses, tabla, id)` | `@true` si el bloqueo `id` sigue vigente para esta sesión. Si no, **lanza un error** (no devuelve 0) | | `dbr.unlock(ses, id)` | Libera el bloqueo (`sys_active=0` y `sys_lock` en nulo); devuelve `@true`. Un solo `dbr.unlock` libera aunque se haya llamado `dbr.lock` varias veces | El bloqueo **no expira solo**: dura hasta `dbr.unlock`. Si la aplicación puede quedar a medias (una pestaña que se cierra), libere los bloqueos huérfanos con un proceso propio. La documentación 1.x describía un tiempo de expiración en el pseudocódigo del patrón; la implementación de `dbr` no lo aplica. > **La firma de `dbr.unlock` es `dbr.unlock(ses, id)`**, con dos argumentos. La documentación 1.x mostraba `dbr.unlock(db, tabla, id)`. ### Eliminación de entidades - **Lógica**: `dbr.erase` marca `sys_deleted=1`. La fila sigue en la base con sus relaciones; sus consultas deben filtrar `WHERE IFNULL(sys_deleted,0)=0`. - **Definitiva**: un `DELETE` (con `dbr.delete` o `dbr.execute`). Puede limitarse a una fila o ir en cascada borrando antes las dependientes. Úsela con cuidado. ## Ejemplo completo El ejemplo crea las tablas del modelo, dos usuarios de prueba y una entidad `cliente`, y recorre todas las funciones: ```dkl #include "dkli.dkh" #! program "modelo" { #include "functions.dkh" #include "serialize.dkh" #include "dbr.dkh" // Preparación: tablas del modelo de Devkron ref db = dbr.open("principal@tienda") text ddl { "DROP TABLE IF EXISTS sys_lockinfo; DROP TABLE IF EXISTS sys_session; DROP TABLE IF EXISTS sys_catalog; DROP TABLE IF EXISTS tuser; DROP TABLE IF EXISTS cliente;" "CREATE TABLE sys_session (sys_pk int AUTO_INCREMENT PRIMARY KEY, sys_timestamp datetime NOT NULL, sys_guid varchar(32) NOT NULL UNIQUE, sys_dtcreated datetime NULL, sys_user varchar(5) NULL, sys_lastuser varchar(5) NULL, sys_exported bool NULL, sys_dtexported datetime NULL, sys_info varchar(32) NULL, sys_recver int NULL, sys_deleted bool NULL, sys_lock int NULL, iuser INT NOT NULL, clientinfo varchar(64) NOT NULL);" "CREATE TABLE sys_catalog (sys_pk int AUTO_INCREMENT PRIMARY KEY, sys_timestamp datetime NOT NULL, sys_guid varchar(32) NOT NULL UNIQUE, sys_dtcreated datetime NULL, sys_user varchar(5) NULL, sys_lastuser varchar(5) NULL, sys_exported bool NULL, sys_dtexported datetime NULL, sys_info varchar(32) NULL, sys_recver int NULL, sys_deleted bool NULL, sys_lock int NULL, objectname varchar(64) NOT NULL UNIQUE, objectdescription varchar(4096) NULL, objecttype varchar(64) NOT NULL);" "CREATE TABLE sys_lockinfo (sys_pk int AUTO_INCREMENT PRIMARY KEY, sys_timestamp datetime NOT NULL, sys_guid varchar(32) NOT NULL UNIQUE, sys_dtcreated datetime NULL, sys_user varchar(5) NULL, sys_lastuser varchar(5) NULL, sys_exported bool NULL, sys_dtexported datetime NULL, sys_info varchar(32) NULL, sys_recver int NULL, sys_deleted bool NULL, sys_lock int NULL, sys_table int NOT NULL, sys_row int NOT NULL, sys_token int NOT NULL, sys_active bool NULL);" "CREATE TABLE tuser (sys_pk Int AUTO_INCREMENT PRIMARY KEY, sys_timestamp Datetime NOT NULL, sys_guid VARCHAR(32) NOT NULL UNIQUE, sys_dtcreated Datetime, sys_user VARCHAR(5), sys_lastuser VARCHAR(5), sys_exported bool, sys_dtexported Datetime, sys_info VARCHAR(32), locked bool, message VARCHAR(255), notes LONGTEXT, pwd VARCHAR(32), userid VARCHAR(120) NOT NULL UNIQUE, username VARCHAR(120) NOT NULL, pwdmd5 VARCHAR(64), sys_recver int NULL, sys_deleted bool NULL, sys_lock int NULL);" "CREATE TABLE cliente (sys_pk int AUTO_INCREMENT PRIMARY KEY, sys_timestamp datetime NOT NULL, sys_guid varchar(32) NOT NULL UNIQUE, sys_dtcreated datetime NULL, sys_recver int NULL, sys_deleted bool NULL, sys_lock int NULL, codigo varchar(20) NOT NULL UNIQUE, nombre varchar(120) NOT NULL, limite decimal(14,2) NULL);" "INSERT INTO sys_catalog (sys_timestamp, sys_guid, sys_dtcreated, objectname, objecttype) VALUES (NOW(), REPLACE(UUID(),'-',''), NOW(), 'cliente', 'TABLE');" } ref sentencias = split(ddl, ";") go foreach.lstr(value:s) with(sentencias) { if trim(s) != "" { do dbr.execute(db, s, @null) } } new u { @"pwd": md5("MiClave#2026") } do dbr.execute(db, "INSERT INTO tuser (sys_timestamp, sys_guid, sys_dtcreated, userid, username, pwd) VALUES (NOW(), REPLACE(UUID(),'-',''), NOW(), 'cajero1', 'Cajero de prueba', @pwd)", u) do dbr.execute(db, "INSERT INTO tuser (sys_timestamp, sys_guid, sys_dtcreated, userid, username, pwd) VALUES (NOW(), REPLACE(UUID(),'-',''), NOW(), 'cajero2', 'Otro cajero', @pwd)", u) // 1. Iniciar sesión ref ses = dbr.login("principal@tienda", "cajero1", "MiClave#2026") sid = dbr.getSID(ses) do print("sesión: " + str(length(sid)) + " caracteres") // 2. Alta con dbr.save (sin sys_pk) new c { @"codigo": "C-001" @"nombre": "Abarrotes La Esperanza" @"limite": 15000 } ref guardado = dbr.save(ses, "cliente", c) pk = field.num(guardado, "sys_pk") do print("alta: sys_pk=" + str(pk) + " sys_recver=" + str(field.num(guardado, "sys_recver")) + " guid=" + str(length(field.str(guardado, "sys_guid")))) // 3. Lectura por clave, por GUID y por expresión ref leido = dbr.get(ses, "cliente", pk) do print("get: " + field.str(leido, "nombre")) ref porguid = dbr.getg(ses, "cliente", field.str(guardado, "sys_guid")) do print("getg: " + field.str(porguid, "codigo")) new filtro { @"cod": "C-001" } ref porexpr = dbr.getw(ses, "cliente", "codigo = @cod", filtro) do print("getw: " + str(field.num(porexpr, "limite"))) // 4. Cambio con concurrencia optimista new cambio { @"sys_pk": pk @"sys_recver": field.num(leido, "sys_recver") @"limite": 20000 } ref r2 = dbr.save(ses, "cliente", cambio) do print("cambio: sys_recver=" + str(field.num(r2, "sys_recver"))) new viejo { @"sys_pk": pk @"sys_recver": 0 @"limite": 1 } do dbr.save(ses, "cliente", viejo) exception { do print("versión vieja: " + last_error()) do clear_exceptions() } // 5. Bloqueo pesimista idlock = dbr.lock(ses, "cliente", pk) do print("lock: " + str(idlock > 0)) do print("lock otra vez (misma sesión): " + str(dbr.lock(ses, "cliente", pk) == idlock)) do print("chklock: " + str(dbr.chklock(ses, "cliente", idlock))) ref otra = dbr.login("principal@tienda", "cajero2", "MiClave#2026") do dbr.lock(otra, "cliente", pk) exception { do print("otra sesión: " + last_error()) do clear_exceptions() } do print("unlock: " + str(dbr.unlock(ses, idlock))) do print("chklock tras unlock: " + str(dbr.chklock(ses, "cliente", idlock))) exception { do print("chklock tras unlock: " + last_error()) do clear_exceptions() } do dbr.logout(otra) // 6. Eliminación lógica do dbr.erase(ses, "cliente", pk) do print("sys_deleted: " + dbr.str(db, "SELECT sys_deleted FROM cliente WHERE sys_pk = " + str(pk), @null)) // 7. Reconectar con el id de sesión y cerrar sesión ref rc = dbr.reconnect("principal@tienda", sid) do print("reconnect: " + str(dbr.getSID(rc) == sid)) do dbr.close(rc) do dbr.logout(ses) do print("logout: is_open=" + str(dbr.is_open(ses))) ref rc2 = dbr.reconnect("principal@tienda", sid) exception { do print("reconnect tras logout: " + last_error()) do clear_exceptions() } do dbr.login("principal@tienda", "cajero1", "otra") exception { do print("login: " + last_error()) do clear_exceptions() } do dbr.get(db, "cliente", 1) exception { do print("con dbr.open: " + last_error()) do clear_exceptions() } do dbr.execute(db, "DROP TABLE sys_lockinfo, sys_session, sys_catalog, tuser, cliente", @null) do dbr.close(db) } ``` ```text sesión: 32 caracteres alta: sys_pk=1 sys_recver=0 guid=32 get: Abarrotes La Esperanza getg: C-001 getw: 15000.00 cambio: sys_recver=1 versión vieja: {1} Error en 'dbr.save. (Save Error. No fue posible actualizar la entidadException has been thrown by the target of an invocation.) [modelo.dkl][Ln= 71] lock: 1 lock otra vez (misma sesión): 1 chklock: 1 otra sesión: {1} Error en 'dbr.lock. (Lock Error. No se logró establecer el bloqueo en la fila solicitadaException has been thrown by the target of an invocation.) [modelo.dkl][Ln= 83] unlock: 1 chklock tras unlock: {1} Error en 'dbr.chklock. (CheckLock Error. No se encontró fila bloqueada para el id proporcionadoException has been thrown by the target of an invocation.) [modelo.dkl][Ln= 90] sys_deleted: True reconnect: 1 logout: is_open=0 reconnect tras logout: {1} Error en 'dbr.reconnect. (Error de recuperación de sesión, la sesión ha caducado o no es válida.Exception has been thrown by the target of an invocation.) [modelo.dkl][Ln= 106] login: {1} Error en 'dbr.login. (Error de inicio de sesión, verifique Usuario y ContraseñaException has been thrown by the target of an invocation.) [modelo.dkl][Ln= 112] con dbr.open: {1} Error en 'dbr.get. (La conexión no es del tipo esperadoException has been thrown by the target of an invocation.) [modelo.dkl][Ln= 118] ``` Observe: - `dbr.save` de un alta deja `sys_recver` en 0; el cambio que trae `sys_recver` 0 lo sube a 1; un segundo cambio con `sys_recver` 0 (versión vieja) es rechazado. - La "otra sesión" es de **otro usuario** (`cajero2`): un `dbr.login` del mismo usuario habría cerrado la primera sesión. - Las funciones del modelo con una conexión de `dbr.open` fallan con `La conexión no es del tipo esperado`. ## Cambios en 2.0 | Antes (1.x) | Ahora (2.0) | |---|---| | MySQL: `dbr.lock`, `dbr.chklock` y `dbr.unlock` fallaban siempre; SQL Server: un segundo `lock` "funcionaba" y `unlock` fallaba | Funcionan en los cuatro motores; `lock` devuelve el `sys_pk` de `sys_lockinfo` | | `dbr.lock` de una fila ya bloqueada por la misma sesión fallaba | Devuelve el mismo id (reentrante) | | `dbr.getg` buscaba por `sys_pk` (nunca encontraba; en SQL Server dejaba la conexión inutilizable) | Busca por `sys_guid` | | `dbr.save` de un cambio devolvía `sys_recver=0` y `sys_guid` vacío | Devuelve la fila guardada, lista para el siguiente cambio | | `dbr.save` con un campo binario fallaba | Se guarda como binario | | `dbr.login` distinto por motor; SQL Server armaba el SQL concatenando | Unificado y parametrizado (ver arriba) | | MySQL: `dbr.login`, `dbr.reconnect`, `dbr.unlock` y `dbr.save` con bloqueo esperaban ~111 s ante errores permanentes | Error inmediato | | Un `dbr.login` fallido dejaba abierta la conexión | Se cierra | ## Errores típicos | Mensaje | Causa | Solución | |---|---|---| | `Error de inicio de sesión, verifique Usuario y Contraseña` | Usuario o contraseña incorrectos, o hash distinto (ASCII/Unicode) | Revise `tuser` y `dbr.setHashUnicode` | | `Error de recuperación de sesión, la sesión ha caducado o no es válida.` | `dbr.reconnect` con una sesión cerrada (`dbr.logout`, o un `dbr.login` posterior del mismo usuario) | Pida iniciar sesión otra vez | | `La conexión no es del tipo esperado` | Función del modelo con una conexión de `dbr.open` | Use `dbr.login` o `dbr.reconnect` | | `No fue posible actualizar la entidad` | `sys_recver` desactualizado, o el `sys_pk` no existe | Vuelva a leer la entidad | | `No se logró establecer el bloqueo en la fila solicitada` | Otra sesión tiene bloqueada la fila | Avise al usuario; reintente después | | `No se encontró la entidad solicitada en el catálogo de objetos` | La tabla no está en `sys_catalog` | Regístrela (`objectname` = nombre de la tabla) | | `Erase Error. No se logró la eliminación lógica del registro.` | `dbr.erase` de un `sys_pk` que no existe | Verifique el `sys_pk` | | `Nombre de entidad inválido 'dk ent'` | Nombre de tabla con espacio o comilla | Use el nombre real de la tabla | | `No se encontró fila bloqueada para el id proporcionado` | `dbr.chklock` de un bloqueo ya liberado o de otra sesión | Vuelva a bloquear | [Regresar a dbr.dkh](/es/devkron/2.0/bibliotecas/motor/dbr/)