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.
import { DatabaseSync } from "node:sqlite"; const db = new DatabaseSync(":memory:"); db.exec("CREATE TABLE t (x)"); db.close();
Try it
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.
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
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
nullprototype, soconsole.logprints[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
usingdeclaration (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
DatabaseSyncobjects can open the same file. Writers take a lock, so givetimeouta value such as5000if two connections write at the same time.