The node:sqlite module facilitates working with SQLite databases.\nTo access it:

import sqlite from 'node:sqlite';\n

const sqlite = require('node:sqlite');\n

This module is only available under the node: scheme.

The following example shows the basic usage of the node:sqlite module to open\nan in-memory database, write data to the database, and then read the data back.

import { DatabaseSync } from 'node:sqlite';\nconst database = new DatabaseSync(':memory:');\n\n// Execute SQL statements from strings.\ndatabase.exec(`\n  CREATE TABLE data(\n    key INTEGER PRIMARY KEY,\n    value TEXT\n  ) STRICT\n`);\n// Create a prepared statement to insert data into the database.\nconst insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');\n// Execute the prepared statement with bound values.\ninsert.run(1, 'hello');\ninsert.run(2, 'world');\n// Create a prepared statement to read data from the database.\nconst query = database.prepare('SELECT * FROM data ORDER BY key');\n// Execute the prepared statement and log the result set.\nconsole.log(query.all());\n// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]\n

'use strict';\nconst { DatabaseSync } = require('node:sqlite');\nconst database = new DatabaseSync(':memory:');\n\n// Execute SQL statements from strings.\ndatabase.exec(`\n  CREATE TABLE data(\n    key INTEGER PRIMARY KEY,\n    value TEXT\n  ) STRICT\n`);\n// Create a prepared statement to insert data into the database.\nconst insert = database.prepare('INSERT INTO data (key, value) VALUES (?, ?)');\n// Execute the prepared statement with bound values.\ninsert.run(1, 'hello');\ninsert.run(2, 'world');\n// Create a prepared statement to read data from the database.\nconst query = database.prepare('SELECT * FROM data ORDER BY key');\n// Execute the prepared statement and log the result set.\nconsole.log(query.all());\n// Prints: [ { key: 1, value: 'hello' }, { key: 2, value: 'world' } ]\n

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

Constructs a new DatabaseSync instance.

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

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

const { DatabaseSync } = require('node:sqlite');\n\nconst db = new DatabaseSync(':memory:');\ndb.exec(`\n  CREATE TABLE t3(x, y);\n  INSERT INTO t3 VALUES ('a', 4),\n                        ('b', 5),\n                        ('c', 3),\n                        ('d', 8),\n                        ('e', 1);\n`);\n\ndb.aggregate('sumint', {\n  start: 0,\n  step: (acc, value) => acc + value,\n});\n\ndb.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }\n

import { DatabaseSync } from 'node:sqlite';\n\nconst db = new DatabaseSync(':memory:');\ndb.exec(`\n  CREATE TABLE t3(x, y);\n  INSERT INTO t3 VALUES ('a', 4),\n                        ('b', 5),\n                        ('c', 3),\n                        ('d', 8),\n                        ('e', 1);\n`);\n\ndb.aggregate('sumint', {\n  start: 0,\n  step: (acc, value) => acc + value,\n});\n\ndb.prepare('SELECT sumint(y) as total FROM t3').get(); // { total: 21 }\n

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

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

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

Enables or disables the defensive flag. When the defensive flag is active,\nlanguage features that allow ordinary SQL to deliberately corrupt the database file are disabled.\nSee SQLITE_DBCONFIG_DEFENSIVE in the SQLite documentation for details.

This method is a wrapper around sqlite3_db_filename()

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

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

Sets an authorizer callback that SQLite will invoke whenever it attempts to\naccess data or modify the database schema through prepared statements.\nThis can be used to implement security policies, audit access, or restrict certain operations.\nThis method is a wrapper around sqlite3_set_authorizer().

When invoked, the callback receives five arguments:

\n
• actionCode <number> The type of operation being performed (e.g., SQLITE_INSERT, SQLITE_UPDATE, SQLITE_SELECT).
\n
• arg1 <string> | <null> The first argument (context-dependent, often a table name).
\n
• arg2 <string> | <null> The second argument (context-dependent, often a column name).
\n
• dbName <string> | <null> The name of the database.
\n
• triggerOrView <string> | <null> The name of the trigger or view causing the access.
\n

The callback must return one of the following constants:

\n
• SQLITE_OK - Allow the operation.
\n
• SQLITE_DENY - Deny the operation (causes an error).
\n
• SQLITE_IGNORE - Ignore the operation (silently skip).
\n

const { DatabaseSync, constants } = require('node:sqlite');\nconst db = new DatabaseSync(':memory:');\n\n// Set up an authorizer that denies all table creation\ndb.setAuthorizer((actionCode) => {\n  if (actionCode === constants.SQLITE_CREATE_TABLE) {\n    return constants.SQLITE_DENY;\n  }\n  return constants.SQLITE_OK;\n});\n\n// This will work\ndb.prepare('SELECT 1').get();\n\n// This will throw an error due to authorization denial\ntry {\n  db.exec('CREATE TABLE blocked (id INTEGER)');\n} catch (err) {\n  console.log('Operation blocked:', err.message);\n}\n

