SQL-Datenbank

Das Modul sql führt Abfragen für konfigurierte PostgreSQL-, MySQL- und SQLite-Datenbanken aus. Es unterstützt parametrisierte Abfragen, Transaktionen, vorbereitete Anweisungen und Abfragegeneratoren.

Diese Seite ist eine API-Referenz. Ihre Ausschnitte setzen eine konfigurierte Datenbank, die Berechtigung zum Abrufen dieser Datenbank und alle in der Abfrage genannten Tabellen voraus. Sie zeigen einzelne Aufrufe und keine eigenständige Anwendung. Das kombinierte Teilrezept am Ende nennt seine zusätzlichen Annahmen zu Schema und Treiber.

Informationen zur Datenbankkonfiguration finden Sie unter Datenbank.

Laden

local sql = require("sql")

sql.get

Holen Sie eine Datenbankverbindung aus der Ressourcen-Registry:

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

local function finish(value, primary_err)
    local _, release_err = db:release()
    if primary_err then return nil, primary_err end
    if release_err then return nil, release_err end
    return value
end

local rows, err = db:query("SELECT * FROM users WHERE active = ?", {1})
if err then
    return finish(nil, err)
end

return finish(rows)

Gibt zurück: DB, error

Konstanten

Datenbanktypen

sql.type.POSTGRES    -- "postgres"
sql.type.MYSQL       -- "mysql"
sql.type.SQLITE      -- "sqlite"
sql.type.UNKNOWN     -- "unknown"

Isolationsebenen

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"

NULL-Wert

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

Typ-Konvertierung

sql.as.int

local value = sql.as.int(42)

Gibt zurück: userdata

sql.as.float

Konvertiert Wert zu SQL-Float-Typ.

local value = sql.as.float(19.99)

Gibt zurück: userdata

sql.as.text

Konvertiert Wert zu SQL-Text-Typ.

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

Gibt zurück: userdata

sql.as.binary

Konvertiert Wert zu SQL-Binary-Typ.

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

Gibt zurück: userdata

sql.as.null

Gibt SQL-NULL-Marker zurück.

local value = sql.as.null()

Gibt zurück: userdata

Abfragegenerator :id=query-builder

sql.builder.select

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

Gibt zurück: SelectBuilder

sql.builder.insert

Erstellt einen INSERT-Abfragegenerator.

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

Gibt zurück: InsertBuilder

sql.builder.update

Erstellt einen UPDATE-Abfragegenerator.

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

Gibt zurück: UpdateBuilder

sql.builder.delete

Erstellt einen DELETE-Abfragegenerator.

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

Gibt zurück: DeleteBuilder

sql.builder.expr

Erstellt rohen SQL-Ausdruck zur Verwendung in WHERE/HAVING-Klauseln.

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

Gibt zurück: Sqlizer

sql.builder.eq

Erstellt Gleichheitsbedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.not_eq

Erstellt Ungleichheitsbedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.lt

Erstellt Kleiner-als-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.lte

Erstellt Kleiner-gleich-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.gt

Erstellt Größer-als-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.gte

Erstellt Größer-gleich-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.like

Erstellt LIKE-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.not_like

Erstellt NOT LIKE-Bedingung aus Table.

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

Gibt zurück: Sqlizer

sql.builder.and_

Kombiniert mehrere Bedingungen mit AND.

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

Gibt zurück: Sqlizer

sql.builder.or_

Kombiniert mehrere Bedingungen mit OR.

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

Gibt zurück: Sqlizer

sqlizer:to_sql

Erzeugt das SQL-Fragment und die Bind-Argumente einer Bedingung.

local frag, args = sql.builder.eq({active = 1}):to_sql()

Gibt zurück: string, table

builder.question

Platzhalterformat für ?-Platzhalter (Standard). Verfügbar als Alias sql.builder.default_placeholder.

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

sql.builder.dollar

Platzhalterformat für $1, $2, ...-Platzhalter.

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

sql.builder.at

Platzhalterformat für @p1, @p2, ...-Platzhalter (SQL-Server-Stil). Wird wie die obigen Formate an placeholder_format übergeben.

