PGLite 实战：在浏览器中运行 PostgreSQL，无需服务器的完整数据库体验

2025 年底，Electric SQL 团队发布了 PGLite 0.3 正式版——一个将完整 PostgreSQL 16 内核编译为 WebAssembly、可在浏览器和 Node.js 中直接运行的嵌入式数据库。在 npm 上，PGLite 的月下载量已突破 50 万，被 Cloudflare、Supabase 等公司在内部工具链中采用。PGLite 不是 PostgreSQL 的阉割版，而是真正的 PostgreSQL——它支持完整的 SQL 语法、JSON/JSONB 操作、全文搜索、甚至 pgvector 向量扩展，所有运算都在浏览器主线程或 Worker 中完成，数据零网络传输。

📌 记住： PGLite 的核心价值不是「又一个前端数据库」，而是让你在浏览器中获得与生产环境完全一致的 PostgreSQL 体验。开发、测试、离线应用、本地优先（Local-First）架构，都能从中受益。

🔬 一、PGLite 技术原理：PostgreSQL 如何跑在浏览器里

1.1 WebAssembly 编译：从 C 到 WASM 的工程挑战

PostgreSQL 内核是用 C 语言编写的，包含约 150 万行代码。PGLite 团队使用 Emscripten 工具链将 PostgreSQL 编译为 WebAssembly（WASM），同时做了几个关键的工程决策：

• 文件系统层：使用 POSIX-to-WASM 的文件系统抽象，将 open()、read()、write() 等系统调用映射到浏览器的 OPFS（Origin Private File System）或 IndexedDB
• 进程模型：PostgreSQL 原生使用多进程架构（postmaster + backend processes），PGLite 将其改造为单进程、协程式架构，通过 Asyncify 技术处理异步 I/O
• 内存管理：WASM 的线性内存模型与 C 的 malloc/free 直接对应，PGLite 默认分配 256MB 内存，可根据需要扩展

// 安装 PGLite — 零原生依赖，纯 WASM
// npm install @electric-sql/pglite

import { PGlite } from '@electric-sql/pglite'

// 创建内存数据库（数据不持久化，适合测试）
const db = new PGlite()
await db.waitReady

// 执行完整的 PostgreSQL SQL — 不是子集，是完整版
await db.exec(`
  CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    profile JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW()
  );
  
  -- 插入 JSONB 数据
  INSERT INTO users (name, email, profile) VALUES
    ('张三', 'zhangsan@example.com', '{"role": "admin", "skills": ["TypeScript", "React"]}'),
    ('李四', 'lisi@example.com', '{"role": "developer", "skills": ["Python", "Go"]}');
  
  -- JSONB 查询 — 这是真正的 PostgreSQL JSONB 操作
  SELECT name, profile->>'role' AS role
  FROM users
  WHERE profile @> '{"skills": ["TypeScript"]}';
`)

1.2 OPFS 持久化：数据在浏览器中真正落地

PGLite 支持两种持久化模式，这是它与 IndexedDB-based 方案（如 sql.js）的根本区别：

// 持久化模式 — 数据在页面刷新后依然存在
import { PGlite } from '@electric-sql/pglite'

// OPFS 持久化：数据存储在浏览器的私有文件系统中
const db = new PGlite('pgdata/my-app')
await db.waitReady

// 创建表并写入数据
await db.exec(`
  CREATE TABLE IF NOT EXISTS notes (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT,
    tags TEXT[] DEFAULT '{}',
    metadata JSONB DEFAULT '{}',
    updated_at TIMESTAMPTZ DEFAULT NOW()
  );
  
  INSERT INTO notes (title, content, tags, metadata) VALUES
    ('会议纪要', '讨论了 Q3 路线图', ARRAY['work', 'meeting'], '{"priority": "high"}'),
    ('学习笔记', 'PGLite 使用 WASM 编译', ARRAY['tech', 'database'], '{"source": "blog"}');
`)

// 查询 — 刷新页面后数据依然存在
const result = await db.query(
  `SELECT * FROM notes WHERE $1 = ANY(tags)`, 
  ['work']
)
console.log(result.rows)
// [{ id: 1, title: '会议纪要', content: '...', tags: ['work', 'meeting'], ... }]

⚠️ 警告： OPFS 在 Safari 17+ 和 Chrome 102+ 中才完全支持。如果你需要兼容旧浏览器，PGLite 会自动回退到 IndexedDB，但性能会下降约 40%。