import { DatabaseSync, constants } from 'node:sqlite';\nconst db = new DatabaseSync(':memory:');\n\n// Set up an authorizer that denies all table creation\ndb.setAuthorizer((actionCode) => {\n  if (actionCode === constants.SQLITE_CREATE_TABLE) {\n    return constants.SQLITE_DENY;\n  }\n  return constants.SQLITE_OK;\n});\n\n// This will work\ndb.prepare('SELECT 1').get();\n\n// This will throw an error due to authorization denial\ntry {\n  db.exec('CREATE TABLE blocked (id INTEGER)');\n} catch (err) {\n  console.log('Operation blocked:', err.message);\n}\n

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

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

Creates a new SQLTagStore, which is a Least Recently Used (LRU) cache\nfor storing prepared statements. This allows for the efficient reuse of\nprepared statements by tagging them with a unique identifier.

When a tagged SQL literal is executed, the SQLTagStore checks if a prepared\nstatement for the corresponding SQL query string already exists in the cache.\nIf it does, the cached statement is used. If not, a new prepared statement is\ncreated, executed, and then stored in the cache for future use. This mechanism\nhelps to avoid the overhead of repeatedly parsing and preparing the same SQL\nstatements.

Tagged statements bind the placeholder values from the template literal as\nparameters to the underlying prepared statement. For example:

sqlTagStore.get`SELECT ${value}`;\n

is equivalent to:

db.prepare('SELECT ?').get(value);\n

However, in the first example, the tag store will cache the underlying prepared\nstatement for future use.

\n

Note: The ${value} syntax in tagged statements binds a parameter to\nthe prepared statement. This differs from its behavior in untagged template\nliterals, where it performs string interpolation.

\n

// This a safe example of binding a parameter to a tagged statement.\nsqlTagStore.run`INSERT INTO t1 (id) VALUES (${id})`;\n\n// This is an *unsafe* example of an untagged template string.\n// `id` is interpolated into the query text as a string.\n// This can lead to SQL injection and data corruption.\ndb.run(`INSERT INTO t1 (id) VALUES (${id})`);\n

\n

The tag store will match a statement from the cache if the query strings\n(including the positions of any bound placeholders) are identical.

// The following statements will match in the cache:\nsqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;\nsqlTagStore.get`SELECT * FROM t1 WHERE id = ${12345} AND active = 1`;\n\n// The following statements will not match, as the query strings\n// and bound placeholders differ:\nsqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;\nsqlTagStore.get`SELECT * FROM t1 WHERE id = 12345 AND active = 1`;\n\n// The following statements will not match, as matches are case-sensitive:\nsqlTagStore.get`SELECT * FROM t1 WHERE id = ${id} AND active = 1`;\nsqlTagStore.get`select * from t1 where id = ${id} and active = 1`;\n

The only way of binding parameters in tagged statements is with the ${value}\nsyntax. Do not add parameter binding placeholders (? etc.) to the SQL query\nstring itself.

import { DatabaseSync } from 'node:sqlite';\n\nconst db = new DatabaseSync(':memory:');\nconst sql = db.createTagStore();\n\ndb.exec('CREATE TABLE users (id INT, name TEXT)');\n\n// Using the 'run' method to insert data.\n// The tagged literal is used to identify the prepared statement.\nsql.run`INSERT INTO users VALUES (1, 'Alice')`;\nsql.run`INSERT INTO users VALUES (2, 'Bob')`;\n\n// Using the 'get' method to retrieve a single row.\nconst name = 'Alice';\nconst user = sql.get`SELECT * FROM users WHERE name = ${name}`;\nconsole.log(user); // { id: 1, name: 'Alice' }\n\n// Using the 'all' method to retrieve all rows.\nconst allUsers = sql.all`SELECT * FROM users ORDER BY id`;\nconsole.log(allUsers);\n// [\n//   { id: 1, name: 'Alice' },\n//   { id: 2, name: 'Bob' }\n// ]\n

const { DatabaseSync } = require('node:sqlite');\n\nconst db = new DatabaseSync(':memory:');\nconst sql = db.createTagStore();\n\ndb.exec('CREATE TABLE users (id INT, name TEXT)');\n\n// Using the 'run' method to insert data.\n// The tagged literal is used to identify the prepared statement.\nsql.run`INSERT INTO users VALUES (1, 'Alice')`;\nsql.run`INSERT INTO users VALUES (2, 'Bob')`;\n\n// Using the 'get' method to retrieve a single row.\nconst name = 'Alice';\nconst user = sql.get`SELECT * FROM users WHERE name = ${name}`;\nconsole.log(user); // { id: 1, name: 'Alice' }\n\n// Using the 'all' method to retrieve all rows.\nconst allUsers = sql.all`SELECT * FROM users ORDER BY id`;\nconsole.log(allUsers);\n// [\n//   { id: 1, name: 'Alice' },\n//   { id: 2, name: 'Bob' }\n// ]\n

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

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

