DatabaseSync

[<Interface>]
type DatabaseSync =
    abstract member isOpen: bool
    abstract member isTransaction: bool
    abstract member ``function`` (name: string, func: SQLOutputValue array -> SQLInputValue) : unit
    abstract member ``function`` (name: string, options: FunctionOptions, func: SQLOutputValue array -> SQLInputValue) : unit
    abstract member ``open`` () : unit
    abstract member aggregate<'T> (name: string, options: AggregateOptions<'T>) : unit
    abstract member aggregate (name: string, options: AggregateOptions<SQLInputValue>) : unit
    abstract member applyChangeset (changeset: Uint8Array<U2<ArrayBuffer,SharedArrayBuffer>>, ?options: ApplyChangesetOptions) : bool
    abstract member close () : unit
    abstract member createSession (?options: CreateSessionOptions) : Session
    abstract member enableLoadExtension (allow: bool) : unit
    abstract member exec (sql: string) : unit
    abstract member loadExtension (path: string) : unit
    abstract member location (?dbName: string) : string option
    abstract member prepare (sql: string) : StatementSync


Assembly	`Xantham.Fable.Node`
Implements	`Disposable`

This class represents a single connection to a SQLite database. All APIs exposed by this class execute synchronously.

@since v22.5.0

Properties

abstract member isOpen: bool

Whether the database is currently open or not.

@since v22.15.0

abstract member isTransaction: bool

Whether the database is currently within a transaction. This method is a wrapper around sqlite3_get_autocommit().

@since v22.16.0

Methods

abstract member ``function`` (name: string, func: SQLOutputValue array -> SQLInputValue) : unit

This method is used to create SQLite user-defined functions. This method is a wrapper around sqlite3_create_function_v2().

@since v22.13.0

Parameter
`name`	The name of the SQLite function to create.
`options`	Optional configuration settings for the function.
`func`	The JavaScript function to call when the SQLite function is invoked. The return value of this function should be a valid SQLite data type: see Type conversion between JavaScript and SQLite. The result defaults to `NULL` if the return value is `undefined`.

abstract member ``function`` (name: string, options: FunctionOptions, func: SQLOutputValue array -> SQLInputValue) : unit

This method is used to create SQLite user-defined functions. This method is a wrapper around sqlite3_create_function_v2().

@since v22.13.0

Parameter
`name`	The name of the SQLite function to create.
`options`	Optional configuration settings for the function.
`func`	The JavaScript function to call when the SQLite function is invoked. The return value of this function should be a valid SQLite data type: see Type conversion between JavaScript and SQLite. The result defaults to `NULL` if the return value is `undefined`.

abstract member ``open`` () : unit

Opens the database specified in the path argument of the DatabaseSyncconstructor. This method should only be used when the database is not opened via the constructor. An exception is thrown if the database is already open.

@since v22.5.0

abstract member aggregate<'T> (name: string, options: AggregateOptions<'T>) : unit

Registers a new aggregate function with the SQLite database. This method is a wrapper around sqlite3_create_window_function().

When used as a window function, the result function will be called multiple times.

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec(`
CREATE TABLE t3(x, y);
INSERT INTO t3 VALUES ('a', 4),
('b', 5),
('c', 3),
('d', 8),
('e', 1);
`);

db.aggregate('sumint', {
start: 0,
step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }

@since v22.16.0

Parameter
`name`	The name of the SQLite function to create.
`options`	Function configuration settings.

abstract member aggregate (name: string, options: AggregateOptions<SQLInputValue>) : unit

Registers a new aggregate function with the SQLite database. This method is a wrapper around sqlite3_create_window_function().

When used as a window function, the result function will be called multiple times.

import { DatabaseSync } from 'node:sqlite';

const db = new DatabaseSync(':memory:');
db.exec(`
CREATE TABLE t3(x, y);
INSERT INTO t3 VALUES ('a', 4),
('b', 5),
('c', 3),
('d', 8),
('e', 1);
`);

db.aggregate('sumint', {
start: 0,
step: (acc, value) => acc + value,
});

db.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }

@since v22.16.0

Parameter
`name`	The name of the SQLite function to create.
`options`	Function configuration settings.

abstract member applyChangeset (changeset: Uint8Array<U2<ArrayBuffer,SharedArrayBuffer>>, ?options: ApplyChangesetOptions) : bool

An exception is thrown if the database is not open. This method is a wrapper around sqlite3changeset_apply().

const sourceDb = new DatabaseSync(':memory:');
const targetDb = new DatabaseSync(':memory:');

sourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');
targetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');

const session = sourceDb.createSession();

const insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');
insert.run(1, 'hello');
insert.run(2, 'world');

const changeset = session.changeset();
targetDb.applyChangeset(changeset);
// Now that the changeset has been applied, targetDb contains the same data as sourceDb.

@since v22.12.0

Parameter
`changeset`	A binary changeset or patchset.
`options`	The configuration options for how the changes will be applied.

Returns. Whether the changeset was applied successfully without being aborted.

abstract member close () : unit

Closes the database connection. An exception is thrown if the database is not open. This method is a wrapper around sqlite3_close_v2().

@since v22.5.0

abstract member createSession (?options: CreateSessionOptions) : Session

Creates and attaches a session to the database. This method is a wrapper around sqlite3session_create() and sqlite3session_attach().

@since v22.12.0

Parameter
`options`	The configuration options for the session.

Returns. A session handle.

abstract member enableLoadExtension (allow: bool) : unit

Enables or disables the loadExtension SQL function, and the loadExtension() method. When allowExtension is false when constructing, you cannot enable loading extensions for security reasons.

@since v22.13.0

Parameter
`allow`	Whether to allow loading extensions.

abstract member exec (sql: string) : unit

This method allows one or more SQL statements to be executed without returning any results. This method is useful when executing SQL statements read from a file. This method is a wrapper around sqlite3_exec().

@since v22.5.0

Parameter
`sql`	A SQL string to execute.

abstract member loadExtension (path: string) : unit

Loads a shared library into the database connection. This method is a wrapper around sqlite3_load_extension(). It is required to enable the allowExtension option when constructing the DatabaseSync instance.

@since v22.13.0

Parameter
`path`	The path to the shared library to load.

abstract member location (?dbName: string) : string option

This method is a wrapper around sqlite3_db_filename()

@since v22.16.0

Parameter
`dbName`	Name of the database. This can be `'main'` (the default primary database) or any other database that has been added with `ATTACH DATABASE`Default:`'main'`.

Returns. The location of the database file. When using an in-memory database, this method returns null.

abstract member prepare (sql: string) : StatementSync

Compiles a SQL statement into a prepared statement. This method is a wrapper around sqlite3_prepare_v2().

@since v22.5.0

Parameter
`sql`	A SQL string to compile to a prepared statement.

Returns. The prepared statement.