std.db

std.db gives you access to databases with a small, familiar set of functions. You open a connection, run SQL statements, fetch values and rows, and control transactions — exactly what you expect, without ceremony.

The default is NorsDB, the lightweight database that ships with the runtime, but the interface is the same whatever the engine. For data that comes from outside there are bound variants that keep the values separate from the statement itself, so malicious input cannot change the query.

When to use it

Use std.db when your app needs to store data that lasts. You open a connection with open, run statements with execute, fetch values with query_text and query_int, and wrap several changes in a transaction with begin, commit and rollback — or let transaction do it for you.

Getting started

bruk std.db som db

funksjon start() -> heiltall {
    la h = db.open("data.norsdb")
    db.execute(h, "CREATE TABLE IF NOT EXISTS notat (id INTEGER, tekst TEXT)")
    db.execute_bundet(h, "INSERT INTO notat (id, tekst) VALUES (?, ?)", ["1", "hei"])
    la tal = db.query_int(h, "SELECT COUNT(*) FROM notat")
    skriv(tekst(tal))
    db.close(h)
    returner 0
}

Use execute_bundet with ? placeholders for values that come from outside — it keeps the data separate from the SQL and stops injection. Close the connection with close when you are done.

The functions

The workflow is always the same: open (open), run (execute, query_text, query_int, query_rader), and close (close). The bound variants (*_bundet) are the ones you should use for outside values. Transactions are controlled with begin, commit and rollback, or all at once with transaction. A pool (pool, pool_acquire) lets you reuse connections under load.

• backend() -> tekst — The name of the database engine in use.
• status() -> ordbok_tekst — Status information about the database.
• open(sti: tekst) -> ordbok_tekst — Opens a database connection to the path and returns a handle.
• close(handle) -> bool — Closes a connection.
• execute(handle, sql: tekst) -> heltall — Runs an SQL statement that changes data (INSERT, UPDATE, CREATE …).
• query_text(handle, sql: tekst) -> tekst — Runs a query and returns the first value as text.
• query_int(handle, sql: tekst) -> heltall — Runs a query and returns the first value as an integer.
• query_rader(handle, sql: tekst) -> tekst — Fetches several rows as text.
• siste_feil(handle) -> tekst — The last error message from the database.
• execute_bundet(handle, sql: tekst, params: liste<tekst>) -> heltall — Like execute, but with bound parameters (?) — safe against injection.
• query_text_bundet(handle, sql: tekst, params: liste<tekst>) -> tekst — Text query with bound parameters.
• query_int_bundet(handle, sql: tekst, params: liste<tekst>) -> heltall — Numeric query with bound parameters.
• migrate(handle, skript: tekst) -> heltall — Runs a migration script against the database.
• transaction(handle, skript: tekst) -> heltall — Runs a script as one transaction — all or nothing.
• pool(sti: tekst, maks: heltall) -> ordbok_tekst — Creates a connection pool with the given maximum size.
• pool_acquire(pool) -> ordbok_tekst — Takes a connection from the pool.
• pool_size(pool) -> heltall — Number of connections in the pool.
• pool_close(pool) -> bool — Closes the pool and all its connections.
• begin(handle) -> bool — Starts a transaction.
• commit(handle) -> bool — Completes and saves a transaction.
• rollback(handle) -> bool — Undoes all changes in a transaction.
• ping(handle) -> bool — Checks that the connection is still alive.
• backup(handle, sti: tekst) -> bool

Good to know

• Always use the bound variants (execute_bundet, query_text_bundet) for outside values — it is the single most important measure against SQL injection.
• Wrap compound changes in a transaction, so you avoid half-finished states if something fails midway.
• Close connections with close when you are done, or use a pool for reuse under load.

std.db is one of the modules in the standard library. Everything ships with the runtime — no installation, no external dependencies. See also Documentation for the language and the runtime.

Back to the overview