Import std.db.database

std.db.database

std.db: SQLite databases, through the runtime's fb_db_ functions. A Database runs SQL with its parameters bound to values, and gives the Rows a query reads, or with Query<T> each as a T that Load<T> makes of its columns; Prepare makes a Statement to run many times, Begin a Transaction, which keeps all of what it does or none of it, and Migrate brings a database up to date, a numbered migration at a time. What SQLite can't do throws a DatabaseError of its kind, with SQLite's message.

std/db/database.fb

Types

`ColumnType` enum

Public Enum ColumnType

SQLite's types of values: which one a Row's column holds.

std/db/database.fb, line 50

INTEGER enum member #

An integer, as an Int64.
REAL enum member #

A floating-point number, as a Double.
TEXT enum member #

Text, as a String.
BLOB enum member #

Bytes, as a UInt8[].
NULL enum member #

No value.

`SqlValue` interface

Public Interface SqlValue

What a statement's parameter takes: an integer, a Bool as 1 or 0, a Float32 or Float64 as a real, but for NaN, a String as text, a UInt8[] as a blob, or a Nullable, NULL when its value is Null. A type of the program's is one too when its BindTo binds one of these, with statement.Bind(index, value).

std/db/database.fb, line 67

Method BindTo(statement: Statement, index: Int) Throws DatabaseError method #

Binds statement's parameter at index, from 1, to the value.

`Nullable` struct

Public Struct Nullable<T: SqlValue> Implements SqlValue

A value that may be Null, for a parameter that's NULL when it is: Nullable(name) for a String? name.

std/db/database.fb, line 164

Public ReadOnly Field Value: T? field #

The value, or Null for SQL's NULL.
Public New(value: T?) constructor #

A Nullable of value.

`Row` struct

Public Struct Row

A row a query read: its columns' names and values, which Integer, Real, Text, and Blob give by the column's index, from 0, or its name, as the SQL gives it, like "id" or "count(*)". Each gives Null for NULL, and panics for a value of another type, but Real takes an integer too, so a column of either reads as one. Type says which a column holds. A name that two columns have is the first's.

std/db/database.fb, line 197

Public Property Count: Int property #

How many columns it has.
@PanicsAtCaller Public Method Name(column: Int): String method #

The name of the column at index. Panics when there's none there.
@PanicsAtCaller Public Method Type(column: Int): ColumnType method #

The type of the column at column's value. Panics when there's none there.
@PanicsAtCaller Public Method Type(name: String): ColumnType method #

The type of the column named name's value. Panics when there's none of that name.
@PanicsAtCaller Public Method IsNull(column: Int): Bool method #

Whether the column at column is NULL. Panics when there's none there.
@PanicsAtCaller Public Method IsNull(name: String): Bool method #

Whether the column named name is NULL. Panics when there's none of that name.
@PanicsAtCaller Public Method Integer(column: Int): Int64? method #

The integer at column, or Null for NULL. Panics when there's no column there, or it's of another type.
@PanicsAtCaller Public Method Integer(name: String): Int64? method #

The integer in the column named name, or Null for NULL. Panics when there's no column of that name, or it's of another type.
@PanicsAtCaller Public Method Real(column: Int): Float64? method #

The real number at column, an integer's too, or Null for NULL. Panics when there's no column there, or it's of another type.
@PanicsAtCaller Public Method Real(name: String): Float64? method #

The real number in the column named name, an integer's too, or Null for NULL. Panics when there's no column of that name, or it's of another type.
@PanicsAtCaller Public Method Text(column: Int): String? method #

The text at column, or Null for NULL. Panics when there's no column there, or it's of another type.
@PanicsAtCaller Public Method Text(name: String): String? method #

The text in the column named name, or Null for NULL. Panics when there's no column of that name, or it's of another type.
@PanicsAtCaller Public Method Blob(column: Int): UInt8[]? method #

The blob at column, or Null for NULL. Panics when there's no column there, or it's of another type.
@PanicsAtCaller Public Method Blob(name: String): UInt8[]? method #

The blob in the column named name, or Null for NULL. Panics when there's no column of that name, or it's of another type.

`Database` class

Public Class Database

