{"id":42478,"library":"bunqldb","title":"bunqldb","description":"bunqldb 0.4.2는 Bun 네이티브 SQL 클라이언트(Bun.sql)를 기반으로 한 MySQL/PostgreSQL 호환 데이터베이스 모듈입니다. 연결 풀링, AsyncLocalStorage 기반 트랜잭션(@Transactional 데코레이터), 템플릿 리터럴 재할당 방식의 동적 쿼리, 자동 camelCase 변환, dateStrings 옵션, 자동 재연결을 지원합니다. Active 개발 중이며, Bun >=1.0.0이 필요합니다. 기존 ORM과 달리 번들 경량성과 Bun 네이티브 성능을 활용하며, 문자열 기반 raw SQL 대신 템플릿 리터럴 재할당을 강제합니다.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/mayajuni/bunqldb","tags":["javascript","bun","sql","database","mysql","postgresql","orm","transaction","typescript"],"install":[{"cmd":"npm install bunqldb","lang":"bash","label":"npm"},{"cmd":"yarn add bunqldb","lang":"bash","label":"yarn"},{"cmd":"pnpm add bunqldb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"런타임 타입 및 SQL 타입 지원에 필요하며, bunqldb의 TypeScript 타입이 의존함","package":"bun-types","optional":true}],"imports":[{"note":"sql은 named export입니다. default export가 아닙니다.","wrong":"import sql from 'bunqldb'","symbol":"sql","correct":"import { sql } from 'bunqldb'"},{"note":"DB는 클래스로도 사용되나 ESM named export로 가져옵니다. CommonJS require도 가능하지만 ESM 사용을 권장합니다.","wrong":"const DB = require('bunqldb').DB","symbol":"DB","correct":"import { DB } from 'bunqldb'"},{"note":"데코레이터 이름은 대문자 T로 시작하는 PascalCase입니다.","wrong":"import { transactional } from 'bunqldb'","symbol":"Transactional","correct":"import { Transactional } from 'bunqldb'"},{"note":"모든 공개 API는 'bunqldb' 단일 진입점에서 export됩니다.","wrong":"import { getDbType } from 'bunqldb/helpers'","symbol":"getDbType","correct":"import { getDbType } from 'bunqldb'"}],"quickstart":{"code":"import { sql, DB } from 'bunqldb';\n\n// .env 또는 환경변수에 DATABASE_URL 설정 필요\n// 예: DATABASE_URL=postgres://user:pass@localhost:5432/mydb\n\n// 1. 조회\nconst users = await sql`SELECT * FROM users`;\nconsole.log(users);\n\n// 2. 파라미터 바인딩\nconst id = 1;\nconst user = await sql`SELECT * FROM users WHERE id = ${id}`;\n\n// 3. INSERT with RETURNING (PostgreSQL)\nconst name = 'Alice';\nconst email = 'alice@example.com';\nconst [newUser] = await sql`\n  INSERT INTO users (name, email)\n  VALUES (${name}, ${email})\n  RETURNING id, name, email\n`;\n\n// 4. DB 헬퍼 사용 (camelCase 자동 변환)\nconst allUsers = await DB.many<{ id: number; name: string; email: string }>(sql`SELECT * FROM users`);\n\n// 5. 템플릿 리터럴 재할당 동적 쿼리\nlet query = sql`SELECT * FROM users WHERE 1=1`;\nif (name) {\n  query = sql`${query} AND name = ${name}`;\n}\nquery = sql`${query} ORDER BY created_at DESC LIMIT 10`;\nconst result = await DB.many(query);\n\n// 6. 트랜잭션 사용\nimport { Transactional } from 'bunqldb';\n\nclass UserService {\n  @Transactional()\n  async createUser(name: string, email: string) {\n    const [user] = await sql`\n      INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *\n    `;\n    return user;\n  }\n}\n\n// 7. 연결 종료 (선택사항)\nawait DB.close();\n","lang":"typescript","description":"기본 쿼리, 파라미터 바인딩, INSERT RETURNING, DB 헬퍼, 동적 쿼리 재할당, 트랜잭션 데코레이터 사용법을 보여줍니다."},"warnings":[{"fix":"Bun v1.0.0 이상에서만 실행하세요.","message":"bunqldb는 Bun의 내장 sql 클라이언트에 의존하므로 Node.js에서는 동작하지 않습니다.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"sql`SELECT * FROM users WHERE id = ${id}` 형태로 변경하세요.","message":"문자열 기반 raw SQL 쿼리는 지원되지 않습니다. 모든 쿼리는 템플릿 리터럴(sql`...`)로 작성해야 합니다.","severity":"breaking","affected_versions":">=0.0.1"},{"fix":"DB.many(sql`...`)처럼 DB 헬퍼를 통해 결과를 받아야 camelCase 변환이 적용됩니다.","message":"자동 camelCase 변환은 DB.many 등 DB 헬퍼 메서드를 사용할 때만 적용됩니다. sql`...`로 직접 조회하면 변환되지 않습니다.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"대신 DB.paginate 또는 DB.cursorPaginate를 사용하세요.","message":"DB.manyPaging 및 DB.manyPagingParams 메서드는 레거시로 간주됩니다.","severity":"deprecated","affected_versions":">=0.4.0"},{"fix":"클래스의 메서드로 정의하고 @Transactional()을 붙이세요.","message":"@Transactional 데코레이터는 클래스 메서드에서만 동작하며, 화살표 함수나 일반 함수에는 사용할 수 없습니다.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"search_vec":"'0.4.2':3 '1.0.0':42 'activ':38 'asynclocalstorag':19 'bun':5,41,50,64 'bun.sql':9 'bunqldb':1,2 'camelcas':31 'databas':66 'datestr':33 'javascript':63 'mysql':67 'mysql/postgresql':13 'orm':69 'orm과':46 'postgresql':68 'raw':56 'sql':7,57,65 'transact':22,70 'typescript':71 '강제합니다':62 '개발':39 '경량성과':49 '기반':20,55 '기반으로':11 '기존':45 '네이티브':6,51 '는':4 '달리':47 '대신':58 '데이터베이스':15 '데코레이터':23 '동적':28 '를':10 '리터럴':25,60 '모듈입니다':16 '문자열':54 '방식의':27 '번들':48 '변환':32 '성능을':52 '연결':17 '옵션':34 '이':43 '자동':30,35 '재연결을':36 '재할당':26 '재할당을':61 '중이며':40 '지원합니다':37 '쿼리':29 '클라이언트':8 '템플릿':24,59 '트랜잭션':21 '풀링':18 '필요합니다':44 '한':12 '호환':14 '활용하며':53","created_at":"2026-06-05T16:55:10.155905+00:00","updated_at":"2026-06-05T16:55:10.155905+00:00","problems":[{"fix":"import { sql } from 'bunqldb'로 수정하세요.","cause":"잘못된 import 방식 (default import) 사용","error":"error: Module 'bunqldb' has no exported member 'sql'"},{"fix":"Bun 실행 전 .env 파일에 DATABASE_URL을 설정하거나 환경변수를 export하세요.","cause":"DATABASE_URL 또는 DB 환경변수가 설정되지 않아 연결이 초기화되지 않음","error":"TypeError: Cannot read properties of undefined (reading 'query')"},{"fix":"bun add -d bun-types 실행","cause":"bun-types가 설치되지 않음 (peer dependency)","error":"error: Cannot find package 'bun-types'"},{"fix":"쿼리는 반드시 템플릿 리터럴로 작성: sql`SELECT * FROM users`","cause":"sql`...` 대신 일반 문자열로 sql()을 호출함","error":"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'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/mayajuni/bunqldb#readme","github":"https://github.com/mayajuni/bunqldb","docs":null,"changelog":null,"pypi":null,"npm":"bunqldb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}