AntOS Library — db (reference)

The db library's design and native core — raw SQL access to the DBFS SQLite database, beneath the friendly fs layer. The script-facing API is luau_db.

What it is

DBFS is a real SQLite database, and db exposes it directly. Where fs gives files, metadata, tags, and the safe fs.query catalogue search, db gives arbitrary SQL — SELECT/INSERT/UPDATE/DDL, prepared statements, transactions — for custom application tables and advanced queries fs.query can't express.

Design notes

• db and fs are two views of one database. fs is the recommended interface for files and the catalogue; db is the escape hatch for custom structured data and complex SQL. fs.query is a safe, shaped subset; db.query is raw.
• Scripts share the DBFS file (sys.db) with the system catalogue, so custom tables live alongside system tables. The convention is to prefix app tables (app_<name>_…) to avoid clashes; direct writes to system catalogue tables are unsupported — use fs for files and tags.
• db writes go through the same DBFS path as every other write, so they are transactional (SQLite WAL) and covered by the D!: shadow backup — a db insert is as durable as a file write. Because it is the same engine and file, a db transaction and a file write can even share a commit.
• D:-only — off DBFS, calls return nil, err.
• Parameterised queries (bound ? / :name) are the rule; SQL is never built by concatenation.

Native core — libantos_db

libantos_db wraps the same SQLite engine DBFS itself uses — the connection to the active database, a prepared-statement cache, and transaction control — plain C, no Luau. The binding marshals rows to/from Lua tables. Because the engine is shared with the VFS/catalogue layer, db and libantos_fs operate on one database rather than two.

Related

• luau_db — the script API · antos_fs (the friendly layer over the same database) · Filesystem · antos_library_design · AntOS Libraries hub