1.3 SharedWorker：多 Tab 安全访问

浏览器中多个 Tab 同时写入同一个 OPFS 数据库会导致数据损坏。PGLite 通过 SharedWorker 模式解决这个问题——所有 Tab 共享同一个数据库实例：

// main-thread.ts — 每个 Tab 中的代码
import { PGlite } from '@electric-sql/pglite'
import { worker } from '@electric-sql/pglite/worker'

// 通过 SharedWorker 连接共享的数据库实例
const db = new PGlite({
  dataDir: 'pgdata/shared-app',
  worker: new Worker(new URL('./pg-worker.ts', import.meta.url), {
    type: 'module'
  })
})

await db.waitReady

// 正常使用 — 多 Tab 之间自动协调，无需手动加锁
await db.query('INSERT INTO events (type, payload) VALUES ($1, $2)', [
  'page_view',
  JSON.stringify({ path: '/dashboard', timestamp: Date.now() })
])

// pg-worker.ts — SharedWorker 中运行
import { PGlite } from '@electric-sql/pglite'
import { SharedWorkerBackend } from '@electric-sql/pglite/worker'

const backend = new SharedWorkerBackend()
const db = new PGlite('pgdata/shared-app')

// Worker 接收来自各 Tab 的查询请求，串行执行
backend.onMessage(async (msg) => {
  const result = await db.query(msg.sql, msg.params)
  backend.postMessage(result)
})

🛠️ 二、实战场景：PGLite 在真实项目中的应用

2.1 与 Drizzle ORM 集成：类型安全的浏览器数据库

PGLite 兼容标准的 pg 协议，可以直接与 Drizzle ORM 配合使用，获得完整的类型安全：

// schema.ts — Drizzle 表定义（与服务器端共享同一份 schema）
import { pgTable, serial, text, jsonb, timestamp, integer } from 'drizzle-orm/pg-core'

export const products = pgTable('products', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  price: integer('price').notNull(),  // 以分为单位存储
  category: text('category').notNull(),
  attributes: jsonb('attributes').default({}),
  createdAt: timestamp('created_at').defaultNow()
})

// db.ts — 浏览器端 Drizzle + PGLite 配置
import { PGlite } from '@electric-sql/pglite'
import { drizzle } from 'drizzle-orm/pglite'
import * as schema from './schema'

const pglite = new PGlite('pgdata/shop')
await pglite.waitReady

// 用 Drizzle 包装 PGLite — 获得完整的类型推导
const db = drizzle(pglite, { schema })

// 类型安全的查询 — IDE 自动补全、编译期类型检查
const cheapProducts = await db
  .select()
  .from(schema.products)
  .where(gt(schema.products.price, 1000))
  .orderBy(asc(schema.products.price))
  .limit(10)

// 插入 — 类型推导会检查字段是否正确
await db.insert(schema.products).values({
  name: 'TypeScript 实战',
  price: 5900,
  category: 'book',
  attributes: { author: '张三', pages: 320 }
})

💡 提示： 使用 Drizzle + PGLite 的最大好处是代码复用。你可以在浏览器端和服务器端共享同一份 schema 定义和查询代码，开发时用 PGLite 做本地测试，部署时切换到远程 PostgreSQL，业务逻辑零修改。

2.2 离线优先应用：Service Worker + PGLite

PGLite 天然适合构建离线优先（Offline-First）应用。以下是一个笔记应用的完整架构：

// sync-engine.ts — 离线同步引擎
import { PGlite } from '@electric-sql/pglite'

class SyncEngine {
  private db: PGlite
  private syncQueue: Array<{ table: string; op: string; data: any }> = []

  constructor(db: PGlite) {
    this.db = db
    this.initSyncTable()
  }

