SQLite3 module – embedded relational database.

Wraps the SQLite3 C library to provide full SQL database access from Luau.

Quick start

local sqlite3 = require("@eryx/sqlite3")
local db = sqlite3.open(":memory:")
db:exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")
db:exec("INSERT INTO users VALUES (1, 'Alice', 30)")

local rows = db:query("SELECT * FROM users WHERE age > ?", 25)
for _, row in rows do
    print(row.name, row.age)
end

 Prepared statements for repeated queries
local stmt = db:prepare("INSERT INTO users VALUES (?, ?, ?)")
stmt:run(2, "Bob", 25)
stmt:run(3, "Charlie", 35)

 Transactions: all-or-nothing batch operations
db:transaction(function(db)
    db:exec("INSERT INTO users VALUES (?, ?, ?)", 4, "Diana", 28)
    db:exec("INSERT INTO users VALUES (?, ?, ?)", 5, "Eve", 32)
end)

db:close()

Summary

Classes

Functions

API Reference

Classes

Statement

A prepared SQL statement.

Statements are compiled once and can be executed multiple times with different parameters. They are automatically finalized by the garbage collector.

Properties

Statement:bind

Resets the statement and binds new parameters (positional). Returns the statement for chaining.

Statement:bind() → Statement

Statement:step

Fetches the next result row, or nil when no more rows remain.

Statement:step() → Row?

Statement:reset

Resets the statement so it can be stepped again from the beginning (without changing bindings).

Statement:reset() → Statement

Statement:all

Convenience: resets, binds parameters, and returns all result rows as an array of Row tables.

Statement:all() → { Row }

Statement:run

Convenience: resets, binds parameters, and executes the statement discarding any results. Use for INSERT/UPDATE/DELETE.

Statement:run() → ()

Statement:__tostring

Statement:__tostring() → string

Database

An open SQLite database connection.

The connection holds a file lock (or memory) and should be closed when no longer needed. It is also closed automatically by the garbage collector, but explicit Close() is recommended to release the file lock promptly.

Properties

Database:exec

Executes one or more SQL statements that return no results (DDL, INSERT, UPDATE, DELETE, etc.). Multiple statements separated by ; are supported.

Database:exec(sql: string) → ()

Database:query

Executes a SQL query with optional positional parameters and returns all result rows as an array of Row tables.

Database:query(sql: string) → { Row }

Database:prepare

Compiles a SQL string into a reusable prepared Statement.

Database:prepare(sql: string) → Statement

Database:close

Explicitly closes the database connection. Safe to call multiple times.

Database:close() → ()

Database:isOpen

Returns true if the database connection is still open.

Database:isOpen() → boolean

Database:lastInsertId

Returns the rowid of the last successful INSERT.

Database:lastInsertId() → number

Database:changes

Returns the number of rows changed by the last INSERT, UPDATE, or DELETE statement.

Database:changes() → number

Database:transaction

Wraps a function in a SQL transaction (BEGIN/COMMIT).

If fn succeeds, the transaction is committed and its return values are forwarded. If fn throws, the transaction is rolled back and the error is re-raised.

db:transaction(function(db)
    db:exec("INSERT INTO users VALUES (?, ?)", 1, "Alice")
    db:exec("INSERT INTO users VALUES (?, ?)", 2, "Bob")
end)

Database:transaction(fn: ((db: Database) → T...)) → T...

Database:__tostring

Database:__tostring() → string

Functions

sqlite3.open

Opens (or creates) a SQLite database at the given path. Use ":memory:" for an in-memory database.

sqlite3.open(path: string) → Database

sqlite3.version

Returns the SQLite library version string (e.g. "3.52.0").

sqlite3.version() → string

Types

Row

A row returned from a query. Keys are column names, values are the corresponding column values (number, string, buffer, or nil).

type Row = { [string]: number | string | buffer | boolean | nil }