import { DatabaseSync } from 'node:sqlite';\n\nconst sourceDb = new DatabaseSync(':memory:');\nconst targetDb = new DatabaseSync(':memory:');\n\nsourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');\ntargetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');\n\nconst session = sourceDb.createSession();\n\nconst insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');\ninsert.run(1, 'hello');\ninsert.run(2, 'world');\n\nconst changeset = session.changeset();\ntargetDb.applyChangeset(changeset);\n// Now that the changeset has been applied, targetDb contains the same data as sourceDb.\n

const { DatabaseSync } = require('node:sqlite');\n\nconst sourceDb = new DatabaseSync(':memory:');\nconst targetDb = new DatabaseSync(':memory:');\n\nsourceDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');\ntargetDb.exec('CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)');\n\nconst session = sourceDb.createSession();\n\nconst insert = sourceDb.prepare('INSERT INTO data (key, value) VALUES (?, ?)');\ninsert.run(1, 'hello');\ninsert.run(2, 'world');\n\nconst changeset = session.changeset();\ntargetDb.applyChangeset(changeset);\n// Now that the changeset has been applied, targetDb contains the same data as sourceDb.\n

Closes the database connection. If the database connection is already closed\nthen this is a no-op.

An object for getting and setting SQLite database limits at runtime.\nEach property corresponds to an SQLite limit and can be read or written.

const db = new DatabaseSync(':memory:');\n\n// Read current limit\nconsole.log(db.limits.length);\n\n// Set a new limit\ndb.limits.sqlLength = 100000;\n\n// Reset a limit to its compile-time maximum\ndb.limits.sqlLength = Infinity;\n

Available properties: length, sqlLength, column, exprDepth,\ncompoundSelect, vdbeOp, functionArg, attach, likePatternLength,\nvariableNumber, triggerDepth.

Setting a property to Infinity resets the limit to its compile-time maximum value.

Retrieves a changeset containing all changes since the changeset was created. Can be called multiple times.\nAn exception is thrown if the database or the session is not open. This method is a wrapper around sqlite3session_changeset().

Similar to the method above, but generates a more compact patchset. See Changesets and Patchsets\nin the documentation of SQLite. An exception is thrown if the database or the session is not open. This method is a\nwrapper around sqlite3session_patchset().

Closes the session. An exception is thrown if the database or the session is not open. This method is a\nwrapper around sqlite3session_delete().

Closes the session. If the session is already closed, does nothing.

This class represents a single prepared statement. This class cannot be\ninstantiated via its constructor. Instead, instances are created via the\ndatabase.prepare() method. All APIs exposed by this class execute\nsynchronously.

A prepared statement is an efficient binary representation of the SQL used to\ncreate it. Prepared statements are parameterizable, and can be invoked multiple\ntimes with different bound values. Parameters also offer protection against\nSQL injection attacks. For these reasons, prepared statements are preferred\nover hand-crafted SQL strings when handling user input.

This method executes a prepared statement and returns all results as an array of\nobjects. If the prepared statement does not return any results, this method\nreturns an empty array. The prepared statement parameters are bound using\nthe values in namedParameters and anonymousParameters.

This method is used to retrieve information about the columns returned by the\nprepared statement.

This method executes a prepared statement and returns the first result as an\nobject. If the prepared statement does not return any results, this method\nreturns undefined. The prepared statement parameters are bound using the\nvalues in namedParameters and anonymousParameters.

This method executes a prepared statement and returns an iterator of\nobjects. If the prepared statement does not return any results, this method\nreturns an empty iterator. The prepared statement parameters are bound using\nthe values in namedParameters and anonymousParameters.

This method executes a prepared statement and returns an object summarizing the\nresulting changes. The prepared statement parameters are bound using the\nvalues in namedParameters and anonymousParameters.

The names of SQLite parameters begin with a prefix character. By default,\nnode:sqlite requires that this prefix character is present when binding\nparameters. However, with the exception of dollar sign character, these\nprefix characters also require extra quoting when used in object keys.

To improve ergonomics, this method can be used to also allow bare named\nparameters, which do not require the prefix character in JavaScript code. There\nare several caveats to be aware of when enabling bare named parameters:

\n
• The prefix character is still required in SQL.
\n
• The prefix character is still allowed in JavaScript. In fact, prefixed names\nwill have slightly better binding performance.
\n
• Using ambiguous named parameters, such as $k and @k, in the same prepared\nstatement will result in an exception as it cannot be determined how to bind\na bare name.
\n

By default, if an unknown name is encountered while binding parameters, an\nexception is thrown. This method allows unknown named parameters to be ignored.