sql.builder.colon

Platzhalterformat für :1, :2, ...-Platzhalter. Wird wie die obigen Formate an placeholder_format übergeben.

Verbindungsmethoden

Datenbankverbindungs-Handle zurückgegeben von sql.get().

db:type

Gibt Datenbanktyp-Konstante zurück.

local dbtype, err = db:type()

Gibt zurück: string, error

db:query

Führt SELECT-Abfrage aus und gibt Zeilen zurück.

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

Gibt zurück: table[], error

db:execute

Führt INSERT/UPDATE/DELETE-Abfrage aus.

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

Gibt zurück: table, error

Gibt Table mit Feldern zurück:

• last_insert_id - Zuletzt eingefügte ID
• rows_affected - Anzahl betroffener Zeilen

db:prepare

Erstellt Prepared Statement für wiederholte Ausführung.

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

Gibt zurück: Statement, error

db:begin

Beginnt Datenbanktransaktion.

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

Options-Table-Felder:

• isolation - Isolationsebene aus sql.isolation.* (Standard: DEFAULT)
• read_only - Nur-Lesen-Transaktions-Flag (Standard: false)

Gibt zurück: Transaction, error

db:release

Gibt Datenbankressource an Pool zurück.

local ok, err = db:release()

Gibt zurück: boolean, error

Die Operation ist idempotent.

db:stats

Gibt Verbindungspool-Statistiken zurück.

local stats, err = db:stats()

Gibt zurück: table, error

Gibt Table mit Feldern zurück:

• max_open_connections - Max. erlaubte offene Verbindungen
• open_connections - Aktuelle offene Verbindungen
• in_use - Aktuell verwendete Verbindungen
• idle - Ungenutzte Verbindungen im Pool
• wait_count - Gesamte Verbindungs-Warteanzahl
• wait_duration - Gesamte Wartezeit
• max_idle_closed - Wegen max idle geschlossene Verbindungen
• max_idle_time_closed - Wegen idle Timeout geschlossene Verbindungen
• max_lifetime_closed - Wegen max lifetime geschlossene Verbindungen

Vorbereitete Anweisungen :id=prepared-statements

Eine von db:prepare() zurückgegebene vorbereitete Anweisung kann wiederholt abgefragt oder ausgeführt werden.

stmt:query

Führt Prepared Statement als SELECT aus.

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

Gibt zurück: table[], error

stmt:execute

Führt Prepared Statement als INSERT/UPDATE/DELETE aus.

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

Gibt zurück: table, error

Gibt Table mit Feldern zurück:

• last_insert_id - Zuletzt eingefügte ID
• rows_affected - Anzahl betroffener Zeilen

stmt:close

Schließt Prepared Statement.

local ok, err = stmt:close()

Gibt zurück: boolean, error

Transaktionen

Eine von db:begin() zurückgegebene Transaktion stellt Operationen für Abfragen, Anweisungen, Savepoints, Commit und Rollback bereit.

Eine aktive Transaktion wird bei der Bereinigung des Ausführungsframes automatisch zurückgerollt. Führen Sie Commit oder Rollback ausdrücklich aus, sobald die Transaktionsarbeit abgeschlossen ist.

tx:db_type

Gibt Datenbanktyp-Konstante zurück.

local dbtype, err = tx:db_type()

Gibt zurück: string, error

tx:query

Führt SELECT-Abfrage innerhalb der Transaktion aus.

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

Gibt zurück: table[], error

tx:execute

Führt INSERT/UPDATE/DELETE innerhalb der Transaktion aus.

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

Gibt zurück: table, error

Gibt Table mit Feldern zurück:

• last_insert_id - Zuletzt eingefügte ID
• rows_affected - Anzahl betroffener Zeilen

tx:prepare

Erstellt Prepared Statement innerhalb der Transaktion.

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

Gibt zurück: Statement, error

tx:commit

Committet die Transaktion.

local ok, err = tx:commit()

Gibt zurück: boolean, error

tx:rollback

Rollt die Transaktion zurück.

local ok, err = tx:rollback()

Gibt zurück: boolean, error

