Base de Datos SQL

Ejecutar consultas SQL contra bases de datos PostgreSQL, MySQL, SQLite, MSSQL y Oracle. Las caracteristicas incluyen consultas parametrizadas, transacciones, sentencias preparadas y un constructor de consultas fluido.

Para configuración de base de datos, consulte Base de Datos.

Carga

local sql = require("sql")

Adquirir una Conexión

Obtener una conexión de base de datos del registro de recursos:

local db, err = sql.get("app.db:main")
if err then
    return nil, err
end

local rows = db:query("SELECT * FROM users WHERE active = ?", {1})

db:release()

Parámetro	Tipo	Descripción
`id`	string	ID de recurso (ej., "app.db:main")

Devuelve: DB, error

Las conexiones se devuelven automaticamente al pool cuando la función termina, pero llamar `db:release()` explicitamente es recomendado para operaciones de larga duración.

Constantes

Tipos de Base de Datos

sql.type.POSTGRES    -- "postgres"
sql.type.MYSQL       -- "mysql"
sql.type.SQLITE      -- "sqlite"
sql.type.MSSQL       -- "mssql"
sql.type.ORACLE      -- "oracle"
sql.type.UNKNOWN     -- "unknown"

Niveles de Aislamiento

sql.isolation.DEFAULT           -- "default"
sql.isolation.READ_UNCOMMITTED  -- "read_uncommitted"
sql.isolation.READ_COMMITTED    -- "read_committed"
sql.isolation.WRITE_COMMITTED   -- "write_committed"
sql.isolation.REPEATABLE_READ   -- "repeatable_read"
sql.isolation.SERIALIZABLE      -- "serializable"

Valor NULL

local insert = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", sql.NULL)

Coercion de Tipos

as.int

local value = sql.as.int(42)

Devuelve: userdata

as.float

Coerciona valor a tipo SQL float.

local value = sql.as.float(19.99)

Devuelve: userdata

as.text

Coerciona valor a tipo SQL text.

local value = sql.as.text("hello")

Devuelve: userdata

as.binary

Coerciona valor a tipo SQL binary.

local value = sql.as.binary("binary data")

Devuelve: userdata

as.null

Devuelve marcador SQL NULL.

local value = sql.as.null()

Devuelve: userdata

Constructor de Consultas

Crear Consultas

local query = sql.builder.select("id", "name")
    :from("users")
    :where({active = 1})

Parámetro	Tipo	Descripción
`columns`	...string	Nombres de columnas (opcional)

Devuelve: SelectBuilder

builder.insert

Crea constructor de consulta INSERT.

local query = sql.builder.insert("users")
    :columns("name", "email")
    :values("alice", "alice@example.com")

Parámetro	Tipo	Descripción
`table`	string	Nombre de tabla (opcional)

Devuelve: InsertBuilder

builder.update

Crea constructor de consulta UPDATE.

local query = sql.builder.update("users")
    :set("status", "active")
    :where({id = 123})

Parámetro	Tipo	Descripción
`table`	string	Nombre de tabla (opcional)

Devuelve: UpdateBuilder

builder.delete

Crea constructor de consulta DELETE.

local query = sql.builder.delete("users")
    :where({active = 0})
    :limit(100)

Parámetro	Tipo	Descripción
`table`	string	Nombre de tabla (opcional)

Devuelve: DeleteBuilder

builder.expr

Crea expresion SQL cruda para usar en clausulas where/having.

local expr = sql.builder.expr("score BETWEEN ? AND ?", 80, 90)

Parámetro	Tipo	Descripción
`sql`	string	Expresion SQL con marcadores ?
`args`	...any	Argumentos de enlace (opcional)

Devuelve: Sqlizer

builder.eq

Crea condición de igualdad desde tabla.

local cond = sql.builder.eq({active = 1, status = "open"})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.not_eq

Crea condición de desigualdad desde tabla.

local cond = sql.builder.not_eq({status = "closed"})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.lt

Crea condición menor-que desde tabla.

local cond = sql.builder.lt({age = 18})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.lte

Crea condición menor-o-igual desde tabla.

local cond = sql.builder.lte({price = 100})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.gt

Crea condición mayor-que desde tabla.

local cond = sql.builder.gt({score = 80})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.gte

Crea condición mayor-o-igual desde tabla.

local cond = sql.builder.gte({age = 21})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.like

Crea condición LIKE desde tabla.

local cond = sql.builder.like({name = "john%"})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.not_like

Crea condición NOT LIKE desde tabla.

local cond = sql.builder.not_like({email = "%@spam.com"})

Parámetro	Tipo	Descripción
`map`	table	pares {columna = valor}

Devuelve: Sqlizer

builder.and_

Combina multiples condiciones con AND.

local cond = sql.builder.and_({
    sql.builder.eq({active = 1}),
    sql.builder.gt({score = 80})
})

