Reference · Database

db.connect

db.connect(str | fn, map=) -> map | error(str)

What it does

Opens another database beside the program's own and gives it as a map of the same functions, called on it: analytics.query(...), analytics.exec(...), one, transaction, migrate, tenants, tenant_exists and sql_name. Any kind works, a SQLite file or a server URL, with replicas in the options as for db.open. It has its own transactions and migrations. The same target again is the same connection, not a new pool, so a route may call it; a failure to open is an error value.

Examples

db.open("app.db")db.exec("create table orders (id integer primary key, total integer)")db.exec("insert into orders (total) values (10), (20)")let analytics = db.connect("analytics.db")print(analytics.exec("create table sales (day text, total integer)"))print(analytics.exec("insert into sales values (?, ?)", "2026-10-29", 30))print(analytics.query("select * from sales"))print(analytics.one("select sum(total) as t from sales"))

{ changes: 0, last_id: null }{ changes: 1, last_id: 1 }[{ day: "2026-10-29", total: 30 }]{ t: 30 }

db.open("app.db")let analytics = db.connect(env("ANALYTICS_URL"))analytics.migrate("migrations/analytics")db.transaction(() => {    db.exec("insert into orders ...")    analytics.transaction(() => analytics.exec("insert into sales ..."))   // its own})

Edge cases

• The databases are apart: db does not see the connection's tables, nor the connection db's. To join their rows, fetch both and use join_on.
• The same target twice gives the same connection (they compare equal), and so does another spelling of the same SQLite file ("./analytics.db", "sub/../analytics.db", its full path): one file is one connection, and one set of live topics, so a write through one refreshes a page that reads through another.
• A server URL with another user, password or options (?application_name=...) is another pool, but its tables are the same live topics: they are named by the scheme, host, port and database alone, so changing a password while servers run keeps their pages in step.
• Inside a function declared with, the connection's calls need db, as db.query does: fn f() with http = analytics.query(...) is an error in quillo check and when it runs. On a parameter with no type (fn f(c) with http = c.query(...)) the check warns, as it cannot tell whether c is a connection. sql_name asks the database nothing and needs no effect.
• A transaction on the connection commits or rolls back on its own, even inside one of db's.
• The map has no error_kind, connect, system, shards or atomic: those are db's and take a connection as a value where they need one.
• A connection never reaches the browser (its URL may hold a password).

db.open("app.db")db.exec("create table orders (id integer primary key)")let analytics = db.connect("analytics.db")analytics.exec("create table sales (total integer)")print(db.query("select * from sales"), analytics.query("select * from orders"))print(db.connect("analytics.db") == analytics, db.connect("./analytics.db") == analytics)print(db.transaction(() => {    db.exec("insert into orders default values")    analytics.transaction(() => { analytics.exec("insert into sales values (1)"); err("no") })}))print(db.query("select count(*) as n from orders"), analytics.query("select count(*) as n from sales"))print(analytics | keys)

err("db: no such table: sales") err("db: no such table: orders")true trueerr("no")[{ n: 0 }] [{ n: 0 }]["$db", "exec", "exec_many", "query", "one", "transaction", "migrate", "tenants", "tenant_exists", "sql_name"]

Errors

A target that cannot be opened is an error value; calling a function on it is then a runtime error (error has no method query), so check it, or unwrap it at the top of the program. A target that is neither a string nor a function is a runtime error.

let c = db.connect("nope/dir/x.db")print(is_err(c), db.error_kind(c))print(db.connect("postgres://user:secret@127.0.0.1:1/app") | is_err)

true nulltrue

print(db.connect(42))

line 1: `db.connect` expects a path, a URL, or a function giving one for each tenant, got int

A connection's call in a function whose with leaves out db is a runtime error, as db.query's is:

let analytics = db.connect("analytics.db")fn totals() with http = analytics.query("select 1 as x")print(totals())

line 2: `db.query` needs the db effect, but `totals` is declared `with http`  in totals, called at main.qwe:3

Chaining

The SQL comes first in a pipeline into the connection's functions:

let analytics = db.connect("analytics.db")analytics.exec("create table sales (total integer)")analytics.exec("insert into sales values (5), (7)")print("select sum(total) as t from sales" | analytics.one)print("select total from sales" | analytics.query | map((r) => r.total))

{ t: 12 }[5, 7]

See also

db.open, db.sql_name, db.atomic, db.shards, db.migrate, join_on

Edit this page on GitHub · every example's output was made by running it (tools/refcheck.mjs) · questions on Discord or r/quillo