직접 연결과 풀

SQLBraid는 duck typing으로 풀을 감지하는 대신 소유권을 명시적으로 만듭니다.

직접 리소스

@sqlbraid/runtime의 createDatabase(executor)와 어댑터별 직접 팩토리는 하나의 물리적 실행 리소스를 감쌉니다. PostgreSQL은 연결된 pg.Client 또는 pg.PoolClient를 받고, MySQL은 mysql2/promise의 해결된 Connection 또는 PoolConnection 객체를 받으며, SQLite는 DatabaseSync 호환 리소스를 받습니다.

const db = createPgDatabase(client);
const db = createMysql2Database(connection);
const db = createNodeSqliteDatabase(native);

소유권 키를 공유하는 직접 wrapper는 물리 작업을 직렬화합니다. 직접 리소스 종료는 애플리케이션이 담당합니다.

풀

명시적인 풀 팩토리를 사용하세요.

const pgDb = createPgPoolDatabase(pgPool);
const mysqlDb = createMysql2PoolDatabase(mysqlPool);
const mariadbDb = createMariaDbPoolDatabase(mariadbPool);
const customDb = createPooledDatabase(connectionProvider);

Provider의 acquire()는 executor와 release({ discard })가 있는 ConnectionLease 하나를 반환합니다. 독립적인 각 풀 루트 작업은 lease 하나를 얻어 DB I/O를 수행하고 반환한 뒤 구체화된 결과를 매핑합니다. 풀 종료는 애플리케이션이 소유합니다.

Provider는 불변 statementBinding 어댑터를 노출합니다. 바인딩 설명과 힌트 검증은 acquire() 전에 수행하며, 모든 lease는 정확히 같은 어댑터 객체를 사용해야 합니다. lease가 전송이나 dialect identity를 조용히 바꾸면 안 됩니다.

풀은 가짜 executor가 아닙니다. BEGIN, 쿼리, COMMIT이 서로 다른 물리적 연결에 도착할 수 있다면 트랜잭션은 실제 트랜잭션이 아닙니다. lease를 고정하려면 db.tx(...)를 사용하세요.

db.session(async (session) => ...)은 callback 동안 하나의 lease를 고정합니다. 중첩 session은 이를 재사용하고 session 안의 db.tx(...)도 재획득하지 않습니다. 바깥 root database로 이 범위를 빠져나갈 수 없습니다. Stream은 cursor/request cleanup까지 lease를 유지합니다. Provider/session primitive를 사용할 수 없으면 BRAID_SESSION_UNSUPPORTED로 실패합니다.

이미 abort된 signal은 자신의 reason을 보존합니다. 활성 cancellation은 driver capability이며, 없으면 I/O 전에 UnsupportedFeatureError / BRAID_CANCEL_UNSUPPORTED로 실패합니다. Transaction option은 acquire 전에 검증됩니다. malformed 값은 TypeError / BRAID_TX_OPTIONS_INVALID, 유효하지만 지원하지 않는 값은 BRAID_TX_OPTION_UNSUPPORTED, 중첩 명시 option은 BRAID_TX_OPTIONS_NESTED를 사용합니다.