深入解析PGlite数据库API使用指南

深入解析PGlite数据库API使用指南

pglite 项目地址: https://gitcode.com/gh_mirrors/pg/pglite

前言

PGlite是一个轻量级的PostgreSQL兼容数据库解决方案，专为现代JavaScript应用设计。本文将全面介绍PGlite的核心API功能，帮助开发者快速掌握其使用方法。

核心概念

PGlite提供了完整的PostgreSQL功能，但以更轻量的方式运行在浏览器、Node.js和Bun等环境中。它支持标准SQL语法、事务、存储过程等PostgreSQL特性。

初始化数据库

创建实例

PGlite提供了两种创建数据库实例的方式：

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

// 推荐方式 - 静态工厂方法
const pg1 = await PGlite.create({
  dataDir: 'memory://',  // 使用内存存储
  debug: 3
})

// 传统构造函数方式
const pg2 = new PGlite('file:///path/to/db')

静态工厂方法的优势：

1. 自动等待数据库初始化完成
2. 更好的TypeScript类型推断支持
3. 更简洁的异步初始化流程

存储选项

PGlite支持多种存储后端：

• file:// - 文件系统存储（Node.js/Bun环境）
• idb:// - 浏览器IndexedDB存储
• memory:// - 内存临时存储（所有环境）

配置参数详解

初始化时可配置的重要参数：

const pg = await PGlite.create({
  dataDir: 'idb://my-db',  // 存储位置
  debug: 3,                // 调试级别1-5
  relaxedDurability: true, // 提升性能但降低持久性保证
  extensions: {            // 加载扩展
    live: liveExtension,
    vector: vectorExtension
  },
  parsers: {              // 自定义类型解析
    [types.TEXT]: (val) => val.toUpperCase()
  },
  serializers: {          // 自定义类型序列化
    [types.NUMERIC]: (val) => val.toString()
  }
})

数据操作API

基本查询

// 带参数查询
const result = await pg.query(
  'SELECT * FROM users WHERE age > $1', 
  [18]
)

// 模板字符串查询
const name = 'Alice'
const user = await pg.sql`SELECT * FROM users WHERE name = ${name}`

批量执行

// 执行多条SQL语句
const results = await pg.exec(`
  CREATE TABLE IF NOT EXISTS products (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL
  );
  INSERT INTO products (name) VALUES ('Laptop');
  SELECT * FROM products;
`)

事务处理

await pg.transaction(async (tx) => {
  await tx.query(`UPDATE accounts SET balance = balance - 100 WHERE id = 1`)
  await tx.query(`UPDATE accounts SET balance = balance + 100 WHERE id = 2`)
  
  // 如需回滚
  if (somethingWrong) {
    tx.rollback()
  }
})

高级功能

通知系统

// 订阅通知
const unsubscribe = await pg.listen('updates', (payload) => {
  console.log('收到更新:', payload)
})

// 发送通知
await pg.query("NOTIFY updates, '数据已变更'")

// 取消订阅
await unsubscribe()

数据导入导出

// 导出数据库
const backup = await pg.dumpDataDir('gzip')

// 导入数据库
const restoredPg = await PGlite.create({
  loadDataDir: backup
})

类型系统

// 查询类型信息
const typeInfo = await pg.describeQuery(
  'SELECT * FROM products WHERE price > $1',
  [100]
)

// 刷新数组类型缓存
await pg.refreshArrayTypes()

性能优化技巧

1. 对于频繁的小查询，使用relaxedDurability模式提升性能
2. 合理设置initialMemory避免运行时内存扩展开销
3. 批量操作使用事务减少I/O次数
4. 浏览器环境中优先使用IndexedDB存储

常见问题

Q: 如何处理大文件导入？

A: 使用/dev/blob虚拟设备配合COPY命令：

const file = new Blob(['id,name\n1,Test'])
await pg.query('COPY products FROM '/dev/blob'', null, {
  blob: file
})

Q: 如何复用数据库连接？

A: 使用clone()方法创建轻量级副本：

const pg2 = await pg.clone()

结语

PGlite为JavaScript应用带来了完整的PostgreSQL功能，同时保持了轻量级和跨平台的特性。通过本文介绍的API，开发者可以充分利用PostgreSQL的强大功能构建各种应用。无论是简单的数据存储还是复杂的业务逻辑，PGlite都能提供可靠的支持。

pglite 项目地址: https://gitcode.com/gh_mirrors/pg/pglite