PowerSync Node.js SDK快速入门Better-SQLite3 Worker、代理支持与加密配置实战【免费下载链接】powersync-jsSDK that enables local-first and real-time reactive apps with embedded SQLite for JavaScript clients, including React Native and Web项目地址: https://gitcode.com/gh_mirrors/po/powersync-js如果你想在 Node.js 应用里拥有本地优先Local-First 实时同步的能力PowerSync Node.js SDK 值得重点关注。它把嵌入式的 SQLite 数据库搬进 Node.js 客户端数据先落本地、再与服务端自动同步读写都快如闪电。本文面向新手带你 5 分钟跑通安装并搞懂三个实战主题Better-SQLite3 Worker 工作原理、代理Proxy支持、以及数据库加密配置。 一句话总结本地 SQLite 秒开 后台自动同步 可选全库加密这就是 PowerSync 给 Node.js 开发者的核心卖点。为什么选 PowerSync Node.js SDK传统做法是每次页面刷新都去请求后端接口网络一卡界面就转圈。PowerSync 的思路完全不同⚡本地优先查询直接打在本地 SQLite响应时间是毫秒级实时同步后台通过 WebSocket 或 HTTP 与同步服务保持连接变更自动推送到本地可选加密数据库文件本身可以被整体加密落盘即密文多平台同款同一套同步协议在 Web、React Native、Electron 等环境通用Node.js 版适合桌面端、CLI 工具和后端批处理场景。Node.js 版 SDK 的源码位于packages/node/核心导出在 index.ts 中它在通用包powersync/common之上封装了 Node 特有的能力。一步安装命令与常见坑安装只需一条命令npm install powersync/node better-sqlite3两个包都有安装脚本better-sqlite3负责本地编译或下载SQLite 原生库powersync/node负责下载 PowerSync 的 SQLite 扩展二进制按平台和 CPU 架构自动匹配逻辑见 SqliteWorker.ts 中的getPowerSyncExtensionFilename()。新手常遇到两个安装问题问题原因与解法node-gyp 编译失败缺少 Python / 编译工具链升级 node-gyp 到 10 或安装 setuptools打包后提示 better-sqlite3 not foundSDK 是动态import的打包器扫描不到显式声明依赖并自定义 Worker见下文详细排错可参考 packages/node/README.md。Better-SQLite3 Worker读写分离的并发设计这是 Node.js SDK 最有意思的架构设计。SQLite 的写操作天然互斥如果在主线程里执行同步的better-sqlite3调用长查询会卡死整个事件循环。PowerSync 的解法是主线程只做调度所有 SQL 都通过 WorkerConnectionPool.ts 派发到独立的 Worker 线程1 个写 Worker N 个读 Worker写连接独占读连接默认 5 条并行常量READ_CONNECTIONS读写互不阻塞默认 Worker 自动就绪正常情况下你什么都不用写SDK 会用内置的DefaultWorker启动线程可插拔 Worker通过openWorker选项替换 Worker 的创建方式——这正是加密、或打包场景的入口。相关类型定义在 options.ts 中database: { dbFilename: app.db, // 数据库文件名 dbLocation: /data, // 可选存放目录需已存在 readWorkerCount: 5, // 可选读 Worker 数量 openWorker: myCustomOpener, // 可选自定义 Worker 加载 }最小可用的数据库初始化代码长这样import { PowerSyncDatabase } from powersync/node; const db new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: app.db }, }); await db.connect(new MyConnector()); await db.waitForFirstSync();AppSchema用声明式 API 描述需要同步的表示例见 powersync.tsPowerSyncBackendConnector负责告诉 SDK 去哪同步、本地修改如何上传。代理支持4 个环境变量搞定企业网络公司内网、CI 环境经常需要走代理才能访问同步服务。PowerSync Node.js SDK 内置了完整的代理支持底层基于 undici 的EnvHttpProxyAgent实现位于 NodeRemote.tsHTTP 请求拉取同步数据读取HTTP_PROXY/HTTPS_PROXY环境变量WebSocket 长连接读取WS_PROXY/WSS_PROXY环境变量同时兼容小写写法https_proxy和ALL_PROXY兜底。也就是说只要设好环境变量SDK 会自动把请求和长连接都路由到代理一行代码都不用改。如果代理需要自定义 CA 证书比如 MITM 企业网关可以不依赖环境变量改用 undici 的ProxyAgent通过remoteOptions.dispatcher注入到连接中官方 demo 里有完整注释示例见 main.ts。加密配置实战让数据库文件落盘即密文本地数据库存在磁盘上敏感业务往往要求文件本身就是密文。PowerSync 通过better-sqlite3-multiple-ciphers这个支持 SQLCipher 加密的better-sqlite3分支来实现全库加密。整套流程只有两步**第一步自定义一个加密 Worker。**它的作用只是把loadBetterSqlite3指向加密版本参考 encryption.worker.tsimport Database from better-sqlite3-multiple-ciphers; import { startPowerSyncWorker } from powersync/node/worker.js; async function resolveBetterSqlite3() { return Database; } startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });**第二步打开数据库时注入密钥。**通过initializeConnection回调执行PRAGMA keyconst db new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: app.db, openWorker: (_, options) new Worker(new URL(./encryption.worker.js, import.meta.url), options), initializeConnection: async (conn) { const escaped encryptionKey.replaceAll(, ); await conn.execute(PRAGMA key ${escaped}); // 立即验证密钥是否正确避免错误延迟暴露 await conn.execute(PRAGMA user_version); }, }, });两个实战要点 密钥里的单引号必须转义否则PRAGMA key会执行失败 建议像上面那样紧跟一条PRAGMA user_version——密钥错误时能第一时间报错而不是同步到一半才失败。demo 里通过.env的ENCRYPTION_KEY控制是否启用加密见 demos/example-node/README.md。跑通官方 Demo从克隆到看到实时数据仓库自带一个开箱即用的 Node.js CLI 示例位于demos/example-node/它演示了打开数据库 → 连接同步服务 → 监听查询变化的完整闭环git clone https://gitcode.com/gh_mirrors/po/powersync-js cd powersync-js/demos/example-node pnpm install pnpm start启动后它会自动完成首次同步然后进入 REPL 交互界面修改后端数据库里的某一行本地输出的查询结果会实时刷新在 REPL 里输入add(my list)本地写入的数据会自动上传回后端。这正是双向同步的直观体现本地读、本地写、后台悄悄同步。示例中还展示了如何切换SyncStreamConnectionMethod.WEB_SOCKET与 HTTP 两种同步通道以及如何开启 undici 诊断日志排查网络问题UndiciDiagnostics.ts。常见问题与最佳实践Q1必须用 better-sqlite3 吗不是。SDK 还实验性支持 Node 内置的node:sqlite在implementation选项中切换但目前官方标注为高度不稳定生产环境建议默认选择better-sqlite3。Q2读 Worker 数量怎么调默认 5 个读 Worker。并发查询多的桌面端应用可以适当调高readWorkerCount纯 CLI 场景保持默认即可别盲目加大线程数。Q3代理和加密可以叠加吗完全可以。两者作用在不同层面代理影响与同步服务的网络通道加密影响本地磁盘上的数据文件互不干扰。Q4和后端部署 PowerSync 是一回事吗不是。本 SDK 是给Node.js 客户端Electron、CLI、桌面工具用的纯服务端部署同步服务是另一套方案参考项目文档目录 docs/ 了解整体架构。总结一张表回顾核心配置能力关键配置 / 入口适用场景基础安装npm install powersync/node better-sqlite3所有项目读写分离 WorkerreadWorkerCount、openWorker高并发查询、打包环境代理支持HTTPS_PROXY、WS_PROXY等环境变量企业内网、CI数据库加密better-sqlite3-multiple-ciphersPRAGMA key敏感数据本地存储PowerSync Node.js SDK 的设计哲学可以概括为一句话把复杂的并发、网络、加密问题封装成几个可选的回调和变量新手装完包就能用进阶玩家再通过 Worker 和 dispatcher 做深度定制。建议下一步直接打开demos/example-node/动手改一改把实时同步、代理和加密各体验一遍——代码比文档更有说服力 【免费下载链接】powersync-jsSDK that enables local-first and real-time reactive apps with embedded SQLite for JavaScript clients, including React Native and Web项目地址: https://gitcode.com/gh_mirrors/po/powersync-js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerSync Node.js SDK快速入门：Better-SQLite3 Worker、代理支持与加密配置实战
PowerSync Node.js SDK快速入门Better-SQLite3 Worker、代理支持与加密配置实战【免费下载链接】powersync-jsSDK that enables local-first and real-time reactive apps with embedded SQLite for JavaScript clients, including React Native and Web项目地址: https://gitcode.com/gh_mirrors/po/powersync-js如果你想在 Node.js 应用里拥有本地优先Local-First 实时同步的能力PowerSync Node.js SDK 值得重点关注。它把嵌入式的 SQLite 数据库搬进 Node.js 客户端数据先落本地、再与服务端自动同步读写都快如闪电。本文面向新手带你 5 分钟跑通安装并搞懂三个实战主题Better-SQLite3 Worker 工作原理、代理Proxy支持、以及数据库加密配置。 一句话总结本地 SQLite 秒开 后台自动同步 可选全库加密这就是 PowerSync 给 Node.js 开发者的核心卖点。为什么选 PowerSync Node.js SDK传统做法是每次页面刷新都去请求后端接口网络一卡界面就转圈。PowerSync 的思路完全不同⚡本地优先查询直接打在本地 SQLite响应时间是毫秒级实时同步后台通过 WebSocket 或 HTTP 与同步服务保持连接变更自动推送到本地可选加密数据库文件本身可以被整体加密落盘即密文多平台同款同一套同步协议在 Web、React Native、Electron 等环境通用Node.js 版适合桌面端、CLI 工具和后端批处理场景。Node.js 版 SDK 的源码位于packages/node/核心导出在 index.ts 中它在通用包powersync/common之上封装了 Node 特有的能力。一步安装命令与常见坑安装只需一条命令npm install powersync/node better-sqlite3两个包都有安装脚本better-sqlite3负责本地编译或下载SQLite 原生库powersync/node负责下载 PowerSync 的 SQLite 扩展二进制按平台和 CPU 架构自动匹配逻辑见 SqliteWorker.ts 中的getPowerSyncExtensionFilename()。新手常遇到两个安装问题问题原因与解法node-gyp 编译失败缺少 Python / 编译工具链升级 node-gyp 到 10 或安装 setuptools打包后提示 better-sqlite3 not foundSDK 是动态import的打包器扫描不到显式声明依赖并自定义 Worker见下文详细排错可参考 packages/node/README.md。Better-SQLite3 Worker读写分离的并发设计这是 Node.js SDK 最有意思的架构设计。SQLite 的写操作天然互斥如果在主线程里执行同步的better-sqlite3调用长查询会卡死整个事件循环。PowerSync 的解法是主线程只做调度所有 SQL 都通过 WorkerConnectionPool.ts 派发到独立的 Worker 线程1 个写 Worker N 个读 Worker写连接独占读连接默认 5 条并行常量READ_CONNECTIONS读写互不阻塞默认 Worker 自动就绪正常情况下你什么都不用写SDK 会用内置的DefaultWorker启动线程可插拔 Worker通过openWorker选项替换 Worker 的创建方式——这正是加密、或打包场景的入口。相关类型定义在 options.ts 中database: { dbFilename: app.db, // 数据库文件名 dbLocation: /data, // 可选存放目录需已存在 readWorkerCount: 5, // 可选读 Worker 数量 openWorker: myCustomOpener, // 可选自定义 Worker 加载 }最小可用的数据库初始化代码长这样import { PowerSyncDatabase } from powersync/node; const db new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: app.db }, }); await db.connect(new MyConnector()); await db.waitForFirstSync();AppSchema用声明式 API 描述需要同步的表示例见 powersync.tsPowerSyncBackendConnector负责告诉 SDK 去哪同步、本地修改如何上传。代理支持4 个环境变量搞定企业网络公司内网、CI 环境经常需要走代理才能访问同步服务。PowerSync Node.js SDK 内置了完整的代理支持底层基于 undici 的EnvHttpProxyAgent实现位于 NodeRemote.tsHTTP 请求拉取同步数据读取HTTP_PROXY/HTTPS_PROXY环境变量WebSocket 长连接读取WS_PROXY/WSS_PROXY环境变量同时兼容小写写法https_proxy和ALL_PROXY兜底。也就是说只要设好环境变量SDK 会自动把请求和长连接都路由到代理一行代码都不用改。如果代理需要自定义 CA 证书比如 MITM 企业网关可以不依赖环境变量改用 undici 的ProxyAgent通过remoteOptions.dispatcher注入到连接中官方 demo 里有完整注释示例见 main.ts。加密配置实战让数据库文件落盘即密文本地数据库存在磁盘上敏感业务往往要求文件本身就是密文。PowerSync 通过better-sqlite3-multiple-ciphers这个支持 SQLCipher 加密的better-sqlite3分支来实现全库加密。整套流程只有两步**第一步自定义一个加密 Worker。**它的作用只是把loadBetterSqlite3指向加密版本参考 encryption.worker.tsimport Database from better-sqlite3-multiple-ciphers; import { startPowerSyncWorker } from powersync/node/worker.js; async function resolveBetterSqlite3() { return Database; } startPowerSyncWorker({ loadBetterSqlite3: resolveBetterSqlite3 });**第二步打开数据库时注入密钥。**通过initializeConnection回调执行PRAGMA keyconst db new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: app.db, openWorker: (_, options) new Worker(new URL(./encryption.worker.js, import.meta.url), options), initializeConnection: async (conn) { const escaped encryptionKey.replaceAll(, ); await conn.execute(PRAGMA key ${escaped}); // 立即验证密钥是否正确避免错误延迟暴露 await conn.execute(PRAGMA user_version); }, }, });两个实战要点 密钥里的单引号必须转义否则PRAGMA key会执行失败 建议像上面那样紧跟一条PRAGMA user_version——密钥错误时能第一时间报错而不是同步到一半才失败。demo 里通过.env的ENCRYPTION_KEY控制是否启用加密见 demos/example-node/README.md。跑通官方 Demo从克隆到看到实时数据仓库自带一个开箱即用的 Node.js CLI 示例位于demos/example-node/它演示了打开数据库 → 连接同步服务 → 监听查询变化的完整闭环git clone https://gitcode.com/gh_mirrors/po/powersync-js cd powersync-js/demos/example-node pnpm install pnpm start启动后它会自动完成首次同步然后进入 REPL 交互界面修改后端数据库里的某一行本地输出的查询结果会实时刷新在 REPL 里输入add(my list)本地写入的数据会自动上传回后端。这正是双向同步的直观体现本地读、本地写、后台悄悄同步。示例中还展示了如何切换SyncStreamConnectionMethod.WEB_SOCKET与 HTTP 两种同步通道以及如何开启 undici 诊断日志排查网络问题UndiciDiagnostics.ts。常见问题与最佳实践Q1必须用 better-sqlite3 吗不是。SDK 还实验性支持 Node 内置的node:sqlite在implementation选项中切换但目前官方标注为高度不稳定生产环境建议默认选择better-sqlite3。Q2读 Worker 数量怎么调默认 5 个读 Worker。并发查询多的桌面端应用可以适当调高readWorkerCount纯 CLI 场景保持默认即可别盲目加大线程数。Q3代理和加密可以叠加吗完全可以。两者作用在不同层面代理影响与同步服务的网络通道加密影响本地磁盘上的数据文件互不干扰。Q4和后端部署 PowerSync 是一回事吗不是。本 SDK 是给Node.js 客户端Electron、CLI、桌面工具用的纯服务端部署同步服务是另一套方案参考项目文档目录 docs/ 了解整体架构。总结一张表回顾核心配置能力关键配置 / 入口适用场景基础安装npm install powersync/node better-sqlite3所有项目读写分离 WorkerreadWorkerCount、openWorker高并发查询、打包环境代理支持HTTPS_PROXY、WS_PROXY等环境变量企业内网、CI数据库加密better-sqlite3-multiple-ciphersPRAGMA key敏感数据本地存储PowerSync Node.js SDK 的设计哲学可以概括为一句话把复杂的并发、网络、加密问题封装成几个可选的回调和变量新手装完包就能用进阶玩家再通过 Worker 和 dispatcher 做深度定制。建议下一步直接打开demos/example-node/动手改一改把实时同步、代理和加密各体验一遍——代码比文档更有说服力 【免费下载链接】powersync-jsSDK that enables local-first and real-time reactive apps with embedded SQLite for JavaScript clients, including React Native and Web项目地址: https://gitcode.com/gh_mirrors/po/powersync-js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考