A connection to an SQLite database, which closes when Close is called, or when its last reference goes, and those of its Statements and Transactions. One thread uses it at a time.

std/db/database.fb, line 345

Public Static Method Open(path: String): Database Throws DatabaseError static method #

The database at path, made when there's none: a file, ":memory:" for a new one in memory that only this Database reaches, or a URI file name, like "file:data.db?mode=ro" to only read one, or "file:name?mode=memory&cache=shared" for one in memory that each Database of that name shares while one is open. Its foreign keys are checked, and it waits up to 5 seconds for another connection that holds the database before it throws a DatabaseError of BUSY.
Public Method Close() method #

Closes it now, and rolls back what an open Transaction did, as its last reference going would, and finalizes its Statements, so it lets go of its file and locks then. Using it, or them, after that panics, but for Close, which does nothing then.
Public Property IsClosed: Bool property #

Whether Close has closed it.
@PanicsAtCaller Public Property Changes: Int64 property #

How many rows the last INSERT, UPDATE, or DELETE changed.
@PanicsAtCaller Public Property LastId: Int64 property #

The rowid of the last row an INSERT added, or 0 before one has.
@PanicsAtCaller Public Method Execute(sql: String) Throws DatabaseError method #

Runs each statement in sql, in turn, and throws what the first that fails fails with, leaving what the ones before it did, but for what a Transaction undoes. Panics when one takes parameters, which Execute(sql, values) binds.
@PanicsAtCaller Public Method Execute<A: SqlValue>(sql: String, a: A) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to values, in order, a value for each, as a Statement's Execute does. Throws a DatabaseError of QUERY when sql isn't one statement.
@PanicsAtCaller Public Method Execute<A, B>(sql: String, a: A, b: B) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through b, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C>(sql: String, a: A, b: B, c: C) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through c, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C, D>(sql: String, a: A, b: B, c: C, d: D) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through d, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C, D, E>(sql: String, a: A, b: B, c: C, d: D, e: E) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through e, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through f, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F, G>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through g, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F, G, H>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H) Throws DatabaseError method #

Runs sql's one statement with its parameters bound to a through h, in order, as the one that takes a alone does.
@PanicsAtCaller Public Method Rows(sql: String): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to values as Execute's are, so Rows(sql) panics when it takes any.
@PanicsAtCaller Public Method Query<T>(sql: String): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads, each a T, as a Statement's Query<T>() gives them. Panics when sql takes parameters, which a Statement binds.
@PanicsAtCaller Public Method Query<T, A: SqlValue>(sql: String, a: A): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to values as Execute's are.
@PanicsAtCaller Public Method Query<T, A, B>(sql: String, a: A, b: B): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through b, in order.
@PanicsAtCaller Public Method Query<T, A, B, C>(sql: String, a: A, b: B, c: C): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through c, in order.
@PanicsAtCaller Public Method Query<T, A, B, C, D>(sql: String, a: A, b: B, c: C, d: D): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through d, in order.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E>(sql: String, a: A, b: B, c: C, d: D, e: E): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through e, in order.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through f, in order.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F, G>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through g, in order.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F, G, H>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): T[] Throws DatabaseError, ParseError method #

The rows sql's one query reads as Ts, with its parameters bound to a through h, in order.
@PanicsAtCaller Public Method Rows<A: SqlValue>(sql: String, a: A): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a, in order.
@PanicsAtCaller Public Method Rows<A, B>(sql: String, a: A, b: B): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through b, in order.
@PanicsAtCaller Public Method Rows<A, B, C>(sql: String, a: A, b: B, c: C): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through c, in order.
@PanicsAtCaller Public Method Rows<A, B, C, D>(sql: String, a: A, b: B, c: C, d: D): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through d, in order.
@PanicsAtCaller Public Method Rows<A, B, C, D, E>(sql: String, a: A, b: B, c: C, d: D, e: E): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through e, in order.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through f, in order.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F, G>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through g, in order.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F, G, H>(sql: String, a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): Row[] Throws DatabaseError method #

The rows sql's one query reads, with its parameters bound to a through h, in order.
@PanicsAtCaller Public Method Prepare(sql: String): Statement Throws DatabaseError method #

