Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sql
✓ import { sql } from 'bunqldb'
✗ import sql from 'bunqldb'
sql은 named export입니다. default export가 아닙니다.
DB
✓ import { DB } from 'bunqldb'
✗ const DB = require('bunqldb').DB
DB는 클래스로도 사용되나 ESM named export로 가져옵니다. CommonJS require도 가능하지만 ESM 사용을 권장합니다.
Transactional
✓ import { Transactional } from 'bunqldb'
✗ import { transactional } from 'bunqldb'
데코레이터 이름은 대문자 T로 시작하는 PascalCase입니다.
getDbType
✓ import { getDbType } from 'bunqldb'
✗ import { getDbType } from 'bunqldb/helpers'
모든 공개 API는 'bunqldb' 단일 진입점에서 export됩니다.
기본 쿼리, 파라미터 바인딩, INSERT RETURNING, DB 헬퍼, 동적 쿼리 재할당, 트랜잭션 데코레이터 사용법을 보여줍니다.
import { sql, DB } from 'bunqldb';
// .env 또는 환경변수에 DATABASE_URL 설정 필요
// 예: DATABASE_URL=postgres://user:pass@localhost:5432/mydb
// 1. 조회
const users = await sql`SELECT * FROM users`;
console.log(users);
// 2. 파라미터 바인딩
const id = 1;
const user = await sql`SELECT * FROM users WHERE id = ${id}`;
// 3. INSERT with RETURNING (PostgreSQL)
const name = 'Alice';
const email = 'alice@example.com';
const [newUser] = await sql`
INSERT INTO users (name, email)
VALUES (${name}, ${email})
RETURNING id, name, email
`;
// 4. DB 헬퍼 사용 (camelCase 자동 변환)
const allUsers = await DB.many<{ id: number; name: string; email: string }>(sql`SELECT * FROM users`);
// 5. 템플릿 리터럴 재할당 동적 쿼리
let query = sql`SELECT * FROM users WHERE 1=1`;
if (name) {
query = sql`${query} AND name = ${name}`;
}
query = sql`${query} ORDER BY created_at DESC LIMIT 10`;
const result = await DB.many(query);
// 6. 트랜잭션 사용
import { Transactional } from 'bunqldb';
class UserService {
@Transactional()
async createUser(name: string, email: string) {
const [user] = await sql`
INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *
`;
return user;
}
}
// 7. 연결 종료 (선택사항)
await DB.close();
Errors
Common errors & fixes
error: Module 'bunqldb' has no exported member 'sql'
잘못된 import 방식 (default import) 사용
fiximport { sql } from 'bunqldb'로 수정하세요. TypeError: Cannot read properties of undefined (reading 'query')
DATABASE_URL 또는 DB 환경변수가 설정되지 않아 연결이 초기화되지 않음
fixBun 실행 전 .env 파일에 DATABASE_URL을 설정하거나 환경변수를 export하세요.
error: Cannot find package 'bun-types'
bun-types가 설치되지 않음 (peer dependency)
fixbun add -d bun-types 실행
error: No function overload matches this call. Overload 1 of 2, '(strings: TemplateStringsArray, ...values: any[]): Promise<...>', gave the following error. Argument of type 'string' is not assignable to parameter of type 'TemplateStringsArray'.
sql`...` 대신 일반 문자열로 sql()을 호출함
fix쿼리는 반드시 템플릿 리터럴로 작성: sql`SELECT * FROM users`
Audit
Dependencies
bun-typesoptional런타임 타입 및 SQL 타입 지원에 필요하며, bunqldb의 TypeScript 타입이 의존함