Parámetro	Tipo	Descripción
`conditions`	table	Array de condiciones Sqlizer o table

Devuelve: Sqlizer

builder.or_

Combina multiples condiciones con OR.

local cond = sql.builder.or_({
    sql.builder.eq({status = "pending"}),
    sql.builder.eq({status = "active"})
})

Parámetro	Tipo	Descripción
`conditions`	table	Array de condiciones Sqlizer o table

Devuelve: Sqlizer

builder.question

Formato de marcador para marcadores ? (predeterminado).

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.question)

builder.dollar

Formato de marcador para marcadores $1, $2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.dollar)

builder.at

Formato de marcador para marcadores @p1, @p2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.at)

builder.colon

Formato de marcador para marcadores :1, :2, ...

local query = sql.builder.select("*")
    :from("users")
    :placeholder_format(sql.builder.colon)

Metodos de Conexión

Handle de conexión de base de datos devuelto por sql.get().

db:type

Devuelve constante de tipo de base de datos.

local dbtype, err = db:type()

Devuelve: string, error

db:query

Ejecuta consulta SELECT y devuelve filas.

local rows, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})

Parámetro	Tipo	Descripción
`sql`	string	Consulta SQL con marcadores ?
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table[], error

db:execute

Ejecuta consulta INSERT/UPDATE/DELETE.

local result, err = db:execute("INSERT INTO users (name) VALUES (?)", {"alice"})

Parámetro	Tipo	Descripción
`sql`	string	Sentencia SQL con marcadores ?
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table, error

Devuelve tabla con campos:

last_insert_id - Ultimo ID insertado
rows_affected - Número de filas afectadas

db:prepare

Crea sentencia preparada para ejecución repetida.

local stmt, err = db:prepare("SELECT * FROM users WHERE id = ?")

Parámetro	Tipo	Descripción
`sql`	string	SQL con marcadores ?

Devuelve: Statement, error

db:begin

Inicia transaccion de base de datos.

local tx, err = db:begin({
    isolation = sql.isolation.SERIALIZABLE,
    read_only = false
})

Parámetro	Tipo	Descripción
`options`	table	Opciones de transaccion (opcional)

Campos de tabla de opciones:

isolation - Nivel de aislamiento de sql.isolation.* (predeterminado: DEFAULT)
read_only - Flag de transaccion de solo lectura (predeterminado: false)

Devuelve: Transaction, error

db:release

Libera recurso de base de datos de vuelta al pool.

local ok, err = db:release()

Devuelve: boolean, error

db:stats

Devuelve estadisticas del pool de conexiones.

local stats, err = db:stats()

Devuelve: table, error

Devuelve tabla con campos:

max_open_connections - Conexiones abiertas maximas permitidas
open_connections - Conexiones abiertas actuales
in_use - Conexiones actualmente en uso
idle - Conexiones inactivas en pool
wait_count - Conteo total de esperas de conexión
wait_duration - Duración total de espera
max_idle_closed - Conexiones cerradas por max idle
max_idle_time_closed - Conexiones cerradas por timeout de inactividad
max_lifetime_closed - Conexiones cerradas por tiempo de vida maximo

Sentencias Preparadas

Sentencia preparada devuelta por db:prepare().

stmt:query

Ejecuta sentencia preparada como SELECT.

local rows, err = stmt:query({123})

Parámetro	Tipo	Descripción
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table[], error

stmt:execute

Ejecuta sentencia preparada como INSERT/UPDATE/DELETE.

local result, err = stmt:execute({"alice"})

Parámetro	Tipo	Descripción
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table, error

Devuelve tabla con campos:

last_insert_id - Ultimo ID insertado
rows_affected - Número de filas afectadas

stmt:close

Cierra sentencia preparada.

local ok, err = stmt:close()

Devuelve: boolean, error

Transacciones

Transaccion de base de datos devuelta por db:begin().

tx:db_type

Devuelve constante de tipo de base de datos.

local dbtype, err = tx:db_type()

Devuelve: string, error

tx:query

Ejecuta consulta SELECT dentro de transaccion.

local rows, err = tx:query("SELECT id, name FROM users WHERE active = ?", {1})

Parámetro	Tipo	Descripción
`sql`	string	Consulta SQL con marcadores ?
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table[], error

tx:execute

Ejecuta INSERT/UPDATE/DELETE dentro de transaccion.

local result, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})

Parámetro	Tipo	Descripción
`sql`	string	Sentencia SQL con marcadores ?
`params`	table	Array de parametros de enlace (opcional)

Devuelve: table, error

Devuelve tabla con campos:

last_insert_id - Ultimo ID insertado
rows_affected - Número de filas afectadas

tx:prepare

Crea sentencia preparada dentro de transaccion.

