# Conexiones a bases de datos Los programas DKL no escriben cadenas de conexión: abren una conexión por su **nombre cualificado** (`ventas@miapp`) y Devkron busca sus datos en el repositorio `connections.xml`, y el adaptador del motor en `adapters.xml`. Así el mismo programa cambia de servidor, base o contraseña editando un solo archivo. Esta página explica los dos archivos, los datos de cada motor (MySQL 8+, SQL Server 2017+, PostgreSQL y Firebird), cómo crear conexiones desde DKL y cómo resolver los errores típicos. ## Nombres cualificados Las conexiones se organizan en **grupos de aplicaciones**. El nombre cualificado es `conexión@aplicación`: ```dkl ref db = dbr.open("ventas@miapp") ``` - Los nombres de aplicación no llevan espacios ni los caracteres `@` y `/`. - Con la forma `repositorio@app/conexión@app2` la conexión se busca en un **repositorio en base de datos** en lugar de `connections.xml`: vea [Repositorios de conexiones en base de datos](/es/devkron/2.0/instalacion/repositorio-conexiones.md). - Los nombres de conexión solo llevan letras (`a-z`), números (`0-9`), puntos y guiones (`-`, `_`). ## `adapters.xml`: los motores disponibles La distribución registra los cuatro adaptadores. Solo se carga la DLL del motor que use cada conexión, así que tenerlos registrados no cuesta nada: ```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 ``` | 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 y 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 y 5.0 | No modifique este archivo salvo que quite un motor que no quiere permitir. ## `connections.xml`: el repositorio de conexiones No viene en la distribución: se crea copiando `connections.xml.example` como `connections.xml`. En la distribución autónoma no hay una ventana de administración de conexiones (la de 1.x para Windows se retiró): el archivo se edita a mano o con las funciones `dba.*` (abajo). **Dónde va**: Devkron lo busca primero en el **directorio de trabajo** (como en 1.x) y, si no está ahí, **junto a `dkl`** (nuevo en 2.0). Para el servidor FastCGI, que arranca en la carpeta de la instalación, ambos lugares son el mismo. Para tareas de consola que corren desde otra carpeta, el de junto a `dkl` evita copiarlo. Estructura: ```xml miapp ventas MY_SQL MY_SQL 127.0.0.1 mi_usuario MiClave#2026 erp 3306 2 ]]> true ``` | Elemento | Uso | |---|---| | `AppItem/Name` | nombre del grupo de aplicaciones (la parte después de `@`) | | `CnnItem/Name` | nombre de la conexión (la parte antes de `@`) | | `CnnItem/EngineType` | motor: `MY_SQL`, `SQL_SERVER`, `POSTGRE_SQL` o `FB_SQL` | | `XmlSettings` | datos de conexión: en claro como XML dentro de ``, o **cifrados** en base 64 ([Cifrar conexiones](/es/devkron/2.0/instalacion/cifrar-conexiones.md)) | | `SQLDic` | diccionario de consultas SQL de la conexión (opcional; puede omitirse) | | `Default` | `true` si es la conexión predeterminada del grupo | Puede haber varias aplicaciones y varias conexiones por aplicación. Proteja el archivo con permisos del sistema (solo lectura para el usuario del servicio) y **nunca** lo ponga en una carpeta publicada por la web. ## Datos de conexión por motor Dentro de `` va siempre `` con el motor y, según el motor: | Elemento | MySQL | SQL Server | PostgreSQL | Firebird | |---|---|---|---|---| | `Host` | servidor | servidor; con puerto o instancia: `servidor,1433` o `servidor\INSTANCIA` | servidor | servidor | | `Port` | puerto (3306) | (va en `Host`) | puerto (5432) | puerto (3050) | | `UserName`, `Password` | usuario y contraseña | usuario y contraseña de SQL Server | usuario y contraseña | usuario y contraseña (por ejemplo `SYSDBA`) | | `DefaultSchema` | base de datos | base de datos | base de datos | **ruta del archivo** `.fdb` en el servidor | | `SSLMode` | número, vea abajo | — | número | número | | `WindowsAuthMode` | — | `true` = autenticación de Windows | — | — | | `NameSpaceSchema` | — | — | esquema (`public`) | — | | `Parameters` | opciones adicionales del driver (`Clave=valor;…`) | ídem | ídem | ídem | En 2.0 `` y `` se leen siempre (en 1.x, en MySQL se perdían si faltaba ``, y en SQL Server `` nunca se leía). Ejemplos (valores ficticios): ```xml SQL_SERVERsql.ejemplo.local,1433mi_usuarioMiClave#2026erpfalse ``` ```xml POSTGRE_SQLpg.ejemplo.localmi_usuarioMiClave#2026erp5432public ``` ```xml FB_SQLfb.ejemplo.localSYSDBAMiClave#2026/var/lib/firebird/data/erp.fdb30500 ``` ### Conexiones cifradas (SSL/TLS) a MySQL El modo SSL se indica con `` **como número**; si se escribe el nombre del modo (por ejemplo `Required`), se ignora y la conexión se hace sin SSL. | Valor | Modo | Descripción | |---|---|---| | `0` | None | sin SSL (el valor si no se indica) | | `1` | Preferred | usa SSL si el servidor lo admite | | `2` | Required | exige SSL; no valida el certificado del servidor | | `3` | VerifyCA | exige SSL y valida que el certificado lo emita una autoridad de confianza | | `4` | VerifyFull | como VerifyCA, y además valida que el certificado corresponda al nombre del host | Se recomienda `2`, o `3`/`4` si el servidor tiene un certificado que el cliente pueda validar. **MySQL 8 y `caching_sha2_password`.** Con el método de autenticación predeterminado de MySQL 8 (`caching_sha2_password`), una conexión sin SSL puede funcionar al principio y fallar después de que el servidor MySQL se reinicia (cuando vacía su caché de autenticación), o fallar desde el inicio si el servidor no es local. Configure la conexión con `SSLMode` `2` o superior o, si no puede usar SSL, agregue `AllowPublicKeyRetrieval=true`. **Fechas cero de MySQL** (`0000-00-00`): fallan al leerse, salvo que la conexión lo pida: ```xml ConvertZeroDateTime=true ``` **SQL Server**: la conexión confía en el certificado del servidor (`TrustServerCertificate`) para que funcione con los certificados autofirmados que traen las instalaciones de SQL Server. ## Probar una conexión Con la conexión `ventas@miapp` apuntando a una base MySQL de prueba: ```dkl #include "dkli.dkh" #! program "consulta" { #include "functions.dkh" #include "serialize.dkh" #include "dbr.dkh" ref db = dbr.open("ventas@miapp") do dbr.execute(db, "CREATE TABLE IF NOT EXISTS producto (clave VARCHAR(10) PRIMARY KEY, nombre VARCHAR(60), precio DECIMAL(12,2))", @null) do dbr.execute(db, "DELETE FROM producto", @null) do dbr.execute(db, "INSERT INTO producto VALUES ('P-01', 'Lápiz', 5.50), ('P-02', 'Goma', 3)", @null) ref p = record.create() p<"min">: 4 ref filas = dbr.list(db, "SELECT clave, nombre, precio FROM producto WHERE precio > @min ORDER BY clave", p) do print(to.json(filas)) do print(dbr.num(db, "SELECT COUNT(*) FROM producto", @null)) do dbr.close(db) } ``` ```text [{"clave":"P-01","nombre":"Lápiz","precio":5.50}] 2 ``` `@min` es un **parámetro enlazado**: el valor viaja aparte del SQL. Úselo siempre para datos que vengan del usuario. Todas las funciones de `dbr.dkh` están en [Bibliotecas](/es/devkron/2.0/bibliotecas/). ## Administrar conexiones desde DKL `dbr.dkh` trae funciones para crear y consultar conexiones sin editar el XML. Sirven para instaladores y herramientas de configuración: | Función | Uso | |---|---| | `dba.addapp("miapp")` | crea el grupo de aplicaciones | | `dba.delapp("miapp")` | elimina el grupo | | `dba.apps("")` | lista de grupos | | `dba.cnns("miapp")` | lista de conexiones del grupo | | `dba.createconnection("ventas@miapp", datos, predeterminada, sqldic)` | agrega la conexión con los datos del registro `datos`; la guarda **cifrada** | | `dba.createschema("ventas@miapp", datos, predeterminada, sqldic)` | como la anterior y además **crea la base de datos** con la estructura base de Devkron (tablas `tuser`, `usergroup`, `profile`, `sys_session`, `sys_lockinfo`, `sys_batch`…) | | `dba.delconnection("ventas@miapp")` | elimina la conexión | | `dba.cnnexists("ventas@miapp")` | 1 si existe | | `dba.getconnection("ventas@miapp")` | registro con los datos de la conexión (descifrados) | El registro `datos` lleva el motor en `Engine` y los mismos campos de la tabla de arriba: ```dkl #include "dkli.dkh" #! program "crear-conexion" { #include "functions.dkh" #include "serialize.dkh" #include "dbr.dkh" new datos { @"Engine": "MY_SQL" @"Host": "127.0.0.1" @"UserName": "mi_usuario" @"Password": "MiClave#2026" @"DefaultSchema": "erp" @"Port": "3306" @"SSLMode": "2" } if not(dba.cnnexists("ventas@miapp")) { do dba.addapp("miapp") do dba.createconnection("ventas@miapp", datos, @false, "") } do print(to.json(dba.apps(""))) do print(to.json(dba.cnns("miapp"))) ref info = dba.getconnection("ventas@miapp") do print(field.str(info, "Host") + " / " + field.str(info, "Engine")) } ``` ```text ["miapp"] ["ventas"] 127.0.0.1 / MY_SQL ``` El programa escribe `connections.xml` en el directorio de trabajo (o en el que ya exista junto a `dkl`), así que el usuario que lo ejecuta necesita permiso de escritura ahí. ### Cambios en `connections.xml` sin reiniciar (2.0.2) Cada proceso lee `connections.xml` una vez. Desde 2.0.2, si `dbr.open` con un nombre **local** falla (el nombre no existe o la conexión no abre) y la fecha de modificación del archivo cambió desde la última lectura, Devkron lo vuelve a leer y reintenta **una sola vez**. Así, con el servidor FastCGI en marcha, puede agregar una conexión nueva o corregir una contraseña y usarla sin reiniciar. - Si el archivo no cambió, sale de inmediato el error original: una base caída no provoca lecturas del archivo. - Si el XML nuevo no es válido, se conservan las conexiones cargadas, se anota el error en la salida de errores del proceso y sale el error original. - Si el reintento también falla, sale el error **original** (el de antes de releer). - Solo un hilo relee el archivo; los demás usan el resultado. **Limitación**: los cambios que no provocan una falla no se ven hasta reiniciar el servidor FastCGI. Por ejemplo, una conexión que se movió a otro servidor que **sigue abriendo** (el proceso sigue usando la dirección anterior), una conexión borrada del archivo, o un cambio de la conexión predeterminada de un grupo (`dbr.open("@ventas")`). Con `dba.createschema` el usuario de la base de datos necesita permiso para crear la base. Es el equivalente de "Crear base de datos" del administrador de conexiones con ventanas de 1.x. `dba.getconnection` devuelve la contraseña en claro: no muestre ni registre su resultado completo. ## Errores típicos | Mensaje | Causa | Solución | |---|---|---| | `El nombre cualificado (QName) x no es válido, debe tener la forma NombreConexión@GrupoAplicación` | falta `@` | use `conexión@aplicación` | | `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`, no se puede leer, o el grupo no existe | revise dónde se ejecuta el programa, el archivo y sus permisos | | `No se pudo obtener una referencia a la conexión especificada o el nombre no existe en el repositorio` | el grupo existe pero la conexión no | revise el nombre de `CnnItem/Name`; si la agregó con el servidor en marcha, desde 2.0.2 se toma sola (en 2.0.1 y anteriores, reinicie) | | `Access denied for user …` | usuario, contraseña o permisos de la base | revise en el servidor de base de datos; para `dba.createschema`, permiso de crear bases | | la conexión funciona y falla tras reiniciar MySQL | `caching_sha2_password` sin SSL | `SSLMode` 2 o `AllowPublicKeyRetrieval=true` | | `Unable to connect to any of the specified MySQL hosts` | host o puerto, o un firewall | pruebe con el cliente `mysql` desde el mismo servidor | | los acentos llegan como `?` en SQL Server | ya no ocurre en 2.0 (los parámetros van como `NVarChar`) | — | | `GetDecimal Error. Object cannot be cast from DBNull…` | `dbr.num` sobre un valor NULL | use `IFNULL`/`COALESCE` en el SQL |