Interface DatabaseSyncInstance

Represents a SQLite database connection. This interface represents an instance of the DatabaseSync class.

interface DatabaseSyncInstance {
    isOpen: boolean;
    isTransaction: boolean;
    "[dispose]"(): void;
    aggregate(name: string, options: AggregateOptions): void;
    applyChangeset(changeset: Buffer, options?: ChangesetApplyOptions): boolean;
    backup(
        path: string | Buffer<ArrayBufferLike> | URL,
        options?: {
            progress?: (
                info: { remainingPages: number; totalPages: number },
            ) => void;
            rate?: number;
            source?: string;
            target?: string;
        },
    ): Promise<number>;
    close(): void;
    createSession(options?: SessionOptions): Session;
    createTagStore(capacity?: number): SQLTagStoreInstance;
    enableDefensive(active: boolean): void;
    enableLoadExtension(enable: boolean): void;
    exec(sql: string): void;
    function(name: string, func: Function): void;
    function(name: string, options: UserFunctionOptions, func: Function): void;
    loadExtension(path: string, entryPoint?: string): void;
    location(dbName?: string): string | null;
    open(): void;
    prepare(sql: string, options?: StatementOptions): StatementSyncInstance;
    setAuthorizer(
        callback:
            | (
                (
                    actionCode: number,
                    param1: string | null,
                    param2: string | null,
                    param3: string | null,
                    param4: string | null,
                ) => number
            )
            | null,
    ): void;
}

Index

Properties

isOpen isTransaction

Methods

[dispose] aggregate applyChangeset backup close createSession createTagStore enableDefensive enableLoadExtension exec function loadExtension location open prepare setAuthorizer

Properties

`Readonly`isOpen

isOpen: boolean

Indicates whether the database connection is open.

`Readonly`isTransaction

isTransaction: boolean

Indicates whether a transaction is currently active.

Methods

[dispose]

"[dispose]"(): void
Dispose of the database resources using the explicit resource management protocol.

Returns void
- Defined in types/database-sync-instance.ts:202

aggregate

aggregate(name: string, options: AggregateOptions): void
This method creates SQLite aggregate functions, wrapping sqlite3_create_window_function().
Parameters
- name: string
  The name of the SQLite aggregate function to create.
- options: AggregateOptions
  Configuration object containing step function and other settings.
Returns void
- Defined in types/database-sync-instance.ts:72

applyChangeset

applyChangeset(changeset: Buffer, options?: ChangesetApplyOptions): boolean
Apply a changeset to the database.
Parameters
- changeset: Buffer
  The changeset data to apply.
- Optionaloptions: ChangesetApplyOptions
  Optional configuration for applying the changeset.
Returns boolean
true if successful, false if aborted.
- Defined in types/database-sync-instance.ts:97

backup

backup(
    path: string | Buffer<ArrayBufferLike> | URL,
    options?: {
        progress?: (
            info: { remainingPages: number; totalPages: number },
        ) => void;
        rate?: number;
        source?: string;
        target?: string;
    },
): Promise<number>
Makes a backup of the database. This method abstracts the sqlite3_backup_init(), sqlite3_backup_step() and sqlite3_backup_finish() functions.

The backed-up database can be used normally during the backup process. Mutations coming from the same connection will be reflected in the backup right away. However, mutations from other connections will cause the backup process to restart.
Parameters
- path: string | Buffer<ArrayBufferLike> | URL
  The path where the backup will be created. If the file already exists, the contents will be overwritten.
- Optionaloptions: {
      progress?: (
          info: { remainingPages: number; totalPages: number },
      ) => void;
      rate?: number;
      source?: string;
      target?: string;
  }
  Optional configuration for the backup operation.
  - Optionalprogress?: (info: { remainingPages: number; totalPages: number }) => void
    Callback function that will be called with the number of pages copied and the total number of pages.
  - Optionalrate?: number
    Number of pages to be transmitted in each batch of the backup.
  - Optionalsource?: string
    Name of the source database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE.
  - Optionaltarget?: string
    Name of the target database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE.
Returns Promise<number>
A promise that resolves when the backup is completed and rejects if an error occurs.
Default
```
100
```
Default
```
'main'
```
Default
```
'main'
```
Example
```
// Basic backup
await db.backup('./backup.db');
```
Example
```
// Backup with progress
await db.backup('./backup.db', {
  rate: 10,
  progress: ({ totalPages, remainingPages }) => {
    console.log(`Progress: ${totalPages - remainingPages}/${totalPages}`);
  }
});
```
- Defined in types/database-sync-instance.ts:191

close

close(): void
Closes the database connection. This method should be called to ensure that the database connection is properly cleaned up. Once a database is closed, it cannot be used again.

Returns void
- Defined in types/database-sync-instance.ts:30

createSession

createSession(options?: SessionOptions): Session
Create a new session to record database changes.
Parameters
- Optionaloptions: SessionOptions
  Optional configuration for the session.
Returns Session
A Session object for recording changes.
- Defined in types/database-sync-instance.ts:78

createTagStore

createTagStore(capacity?: number): SQLTagStoreInstance
Create a new SQLTagStore for cached prepared statements via tagged template syntax.
Parameters
- Optionalcapacity: number
  Optional maximum number of statements to cache.
Returns SQLTagStoreInstance
A SQLTagStore instance.
Default
```
1000
```
Example
```
const sql = db.createTagStore();
sql.run`INSERT INTO users VALUES (${id}, ${name})`;
const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
```
- Defined in types/database-sync-instance.ts:90

enableDefensive

