브라우저 속 PostgreSQL: PGlite 실전 가이드

import { useLiveQuery } from '@electric-sql/pglite-react'
 
function TaskList() {
  const tasks = useLiveQuery<{ id: number; title: string; done: boolean }>(
    'SELECT * FROM tasks WHERE done = false ORDER BY created_at DESC'
  )
 
  return (
    <ul>
      {tasks?.rows.map(task => (
        <li key={task.id}>{task.title}</li>
      ))}
    </ul>
  )
}

pnpm add @electric-sql/pglite

import { PGlite } from '@electric-sql/pglite'
 
// 인메모리 (테스트용 — 새로고침 시 초기화)
const db = new PGlite()
 
// IndexedDB 영속성 (브라우저 앱)
const db = new PGlite('idb://my-app-db', {
  relaxedDurability: true, // fsync 완화 — 강제 종료 시 최근 쓰기 유실 가능
})
 
// OPFS (반드시 Web Worker 컨텍스트 안에서만)
const db = new PGlite('opfs://my-app-db')
 
// DDL은 exec() — 세미콜론으로 구분된 여러 문장 실행 가능
await db.exec(`
  CREATE TABLE IF NOT EXISTS tasks (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    done BOOLEAN DEFAULT false,
    created_at TIMESTAMPTZ DEFAULT NOW()
  )
`)
 
try {
  // 파라미터 바인딩은 query() — $1 형태로 SQL 인젝션 방지 및 플랜 재사용
  const result = await db.query<{ id: number; title: string }>(
    'SELECT id, title FROM tasks WHERE done = $1',
    [false]
  )
  console.log(result.rows)
} catch (err) {
  // IndexedDB는 스토리지 쿼터 초과 등으로 실패할 수 있습니다
  console.error('쿼리 실패:', err)
}

pnpm add drizzle-orm @electric-sql/pglite
pnpm add -D drizzle-kit

// schema.ts
import { pgTable, serial, text, boolean, timestamp } from 'drizzle-orm/pg-core'
 
export const tasks = pgTable('tasks', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  done: boolean('done').default(false),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow(),
})

// db.ts
import { PGlite } from '@electric-sql/pglite'
import { drizzle } from 'drizzle-orm/pglite'
import { migrate } from 'drizzle-orm/pglite/migrator'
import * as schema from './schema'
 
const client = new PGlite('idb://my-app-db', {
  relaxedDurability: true,
})
 
export const db = drizzle(client, { schema })
 
// 브라우저 마이그레이션: 서버와 달리 drizzle-kit push 대신 런타임에 직접 실행합니다.
// migrations 폴더를 번들에 포함시키고 앱 초기화 시 한 번 호출합니다.
export async function initDb() {
  try {
    await migrate(db, { migrationsFolder: './drizzle' })
  } catch (err) {
    console.error('마이그레이션 실패:', err)
    throw err
  }
}

// 사용 예시
import { db, initDb } from './db'
import { tasks } from './schema'
import { eq } from 'drizzle-orm'
 
await initDb() // 앱 진입점에서 한 번 호출
 
await db.insert(tasks).values({ title: '브라우저 DB 테스트' })
 
const pendingTasks = await db
  .select()
  .from(tasks)
  .where(eq(tasks.done, false))
  .orderBy(tasks.createdAt)
 
await db.update(tasks).set({ done: true }).where(eq(tasks.id, 1))

pnpm add @electric-sql/pglite-worker

// worker.ts (별도 파일로 분리, 번들러가 별도 청크로 처리)
import { PGlite } from '@electric-sql/pglite'
import { worker } from '@electric-sql/pglite/worker'
 
// worker() 함수로 초기화 — PGliteWorker.init()은 구버전 API입니다.
worker({
  async init() {
    return new PGlite('idb://my-app-db', { relaxedDurability: true })
  },
})

// main.ts
import { PGliteWorker } from '@electric-sql/pglite/worker'
 
let db: PGliteWorker
 
export async function getDb() {
  if (!db) {
    try {
      db = await PGliteWorker.create(
        new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
      )
    } catch (err) {
      console.error('Worker DB 초기화 실패:', err)
      throw err
    }
  }
  return db
}
 
// 이후 db 사용법은 일반 PGlite와 동일
const db = await getDb()
await db.query('SELECT * FROM tasks')

pnpm add @electric-sql/pglite-sync

import { PGlite } from '@electric-sql/pglite'
import { electricSync } from '@electric-sql/pglite-sync'
 