When enabled, query results returned by the all(), get(), and iterate() methods will be returned as arrays instead\nof objects.

When reading from the database, SQLite INTEGERs are mapped to JavaScript\nnumbers by default. However, SQLite INTEGERs can store values larger than\nJavaScript numbers are capable of representing. In such cases, this method can\nbe used to read INTEGER data using JavaScript BigInts. This method has no\nimpact on database write operations where numbers and BigInts are both\nsupported at all times.

The source SQL text of the prepared statement with parameter\nplaceholders replaced by the values that were used during the most recent\nexecution of this prepared statement. This property is a wrapper around\nsqlite3_expanded_sql().

The source SQL text of the prepared statement. This property is a\nwrapper around sqlite3_sql().

This class represents a single LRU (Least Recently Used) cache for storing\nprepared statements.

Instances of this class are created via the database.createTagStore()\nmethod, not by using a constructor. The store caches prepared statements based\non the provided SQL query string. When the same query is seen again, the store\nretrieves the cached statement and safely applies the new values through\nparameter binding, thereby preventing attacks like SQL injection.

The cache has a maxSize that defaults to 1000 statements, but a custom size can\nbe provided (e.g., database.createTagStore(100)). All APIs exposed by this\nclass execute synchronously.

Executes the given SQL query and returns all resulting rows as an array of\nobjects.

This function is intended to be used as a template literal tag, not to be\ncalled directly.

Executes the given SQL query and returns the first resulting row as an object.

This function is intended to be used as a template literal tag, not to be\ncalled directly.

Executes the given SQL query and returns an iterator over the resulting rows.

This function is intended to be used as a template literal tag, not to be\ncalled directly.

Executes the given SQL query, which is expected to not return any rows (e.g., INSERT, UPDATE, DELETE).

This function is intended to be used as a template literal tag, not to be\ncalled directly.

Resets the LRU cache, clearing all stored prepared statements.

A read-only property that returns the number of prepared statements currently in the cache.

A read-only property that returns the maximum number of prepared statements the cache can hold.

A read-only property that returns the DatabaseSync object associated with this SQLTagStore.

When Node.js writes to or reads from SQLite, it is necessary to convert between\nJavaScript data types and SQLite's data types. Because JavaScript supports\nmore data types than SQLite, only a subset of JavaScript types are supported.\nAttempting to write an unsupported data type to SQLite will result in an\nexception.

APIs that read values from SQLite have a configuration option that determines\nwhether INTEGER values are converted to number or bigint in JavaScript,\nsuch as the readBigInts option for statements and the useBigIntArguments\noption for user-defined functions. If Node.js reads an INTEGER value from\nSQLite that is outside the JavaScript safe integer range, and the option to\nread BigInts is not enabled, then an ERR_OUT_OF_RANGE error will be thrown.

This method makes a database backup. This method abstracts the sqlite3_backup_init(), sqlite3_backup_step()\nand sqlite3_backup_finish() functions.

The backed-up database can be used normally during the backup process. Mutations coming from the same connection - same\n<DatabaseSync> - object will be reflected in the backup right away. However, mutations from other connections will cause\nthe backup process to restart.

const { backup, DatabaseSync } = require('node:sqlite');\n\n(async () => {\n  const sourceDb = new DatabaseSync('source.db');\n  const totalPagesTransferred = await backup(sourceDb, 'backup.db', {\n    rate: 1, // Copy one page at a time.\n    progress: ({ totalPages, remainingPages }) => {\n      console.log('Backup in progress', { totalPages, remainingPages });\n    },\n  });\n\n  console.log('Backup completed', totalPagesTransferred);\n})();\n

import { backup, DatabaseSync } from 'node:sqlite';\n\nconst sourceDb = new DatabaseSync('source.db');\nconst totalPagesTransferred = await backup(sourceDb, 'backup.db', {\n  rate: 1, // Copy one page at a time.\n  progress: ({ totalPages, remainingPages }) => {\n    console.log('Backup in progress', { totalPages, remainingPages });\n  },\n});\n\nconsole.log('Backup completed', totalPagesTransferred);\n

An object containing commonly used constants for SQLite operations.

The following constants are exported by the sqlite.constants object.

One of the following constants is available as an argument to the onConflict\nconflict resolution handler passed to database.applyChangeset(). See also\nConstants Passed To The Conflict Handler in the SQLite documentation.

One of the following constants must be returned from the onConflict conflict\nresolution handler passed to database.applyChangeset(). See also\nConstants Returned From The Conflict Handler in the SQLite documentation.

The following constants are used with the database.setAuthorizer() method.

One of the following constants must be returned from the authorizer callback\nfunction passed to database.setAuthorizer().

The following constants are passed as the first argument to the authorizer\ncallback function to indicate what type of operation is being authorized.