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;
    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): null | string;
    open(configuration?: DatabaseSyncOptions): void;
    prepare(sql: string, options?: StatementOptions): StatementSyncInstance;
}

Index

Properties

isOpen isTransaction

Methods

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

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 index.ts:344

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 index.ts:278

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 index.ts:291

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 index.ts:333

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 index.ts:236

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 index.ts:284

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 index.ts:296

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 index.ts:257

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 index.ts:264
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 index.ts:271

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 index.ts:302

location

location(dbName?: string): null | string
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 null | string
The file path of the database, or null for in-memory databases.
- Defined in index.ts:243

open

open(configuration?: DatabaseSyncOptions): void
Opens a database connection. This method is called automatically when creating a DatabaseSync instance, so typically should not be called directly.
Parameters
- Optionalconfiguration: DatabaseSyncOptions
  Optional configuration for opening the database.
Returns void
- Defined in index.ts:230

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 index.ts:250

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

enableLoadExtension

Parameters

Returns void

exec

Parameters

Returns void

function

Parameters

Returns void

Parameters

Returns void

loadExtension

Parameters

Returns void

location

Parameters

Returns null | string

open

Parameters

Returns void

prepare

Parameters

Returns StatementSyncInstance

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