BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Coconstructor
Bun

constructor

sqlite.DatabaseSync.constructor

Not implemented in Bun

constructor DatabaseSync(
path: string | Buffer<ArrayBufferLike> | URL,
options?: DatabaseSyncOptions

Constructs a new DatabaseSync instance.

@param path

The path of the database. A SQLite database can be stored in a file or completely in memory. To use a file-backed database, the path should be a file path. To use an in-memory database, the path should be the special name ':memory:'.

@param options

Configuration options for the database connection.

Referenced types

class URL

The URL interface represents an object providing static methods used for creating object URLs.

MDN Reference

interface DatabaseSyncOptions

  • allowExtension?: boolean

    If true, the loadExtension SQL function and the loadExtension() method are enabled. You can call enableLoadExtension(false) later to disable this feature.

  • enableDoubleQuotedStringLiterals?: boolean

    If true, SQLite will accept double-quoted string literals. This is not recommended but can be enabled for compatibility with legacy database schemas.

  • enableForeignKeyConstraints?: boolean

    If true, foreign key constraints are enabled. This is recommended but can be disabled for compatibility with legacy database schemas. The enforcement of foreign key constraints can be enabled and disabled after opening the database using PRAGMA foreign_keys.

  • open?: boolean

    If true, the database is opened by the constructor. When this value is false, the database must be opened via the open() method.

  • readOnly?: boolean

    If true, the database is opened in read-only mode. If the database does not exist, opening it will fail.

  • timeout?: number

    The busy timeout in milliseconds. This is the maximum amount of time that SQLite will wait for a database lock to be released before returning an error.

class DatabaseSync

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

  • readonly isOpen: boolean

    Whether the database is currently open or not.

  • readonly isTransaction: boolean

  • Closes the database connection. If the database connection is already closed then this is a no-op.

  • name: string,
    options: AggregateOptions
    ): void;

    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 }
    @param name

    The name of the SQLite function to create.

    @param options

    Function configuration settings.

    name: string,
    options: AggregateOptions<T>
    ): void;

    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 }
    @param name

    The name of the SQLite function to create.

    @param options

    Function configuration settings.

  • changeset: Uint8Array,
    options?: ApplyChangesetOptions
    ): boolean;

    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.
    @param changeset

    A binary changeset or patchset.

    @param options

    The configuration options for how the changes will be applied.

    @returns

    Whether the changeset was applied successfully without being aborted.

  • close(): void;

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

  • options?: CreateSessionOptions
    @param options

    The configuration options for the session.

    @returns

    A session handle.

  • allow: boolean
    ): void;

    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.

    @param allow

    Whether to allow loading extensions.

  • sql: string
    ): void;

    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().

    @param sql

    A SQL string to execute.

  • name: string,
    options: FunctionOptions,
    func: (...args: SQLOutputValue[]) => SQLInputValue
    ): void;
    @param name

    The name of the SQLite function to create.

    @param options

    Optional configuration settings for the function.

    @param 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.

    name: string,
    func: (...args: SQLOutputValue[]) => SQLInputValue
    ): void;
    @param name

    The name of the SQLite function to create.

    @param 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.

  • path: string
    ): void;

    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.

    @param path

    The path to the shared library to load.

  • dbName?: string
    ): null | string;
    @param 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.

  • open(): void;

    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.

  • sql: string
    @param sql

    A SQL string to compile to a prepared statement.

    @returns

    The prepared statement.