feat: export database instances (#132)

src/connectors/better-sqlite3.ts

@@ -29,9 +29,10 @@ export default function sqliteConnector(opts: ConnectorOptions) {
     return _db;
   };
 
-  return <Connector>{
+  return <Connector<Database.Database>>{
     name: "sqlite",
     dialect: "sqlite",
+    getInstance: () => getDB(),
     exec(sql: string) {
       return getDB().exec(sql);
     },

src/connectors/bun-sqlite.ts

@@ -29,9 +29,10 @@ export default function bunSqliteConnector(opts: ConnectorOptions) {
     return _db;
   };
 
-  return <Connector>{
+  return <Connector<Database>>{
     name: "sqlite",
     dialect: "sqlite",
+    getInstance: () => getDB(),
     exec(sql: string) {
       return getDB().exec(sql);
     },

src/connectors/cloudflare-d1.ts

@@ -17,6 +17,7 @@ export default function cloudflareD1Connector(options: ConnectorOptions) {
   return <Connector>{
     name: "cloudflare-d1",
     dialect: "sqlite",
+    getInstance: () => getDB(),
     exec: (sql: string) => getDB().exec(sql),
     prepare: (sql: string) => {
       const _stmt = getDB().prepare(sql);

src/connectors/libsql/core.ts

@@ -12,9 +12,10 @@ export default function libSqlCoreConnector(opts: ConnectorOptions) {
     return client.execute(sql);
   }
 
-  return <Connector>{
+  return <Connector<Client>>{
     name: opts.name || "libsql-core",
     dialect: "libsql",
+    getInstance: async () => opts.getClient(),
     exec(sql: string) {
       return query(sql);
     },

src/connectors/mysql2.ts

@@ -18,9 +18,10 @@ export default function mysqlConnector(opts: ConnectorOptions) {
     return _connection;
   };
 
-  return <Connector>{
+  return <Connector<mysql.Connection>>{
     name: "mysql",
     dialect: "mysql",
+    getInstance: () => getConnection(),
     exec(sql: string) {
       return getConnection().then((c) => c.query(sql).then((res) => res[0]));
     },

src/connectors/pglite.ts

@@ -21,9 +21,10 @@ export default function pgliteConnector(opts: ConnectorOptions = {}) {
     return result;
   }
 
-  return <Connector>{
+  return <Connector<PGlite>>{
     name: "pglite",
     dialect: "postgresql",
+    getInstance: () => getClient(),
     exec(sql: string) {
       return query(sql);
     },

src/connectors/planetscale.ts

@@ -22,9 +22,10 @@ export default function planetscaleConnector(opts: ConnectorOptions) {
     return client.execute(sql, params);
   }
 
-  return <Connector>{
+  return <Connector<Client>>{
     name: "planetscale",
     dialect: "mysql",
+    getInstance: () => getClient(),
     exec(sql: string) {
       return query(sql);
     },

src/connectors/postgresql.ts

@@ -23,9 +23,10 @@ export default function postgresqlConnector(opts: ConnectorOptions) {
     return client.query(normalizeParams(sql), params);
   }
 
-  return <Connector>{
+  return <Connector<pg.Client>>{
     name: "postgresql",
     dialect: "postgresql",
+    getInstance: () => getClient(),
     exec(sql: string) {
       return query(sql);
     },

src/database.ts

@@ -11,12 +11,18 @@ const SQL_WITH_RES_RE = /^select/i;
  * @param {Connector} connector - The database connector used to execute and prepare SQL statements. See {@link Connector}.
  * @returns {Database} The database interface that allows SQL operations. See {@link Database}.
  */
-export function createDatabase(connector: Connector): Database {
-  return <Database>{
+export function createDatabase<TConnector extends Connector = Connector>(
+  connector: TConnector,
+): Database<TConnector> {
+  return <Database<TConnector>>{
     get dialect() {
       return connector.dialect;
     },
 
+    getInstance() {
+      return connector.getInstance();
+    },
+
     exec: (sql: string) => {
       return Promise.resolve(connector.exec(sql));
     },

src/types.ts

@@ -43,7 +43,7 @@ export type ExecResult = unknown;
 /**
  * Defines a database connector for executing SQL queries and preparing statements.
  */
-export type Connector = {
+export type Connector<TInstance = any> = {
   /**
    * The name of the connector.
    */
@@ -54,6 +54,11 @@ export type Connector = {
    */
   dialect: SQLDialect;
 
+  /**
+   * The client instance used internally.
+   */
+  getInstance: () => TInstance | Promise<TInstance>;
+
   /**
    * Executes an SQL query directly and returns the result.
    * @param {string} sql - The SQL string to execute.
@@ -79,9 +84,15 @@ type DefaultSQLResult = {
   rows?: { id?: string | number; [key: string]: unknown }[];
 };
 
-export interface Database {
+export interface Database<TConnector extends Connector = Connector> {
   readonly dialect: SQLDialect;
 
+  /**
+   * The client instance used internally.
+   * @returns {Promise<TInstance>} A promise that resolves with the client instance.
+   */
+  getInstance: () => Promise<TConnector["getInstance"]>;
+
   /**
    * Executes a raw SQL string.
    * @param {string} sql - The SQL string to execute.

test/connectors/_tests.ts

@@ -1,14 +1,20 @@
 import { beforeAll, expect, it } from "vitest";
 import { Connector, Database, createDatabase, type SQLDialect } from "../../src";
 
-export function testConnector(opts: { connector: Connector, dialect: SQLDialect }) {
-  let db: Database;
+export function testConnector<TConnector extends Connector = Connector>(opts: { connector: TConnector, dialect: SQLDialect }) {
+  let db: Database<TConnector>;
   beforeAll(() => {
     db = createDatabase(opts.connector);
   });
 
   const userId = "1001";
 
+  it("instance matches", async () => {
+    const instance = await db.getInstance();
+    expect(instance).toBeDefined();
+    expect(instance).toBe(await opts.connector.getInstance());
+  })
+
   it("dialect matches", () => {
     expect(db.dialect).toBe(opts.dialect);
   })

test/integrations/drizzle.test.ts

@@ -57,7 +57,7 @@ describe.runIf(process.env.POSTGRESQL_URL)("integrations: drizzle: postgres", ()
   });
 
   let drizzleDb: DrizzleDatabase;
-  let db: Database;
+  let db: Database<ReturnType<typeof pgConnector>>;
 
   beforeAll(async () => {
     db = createDatabase(pgConnector({