---@meta
---@diagnostic disable: missing-return
-- Type stubs for the `sqlite` module. The native core provides sqlite.connect
-- and the connection methods; lua/stdlib/sqlite.lua adds the transaction
-- helpers (typed here too, since the source defines them on a hidden method
-- table). Reference: docs/sqlite.md
--
-- Failures raise Lua errors (bad SQL, unbindable type, parameter mismatch,
-- closed connection) — trap with pcall/utils.try where needed.

sqlite = {}

---Parameters bind positionally (array for `?`) or by name (string keys for
---`:name`/`@name`/`$name`); mixing the two is an error. Bind utils.NULL for
---SQL NULL — a literal nil cannot live in a table.
---@alias sqlite.Params any[]|table<string, any>

---@class sqlite.Connection
local Connection = {}

---Run a statement that changes data (INSERT, UPDATE, DELETE, CREATE, …).
---@param sql string
---@param params sqlite.Params?
---@return integer changed number of rows changed
function Connection:execute(sql, params) end

---Run a SELECT and return all rows, each a table keyed by column name.
---A NULL column is simply absent from its row table.
---@param sql string
---@param params sqlite.Params?
---@return table[] rows
function Connection:query(sql, params) end

---Like query, but returns only the first row, or nil if nothing matched.
---@param sql string
---@param params sqlite.Params?
---@return table? row
function Connection:queryOne(sql, params) end

---Rowid of the most recent successful INSERT on this connection.
---@return integer
function Connection:lastInsertRowid() end

---Rows changed by the most recent INSERT/UPDATE/DELETE.
---@return integer
function Connection:changes() end

---Release the connection eagerly (also happens on garbage collection).
---Any further call on the connection raises.
function Connection:close() end

---Start a transaction (BEGIN).
function Connection:begin() end

---Commit the current transaction (COMMIT).
function Connection:commit() end

---Discard the current transaction (ROLLBACK).
function Connection:rollback() end

---Run fn inside a transaction: commit on success, roll back and re-raise on
---error. fn's return values are passed through.
---@param fn function
---@return any ...
function Connection:transaction(fn) end

---Open a database file (created if missing), or ":memory:" for a private
---in-memory database.
---@param path string
---@return sqlite.Connection
function sqlite.connect(path) end