tx:savepoint

Erstellt benannten Savepoint innerhalb der Transaktion.

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

Gibt zurück: boolean, error

tx:rollback_to

Rollt zum benannten Savepoint zurück.

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

Gibt zurück: boolean, error

tx:release

Gibt Savepoint frei.

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

Gibt zurück: boolean, error

SELECT-Generator :id=select-builder

Fluent-Interface zum Erstellen von SELECT-Abfragen.

select:from

Setzt FROM-Klausel.

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

Gibt zurück: SelectBuilder

select:join

Fügt JOIN-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:left_join

Fügt LEFT JOIN-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:right_join

Fügt RIGHT JOIN-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:inner_join

Fügt INNER JOIN-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:where

Fügt WHERE-Bedingung hinzu.

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

Unterstützt drei Formate:

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

Gibt zurück: SelectBuilder

select:order_by

Fügt ORDER BY-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:group_by

Fügt GROUP BY-Klausel hinzu.

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

Gibt zurück: SelectBuilder

select:having

Fügt HAVING-Bedingung hinzu.

local query = sql.builder.select("status", "COUNT(*) as cnt")
    :from("users")
    :group_by("status")
    :having(sql.builder.gt({cnt = 10}))

Gibt zurück: SelectBuilder

select:limit

Setzt LIMIT.

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

Gibt zurück: SelectBuilder

select:offset

Setzt OFFSET.

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

Gibt zurück: SelectBuilder

select:columns

Fügt Spalten zu SELECT hinzu.

local query = sql.builder.select():columns("id", "name", "email")

Gibt zurück: SelectBuilder

select:distinct

Fügt DISTINCT-Modifikator hinzu.

local query = sql.builder.select("status")
    :from("users")
    :distinct()

Gibt zurück: SelectBuilder

select:suffix

Fügt SQL-Suffix hinzu.

local query = sql.builder.select("*")
    :from("users")
    :suffix("FOR UPDATE")

Gibt zurück: SelectBuilder

select:placeholder_format

Setzt Platzhalterformat.

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

Gibt zurück: SelectBuilder

select:to_sql

Generiert SQL-String und Bind-Argumente.

local sql_str, args = query:to_sql()

Gibt zurück: bei Erfolg string, table; bei einem ungültigen Builder-Zustand nil, error

select:run_with

Erstellt Executor für Abfrage.

local executor, err = query:run_with(db)
if err then
    return nil, err
end
local rows, err = executor:query()

Gibt zurück: QueryExecutor, error

INSERT-Generator :id=insert-builder

Fluent-Interface zum Erstellen von INSERT-Abfragen.

insert:into

Setzt Tabellennamen.

local query = sql.builder.insert():into("users")

Gibt zurück: InsertBuilder

insert:columns

Setzt Spaltennamen.

local query = sql.builder.insert("users"):columns("name", "email")

Gibt zurück: InsertBuilder

insert:values

Fügt Zeilenwerte hinzu.

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

Gibt zurück: InsertBuilder

insert:set_map

Setzt Spalten und Werte aus Table.

local query = sql.builder.insert("users")
    :set_map({name = "alice", email = "alice@example.com"})

Gibt zurück: InsertBuilder

insert:select

Fügt aus SELECT-Abfrage ein.

local select_query = sql.builder.select("name", "email"):from("temp_users")
local query = sql.builder.insert("users")
    :columns("name", "email")
    :select(select_query)

Gibt zurück: InsertBuilder

insert:prefix

Fügt SQL-Präfix hinzu.

local query = sql.builder.insert("users")
    :prefix("/* audit import */")

Gibt zurück: InsertBuilder

insert:suffix

Fügt SQL-Suffix hinzu.

local query = sql.builder.insert("users")
    :columns("name")
    :values("alice")
    :suffix("RETURNING id")

Gibt zurück: InsertBuilder

insert:options

Fügt INSERT-Optionen hinzu.

local query = sql.builder.insert("users")
    :options("DELAYED", "IGNORE")

Gibt zurück: InsertBuilder

insert:placeholder_format

Setzt Platzhalterformat.

