@runlot/pg

env.db 위에서 node-postgres와 유사한 Pool·Client API를 제공합니다. 연결 문자열은 필요하지 않습니다.

env.db보다 node-postgres에 가까운 API를 원하면 @runlot/pg를 사용하세요.

import { Pool } from "@runlot/pg";

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const pool = new Pool({ db: env.db });
    const { rows } = await pool.query("select id, name from users where id = $1", [1]);
    return Response.json(rows);
  },
};

필요한 설정은 `db`뿐입니다

new Pool({ db: env.db });
new Client({ db: env.db });

호스트, 포트, 비밀번호를 설정하지 않습니다. node-postgres 호환을 위해 다른 옵션 키도 받지만 사용하지 않습니다. db를 빼면 다음 오류가 표시됩니다.

@runlot/pg: `db` 가 없어요 — new Pool({ db: env.db }) 로 만드세요.

제공하는 기능

pool.query(text, values) — 호출마다 새 세션을 엽니다. 단일 SQL 문에 적합합니다.
pool.connect() / new Client({ db }) — 세션 하나를 엽니다. BEGIN … COMMIT, prepared statement, SET 설정이 세션 안에서 유지됩니다. 사용 후 release() 또는 end()를 호출하세요.
오류는 DatabaseError로 던지며 err.code에서 SQLSTATE를 확인할 수 있습니다.
types.setTypeParser(oid, fn)으로 타입 변환을 바꿀 수 있습니다. 기본값은 pg와 같습니다. timestamptz와 date는 Date, int8과 numeric은 문자열입니다.

import { Pool, DatabaseError } from "@runlot/pg";

const pool = new Pool({ db: env.db });
try {
  await pool.query("insert into users (email) values ($1)", [email]);
} catch (e) {
  if (e instanceof DatabaseError && e.code === "23505") {
    return new Response("이미 있는 이메일입니다", { status: 409 });
  }
  throw e;
}

트랜잭션

const client = await pool.connect();
try {
  await client.query("begin");
  await client.query("update accounts set balance = balance - $1 where id = $2", [100, 1]);
  await client.query("update accounts set balance = balance + $1 where id = $2", [100, 2]);
  await client.query("commit");
} catch (e) {
  await client.query("rollback");
  throw e;
} finally {
  client.release();
}

pool.query()는 호출마다 새 세션을 사용하므로 호출 사이에 트랜잭션을 유지하지 않습니다. 트랜잭션에는 반드시 connect()를 사용하세요.

이름은 Pool이지만 연결을 재사용하지 않습니다

Pool이라는 이름과 달리 연결 풀링은 하지 않습니다. connect()를 호출할 때마다 새 엔진 세션을 엽니다. 이유는 세션을 참고하세요.

`nodejs_compat` 없이 사용할 수 있습니다

이 패키지는 Node 내장 모듈을 import하지 않습니다. EventEmitter 대신 최소한의 emitter를 사용하므로, 이 패키지만 사용하는 워커에는 호환성 플래그가 필요하지 않습니다.

배포 시 설정

추가 설정은 필요하지 않습니다. runlot deploy의 번들러는 pg import를 이 패키지로 해석합니다. ORM이 Node 내장 모듈을 사용하면 nodejs_compat을 자동으로 활성화하고, Prisma의 WASM 쿼리 컴파일러는 별도 모듈로 매니페스트에 포함합니다.

직접 번들링하는 경우에도 같은 번들러를 사용할 수 있습니다.

import { buildWorker } from "@runlot/pg/bundler";

const { code, report } = await buildWorker({ entry: "src/index.ts", absWorkingDir: process.cwd() });
// report.nodeImports가 비어 있지 않으면 nodejs_compat가 필요합니다.
// report.wasmModules는 배포에 함께 포함해야 하는 파일입니다.

필요한 설정은 db뿐입니다