  private async initSyncTable() {
    await this.db.exec(`
      -- 同步日志表：记录所有本地变更
      CREATE TABLE IF NOT EXISTS _sync_log (
        id SERIAL PRIMARY KEY,
        table_name TEXT NOT NULL,
        operation TEXT NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE')),
        record_id INTEGER NOT NULL,
        payload JSONB,
        synced BOOLEAN DEFAULT FALSE,
        created_at TIMESTAMPTZ DEFAULT NOW()
      );
      
      -- 创建触发器：自动记录变更
      CREATE OR REPLACE FUNCTION log_changes() RETURNS TRIGGER AS $$
      BEGIN
        IF TG_OP = 'DELETE' THEN
          INSERT INTO _sync_log (table_name, operation, record_id)
          VALUES (TG_TABLE_NAME, TG_OP, OLD.id);
          RETURN OLD;
        ELSE
          INSERT INTO _sync_log (table_name, operation, record_id, payload)
          VALUES (TG_TABLE_NAME, TG_OP, NEW.id, to_jsonb(NEW));
          RETURN NEW;
        END IF;
      END;
      $$ LANGUAGE plpgsql;
      
      -- 为 notes 表启用变更追踪
      DROP TRIGGER IF EXISTS notes_sync_trigger ON notes;
      CREATE TRIGGER notes_sync_trigger
        AFTER INSERT OR UPDATE OR DELETE ON notes
        FOR EACH ROW EXECUTE FUNCTION log_changes();
    `)
  }

  // 将未同步的变更推送到服务器
  async pushToServer(serverUrl: string) {
    const unsynced = await this.db.query(
      `SELECT * FROM _sync_log WHERE synced = FALSE ORDER BY id`
    )

    if (unsynced.rows.length === 0) return

    try {
      const response = await fetch(`${serverUrl}/sync`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ changes: unsynced.rows })
      })

      if (response.ok) {
        // 标记为已同步
        const ids = unsynced.rows.map((r: any) => r.id)
        await this.db.query(
          `UPDATE _sync_log SET synced = TRUE WHERE id = ANY($1)`,
          [ids]
        )
      }
    } catch (error) {
      // 离线状态 — 变更保留在本地，下次在线时自动同步
      console.log('离线状态，变更将在恢复连接后同步')
    }
  }
}

2.3 浏览器端数据探索：用 PGLite 替代在线 SQL 工具

对于 jsjson.com 这样的开发者工具站，PGLite 可以用来构建一个完全在浏览器中运行的 SQL 练习场——用户粘贴 JSON 数据，自动建表，然后用 SQL 查询：

// json-to-sql-playground.ts — JSON 数据转 SQL 查询的浏览器端工具
import { PGlite } from '@electric-sql/pglite'

async function createPlaygroundFromJson(jsonData: any[], tableName: string) {
  const db = new PGlite()
  await db.waitReady

  // 自动推断列类型
  const columns = inferColumns(jsonData[0])
  const createSQL = buildCreateTableSQL(tableName, columns)
  await db.exec(createSQL)

  // 批量插入数据
  for (const row of jsonData) {
    const fields = Object.keys(row)
    const values = Object.values(row)
    const placeholders = fields.map((_, i) => `$${i + 1}`).join(', ')
    
    await db.query(
      `INSERT INTO ${tableName} (${fields.join(', ')}) VALUES (${placeholders})`,
      values
    )
  }

  return db
}

function inferColumns(sample: Record<string, any>): Array<{ name: string; type: string }> {
  return Object.entries(sample).map(([key, value]) => {
    let type = 'TEXT'
    if (typeof value === 'number') {
      type = Number.isInteger(value) ? 'INTEGER' : 'DOUBLE PRECISION'
    } else if (typeof value === 'boolean') {
      type = 'BOOLEAN'
    } else if (value instanceof Date) {
      type = 'TIMESTAMPTZ'
    } else if (Array.isArray(value)) {
      type = 'JSONB'
    } else if (typeof value === 'object' && value !== null) {
      type = 'JSONB'
    }
    return { name: key, type }
  })
}

// 使用示例
const userData = [
  { name: '张三', age: 28, skills: ['JS', 'Python'], active: true },
  { name: '李四', age: 32, skills: ['Go', 'Rust'], active: false },
  { name: '王五', age: 25, skills: ['TypeScript'], active: true }
]

const db = await createPlaygroundFromJson(userData, 'users')

// 用户可以在浏览器中自由查询
const result = await db.query(`
  SELECT name, age, 
         jsonb_array_length(skills) AS skill_count
  FROM users 
  WHERE active = true 
  ORDER BY age DESC
`)
console.log(result.rows)
// [{ name: '张三', age: 28, skill_count: 2 }, { name: '王五', age: 25, skill_count: 1 }]

⚡ 三、性能实测与生产环境注意事项

3.1 性能基准测试

以下数据在 Chrome 126、MacBook Pro M3、16GB RAM 环境下测试：

