# dbr.dkh: bases de datos relacionales `dbr.dkh` es la capa de datos de Devkron: abre conexiones por nombre, ejecuta SQL con parámetros, devuelve resultados como valores, registros, listas o tablas, maneja transacciones y, para las bases que siguen el **modelo de datos de Devkron**, ofrece inicio de sesión, lectura y guardado de entidades con control de concurrencia, bloqueos y eliminación lógica. También administra el repositorio de conexiones. Funciona igual con **MySQL, SQL Server, PostgreSQL y Firebird**: el mismo código DKL, distinto adaptador. ```dkl #include "dkli.dkh" #! program "consulta" { #include "functions.dkh" #include "dbr.dkh" ref db = dbr.open("principal@tienda") do print(dbr.str(db, "SELECT version()", @null)) do dbr.close(db) } ``` ```text 8.0.46-0ubuntu0.24.04.4 ``` ## Páginas | Página | Contenido | |---|---| | [Consultas y comandos](/es/devkron/2.0/bibliotecas/motor/dbr/consultas.md) | `dbr.open`, `dbr.close`, `dbr.is_open`, `dbr.execute`, `dbr.str`, `dbr.num`, `dbr.scalar`, `dbr.rec`, `dbr.list`, `dbr.table`, `dbr.insert`, `dbr.update`, `dbr.delete`, `dbr.sql`, parámetros, nombres cualificados | | [Transacciones](/es/devkron/2.0/bibliotecas/motor/dbr/transacciones.md) | `dbr.begin`, `dbr.commit`, `dbr.rollback`, `dbr.in_transaction` | | [Modelo de datos de Devkron](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md) | Campos de control `sys_*`, `dbr.login`, `dbr.logout`, `dbr.reconnect`, `dbr.getSID`, `dbr.setHashUnicode`, `dbr.get`, `dbr.getg`, `dbr.getw`, `dbr.save`, `dbr.erase`, `dbr.lock`, `dbr.chklock`, `dbr.unlock` | | [Administración de conexiones](/es/devkron/2.0/bibliotecas/motor/dbr/dba.md) | `dba.*`: crear bases y conexiones, listar aplicaciones y conexiones, repositorio en base de datos | ## Conexiones: connections.xml y nombres cualificados Un programa nunca escribe el servidor, el usuario ni la contraseña: abre la conexión por su **nombre cualificado** `conexión@aplicación`. Los datos reales están en el **repositorio de conexiones**, el archivo `connections.xml`: ```xml tienda principal MY_SQL MY_SQL 127.0.0.1 mi_usuario MiClave#2026 tienda 3306 0 ]]> true ``` - Una **aplicación** (`AppItem`) agrupa conexiones; cada **conexión** (`CnnItem`) tiene nombre, motor (`EngineType`) y sus datos en `XmlSettings`. - `XmlSettings` puede ir en claro dentro de un bloque `CDATA` (como arriba) o **cifrado** en Base64; las conexiones que crean `dba.createconnection`, `dba.createdb` o la utilidad `dba` se guardan cifradas. - `Default` = `true` marca la conexión predeterminada de la aplicación: `dbr.open("@tienda")` abre esa. - La distribución trae `connections.xml.example` como plantilla. - Devkron busca `connections.xml` y `adapters.xml` **primero en el directorio de trabajo** del proceso y, si no están, **junto a los ensamblados de Devkron** (la carpeta de `dkl`). En 1.x solo se buscaban en el directorio de trabajo. - El repositorio se lee una vez por proceso: una conexión que se crea durante la ejecución con `dba.*` se ve completa en las ejecuciones siguientes (en FastCGI, reinicie el servicio después de editar el archivo). ### Formas del nombre cualificado | Nombre | Significado | |---|---| | `principal@tienda` | Conexión `principal` de la aplicación `tienda` | | `@tienda` | Conexión predeterminada de `tienda` | | `conexiones@miempresa/sucursal1@ventas` | Conexión `sucursal1@ventas` guardada en un **repositorio en base de datos**, al que se llega con la conexión `conexiones@miempresa` (ver [dba](/es/devkron/2.0/bibliotecas/motor/dbr/dba.md)) | ### Datos de conexión por motor Son las etiquetas dentro de `` (o los campos del registro que recibe `dba.createconnection`): | Etiqueta | MySQL | SQL Server | PostgreSQL | Firebird | |---|---|---|---|---| | `Name` (motor) | `MY_SQL` | `SQL_SERVER` | `POSTGRE_SQL` | `FB_SQL` | | `Host` | Nombre o IP | Nombre o IP; puerto con coma: `127.0.0.1,1433` | Nombre o IP | Nombre o IP | | `Port` | 3306 | (en `Host`) | 5432 | 3050 | | `UserName`, `Password` | Usuario | Usuario | Usuario | Usuario (p. ej. `SYSDBA`) | | `DefaultSchema` | Base de datos | Base de datos | Base de datos | **Ruta del archivo** `.fdb` | | Otras | `SSLMode` (0 sin TLS) | `WindowsAuthMode` (`true` autenticación de Windows) | `NameSpaceSchema` (esquema, p. ej. `public`) | | | `Parameters` | Opciones extra del driver separadas por `;` | igual | igual | igual | Ejemplos de `Parameters`: - MySQL 8 remoto con `caching_sha2_password`: `AllowPublicKeyRetrieval=true`; - MySQL con fechas `0000-00-00`: `ConvertZeroDateTime=true` (sin esto, leerlas falla); - SQL Server sin certificado confiable: `Encrypt=false` o `TrustServerCertificate=true`; - Firebird con datos en Latin-1: `Charset=ISO8859_1`. En 2.0 `` y `` se leen siempre (en 1.x MySQL los perdía si faltaba `` y SQL Server nunca leía ``). ## Adaptadores Cada motor se atiende con un adaptador registrado en `adapters.xml`, junto a `dkl`. La distribución 2.0 trae y registra los cuatro; solo se carga el que usa cada conexión. | Motor | `EngineType` | Adaptador | Driver | Versiones probadas | |---|---|---|---|---| | MySQL | `MY_SQL` | `MySqlAdapter.dll` | MySqlConnector 2.6.2 | 8.0 | | SQL Server | `SQL_SERVER` | `SQLSvrAdapter.dll` | Microsoft.Data.SqlClient 7.1.1 | 2017, 2019, 2022 | | PostgreSQL | `POSTGRE_SQL` | `PostgreAdapter.dll` | Npgsql 10.0.3 | 16 | | Firebird | `FB_SQL` | `FirebirdSqlAdapter.dll` | FirebirdSql.Data.FirebirdClient 10.3.4 | 2.5, 3.0, 4.0, 5.0 | ```xml MySqlAdapter.dll0.9.2.4MySqlAdapterMY_SQL SQLSvrAdapter.dll0.9.2.4SQLSvrAdapterSQL_SERVER PostgreAdapter.dll0.9.2.4PostgreAdapterPOSTGRE_SQL FirebirdSqlAdapter.dll0.9.2.4FirebirdSqlAdapterFB_SQL ``` ### Diferencias entre motores Los cuatro adaptadores se comportan igual hacia DKL salvo en lo siguiente: | Tema | MySQL | SQL Server | PostgreSQL | Firebird | |---|---|---|---|---| | Parámetro `@x` que **no** viene en el registro de parámetros | Vale `NULL` sin error (MySQL lo trata como variable de usuario) | Error | Error | Error | | Tipos especiales al leer | `CHAR(36)` se lee como GUID (un contenido que no es GUID falla), `TINYINT(1)` como booleano, `BIT(n)` como entero sin signo, `BINARY(16)` como bytes | `NVARCHAR` para cadenas (Unicode completo) | | `TRUNCATE` no existe | | Reintentos | Errores transitorios (deadlock, espera de bloqueo, red) se reintentan; los permanentes responden de inmediato | | | | | SQL | El SQL que escribe es del dialecto de cada motor: `dbr` no lo traduce. `dbr.insert`, `dbr.update`, `dbr.delete` y las funciones del modelo sí generan SQL portable | | | | Lo que en 2.0 se **unificó** entre motores (detalle en cada página): `dbr.execute` con DDL devuelve 0 en todos; `dbr.login` compara igual y con consulta parametrizada; `dbr.lock`, `dbr.chklock` y `dbr.unlock` funcionan en los cuatro. ## Índice de funciones | Función | Página | |---|---| | `dbr.open`, `dbr.close`, `dbr.is_open`, `dbr.full_qname`, `dbr.relative_qname`, `dbr.base_qname` | [Consultas](/es/devkron/2.0/bibliotecas/motor/dbr/consultas.md) | | `dbr.execute`, `dbr.str`, `dbr.num`, `dbr.scalar`, `dbr.rec`, `dbr.list`, `dbr.table`, `dbr.sql` | [Consultas](/es/devkron/2.0/bibliotecas/motor/dbr/consultas.md) | | `dbr.insert`, `dbr.update`, `dbr.delete` | [Consultas](/es/devkron/2.0/bibliotecas/motor/dbr/consultas.md) | | `dbr.begin`, `dbr.commit`, `dbr.rollback`, `dbr.in_transaction` | [Transacciones](/es/devkron/2.0/bibliotecas/motor/dbr/transacciones.md) | | `dbr.login`, `dbr.logout`, `dbr.reconnect`, `dbr.getSID`, `dbr.setHashUnicode` | [Modelo de Devkron](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md) | | `dbr.get`, `dbr.getg`, `dbr.getw`, `dbr.save`, `dbr.erase`, `dbr.lock`, `dbr.chklock`, `dbr.unlock` | [Modelo de Devkron](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md) | | `dba.addapp`, `dba.apps`, `dba.cnnexists`, `dba.cnns`, `dba.createconnection`, `dba.createdb`, `dba.createschema`, `dba.delapp`, `dba.delconnection`, `dba.getconnection`, `dba.getconnectionset`, `dba.newconnection` | [Administración de conexiones](/es/devkron/2.0/bibliotecas/motor/dbr/dba.md) | ## Errores típicos al conectar | Mensaje | Causa | Solución | |---|---|---| | `El nombre cualificado (QName) principal no es válido, debe tener la forma NombreConexión@GrupoAplicación` | Falta `@aplicación` | `dbr.open("principal@tienda")` | | `El nombre de la aplicación no se encuentra en el repositorio` | No hay `connections.xml` en el directorio de trabajo ni junto a `dkl`, o la aplicación no existe en él | Revise el directorio de trabajo y el archivo | | `No se pudo obtener una referencia a la conexión especificada o el nombre no existe en el repositorio` | La conexión no existe en esa aplicación | Revise el nombre (`dba.cnns("tienda")` lista las que hay) | | `No se pudo seleccionar el esquema X de conexión@app` | La base no existe, o el usuario no puede entrar (usuario, contraseña, host permitido, `AllowPublicKeyRetrieval`) | Pruebe las credenciales con el cliente del motor | ## Si viene de Devkron 1.x `dbr.*`, `connections.xml`, `adapters.xml` y los nombres cualificados funcionan igual. Cambian los drivers (versiones actuales con la misma salida), se agregan PostgreSQL y Firebird probados, y se corrigieron defectos: ver las secciones "Cambios en 2.0" de cada página. La ventana gráfica de administración de conexiones de 1.x (WinForms) ya no existe: edite `connections.xml`, use las funciones `dba.*` o la utilidad `dba` de [DDM](/es/devkron/2.0/bibliotecas/ddm/). La documentación 1.x del patrón de diseño (campos de control, bloqueo pesimista, eliminación lógica) está ahora en [Modelo de datos de Devkron](/es/devkron/2.0/bibliotecas/motor/dbr/modelo.md).