sql

import sql

One way to talk to a relational database, whichever one it is.

sql is the entry point for every database Zuri supports. It defines what a database adapter has to provide, supplies everything that is the same whichever engine answers, and picks the adapter from the connection string. Changing database means changing that string, and whatever SQL the engines genuinely spell differently.

import sql

var db = sql.open(':memory:')

db.exec('create table posts (id integer primary key, title text)')

var id = db.insert('posts', { title: 'Hello' })

for post in db.query('select * from posts where id = ?', [id]) {
  echo post.title
}

db.close()

The only line above that names an engine is the first. Point it at postgres://localhost/app or mysql://localhost/app and the rest runs unchanged: the ? becomes $1 on PostgreSQL and stays ? on MySQL, the insert gets a RETURNING clause where the engine has no last insert id, and a unique key violation still arrives as UniqueViolation.

What is here

Parameters

Values are bound, never pasted into the statement. Write ? for positional parameters or :name for named ones and sql translates them into whatever the adapter wants:

db.query('select * from posts where author = ? and year = ?', [name, 2026])
db.query('select * from posts where author = :who', { who: name })

Errors

Every error is a SqlError. The subclasses are the same on every engine, so the code that handles a duplicate key does not change when the engine does:

catch {
  db.insert('users', { email: address })
} as error {
  if instance_of(error, sql.UniqueViolation) {
    echo 'that address is already registered'
  } else {
    raise error
  }
}

Isolates

A connection belongs to the isolate that opened it and cannot be shared with another. An isolate that needs a database opens its own connection or its own pool.

The sql API

Every public name in sql, wherever it is declared. Each links to the page that documents it.

Submodules

Functions

register()

sql.register(driver) -> Driver

Registers an adapter, so open() recognises its connection strings.

An adapter is anything implementing Driver. Registering one under a name already taken replaces it, which is how a program swaps in an adapter of its own for an engine sql already knows.

sql.register(MyOracleDriver())

var db = sql.open('oracle://localhost/app')

Parameters

• driver (Driver)

Returns Driver — The driver, so a registration can be an expression.

Raises SqlError if driver is not one.

drivers()

sql.drivers() -> list[string]

The names of every registered adapter.

Returns list[string]

driver()

sql.driver(name: string) -> Driver

The adapter registered under name.

Parameters

• name (string)

Returns Driver

Raises SqlError if nothing is registered under that name.

driver_for()

sql.driver_for(dsn: string) -> Driver

The adapter a connection string names.

The scheme decides: sqlite:// and postgres:// reach the adapters of those names, and a string with no scheme at all is taken as a SQLite path, which is the only form that could not be anything else.

Parameters

• dsn (string)

Returns Driver

Raises SqlError if no adapter claims the scheme.

open()

sql.open(dsn, options) -> Connection

Opens a connection.

sql.open('sqlite://./app.db')
sql.open('postgres://alice:secret@localhost/app')
sql.open('./app.db')

An options dictionary works too, and needs driver to say which adapter it is for:

sql.open({ driver: 'sqlite', path: './app.db', journal_mode: 'wal' })

Parameters

• dsn (string|dict) — A connection string, or options.
• options (dict|nil) — Extra options, merged over whatever the connection string carried. Anything an adapter accepts in its own options goes here.

Returns Connection

Raises ConnectionError if the database cannot be reached.

pool()

sql.pool(dsn, options) -> Pool

Opens a pool of connections.

Parameters

• dsn (string|dict) — As open() takes.
• options (dict|nil) — The pool’s own settings, and any the adapter accepts. See Pool for what the pool reads.

Returns Pool

2026, Richard Ore and Zuri contributors