> ## Documentation Index > Fetch the complete documentation index at: https://powersync-sync-streams-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Node.js Client SDK > Use PowerSync in Node.js apps. This page describes the PowerSync *client* SDK for Node.js. If you're interested in using PowerSync for your Node.js backend, no special package is required. Instead, follow our guides on [app backend setup](/configuration/app-backend/setup). ```text Build with AI icon="sparkles" wrap theme={null} Install the PowerSync Agent Skills with: npx skills add powersync-ja/agent-skills. Then follow the skills to onboard this project to PowerSync using the Node.js client SDK. ``` This SDK is distributed via NPM Refer to `packages/node` in the `powersync-js` repo on GitHub Full API reference for the SDK Gallery of example projects/demo apps built with Node.js and PowerSync Changelog for the SDK ## SDK Features * **Real-time streaming of database changes**: Changes made by one user are instantly streamed to all other users with access to that data. This keeps clients automatically in sync without manual polling or refresh logic. * **Direct access to a local SQLite database**: Data is stored locally, so apps can read and write instantly without network calls. This enables offline support and faster user interactions. * **Asynchronous background execution**: The SDK performs database operations in the background to avoid blocking the application’s main thread. This means that apps stay responsive, even during heavy data activity. * **Query subscriptions for live updates**: The SDK supports query subscriptions that automatically push real-time updates to client applications as data changes, keeping your UI reactive and up to date. * **Automatic schema management**: PowerSync syncs schemaless data and applies a client-defined schema using SQLite views. This architecture means that PowerSync SDKs handle schema changes without explicit migrations on the client side. ## Quickstart Add the [PowerSync Node NPM package](https://www.npmjs.com/package/@powersync/node) to your project: ```bash theme={null} npm install @powersync/node ``` ```bash theme={null} yarn add @powersync/node ``` ```bash theme={null} pnpm install @powersync/node ``` **Install Peer Dependencies** The PowerSync SDK for Node.js supports multiple drivers. More details are available under [Encryption and Custom SQLite Drivers](/client-sdks/reference/node#encryption-and-custom-sqlite-drivers). We currently recommend the `better-sqlite3` package for most users: ```bash theme={null} npm install better-sqlite3 ``` ```bash theme={null} yarn add better-sqlite3 ``` ```bash theme={null} pnpm install better-sqlite3 ``` Previous versions of the PowerSync SDK for Node.js used the `@powersync/better-sqlite3` fork as a required peer dependency. This is no longer recommended. After upgrading to `@powersync/node` version `0.12.0` or later, ensure the old package is no longer installed by running `npm uninstall @powersync/better-sqlite3` **Common Installation Issues** The `better-sqlite3` package requires native compilation, which depends on certain system tools. Prebuilt assets are available and used by default, but a custom compilation may be started depending on the Node.js or Electron version used. This compilation process is handled by `node-gyp` and may fail if required dependencies are missing or misconfigured. Refer to the [PowerSync Node package README](https://www.npmjs.com/package/@powersync/node) for more details. **Prerequisites:** Before you start, connect your source database to the PowerSync Service and deploy Sync Streams. These are steps 1-4 in the [Setup Guide](/intro/setup-guide). ### 1. Define the Client-Side Schema The client-side schema defines the tables and columns of the SQLite database that the PowerSync client SDK manages and that your app reads from and writes to. It is usually derived from your backend database schema and your [Sync Streams](/sync/streams/overview), and it can also include [local-only tables](/client-sdks/advanced/local-only-usage). You apply the schema when you instantiate the database in the next step. Schema migrations are not required. The SDK syncs schemaless data and applies the schema to that data with SQLite views. The exception is [raw tables](/client-sdks/advanced/raw-tables), which you create and migrate yourself. You can use [this example](https://github.com/powersync-ja/powersync-js/blob/e5a57a539150f4bc174e109d3898b6e533de272f/demos/example-node/src/powersync.ts#L47-L77) as a reference when defining your schema. **Generate schema automatically** In the [PowerSync Dashboard](https://dashboard.powersync.com/), select your project and instance and click the **Connect** button in the top bar to generate the client-side schema in your preferred language. The schema is generated from your Sync Streams. The [CLI](/tools/cli) offers the same function. The generated schema does not include an `id` column. The client SDK creates an `id` column of type `text` automatically, so you do not need to declare it. See [Client ID](/sync/advanced/client-id) for details. In the Dashboard, select JavaScript and replace the suggested import with `@powersync/node`. The available column types are `text`, `integer`, and `real`. These should match the values produced by your Sync Streams. If a value does not match, it is cast automatically. For details on how source database types map to SQLite types, see [Types](/sync/types). ### 2. Instantiate the PowerSync Database Next, instantiate the PowerSync database. PowerSync streams changes from your backend source database into the client-side SQLite database, based on your Sync Streams. Your app reads from and writes to this local database whether the user is online or offline. **Example:** ```js theme={null} import { PowerSyncDatabase } from '@powersync/node'; import { Connector } from './Connector'; import { AppSchema } from './Schema'; export const db = new PowerSyncDatabase({ // The schema you defined in the previous step schema: AppSchema, database: { // Filename for the SQLite database — it's important to only instantiate one instance per file. dbFilename: 'powersync.db', // Optional. Directory where the database file is located. // dbLocation: 'path/to/directory' }, }); ``` ### 3. Integrate with Your Backend The backend connector connects the PowerSync client SDK to your application backend. The SDK uses it to: 1. Get an auth token to connect to the PowerSync instance. 2. Upload client-side writes to your backend API. The SDK places every write to the SQLite database in an upload queue and uploads the queue to your backend when the user is connected. Your backend then applies the changes to the source database. The connector must implement two methods: 1. [PowerSyncBackendConnector.fetchCredentials](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L16) - The SDK calls this method to get authentication credentials. It caches the credentials and calls the method again only when needed, for example on the first connection or when the token is near expiry. See [When `fetchCredentials()` is Called](/configuration/app-backend/client-side-integration#when-fetchcredentials-is-called) for details and [Authentication Setup](/configuration/auth/overview) for how to generate credentials. 2. [PowerSyncBackendConnector.uploadData](https://github.com/powersync-ja/powersync-js/blob/ed5bb49b5a1dc579050304fab847feb8d09b45c7/packages/common/src/client/connection/PowerSyncBackendConnector.ts#L24) - The SDK calls this method whenever it has client-side writes to upload to your backend API. Implement how those writes are processed and uploaded. See [When `uploadData()` is Called](/configuration/app-backend/client-side-integration#when-uploaddata-is-called) for triggers, throttling, and retry behavior, and [Writing Client Changes](/handling-writes/writing-client-changes) for the app backend implementation. **Example:** ```js theme={null} import { UpdateType } from '@powersync/node'; export class Connector { async fetchCredentials() { // Implement fetchCredentials to obtain a JWT from your authentication service. // See https://docs.powersync.com/configuration/auth/overview return { endpoint: '[Your PowerSync instance URL or self-hosted endpoint]', // Use a development token (see Authentication Setup https://docs.powersync.com/configuration/auth/development-tokens) to get up and running quickly token: 'An authentication token' }; } async uploadData(database) { // Implement uploadData to send local changes to your backend service. // You can omit this method if you only want to sync data from the database to the client // See example implementation here: https://docs.powersync.com/client-sdks/usage-examples#send-changes-in-local-data-to-your-backend-service } } ``` With your database instantiated and your connector ready, call `connect()` to start syncing data with your backend: ```js theme={null} await db.connect(new Connector()); await db.waitForFirstSync(); // Optional, to wait for a complete snapshot of data to be available ``` This section assumes that you use PowerSync to sync your backend source database with SQLite in your app. To manage a local SQLite database without sync, instantiate the PowerSync database without calling `connect()` and see the [Local-Only](/client-sdks/advanced/local-only-usage) guide. ### 4. Subscribe to Sync Streams Streams defined with `auto_subscribe: true` start syncing as soon as the client connects. For all other streams, your app must subscribe before their data downloads. The basic pattern is: subscribe to a stream, wait for its data to sync, then unsubscribe when the data is no longer needed. ```js theme={null} // Subscribe to a stream with parameters const sub = await db.syncStream('list_todos', { list_id: 'abc123' }).subscribe(); // Wait for the initial data to sync await sub.waitForFirstSync(); // The stream's rows are now in the local SQLite database. // TODO: Read the todos for this list with a local query. // When the data is no longer needed sub.unsubscribe(); ``` After you unsubscribe, the synced data stays in the local database for the stream's time-to-live (TTL), which is 24 hours by default. If the app subscribes again within that time, the data is already available. See [Client-Side Usage](/sync/streams/client-usage) for framework hooks, per-subscription sync status, custom TTLs, priority overrides, and connection parameters. ## Usage Once the PowerSync database is connected and your streams have synced, the data is in the local SQLite database. The API to run queries and updates is identical to the [JavaScript Web SDK](/client-sdks/reference/javascript-web#using-powersync-crud-functions): ```js theme={null} // Use db.get() to fetch a single row: console.log(await db.get('SELECT powersync_rs_version();')); // Or db.getAll() to fetch all: console.log(await db.getAll('SELECT * FROM lists;')); // And db.execute for inserts, updates and deletes: await db.execute( "INSERT INTO lists (id, created_at, name, owner_id) VALUES (uuid(), datetime('now'), ?, uuid());", ['My new list'] ); ``` ### Confirming Mutation Success with `RETURNING` When using the default client-side [JSON-based view system](/architecture/client-architecture#client-side-schema-and-sqlite-database-structure), writes are applied to a view, with triggers writing to the underlying table. Because of this, `result.rowsAffected` from `db.execute()` can be `0` even when an `UPDATE` or `DELETE` succeeds. When you need to confirm whether a mutation changed any rows, add a `RETURNING` clause and check the returned rows: ```js theme={null} const result = await db.execute( 'UPDATE tasks SET deleted_at = ? WHERE id = ? AND deleted_at IS NULL RETURNING id', [now, id] ); const wasUpdated = (result.rows?.length ?? 0) > 0; ``` If you need direct table writes, use [raw tables](/client-sdks/advanced/raw-tables). ### Watch Queries The `db.watch()` method executes a read query whenever a change to a dependent table is made. ```javascript theme={null} async function* pendingLists(): AsyncIterable { for await (const result of db.watch( `SELECT * FROM lists WHERE state = ?`, ['pending'] )) { yield result.rows?._array ?? []; } } ``` ```javascript theme={null} const pendingLists = (onResult: (lists: any[]) => void): void => { db.watch( 'SELECT * FROM lists WHERE state = ?', ['pending'], { onResult: (result: any) => { onResult(result.rows?._array ?? []); } } ); } ``` For advanced watch query features such as incremental updates and differential results, see [Live Queries / Watch Queries](/client-sdks/watch-queries). PowerSync runs queries asynchronously on a background pool of workers. It configures SQLite write-ahead logging (WAL) so that one writer and multiple readers can operate in parallel. ## Configure Logging ```js theme={null} import { createConsoleLogger, LogLevels } from '@powersync/node'; // Create a logger with trace minimum level to see all log messages // Available levels: trace, debug, info, warn, error const logger = createConsoleLogger({ minLevel: LogLevels.trace }); ``` Enable verbose output in the developer tools for detailed logs. ## Additional Usage Examples For more usage examples including accessing connection status, monitoring sync progress, and waiting for initial sync, see the [Usage Examples](/client-sdks/usage-examples) page. ## ORM Support See [JavaScript ORM Support](/client-sdks/orms/js/overview) for details. ## Troubleshooting See [Troubleshooting](/debugging/troubleshooting) for pointers to debug common issues. ## Supported Platforms See [Supported Platforms -> Node.js SDK](/resources/supported-platforms#node-js). ## Upgrading the SDK Run the following command in your project folder: ```bash theme={null} npm upgrade @powersync/node ``` ```bash theme={null} yarn upgrade @powersync/node ``` ```bash theme={null} pnpm upgrade @powersync/node ``` ## Encryption and Custom SQLite Drivers The SDK has an optional dependency on `better-sqlite3` which is used as the default SQLite driver for that package. Because that dependency is optional, it can be replaced or removed to customize how SQLite gets loaded. This section lists common options. ### Encryption To encrypt databases managed by the PowerSync SDK for Node.js, replace the `better-sqlite3` dependency with the [`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers) fork. That package has the same API as `better-sqlite3` while bundling [SQLite3MultipleCiphers](https://github.com/utelle/SQLite3MultipleCiphers) instead of upstream SQLite. The [node example](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-node) in the PowerSync repository can use both `better-sqlite3` and `better-sqlite3-multiple-ciphers` and may be a useful example here. Because PowerSync attempts to dynamically load `better-sqlite3` at runtime, using a different package requires patching the database worker. To do that, create a file (say `database.worker.js`) with the following contents: ```Typescript theme={null} // This worker uses bindings to sqlite3 multiple ciphers instead of the original better-sqlite3 worker. import Database from 'better-sqlite3-multiple-ciphers'; import { startPowerSyncWorker } from '@powersync/node/worker.js'; async function resolveBetterSqlite3() { return Database; } startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 }); ``` When opening the database, instruct PowerSync to use the custom worker. Also use the `initializeConnection` option to install an encryption key: ```Typescript theme={null} const encryptionKey = 'todo: generate encryption key and store it safely'; const db = new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: 'app.db', openWorker: (_, options) => { return new Worker(new URL('./database.worker.js', import.meta.url), options); }, initializeConnection: async (db) => { if (encryptionKey.length) { const escapedKey = encryptionKey.replaceAll("'", "''"); await db.execute(`pragma key = '${escapedKey}'`); } // Make sure the database is readable, this fails early if the key is wrong. await db.execute('pragma user_version'); } }, logger }); ``` If you're using a custom compilation toolchain, for instance because you're compiling from TypeScript or are applying a bundler to your project, loading workers may require additional configuration on that toolchain. ### `node:sqlite` Recent versions of Node.js contain an [experimental SQLite API](https://nodejs.org/api/sqlite.html). Using the built-in SQLite API can reduce code size and external native dependencies. To enable it, remove your dependency on `better-sqlite3` and configure PowerSync to use the built-in API: ```JavaScript theme={null} const database = new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: 'app.db', dbLocation: directory, // Use node:sqlite instead of better-sqlite3 implementation: { type: 'node:sqlite' } } }); ``` PowerSync has stability issues with this API. Use it for testing only.