local stmt, err = tx:prepare("SELECT * FROM users WHERE id = ?")

Parámetro	Tipo	Descripción
`sql`	string	SQL con marcadores ?

Devuelve: Statement, error

tx:commit

Confirma transaccion.

local ok, err = tx:commit()

Devuelve: boolean, error

tx:rollback

Revierte transaccion.

local ok, err = tx:rollback()

Devuelve: boolean, error

tx:savepoint

Crea savepoint nombrado dentro de transaccion.

local ok, err = tx:savepoint("sp1")

Parámetro	Tipo	Descripción
`name`	string	Nombre de savepoint (solo alfanumerico y guion bajo)

Devuelve: boolean, error

tx:rollback_to

Revierte a savepoint nombrado.

local ok, err = tx:rollback_to("sp1")

Parámetro	Tipo	Descripción
`name`	string	Nombre de savepoint

Devuelve: boolean, error

tx:release

Libera savepoint.

local ok, err = tx:release("sp1")

Parámetro	Tipo	Descripción
`name`	string	Nombre de savepoint

Devuelve: boolean, error

Constructor SELECT

Interfaz fluida para construir consultas SELECT.

select:from

Establece clausula FROM.

local query = sql.builder.select("id", "name"):from("users")

Parámetro	Tipo	Descripción
`table`	string	Nombre de tabla

Devuelve: SelectBuilder

select:join

Agrega clausula JOIN.

local query = sql.builder.select("*")
    :from("users")
    :join("orders ON orders.user_id = users.id")

Parámetro	Tipo	Descripción
`join`	string	Clausula JOIN con marcadores ?
`args`	...any	Argumentos de enlace (opcional)

Devuelve: SelectBuilder

select:left_join

Agrega clausula LEFT JOIN.

local query = sql.builder.select("*")
    :from("users")
    :left_join("orders ON orders.user_id = users.id")

Parámetro	Tipo	Descripción
`join`	string	Clausula JOIN con marcadores ?
`args`	...any	Argumentos de enlace (opcional)

Devuelve: SelectBuilder

select:where

Agrega condición WHERE.

local query = sql.builder.select("*")
    :from("users")
    :where({active = 1})

Parámetro	Tipo	Descripción
`condition`	string\|table\|Sqlizer	Condición WHERE
`args`	...any	Argumentos de enlace (opcional, cuando se usa string)

Soporta tres formatos:

String: where("status = ?", "active")
Table: where({status = "active"})
Sqlizer: where(sql.builder.gt({score = 80}))

Devuelve: SelectBuilder

select:order_by

Agrega clausula ORDER BY.

local query = sql.builder.select("*")
    :from("users")
    :order_by("name ASC", "created_at DESC")

Parámetro	Tipo	Descripción
`columns`	...string	Nombres de columnas con ASC/DESC opcional

Devuelve: SelectBuilder

select:group_by

Agrega clausula GROUP BY.

local query = sql.builder.select("status", "COUNT(*)")
    :from("users")
    :group_by("status")

Parámetro	Tipo	Descripción
`columns`	...string	Nombres de columnas

Devuelve: SelectBuilder

select:limit

Establece LIMIT.

local query = sql.builder.select("*")
    :from("users")
    :limit(10)

Parámetro	Tipo	Descripción
`n`	integer	Valor de limite

Devuelve: SelectBuilder

select:offset

Establece OFFSET.

local query = sql.builder.select("*")
    :from("users")
    :offset(20)

Parámetro	Tipo	Descripción
`n`	integer	Valor de offset

Devuelve: SelectBuilder

select:to_sql

Genera string SQL y argumentos de enlace.

local sql_str, args = query:to_sql()

Devuelve: string, table

select:run_with

Crea ejecutor para consulta.

local executor = query:run_with(db)
local rows, err = executor:query()

Parámetro	Tipo	Descripción
`db`	DB\|Transaction	Handle de base de datos o transaccion

Devuelve: QueryExecutor

Permisos

El acceso a base de datos esta sujeto a evaluacion de politica de seguridad.

Accion	Recurso	Descripción
`db.get`	ID de Database	Adquirir conexión de base de datos

Errores

Condición	Tipo	Reintentable
ID de recurso vacio	`errors.INVALID`	no
Permiso denegado	`errors.PERMISSION_DENIED`	no
Recurso no encontrado	`errors.NOT_FOUND`	no
Recurso no es base de datos	`errors.INVALID`	no
Parametros invalidos	`errors.INVALID`	no
Error de sintaxis SQL	`errors.INVALID`	no
Sentencia cerrada	`errors.INVALID`	no
Transaccion no activa	`errors.INVALID`	no
Nombre de savepoint invalido	`errors.INVALID`	no
Error de ejecución de consulta	varia	varia

Consulte Manejo de Errores para trabajar con errores.