sql's one statement, prepared to run many times. Throws a DatabaseError of QUERY when sql holds no statement or more than one, or one that doesn't prepare, like one that names a table the database hasn't got.
@PanicsAtCaller Public Method Begin(): Transaction Throws DatabaseError method #

A new Transaction, which keeps all of what this Database does until its Commit, or undoes it: see Transaction. One begun while another is open is a part of that one. The outermost is SQLite's IMMEDIATE, which waits for other connections to finish writing when it begins.
@PanicsAtCaller Public Method Migrate(migrations: String...) Throws DatabaseError method #

Brings the database up to date with migrations, the SQL that makes each version of it from the one before: the first makes version 1 from an empty database, the second version 2, and so on. The database keeps its version, as PRAGMA user_version, so each migration runs once, in order, in a Transaction of its own with the version it makes, and one that fails leaves the database as the one before it left it, and throws. Throws a DatabaseError too when the database's version is past the last migration's, as a newer program's would be.

`Statement` class

Public Class Statement

A statement prepared once, to run many times, its parameters bound to new values each time: what Database.Prepare makes. Its parameters are ?, ?NNN, :name, @name, and $name, numbered from 1 in order, as SQLite numbers them, and keep the values they're bound to until they're bound again, or Clear sets them to NULL. Closing its Database finalizes it, and using it after that panics, but for Parameters.

std/db/database.fb, line 822

Public Property Parameters: Int property #

How many parameters it takes: the largest number one has.
@PanicsAtCaller Public Method Bind<A: SqlValue>(index: Int, value: A) Throws DatabaseError method #

Binds the parameter at index, from 1, to value. Panics when it has none there.
@PanicsAtCaller Public Method Bind<A: SqlValue>(name: String, value: A) Throws DatabaseError method #

Binds the parameter of name, like ":id", to value. Panics when it has none of that name.
@PanicsAtCaller Public Method Clear() method #

Sets each parameter to NULL.
@PanicsAtCaller Public Method Execute() Throws DatabaseError method #

Runs it, with its parameters as they're bound, and throws a DatabaseError when it fails.
@PanicsAtCaller Public Method Execute<A: SqlValue>(a: A) Throws DatabaseError method #

Binds its parameters to values, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B>(a: A, b: B) Throws DatabaseError method #

Binds its parameters to a through b, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C>(a: A, b: B, c: C) Throws DatabaseError method #

Binds its parameters to a through c, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C, D>(a: A, b: B, c: C, d: D) Throws DatabaseError method #

Binds its parameters to a through d, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E) Throws DatabaseError method #

Binds its parameters to a through e, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F) Throws DatabaseError method #

Binds its parameters to a through f, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G) Throws DatabaseError method #

Binds its parameters to a through g, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Execute<A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H) Throws DatabaseError method #

Binds its parameters to a through h, in order, then runs it. Panics when it takes another number of them.
@PanicsAtCaller Public Method Rows(): Row[] Throws DatabaseError method #

The rows it reads, with its parameters as they're bound.
@PanicsAtCaller Public Method Query<T>(): T[] Throws DatabaseError, ParseError method #

The rows it reads, with its parameters as they're bound, each a T that Load<T> makes of an Object of its columns by their names, each an integer, a Double, text, bytes, or Null, so a T's Fields of numbers, Bools as 0 or 1, Strings, UInt8[]s, Enums by their names, and T?s take them, and a Field no column has takes its default, or else its zero. Throws a ParseError for a row that doesn't make a T, whose Path starts with the row's index, as "[2].Age" does.
@PanicsAtCaller Public Method Query<T, A: SqlValue>(a: A): T[] Throws DatabaseError, ParseError method #

Binds its parameters to values, in order, as Execute does, then gives the rows it reads as Ts, as Query<T>() does.
@PanicsAtCaller Public Method Query<T, A, B>(a: A, b: B): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through b, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C>(a: A, b: B, c: C): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through c, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C, D>(a: A, b: B, c: C, d: D): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through d, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through e, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through f, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through g, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Query<T, A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): T[] Throws DatabaseError, ParseError method #

Binds its parameters to a through h, in order, then gives the rows it reads as Ts.
@PanicsAtCaller Public Method Rows<A: SqlValue>(a: A): Row[] Throws DatabaseError method #

