# 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