# Consultas y comandos Funciones de `dbr.dkh` para abrir y cerrar conexiones, ejecutar SQL con parámetros y leer los resultados como un valor, un registro, una lista de registros o una tabla; y para insertar, actualizar y borrar filas sin escribir el SQL completo. Los ejemplos de esta página se ejecutaron contra MySQL 8.0 con la conexión `principal@tienda` (ver [conexiones](/es/devkron/2.0/bibliotecas/motor/dbr/)). ## Abrir y cerrar | Función | Devuelve | Qué hace | |---|---|---| | `dbr.open(qname)` | Conexión (use `ref`) | Abre la conexión con ese nombre cualificado y selecciona su base de datos | | `dbr.close(db)` | — | Cierra la conexión. Un segundo `dbr.close` no hace nada | | `dbr.is_open(db)` | `@true`/`@false` | Si la conexión sigue abierta (en 2.0 da 0 después de `dbr.close` o `dbr.logout`) | | `dbr.full_qname(db)` | Cadena | El nombre cualificado completo con que se abrió (`principal@tienda`, o `repo@app/cnn@app2`) | | `dbr.relative_qname(db)` | Cadena | La parte de la conexión (`cnn@app2`) | | `dbr.base_qname(db)` | Cadena | La conexión del repositorio en base de datos (`repo@app`), o `""` si el repositorio es local | Abra una conexión al inicio del programa o de la petición, úsela para todo y ciérrela al final. En FastCGI, una conexión que quede abierta se libera al terminar la petición. ## Ejecutar y leer | Función | Devuelve | |---|---| | `dbr.execute(db, sql, params)` | Número: filas afectadas para `INSERT`/`UPDATE`/`DELETE` (0 si ninguna), **0** para DDL y comandos sin conteo, **-1** para `SELECT` | | `dbr.str(db, sql, params)` | Primera columna de la primera fila como cadena; `""` si no hay filas o el valor es `NULL` | | `dbr.num(db, sql, params)` | Primera columna de la primera fila como número; 0 si no hay filas; **error** si el valor es `NULL` o no es numérico | | `dbr.scalar(db, sql, params)` | Referencia al valor de la primera columna de la primera fila (fechas, binarios); nulo si no hay filas, `System.DBNull` si el valor es `NULL` | | `dbr.rec(db, sql, params)` | Registro con las columnas de la primera fila; `@null` si no hay filas | | `dbr.list(db, sql, params)` | Lista de registros, uno por fila (lista vacía si no hay filas). Es la forma más directa de convertir un resultado a JSON | | `dbr.table(db, sql, params)` | [Tabla en memoria](/es/devkron/2.0/bibliotecas/motor/functions/tablas.md) con el resultado; **`@null` si no hay filas** | `params` es un registro con los parámetros del SQL, o `@null` si no hay. ## Insertar, actualizar y borrar sin escribir el SQL | Función | SQL que genera | |---|---| | `dbr.insert(db, tabla, registro)` | `INSERT INTO tabla (campos…) VALUES (@valores…)` con un parámetro por campo | | `dbr.update(db, tabla, registro, filtro, params)` | `UPDATE tabla SET campo = @valor, … WHERE filtro`; `params` son los parámetros del filtro (o `@null`) | | `dbr.delete(db, tabla, filtro, params)` | `DELETE FROM tabla WHERE filtro` | | `dbr.sql(expresión)` | Un objeto que representa SQL **literal**: asignado a un campo del registro de `dbr.insert`/`dbr.update`, se escribe tal cual en lugar de un parámetro (`NOW()`, `UPPER(nombre)`, `existencia - 1`) | `dbr.insert` y `dbr.update` no devuelven nada; si falla, lanzan una excepción con el mensaje del motor. ## Parámetros - **`@nombre`** en el SQL es un parámetro enlazado: su valor viaja aparte y nunca se mezcla con el texto del SQL. Es la forma segura de usar datos recibidos del usuario. - **`@{nombre}`** se **sustituye en el texto** del SQL sin escapar (sirve para nombres de tabla o columna variables). Nunca lo use con datos del usuario. - Un parámetro con valor nulo se envía como `NULL`. - Los números de DKL viajan como `decimal` y las cadenas como texto (`NVARCHAR` en SQL Server, así que los acentos y caracteres de cualquier idioma llegan íntegros). Las fechas se pasan como objetos fecha (`str2dt`); una fecha numérica `AAAAMMDD.HHMMSS` de DKL es un número, conviértala antes. - Números y fechas se envían y se leen siempre con cultura invariante (punto decimal), en cualquier servidor. ## Ejemplo completo ```dkl #include "dkli.dkh" #! program "consultas" { #include "functions.dkh" #include "serialize.dkh" #include "dbr.dkh" ref db = dbr.open("principal@tienda") do dbr.execute(db, "DROP TABLE IF EXISTS producto", @null) do print(dbr.execute(db, "CREATE TABLE producto (id INT AUTO_INCREMENT PRIMARY KEY, sku VARCHAR(20) NOT NULL UNIQUE, nombre VARCHAR(80), precio DECIMAL(12,2) NULL, alta DATETIME NULL)", @null)) new p { @"sku": "P-01" @"nombre": "Café 1 kg" @"precio": 189.9 } do dbr.insert(db, "producto", p) p<"sku">: "P-02" p<"nombre">: "Azúcar 1 kg" p<"precio">: 32.5 do dbr.insert(db, "producto", p) new p3 { @"sku": "P-03" @"nombre": "Sal" } p3<"precio*">: @null p3<"alta*">: dbr.sql("NOW()") do dbr.insert(db, "producto", p3) do print(dbr.num(db, "SELECT COUNT(*) FROM producto", @null)) new f { @"sku": "P-01" } do print(dbr.str(db, "SELECT nombre FROM producto WHERE sku = @sku", f)) do print(dbr.num(db, "SELECT precio FROM producto WHERE sku = @sku", f) * 2) ref alta = dbr.scalar(db, "SELECT alta FROM producto WHERE sku = 'P-03'", @null) do print(length(date_str(alta, "yyyy-MM-dd HH:mm:ss"))) ref rec = dbr.rec(db, "SELECT sku, nombre, precio FROM producto WHERE sku = @sku", f) do print(to.json(rec)) ref nada = dbr.rec(db, "SELECT * FROM producto WHERE sku = 'X'", @null) do print(isnull(nada)) ref t = dbr.table(db, "SELECT sku, nombre, precio FROM producto ORDER BY sku", @null) for i=0; i: dbr.sql("UPPER(nombre)") do dbr.update(db, "producto", todos, "precio IS NULL", @null) do print(dbr.str(db, "SELECT nombre FROM producto WHERE sku = 'P-03'", @null)) new borra { @"sku": "P-02" } do dbr.delete(db, "producto", "sku = @sku", borra) do print(dbr.execute(db, "UPDATE producto SET precio = 1 WHERE sku = 'NADA'", @null)) do print(dbr.execute(db, "SELECT * FROM producto", @null)) new pr { @"tabla": "producto" } do print(dbr.num(db, "SELECT COUNT(*) FROM @{tabla}", pr)) do dbr.insert(db, "producto", f) exception { do print(last_error()) do clear_exceptions() } do dbr.execute(db, "DROP TABLE producto", @null) do dbr.close(db) do print(dbr.is_open(db)) do print(dbr.num(db, "SELECT 1", @null)) exception { do print(last_error()) do clear_exceptions() } } ``` ```text 0 3 Café 1 kg 379.80 19 {"sku":"P-01","nombre":"Caf\u00E9 1 kg","precio":189.90} 1 P-01 Café 1 kg 189.90 P-02 Azúcar 1 kg 32.50 P-03 Sal (sin precio) 1 [{"sku":"P-01","precio":189.90},{"sku":"P-02","precio":32.50},{"sku":"P-03","precio":null}] 199.00 SAL 0 -1 2 {1} Error en 'dbr.insert. (INSERT Error. Execute Error. Duplicate entry 'P-01' for key 'producto.sku'Exception has been thrown by the target of an invocation.) [consultas.dkl][Ln= 74] 0 {1} Error en 'dbr.num. (GetScalar Error. La conexión no ha sido abiertaException has been thrown by the target of an invocation.) [consultas.dkl][Ln= 83] ``` Línea por línea: el `CREATE TABLE` devuelve 0; `dbr.scalar` devolvió una fecha (su texto mide 19 caracteres); `dbr.rec` sin filas da nulo (`1`); `dbr.table` sin filas también; `dbr.update` con `dbr.sql("UPPER(nombre)")` convirtió `Sal` en `SAL`; el `UPDATE` sin filas afectadas da 0 y el `SELECT` da -1; `@{tabla}` se sustituyó por `producto`; el duplicado muestra el mensaje del motor; y después de `dbr.close` cualquier consulta dice `La conexión no ha sido abierta`. > Dentro de `new … { }`, `@"campo": dbr.sql(…)` guarda el **índice** del objeto, no el objeto. Asigne los valores `dbr.sql` con `registro<"campo*">: dbr.sql(…)`, como en el ejemplo. ## Responder una consulta como JSON El patrón más común en un servicio: ```dkl ref filas = dbr.list(db, "SELECT sku, nombre, precio FROM producto WHERE nombre LIKE @q ORDER BY sku", p) @http_context<"response/headers/content-type">: "application/json;charset=utf-8" @http_context<"response/output">: "text" @http_context<"response/text">: to.json(filas) ``` ## Cambios en 2.0 | Antes (1.x) | Ahora (2.0) | |---|---| | SQL Server: `dbr.execute` con DDL devolvía -1, igual que un `SELECT` | 0 en los cuatro motores. Si su código en SQL Server distinguía un `SELECT` de un DDL por el -1, revíselo | | `dbr.is_open` seguía en 1 después de `dbr.close`; un segundo `close` fallaba | 0; un segundo `close` no hace nada | | `dbr.update` con filtro sin parámetros (`@null`) daba `NullReferenceException` | Funciona | | Tras un error al leer filas (`dbr.table`, `dbr.rec`, `dbr.list`) la conexión quedaba inutilizable | El lector se cierra y la conexión sigue usable | | `dbr.num` sobre texto no numérico: mensaje de .NET distinto en cada versión | `GetDecimal Error. El valor 'abc' no es numérico`; `"1.5"` y `"1,234.5"` se leen con punto decimal | | Números y fechas hacia y desde el SQL con la cultura del servidor | Siempre invariantes | | SQL Server: cadenas como `VarChar` (caracteres fuera de la página de códigos llegaban como `?`), `Double` como `Real` (perdía precisión), `Single` y `byte[]` fallaban | `NVarChar`, `Float`, `Real` y `VarBinary` | | MySQL: parámetros `Single` y `byte[]` se ignoraban (se guardaba `NULL`) | Se envían | | MySQL: ~111 s de espera ante errores permanentes | Error inmediato; los transitorios conservan los reintentos | Se conservan a propósito: `dbr.num` sobre `NULL` lanza error (sin filas da 0); en MySQL un parámetro que falta vale `NULL`; las fechas cero de MySQL fallan salvo `ConvertZeroDateTime=true`. ## Errores típicos | Mensaje | Causa | Solución | |---|---|---| | `Object cannot be cast from DBNull to other types.` en `dbr.num` | El valor es `NULL` | `SELECT IFNULL(col, 0)` (o `COALESCE`), o lea con `dbr.str` | | `GetDecimal Error. El valor 'x' no es numérico` | `dbr.num` sobre texto | Lea con `dbr.str` | | `Duplicate entry 'P-01' for key …` | Viola un índice único | Valide antes o capture la excepción | | `Comando SQL vacío` | `sql` es `""` | Revise cómo arma el SQL | | `La conexión no ha sido abierta` | Consulta después de `dbr.close`/`dbr.logout` | Abra otra conexión | | `El objeto de parámetros no es del tipo esperado` | `params` no es un registro | Use un registro o `@null` | | `Must declare the scalar variable "@x".` (SQL Server) / error de parámetro (PostgreSQL, Firebird) | Falta el parámetro en el registro | Agréguelo, aunque sea nulo | | `table.rows` da -1 después de `dbr.table` | La consulta no devolvió filas (`dbr.table` da `@null`) | Compruebe `isnull(t)`, o use `dbr.list` | [Regresar a dbr.dkh](/es/devkron/2.0/bibliotecas/motor/dbr/)