# 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).