const db = new PGlite('idb://my-app-db', {
  relaxedDurability: true,
  extensions: { electric: electricSync() },
})
 
try {
  await db.electric.syncShapeToTable({
    shape: {
      url: 'https://your-electric-server.com/v1/shape',
      params: { table: 'tasks' },
    },
    table: 'tasks',
    primaryKey: ['id'],
  })
} catch (err) {
  // 네트워크 오류는 Electric이 내부적으로 재시도하지만,
  // 초기 연결 자체가 실패하는 경우는 앱 레벨에서 처리해야 합니다.
  console.error('동기화 설정 실패:', err)
}

// AES-GCM으로 암호화 후 IndexedDB 저장하는 패턴 (의사코드 수준)
async function encryptAndStore(db: PGlite, plaintext: string, key: CryptoKey) {
  const iv = crypto.getRandomValues(new Uint8Array(12))
  const encoded = new TextEncoder().encode(plaintext)
 
  const ciphertext = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv },
    key,
    encoded
  )
 
  // 암호화된 바이너리를 base64로 직렬화해서 저장
  const stored = btoa(String.fromCharCode(...new Uint8Array(ciphertext)))
  await db.query(
    'INSERT INTO secrets (iv, ciphertext) VALUES ($1, $2)',
    [btoa(String.fromCharCode(...iv)), stored]
  )
}
 
// 키는 IndexedDB가 아닌 Web Crypto Key Storage 또는 세션 메모리에 보관
// 기기에 평문 키를 저장하면 암호화 의미가 없습니다.

import { PGlite } from '@electric-sql/pglite'
import { vector } from '@electric-sql/pglite/vector'
 
const db = new PGlite('idb://ai-app-db', {
  extensions: { vector },
})
 
await db.exec(`
  CREATE EXTENSION IF NOT EXISTS vector;
 
  CREATE TABLE IF NOT EXISTS documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(384)
  );
 
  CREATE INDEX ON documents
  USING hnsw (embedding vector_cosine_ops);
`)
 
// @xenova/transformers로 클라이언트에서 임베딩 생성
// import { pipeline } from '@xenova/transformers'
// const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2')
// const output = await embedder('검색할 텍스트', { pooling: 'mean', normalize: true })
// const embedding = Array.from(output.data) // 384차원 float 배열
 
// 임베딩이 없을 때 테스트용 더미 벡터: Array.from({ length: 384 }, (_, i) => i * 0.001)
const dummyEmbedding = Array.from({ length: 384 }, (_, i) => i * 0.001)
 
try {
  await db.query(
    'INSERT INTO documents (content, embedding) VALUES ($1, $2::vector)',
    ['오프라인 퍼스트 앱 개발', JSON.stringify(dummyEmbedding)]
  )
 
  // 코사인 유사도 기반 검색
  const results = await db.query<{ content: string; similarity: number }>(
    `SELECT content, 1 - (embedding <=> $1::vector) AS similarity
     FROM documents
     ORDER BY embedding <=> $1::vector
     LIMIT 5`,
    [JSON.stringify(dummyEmbedding)]
  )
  console.log(results.rows)
} catch (err) {
  console.error('벡터 검색 실패:', err)
}

// ❌ 메인 스레드에서 실행하면 런타임 에러
const db = new PGlite('opfs://my-db')
 
// ✅ Web Worker 파일 안에서만 동작
// worker.ts 안에서:
const db = new PGlite('opfs://my-db')

// ❌ fsync를 매 쓰기마다 기다려 성능이 느림
const db = new PGlite('idb://my-db')
 
// ✅ WAL 플러시 완화로 성능 개선 — 단, 앱 강제 종료 시 최근 쓰기 유실 가능
const db = new PGlite('idb://my-db', {
  relaxedDurability: true,
})
// 금융 트랜잭션처럼 유실이 절대 허용 안 되는 데이터라면 false를 유지하세요.

// ❌ 마이그레이션 전에 쿼리 실행
const db = drizzle(client, { schema })
await db.select().from(tasks) // 테이블이 없을 수 있음
 
// ✅ 앱 진입점에서 마이그레이션을 먼저
await initDb() // migrate() 호출 포함
const results = await db.select().from(tasks)

// ❌ 두 번째 탭에서 같은 IndexedDB를 열면 잠금 충돌
const db = new PGlite('idb://my-db') // 탭마다 독립 인스턴스 — 충돌
 
// ✅ Worker를 통해 단일 인스턴스를 모든 탭이 공유
const db = await PGliteWorker.create(new Worker(...))