⚠️ 警告： PGLite 的性能比原生 PostgreSQL 慢 5-10 倍，这是 WASM 运行时的固有开销。但对于浏览器端场景（数据量通常在万级以下），这个性能完全够用。不要试图用 PGLite 替代服务器端数据库——它的定位是开发、测试和离线场景。

3.2 内存管理：避免浏览器崩溃

WASM 的内存是预分配的线性内存，PGLite 默认 256MB。处理大数据集时需要注意：

// ❌ 错误写法 — 一次性加载所有数据到内存
const allData = await db.query('SELECT * FROM huge_table')  // 可能 OOM

// ✅ 正确写法 — 使用游标分批处理
await db.exec('DECLARE data_cursor CURSOR FOR SELECT * FROM huge_table')
const batch = await db.query('FETCH 100 FROM data_cursor')
// 处理完一批后再 FETCH 下一批

// ✅ 或者使用 LIMIT/OFFSET 分页
const PAGE_SIZE = 100
let offset = 0
while (true) {
  const page = await db.query(
    'SELECT * FROM huge_table ORDER BY id LIMIT $1 OFFSET $2',
    [PAGE_SIZE, offset]
  )
  if (page.rows.length === 0) break
  processPage(page.rows)
  offset += PAGE_SIZE
}

3.3 常见坑点与避坑指南

// pgvector 扩展使用示例
import { PGlite } from '@electric-sql/pglite'
import { vector } from '@electric-sql/pglite/vector'

const db = new PGlite({
  extensions: { vector }
})
await db.waitReady

// 创建向量表 — 在浏览器中做向量搜索！
await db.exec(`
  CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    embedding vector(384)  -- 384 维向量
  );
  
  -- 插入向量数据（通常由前端 embedding 模型生成）
  INSERT INTO documents (content, embedding) VALUES
    ('TypeScript 是 JavaScript 的超集', '[0.1, 0.2, ..., 0.3]'),
    ('PostgreSQL 支持 JSONB 数据类型', '[0.4, 0.1, ..., 0.2]');
  
  -- 向量相似度搜索
  SELECT content, embedding <=> '[0.15, 0.25, ..., 0.28]'::vector AS distance
  FROM documents
  ORDER BY distance
  LIMIT 5;
`)

💡 四、最佳实践与选型建议

4.1 什么时候该用 PGLite

• ✅ 开发环境：无需 Docker/本地 PostgreSQL，new PGlite() 即可开始
• ✅ 单元测试：每个测试用例独立的数据库实例，测试完即销毁
• ✅ Demo/原型：构建完全离线可运行的产品演示
• ✅ Local-First 应用：离线编辑，在线同步的架构模式
• ✅ 数据探索工具：让用户在浏览器中用 SQL 查询 JSON/CSV 数据
• ✅ 学习/教学：零配置的 PostgreSQL 学习环境

4.2 什么时候不该用 PGLite

• ❌ 替代生产数据库：PGLite 是单用户、单连接的嵌入式数据库
• ❌ 处理大数据集：超过 10 万行时性能会显著下降
• ❌ 多用户协作：没有内置的并发用户访问控制
• ❌ 需要高可用：没有复制、备份、故障转移能力

4.3 PGLite vs SQLite (OPFS)：如何选择

⚡ 关键结论： PGLite 的核心竞争力是与生产环境 PostgreSQL 的一致性。如果你的后端已经是 PostgreSQL，前端用 PGLite 可以实现 schema 共享、查询代码复用、开发环境零配置——这种一致性带来的开发效率提升，远超 3MB 的包体积增量。

🔧 五、相关工具推荐

• 🔧 @electric-sql/pglite — PGLite 核心库
• 🔧 Drizzle ORM — 类型安全的 TypeScript ORM，完美支持 PGLite
• 🔧 pglite-sync — PGLite 与 Electric SQL 的实时同步扩展
• 🔧 OPFS Explorer — Chrome DevTools 扩展，可视化查看 OPFS 文件
• 🔧 PGLite Fiddle — 官方在线 REPL，直接在浏览器中体验 PGLite

PGLite 代表了浏览器能力的一次质变——从「只能用 localStorage 存几 KB 数据」到「在浏览器中运行完整的关系型数据库」。虽然它不会取代服务器端的 PostgreSQL，但它为开发体验、离线优先架构和数据密集型前端应用打开了一扇新的大门。如果你的项目已经在用 PostgreSQL，没有理由不试试 PGLite。