Binds its parameters to values, in order, as Execute does, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B>(a: A, b: B): Row[] Throws DatabaseError method #

Binds its parameters to a through b, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C>(a: A, b: B, c: C): Row[] Throws DatabaseError method #

Binds its parameters to a through c, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C, D>(a: A, b: B, c: C, d: D): Row[] Throws DatabaseError method #

Binds its parameters to a through d, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): Row[] Throws DatabaseError method #

Binds its parameters to a through e, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): Row[] Throws DatabaseError method #

Binds its parameters to a through f, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): Row[] Throws DatabaseError method #

Binds its parameters to a through g, in order, then gives the rows it reads.
@PanicsAtCaller Public Method Rows<A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): Row[] Throws DatabaseError method #

Binds its parameters to a through h, in order, then gives the rows it reads.

`Transaction` class

Public Class Transaction

What Database.Begin gives. What the Database does from then on is kept when it commits, and undone when it rolls back, or when it's let go of without a Commit, as when an error leaves the code that holds it, so a transaction that fails leaves nothing. One begun while another was open is a part of that one: its Commit keeps what it did only as far as that one does, and that one's Rollback undoes it too.

std/db/database.fb, line 1328

Public Property IsOpen: Bool property #

Whether it's open: not committed or rolled back, by its own Methods, with the Transaction it's a part of, or by SQLite, as some errors do.
@PanicsAtCaller Public Method Commit() Throws DatabaseError method #

Keeps what it did. Throws a DatabaseError when SQLite can't, and it stays open, as when another connection is reading the database, or when it isn't open. Panics after its Commit or Rollback, or while a Transaction begun inside it is open.
@PanicsAtCaller Public Method Rollback() Throws DatabaseError method #

Undoes what it did, and what each Transaction begun inside it did, or nothing when it isn't open. Panics after its Commit or Rollback.

Extends

`Int8` extend

Extend Int8 Implements SqlValue

No doc comment.

std/db/database.fb, line 72

`Int16` extend

Extend Int16 Implements SqlValue

No doc comment.

std/db/database.fb, line 78

`Int32` extend

Extend Int32 Implements SqlValue

No doc comment.

std/db/database.fb, line 84

`Int64` extend

Extend Int64 Implements SqlValue

No doc comment.

std/db/database.fb, line 90

`UInt8` extend

Extend UInt8 Implements SqlValue

No doc comment.

std/db/database.fb, line 96

`UInt16` extend

Extend UInt16 Implements SqlValue

No doc comment.

std/db/database.fb, line 102

`UInt32` extend

Extend UInt32 Implements SqlValue

No doc comment.

std/db/database.fb, line 108

`UInt64` extend

Extend UInt64 Implements SqlValue

No doc comment.

std/db/database.fb, line 115

`Bool` extend

Extend Bool Implements SqlValue

No doc comment.

std/db/database.fb, line 126

`Float32` extend

Extend Float32 Implements SqlValue

No doc comment.

std/db/database.fb, line 133

`Float64` extend

Extend Float64 Implements SqlValue

No doc comment.

std/db/database.fb, line 139

`String` extend

Extend String Implements SqlValue

No doc comment.

std/db/database.fb, line 150

`UInt8[]` extend

Extend UInt8[] Implements SqlValue

No doc comment.

std/db/database.fb, line 156

Report an issue with this page or with FutureBlitz on GitHub.

std.db.database

Types

ColumnType enum

SqlValue interface

Nullable struct

Row struct

Database class

Statement class

Transaction class

Extends

Int8 extend

Int16 extend

Int32 extend

Int64 extend

UInt8 extend

UInt16 extend

UInt32 extend

UInt64 extend

Bool extend

Float32 extend

Float64 extend

String extend

UInt8[] extend

`ColumnType` enum

`SqlValue` interface

`Nullable` struct

`Row` struct

`Database` class

`Statement` class

`Transaction` class

`Int8` extend

`Int16` extend

`Int32` extend

`Int64` extend

`UInt8` extend

`UInt16` extend

`UInt32` extend

`UInt64` extend

`Bool` extend

`Float32` extend

`Float64` extend

`String` extend

`UInt8[]` extend