feat: expose raw sqlite client in sql-sqlite-bun and sql-sqlite-node

.changeset/crazy-icons-rush.md

@@ -0,0 +1,36 @@
+---
+"@effect/sql-sqlite-node": minor
+"@effect/sql-sqlite-bun": minor
+---
+
+## Raw Database Client Access
+
+Both `@effect/sql-sqlite-node` and `@effect/sql-sqlite-bun` now expose the underlying database client through a new `rawClient` property. This provides direct access to the native database APIs when needed for advanced operations.
+
+**Example**
+
+```ts
+import { SqliteClient } from "@effect/sql-sqlite-bun"
+import { Effect } from "effect"
+
+const program = Effect.gen(function* () {
+  const client = yield* SqliteClient.make({ filename: "test.db" })
+
+  // Access the raw Bun SQLite Database instance
+  const rawDb = yield* client.rawClient
+
+  // Use native database methods directly
+  const result = yield* Effect.try(() =>
+    rawClient.prepare("SELECT * FROM users").all()
+  )
+
+  return result
+})
+```
+
+The `rawClient` property returns:
+
+- `Effect<Database>` for `@effect/sql-sqlite-bun` (Bun's native SQLite Database)
+- `Effect<Database>` for `@effect/sql-sqlite-node` (better-sqlite3 Database)
+
+This enables users to access vendor-specific functionality while maintaining the Effect-based workflow.

packages/sql-sqlite-bun/examples/Client.test.ts

@@ -17,6 +17,7 @@ describe("Client", () => {
   test("works", () =>
     Effect.gen(function*() {
       const sql = yield* makeClient
+      const rawClient = yield* sql.rawClient
       yield* sql`CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)`
       yield* sql`INSERT INTO test (name) VALUES ('hello')`
       let rows = yield* sql`SELECT * FROM test`
@@ -27,5 +28,10 @@ describe("Client", () => {
         { id: 1, name: "hello" },
         { id: 2, name: "world" }
       ])
+      const rawRows = yield* Effect.try(() => rawClient.query("SELECT * FROM test").all())
+      expect(rawRows).toEqual([
+        { id: 1, name: "hello" },
+        { id: 2, name: "world" }
+      ])
     }).pipe(Effect.scoped, Effect.runPromise))
 })

packages/sql-sqlite-bun/src/SqliteClient.ts

@@ -15,6 +15,12 @@ import { identity } from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
 
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export type { Database }
+
 const ATTR_DB_SYSTEM_NAME = "db.system.name"
 
 /**
@@ -36,6 +42,7 @@ export type TypeId = typeof TypeId
 export interface SqliteClient extends Client.SqlClient {
   readonly [TypeId]: TypeId
   readonly config: SqliteClientConfig
+  readonly rawClient: Effect.Effect<Database>
   readonly export: Effect.Effect<Uint8Array, SqlError>
   readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
 
@@ -67,6 +74,7 @@ export interface SqliteClientConfig {
 }
 
 interface SqliteConnection extends Connection {
+  readonly database: Database
   readonly export: Effect.Effect<Uint8Array, SqlError>
   readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
 }
@@ -117,6 +125,7 @@ export const make = (
         })
 
       return identity<SqliteConnection>({
+        database: db,
         execute(sql, params, transformRows) {
           return transformRows
             ? Effect.map(run(sql, params), transformRows)
@@ -177,6 +186,7 @@ export const make = (
       {
         [TypeId]: TypeId as TypeId,
         config: options,
+        rawClient: Effect.flatMap(acquirer, (_) => Effect.succeed(_.database)),
         export: Effect.flatMap(acquirer, (_) => _.export),
         loadExtension: (path: string) => Effect.flatMap(acquirer, (_) => _.loadExtension(path))
       }

packages/sql-sqlite-node/src/SqliteClient.ts

@@ -17,6 +17,12 @@ import { identity } from "effect/Function"
 import * as Layer from "effect/Layer"
 import * as Scope from "effect/Scope"
 
+/**
+ * @category models
+ * @since 1.0.0
+ */
+export type Database = Sqlite.Database
+
 const ATTR_DB_SYSTEM_NAME = "db.system.name"
 
 /**
@@ -38,6 +44,7 @@ export type TypeId = typeof TypeId
 export interface SqliteClient extends Client.SqlClient {
   readonly [TypeId]: TypeId
   readonly config: SqliteClientConfig
+  readonly rawClient: Effect.Effect<Database>
   readonly export: Effect.Effect<Uint8Array, SqlError>
   readonly backup: (destination: string) => Effect.Effect<BackupMetadata, SqlError>
   readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
@@ -78,6 +85,7 @@ export interface SqliteClientConfig {
 }
 
 interface SqliteConnection extends Connection {
+  readonly database: Database
   readonly export: Effect.Effect<Uint8Array, SqlError>
   readonly backup: (destination: string) => Effect.Effect<BackupMetadata, SqlError>
   readonly loadExtension: (path: string) => Effect.Effect<void, SqlError>
@@ -173,6 +181,7 @@ export const make = (
         )
 
       return identity<SqliteConnection>({
+        database: db,
         execute(sql, params, transformRows) {
           return transformRows
             ? Effect.map(run(sql, params), transformRows)
@@ -241,6 +250,7 @@ export const make = (
       {
         [TypeId]: TypeId as TypeId,
         config: options,
+        rawClient: Effect.flatMap(acquirer, (_) => Effect.succeed(_.database)),
         export: Effect.flatMap(acquirer, (_) => _.export),
         backup: (destination: string) => Effect.flatMap(acquirer, (_) => _.backup(destination)),
         loadExtension: (path: string) => Effect.flatMap(acquirer, (_) => _.loadExtension(path))

packages/sql-sqlite-node/test/Client.test.ts

@@ -52,6 +52,16 @@ describe("Client", () => {
       ])
     }))
 
+  it.scoped("should work with rawClient", () =>
+    Effect.gen(function*() {
+      const sql = yield* makeClient
+      const rawClient = yield* sql.rawClient
+      yield* Effect.sync(() => rawClient.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)"))
+      yield* Effect.sync(() => rawClient.exec("INSERT INTO test (name) VALUES ('hello')"))
+      const rows = yield* Effect.try(() => rawClient.prepare("SELECT * FROM test").all())
+      assert.deepStrictEqual(rows, [{ id: 1, name: "hello" }])
+    }))
+
   it.scoped("withTransaction", () =>
     Effect.gen(function*() {
       const sql = yield* makeClient