enableDefensive(active: boolean): void
Enables or disables the defensive flag. When the defensive flag is active, language features that allow ordinary SQL to deliberately corrupt the database file are disabled.
Parameters
- active: boolean
  Whether to enable or disable the defensive flag.
Returns void
See
https://sqlite.org/c3ref/c_dbconfig_defensive.html
- Defined in types/database-sync-instance.ts:116

enableLoadExtension

enableLoadExtension(enable: boolean): void
Enables or disables the loading of SQLite extensions.
Parameters
- enable: boolean
  If true, enables extension loading. If false, disables it.
Returns void
- Defined in types/database-sync-instance.ts:102

exec

exec(sql: string): void
This method allows one or more SQL statements to be executed without returning any results. This is useful for commands like CREATE TABLE, INSERT, UPDATE, or DELETE.
Parameters
- sql: string
  The SQL statement(s) to execute.
Returns void
- Defined in types/database-sync-instance.ts:51

function

function(name: string, func: Function): void
This method creates SQLite user-defined functions, wrapping sqlite3_create_function_v2().
Parameters
- name: string
  The name of the SQLite function to create.
- func: Function
  The JavaScript function to call when the SQLite function is invoked.
Returns void
- Defined in types/database-sync-instance.ts:58
function(name: string, options: UserFunctionOptions, func: Function): void
This method creates SQLite user-defined functions, wrapping sqlite3_create_function_v2().
Parameters
- name: string
  The name of the SQLite function to create.
- options: UserFunctionOptions
  Optional configuration settings.
- func: Function
  The JavaScript function to call when the SQLite function is invoked.
Returns void
- Defined in types/database-sync-instance.ts:65

loadExtension

loadExtension(path: string, entryPoint?: string): void
Loads an SQLite extension from the specified file path.
Parameters
- path: string
  The path to the extension library.
- OptionalentryPoint: string
  Optional entry point function name. If not provided, uses the default entry point.
Returns void
- Defined in types/database-sync-instance.ts:108

location

location(dbName?: string): string | null
Returns the location of the database file. For attached databases, you can specify the database name. Returns null for in-memory databases.
Parameters
- OptionaldbName: string
  The name of the database. Defaults to 'main' (the primary database).
Returns string | null
The file path of the database, or null for in-memory databases.
- Defined in types/database-sync-instance.ts:37

open

open(): void
Opens a database connection. This method should only be used when the database was created with { open: false }. An exception is thrown if the database is already open.

Returns void
- Defined in types/database-sync-instance.ts:24

prepare

prepare(sql: string, options?: StatementOptions): StatementSyncInstance
Compiles an SQL statement and returns a StatementSyncInstance object.
Parameters
- sql: string
  The SQL statement to prepare.
- Optionaloptions: StatementOptions
  Optional configuration for the statement.
Returns StatementSyncInstance
A StatementSyncInstance object that can be executed multiple times.
- Defined in types/database-sync-instance.ts:44

setAuthorizer

setAuthorizer(
    callback:
        | (
            (
                actionCode: number,
                param1: string | null,
                param2: string | null,
                param3: string | null,
                param4: string | null,
            ) => number
        )
        | null,
): void
Sets an authorization callback that is invoked before each SQL operation. The authorizer can allow, deny, or ignore each operation.
Parameters
- callback:
      | (
          (
              actionCode: number,
              param1: string | null,
              param2: string | null,
              param3: string | null,
              param4: string | null,
          ) => number
      )
      | null
  The authorization callback function, or null to remove the authorizer.
  
  actionCode: The action being requested (e.g., SQLITE_SELECT, SQLITE_INSERT)
  
  param1: First parameter (varies by action, often table name)
  
  param2: Second parameter (varies by action, often column name)
  
  param3: Third parameter (usually database name like "main")
  
  param4: Fourth parameter (trigger or view name if applicable)
  
  The callback must return one of:
  
  constants.SQLITE_OK: Allow the operation
  
  constants.SQLITE_DENY: Deny the operation and abort the SQL statement
  
  constants.SQLITE_IGNORE: Silently ignore/skip the operation
Returns void
Example
```
// Block all DELETE operations
db.setAuthorizer((actionCode, table, column, dbName, trigger) => {
  if (actionCode === constants.SQLITE_DELETE) {
    return constants.SQLITE_DENY;
  }
  return constants.SQLITE_OK;
});

// Remove the authorizer
db.setAuthorizer(null);
```
See
https://sqlite.org/c3ref/set_authorizer.html
- Defined in types/database-sync-instance.ts:150

Interface DatabaseSyncInstance

Index

Properties

Methods

Properties

ReadonlyisOpen

ReadonlyisTransaction

Methods

[dispose]

Returns void

aggregate

Parameters

Returns void

applyChangeset

Parameters

Returns boolean

backup

Parameters

Optionalprogress?: (info: { remainingPages: number; totalPages: number }) => void

Optionalrate?: number

Optionalsource?: string

Optionaltarget?: string

Returns Promise<number>

Default

Default

Default

Example

Example

close

Returns void

createSession

Parameters

Returns Session

createTagStore

Parameters

Returns SQLTagStoreInstance

Default

Example

enableDefensive

Parameters

Returns void

See

enableLoadExtension

Parameters

Returns void

exec

Parameters

Returns void

function

Parameters

Returns void

Parameters

Returns void

loadExtension

Parameters

Returns void

location

Parameters

Returns string | null

open

Returns void

prepare

Parameters

Returns StatementSyncInstance

setAuthorizer

Parameters

Returns void

Example

See

Settings

On This Page

`Readonly`isOpen

`Readonly`isTransaction

`Optional`progress?: (info: { remainingPages: number; totalPages: number }) => void

`Optional`rate?: number

`Optional`source?: string

`Optional`target?: string