local query = sql.builder.insert("users")
    :placeholder_format(sql.builder.dollar)

Gibt zurück: InsertBuilder

insert:to_sql

Generiert SQL-String und Bind-Argumente.

local sql_str, args = query:to_sql()

Gibt zurück: bei Erfolg string, table; bei einem ungültigen Builder-Zustand nil, error

insert:run_with

Erstellt Executor für Abfrage.

local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()

Gibt zurück: QueryExecutor, error

UPDATE-Generator :id=update-builder

Fluent-Interface zum Erstellen von UPDATE-Abfragen.

update:table

Setzt Tabellennamen.

local query = sql.builder.update():table("users")

Gibt zurück: UpdateBuilder

update:set

Setzt Spaltenwert.

local query = sql.builder.update("users")
    :set("status", "active")
    :set("updated_at", sql.builder.expr("NOW()"))

Gibt zurück: UpdateBuilder

update:set_map

Setzt mehrere Spalten aus Table.

local query = sql.builder.update("users")
    :set_map({status = "active", login_count = 0})

Gibt zurück: UpdateBuilder

update:where

Fügt WHERE-Bedingung hinzu.

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

Gibt zurück: UpdateBuilder

update:order_by

Fügt ORDER BY-Klausel hinzu.

local query = sql.builder.update("users")
    :set("rank", 1)
    :order_by("score DESC")

Gibt zurück: UpdateBuilder

update:limit

Setzt LIMIT.

local query = sql.builder.update("users")
    :set("status", "active")
    :limit(10)

Gibt zurück: UpdateBuilder

update:offset

Setzt OFFSET.

local query = sql.builder.update("users")
    :set("status", "active")
    :offset(5)

Gibt zurück: UpdateBuilder

update:suffix

Fügt SQL-Suffix hinzu.

local query = sql.builder.update("users")
    :set("status", "active")
    :suffix("RETURNING id")

Gibt zurück: UpdateBuilder

update:from

Fügt FROM-Klausel hinzu.

local query = sql.builder.update("users")
    :set("status", "active")
    :from("other_table")

Gibt zurück: UpdateBuilder

update:from_select

Aktualisiert aus SELECT-Abfrage.

local select_query = sql.builder.select("*"):from("temp_users")
local query = sql.builder.update("users")
    :set("status", "active")
    :from_select(select_query, "t")

Gibt zurück: UpdateBuilder

update:placeholder_format

Setzt Platzhalterformat.

local query = sql.builder.update("users")
    :placeholder_format(sql.builder.dollar)

Gibt zurück: UpdateBuilder

update:to_sql

Generiert SQL-String und Bind-Argumente.

local sql_str, args = query:to_sql()

Gibt zurück: bei Erfolg string, table; bei einem ungültigen Builder-Zustand nil, error

update:run_with

Erstellt Executor für Abfrage.

local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()

Gibt zurück: QueryExecutor, error

DELETE-Generator :id=delete-builder

Fluent-Interface zum Erstellen von DELETE-Abfragen.

delete:from

Setzt Tabellennamen.

local query = sql.builder.delete():from("users")

Gibt zurück: DeleteBuilder

delete:where

Fügt WHERE-Bedingung hinzu.

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

Gibt zurück: DeleteBuilder

delete:order_by

Fügt ORDER BY-Klausel hinzu.

local query = sql.builder.delete("users")
    :where({active = 0})
    :order_by("created_at ASC")

Gibt zurück: DeleteBuilder

delete:limit

Setzt LIMIT.

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

Gibt zurück: DeleteBuilder

delete:offset

Setzt OFFSET.

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

Gibt zurück: DeleteBuilder

delete:suffix

Fügt SQL-Suffix hinzu.

local query = sql.builder.delete("users")
    :where({active = 0})
    :suffix("RETURNING id")

Gibt zurück: DeleteBuilder

delete:placeholder_format

Setzt Platzhalterformat.

local query = sql.builder.delete("users")
    :placeholder_format(sql.builder.dollar)

Gibt zurück: DeleteBuilder

delete:to_sql

