在浏览器中为 PGlite 打造交互式 Postgres 终端:`@electric-sql/pglite-repl` 完全指南 📅 发布时间:2026/9/14 23:07:14 👁 浏览次数: 在浏览器中为 PGlite 打造交互式 Postgres 终端electric-sql/pglite-repl完全指南【免费下载链接】pgliteEmbeddable Postgres with real-time, reactive bindings.项目地址: https://gitcode.com/GitHub_Trending/pg/pglitePGlite 是运行在 WASM 中的可嵌入 Postgres而electric-sql/pglite-repl则为它提供了浏览器内的 REPLRead-Eval-Print Loop交互终端。本文围绕仓库内 packages/pglite-repl/README.md 展开结合源码逐层拆解其 Props、键盘交互、自动补全、主题机制与 Web Component 封装让你既能在 React 项目中快速嵌入终端也能理解其底层实现随时按需定制。一、PGlite REPL 能做什么PGlite REPL 是一个面向浏览器的终端组件让用户可以在页面中与 WASM Postgres 保持交互式会话——就像在本地终端里敲 psql 一样边输入 SQL 边查看结果。核心能力包括同时提供React 组件与Web Component两种形态后者可被任何框架或纯 HTML 页面直接使用基于 CodeMirror 实现输入编辑自带语法高亮自动补全包括从当前数据库中动态读取的表名、列名与 SQL 关键字输入历史上/下方向键回退与前进支持\d系列psql 元命令借助psql-describe包实现。从 package.json 可以看到该包以electric-sql/pglite-repl发布peerDependencies声明了electric-sql/pglite当前 workspace 版本 0.5.4且标记为可选构建产物包含distReact 库与dist-webcomponentWeb Component两份。二、快速开始在 React 中集成 REPL安装依赖npm install electric-sql/pglite electric-sql/pglite-repl然后引入组件并传入一个 PGlite 实例import { PGlite } from electric-sql/pglite; import { Repl } from electric-sql/pglite-repl; function MyComponent() { const pg new PGlite(); return Repl pg{pg} / / }几点关键说明Repl会通过pg.waitReady等待数据库初始化完成期间编辑器处于editable{!loading}的只读状态并显示 Loading...见 src/Repl.tsxpg参数实际被透传给usePGlite()来自electric-sql/pglite-react因此在已经挂载了PGliteProvider的应用里甚至可以省略pgprop直接复用上下文中的实例仓库内的开发示例 src/App.tsx 就是最简用法new PGlite()后Repl pg{pg} border /。三、ReplProps 完整解析README 给出了ReplProps接口而源码 src/Repl.tsx 中实际定义更为完整除了文档列出的 4 个字段外还包含showTime与disableUpdateSchema// 主题模式auto 跟随系统深浅色自动切换 type ReplTheme light | dark | auto; interface ReplProps { pg: PGlite; // PGlite 数据库实例可通过 context 省略 border?: boolean; // 是否显示组件外边框默认 false lightTheme?: Extension; // 浅色主题的 CodeMirror Extension darkTheme?: Extension; // 深色主题的 CodeMirror Extension theme?: ReplTheme; // 主题模式默认 auto showTime?: boolean; // 是否在每次查询输出后显示耗时(ms)默认 false disableUpdateSchema?: boolean; // 是否禁用执行后自动刷新补全 schema默认 false }lightTheme/darkTheme需要是 React CodeMirrorexport const defaultLightThemeInit: ThemeInit githubLightInit export const defaultLightTheme githubLight export const defaultDarkThemeInit: ThemeInit githubDarkInit export const defaultDarkTheme githubDark3.1 参数默认值与内部处理在 src/Repl.tsx 中组件以解构默认值的方式落地这些参数border false、lightTheme defaultLightTheme、darkTheme defaultDarkTheme、theme auto、showTime false、disableUpdateSchema false。showTime打开后每次查询的分隔线右侧会显示response.time.toFixed(1)ms见 src/ReplResponse.tsx耗时由performance.now()在 src/utils.ts 中精确测量适合用来评估 WASM Postgres 的查询性能disableUpdateSchema默认情况下每次执行查询后组件都会重新查询information_schema.columns刷新补全数据以保证新建的表能立即出现在自动补全里。如果数据库结构固定、需要减少额外查询可将其设为true见 src/Repl.tsx。四、键盘交互与命令执行机制Repl重写了 CodeMirror 的默认键位src/Repl.tsx形成了一套贴近 psql 的交互体验。4.1 Enter 执行查询默认键位中的Enter被过滤掉改由自定义 handler 接管输入为空时直接忽略否则调用runQuery(value, pg)执行将结果追加到输出区并自动滚动到底部。每次执行后若未禁用disableUpdateSchema还会刷新 schema 供补全使用随后清空输入框等待下一条命令run: () { if (value.trim() ) return false // 输入为空则不执行 runQuery(value, pg).then((response) { setOutput((prev) [...prev, response]) // 自动滚动到底部 // 刷新 schema 用于自动补全 }) setValue() return true }4.2 上/下方向键回放历史当光标位于第一行时按ArrowUp进入历史回溯模式把此前执行过的查询依次回填到输入框当光标位于最后一行时按ArrowDown向前翻阅历史历史之外的输入内容会被暂存在valueNoHistoryref 中翻回草稿时原样恢复光标在中间行时方向键行为保持不变方便在编辑器中移动光标、编辑多行 SQL。4.3 查询分发SQL 与 \d 元命令src/utils.ts 中的runQuery是执行入口以\开头的输入被判定为 psql 元命令转交给runDescribe其余输入直接调用pg.exec(query, { rowMode: array })数组行模式执行成功则返回{ query, results, time }失败则捕获异常返回{ query, error, time }错误会以红色展示在输出区。runDescribesrc/utils.ts调用psql-describe包的describe()函数传入查询、数据库名postgres和一个执行器回调回调把describe生成的 SQL 交给 PGlite 执行并返回行与字段最终输出可能是纯文本如ERROR:前缀会被识别为错误、也可能是带标题与结果集的表格。五、SQL 自动补全与 \d 元命令自动补全由 src/sqlSupport.ts 的makeSqlExt组装而成它重写了codemirror/lang-sql的sql()工厂注入三层补全源schema 补全schemaCompletionSource(config)使用组件内维护的schema形如public.users - [id, name, ...]补全表名与列名关键字补全keywordCompletionSource(lang, upperCaseKeywords)补全 PostgreSQL 关键字自定义 \d 补全describeCompletionsAutoComplete匹配/\w*/前缀弹出\d系列命令补全列表。schema数据由 src/utils.ts 的getSchema通过查询information_schema.columns聚合生成并在编辑器创建、每次查询执行后刷新——这就是自动补全包括数据库中的表名和列名的实现来源。5.1 内置的 \d 命令补全清单sqlSupport.ts 内置了超过 40 条 psql 元命令的补全项type: function带显示文本与说明常用示例命令说明\d[S] [ pattern ]列出表、视图、序列、索引等\dt[S] [ pattern ]列出表\dv[S] [ pattern ]列出视图\di[S] [ pattern ]列出索引\df[anptwS] [ pattern [ arg_pattern ... ] ]列出函数\dn[S] [ pattern ]列出模式(schema)\du[S] [ pattern ]/\dg[S] [ pattern ]列出数据库角色\dx[] [ pattern ]列出已安装扩展\dT[S] [ pattern ]列出数据类型\dp[S] [ pattern ]列出对象访问权限\dF[]/\dFd/\dFp/\dFt文本搜索配置/词典/解析器/模板\dconfig[] [ pattern ]列出服务端配置参数\drds [ role-pattern [ database-pattern ] ]列出角色/数据库级配置补全项还包含\dA、\dAc、\dAf、\dAo、\dAp访问方法及其操作符类/族、\dD域、\dE外部表、\dP[itn]分区表、\dRp/\dRs复制发布/订阅、\dX扩展统计、\dy事件触发器等覆盖了 psql 元命令的绝大部分常用场景。六、主题机制与样式体系主题策略在 src/Repl.tsx 中实现themelight/themedark固定使用对应主题themeauto默认通过window.matchMedia((prefers-color-scheme: dark))监听系统深浅色偏好并注册change监听器系统切换时自动跟随。组件通过extractStyles()src/Repl.tsx从 CodeMirror 编辑器的计算样式中提取前景色、背景色、gutter 边框等写入一组 CSS 变量--PGliteRepl-foreground-color --PGliteRepl-background-color --PGliteRepl-border --PGliteRepl-gutter-border --PGliteRepl-border-color外层根节点PGliteRepl-root正是通过这组变量实现编辑器和结果区外观统一见 src/Repl.css且支持通过--PGliteRepl-font-size调整整体字号。borderprop 为true时会追加PGliteRepl-root-border类为整个终端绘制外边框。这些 CSS 变量是结果区、表格与分隔线保持视觉一致的关键也意味着自定义主题时只要保证 Extension 输出的计算样式合理终端其余部分会自动跟随。七、作为 Web Component 使用尽管 REPL 用 React 构建但它同时被打包为 Web Componentpglite-repl方便在任何页面或框架中零成本接入。其实现位于 src-webcomponent/main.tsx通过customElements.define(pglite-repl, PGliteREPL)注册内部用 Shadow DOM 隔离样式attachShadow({ mode: open })再以createRoot挂载 React 组件。CDN 引入示例script srchttps://cdn.jsdelivr.net/npm/electric-sql/pglite/dist-webcomponent/Repl.js typemodule/script !-- 在页面中放置 Repl Web Component -- pglite-repl idrepl/pglite-repl script typemodule import { PGlite } from https://cdn.jsdelivr.net/npm/electric-sql/pglite/dist/index.js; // 创建 PGlite 实例 const pg new PGlite(); // 获取 Repl 元素 const repl document.getElementById(repl); // 将 PGlite 实例挂到组件上 repl.pg pg; /script7.1 支持的属性与属性映射PGliteREPL的observedAttributes为[border, theme, show-time, disable-update-schema]src-webcomponent/main.tsx属性变更会触发重新渲染HTML 属性对应 React prop说明borderborder布尔属性borderfalse可显式关闭themethemelight \| dark \| auto缺省为autoshow-timeshowTime布尔属性显示每次查询耗时disable-update-schemadisableUpdateSchema布尔属性禁用执行后刷新补全 schema此外还暴露了pg、lightTheme、darkTheme三个可读写属性getter/setter例如repl.pg pg传入数据库实例未设置pg时组件渲染 PGlite instance not provided 提示。构建产物通过 vite.webcomp.config.ts 生成输出为dist-webcomponent/Repl.jsES 格式terser 压缩带 sourcemap并在 package.json 的exports中以./webcomponent子路径导出。八、结果渲染响应、表格与分页每次执行的结果由 src/ReplResponse.tsx 渲染结构为回显查询语句❯前缀若有文本输出如\d的描述文本展示文本行结果集按条渲染有字段时渲染表格无字段时输出null错误信息以红色!前缀样式呈现分隔线showTime开启时附带耗时。表格组件 src/ReplTable.tsx 有几个值得注意的细节单元格类型化展示null、数字右对齐、等宽数字、布尔值、DateISO 字符串、数组、对象JSON 字符串均有不同样式超长单元格截断超过 200 字符的单元格内容截断并追加…避免撑爆布局maxCellLength 200大结果集分页初始只渲染 100 行点击 Show more 每次再加载 100 行tableRowIncrement 100保证大数据量下页面依旧流畅结果变化时行数上限自动重置。九、本地开发与构建在仓库根目录pnpm workspace 环境进入本包目录即可# 安装依赖 pnpm install # 启动开发服务器 pnpm dev # 打开终端中显示出的 URL基于 Vite入口为 index.html 与 src/main.tsx # 构建库产物 pnpm build构建流程见 package.json 的 scriptsbuild:reacttsc类型检查后执行vite build产出dist/React 库通过 vite.config.ts 配置使用vite-plugin-libcss内联样式、vite-plugin-dts生成类型声明build:webcomp以 vite.webcomp.config.ts 构建dist-webcomponent/Repl.js另有lint、typecheck、format、preview、check:exports用attw校验 ESM 导出等辅助脚本。十、延伸阅读若想继续深入可从以下仓库路径入手组件核心实现与键盘/主题逻辑src/Repl.tsx查询分发、\d元命令与 schema 采集src/utils.ts自动补全schema/关键字/\d命令src/sqlSupport.ts响应与表格渲染src/ReplResponse.tsx、src/ReplTable.tsxWeb Component 封装src-webcomponent/main.tsx样式与 CSS 变量src/Repl.css构建与发布配置vite.config.ts、vite.webcomp.config.ts、package.json配合主包 packages/pglite 的 PGlite 实例new PGlite()、pg.exec、pg.waitReady等 API你可以在几行代码内为任何 Web 应用注入一个功能完整的 Postgres 交互终端——无论用于文档演示、数据教学还是内部工具pglite-repl都是直接可用的开箱方案。【免费下载链接】pgliteEmbeddable Postgres with real-time, reactive bindings.项目地址: https://gitcode.com/GitHub_Trending/pg/pglite创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考