Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท node:sqlite and Runtime Services

Node.js DatabaseSync class

Reference for DatabaseSync from node:sqlite: opening in-memory and file databases, constructor options, isOpen and isTransaction, close(), location() and methods.

DatabaseSync is the class that represents one SQLite database connection in the built-in node:sqlite module. You create it with a path (or ":memory:"), run SQL through it, and close it when you are done. The word Sync is literal: every call blocks the event loop until SQLite has finished, and nothing returns a promise.

A database lives in a file, or in memory for the lifetime of the object. Opening a path that does not exist creates the file. node:sqlite is still marked experimental in Node.js 24, so the first import can print an ExperimentalWarning on the error stream.

NODE
import { DatabaseSync } from "node:sqlite";

const db = new DatabaseSync(":memory:");
db.exec("CREATE TABLE t (x)");
db.close();

Try it

Node.js Open, check state and close

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Constructor options

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
new DatabaseSync(path[, options])
Parameter Description
path A string, a Buffer or Uint8Array, or a file: URL. Use ":memory:" for a private in-memory database.
options.open Open immediately (default true). With false you call db.open() yourself.
options.readOnly Open the file for reading only (default false). The file must already exist.
options.timeout Busy timeout in milliseconds: how long SQLite waits for a lock before failing (default 0).
options.enableForeignKeyConstraints Enforce foreign keys (default true).
options.enableDoubleQuotedStringLiterals Accept "text" as a string when no such column exists (default false).
options.allowExtension Allow loading SQLite extensions (default false).
options.readBigInts Return every integer as a bigint for all statements (default false).
options.returnArrays Return rows as arrays instead of objects (default false).
options.allowBareNamedParameters Let { name: 1 } bind :name without the prefix (default true).
options.allowUnknownNamedParameters Ignore object keys that match no parameter (default false).

Properties. db.isOpen is true while the connection is open. db.isTransaction is true between BEGIN and COMMIT or ROLLBACK.

Methods.

Method Purpose
open() Opens a database created with open: false.
close() Closes the connection.
exec(sql) Runs SQL text and returns undefined. See database.exec().
prepare(sql) Compiles a statement. See database.prepare().
function(name[, options], fn) Registers a scalar SQL function.
aggregate(name, options) Registers an aggregate function.
location([dbName]) The file path of the database, or null for an in-memory one.
createSession(), applyChangeset() Record and apply row changes.
serialize(), deserialize() Export or import the whole database as bytes (Uint8Array).
loadExtension(), enableLoadExtension() Load SQLite extensions when allowExtension is set.

Errors. A path that cannot be opened throws an Error with code: "ERR_SQLITE_ERROR" and the message "unable to open database file". Calling any method on a closed database throws ERR_INVALID_STATE ("database is not open"), and so does closing twice. Passing a non-string path throws ERR_INVALID_ARG_TYPE.

Usage notes

  • Rows are objects with a null prototype, so console.log prints [Object: null prototype] in front of them. Property access works as usual.
  • Create a statement once and reuse it. Preparing the same SQL for every call wastes time.
  • new DatabaseSync() is synchronous, so it blocks the thread for as long as opening takes. For many parallel clients, give each worker thread its own connection.
  • Close databases you open. A process that exits closes them anyway, but a long-running server that forgets leaks file handles. The using declaration (using db = new DatabaseSync(...)) closes the database at the end of the block.
  • The option defaults here differ from plain SQLite: foreign keys are enforced from the start, and double-quoted strings are rejected, which catches many typos early.
  • The module is experimental in Node.js 24 and arrived in Node.js 22.5. It needs no flag in current releases, but details such as option names may still change.
  • Several DatabaseSync objects can open the same file. Writers take a lock, so give timeout a value such as 5000 if two connections write at the same time.