Generiert SQL-String und Bind-Argumente.

local sql_str, args = query:to_sql()

Gibt zurück: bei Erfolg string, table; bei einem ungültigen Builder-Zustand nil, error

delete:run_with

Erstellt Executor für Abfrage.

local executor, err = query:run_with(db)
if err then
    return nil, err
end
local result, err = executor:exec()

Gibt zurück: QueryExecutor, error

Abfragen ausführen

Der Query-Executor führt vom Builder generierte Abfragen aus.

executor:query

Führt Abfrage aus und gibt Zeilen zurück (für SELECT).

local rows, err = executor:query()

Gibt zurück: table[], error

executor:exec

Führt Abfrage aus und gibt Ergebnis zurück (für INSERT/UPDATE/DELETE).

local result, err = executor:exec()

Gibt zurück: table, error

Gibt Table mit Feldern zurück:

• last_insert_id - Zuletzt eingefügte ID
• rows_affected - Anzahl betroffener Zeilen

executor:to_sql

Gibt generierten SQL und Argumente ohne Ausführung zurück.

local sql_str, args = executor:to_sql()

Gibt zurück: string, table

Berechtigungen

Datenbankzugriff unterliegt der Auswertung der Sicherheitsrichtlinien.

Fehler

Informationen zum Umgang mit Fehlern finden Sie unter Fehlerbehandlung.

Kombiniertes Teilrezept

Dieses Rezept setzt voraus, dass app.db:main als SQLite- oder MySQL-Datenbank konfiguriert ist und bereits die Tabellen users, orders und logs mit den referenzierten Spalten enthält. Es verwendet ?-Platzhalter; verwenden Sie für eine PostgreSQL-Ressource $1, $2 und so weiter. Die zurückgegebenen Zeilen hängen von den Daten der Anwendung ab. Die umgebende Anwendung stellt report_cleanup_error(err) bereit, damit Fehler beim Rollback oder Schließen sichtbar bleiben, ohne den ursprünglichen Operationsfehler zu ersetzen.

local sql = require("sql")

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

local function finish(value, primary_err)
    local _, release_err = db:release()
    if primary_err then return nil, primary_err end
    if release_err then return nil, release_err end
    return value
end

-- Direct query
local users, err = db:query("SELECT id, name FROM users WHERE active = ?", {1})
if err then
    return finish(nil, err)
end

for _, user in ipairs(users) do
    print(user.id, user.name)
end

-- Builder pattern
local query = sql.builder.select("u.id", "u.name", "COUNT(o.id) as order_count")
    :from("users u")
    :left_join("orders o ON o.user_id = u.id")
    :where(sql.builder.and_({
        sql.builder.eq({["u.active"] = 1}),
        sql.builder.gte({["u.score"] = 80})
    }))
    :group_by("u.id", "u.name")
    :having(sql.builder.gt({["COUNT(o.id)"] = 0}))
    :order_by("order_count DESC")
    :limit(10)

local executor, build_err = query:run_with(db)
if build_err then
    return finish(nil, build_err)
end
local results, err = executor:query()
if err then
    return finish(nil, err)
end

-- Transaction
local tx, err = db:begin({isolation = sql.isolation.SERIALIZABLE})
if err then
    return finish(nil, err)
end

local _, err = tx:execute("INSERT INTO users (name) VALUES (?)", {"alice"})
if err then
    local _, rollback_err = tx:rollback()
    if rollback_err then report_cleanup_error(rollback_err) end
    return finish(nil, err)
end

local _, commit_err = tx:commit()
if commit_err then
    return finish(nil, commit_err)
end

-- Prepared statements
local stmt, err = db:prepare("INSERT INTO logs (message, level) VALUES (?, ?)")
if err then
    return finish(nil, err)
end

for i = 1, 3 do
    local _, err = stmt:execute({"log message " .. i, "info"})
    if err then
        local _, close_err = stmt:close()
        if close_err then report_cleanup_error(close_err) end
        return finish(nil, err)
    end
end

local _, close_err = stmt:close()
if close_err then
    return finish(nil, close_err)
end

return finish({users = users, ranked_users = results})