effect-start 0.26.0 → 0.28.0

package/src/sql/SqlCache.ts

@@ -0,0 +1,50 @@
+import * as Cache from "effect/Cache"
+import * as Context from "effect/Context"
+import type * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import type * as SqlClient from "./SqlClient.ts"
+
+type SqlCacheInstance = Cache.Cache<string, ReadonlyArray<any>>
+
+export class SqlCache extends Context.Tag("effect-start/SqlCache")<SqlCache, SqlCacheInstance>() {}
+
+export function layer(options: {
+  readonly capacity: number
+  readonly timeToLive: Duration.DurationInput
+}): Layer.Layer<SqlCache> {
+  return Layer.effect(
+    SqlCache,
+    Cache.make<string, ReadonlyArray<any>>({
+      capacity: options.capacity,
+      timeToLive: options.timeToLive,
+      lookup: (key) => Effect.die(`cache miss without populate for key: ${key}`),
+    }),
+  )
+}
+
+export function withCache(
+  cache: SqlCacheInstance,
+): <A extends object>(
+  self: SqlClient.SqlEffect<A>,
+) => Effect.Effect<ReadonlyArray<A>, SqlClient.SqlError>
+export function withCache(): <A extends object>(
+  self: SqlClient.SqlEffect<A>,
+) => Effect.Effect<ReadonlyArray<A>, SqlClient.SqlError, SqlCache>
+export function withCache(cache?: SqlCacheInstance) {
+  return <A extends object>(self: SqlClient.SqlEffect<A>) => {
+    const key = JSON.stringify({ sql: self.sql, parameters: self.parameters })
+    if (cache) {
+      return Effect.flatMap(cache.getOption(key), (option) => {
+        if (option._tag === "Some") return Effect.succeed(option.value as ReadonlyArray<A>)
+        return Effect.tap(self, (result) => cache.set(key, result))
+      })
+    }
+    return Effect.flatMap(SqlCache, (c) =>
+      Effect.flatMap(c.getOption(key), (option) => {
+        if (option._tag === "Some") return Effect.succeed(option.value as ReadonlyArray<A>)
+        return Effect.tap(self, (result) => c.set(key, result))
+      }),
+    )
+  }
+}

package/src/sql/SqlClient.ts

@@ -0,0 +1,400 @@
+import * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
+import * as Data from "effect/Data"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as FiberRef from "effect/FiberRef"
+import * as GlobalValue from "effect/GlobalValue"
+import type * as Scope from "effect/Scope"
+import * as Values from "../Values.ts"
+
+export class SqlError extends Data.TaggedError("SqlError")<{
+  readonly code: string
+  readonly message: string
+  readonly cause?: unknown
+}> {}
+
+export interface DialectConfig {
+  readonly placeholder: (index: number) => string
+  readonly identifier: (name: string) => string
+}
+
+export type SqlRow = Record<string, unknown>
+
+export type SqlEffect<A extends object = SqlRow> = Effect.Effect<ReadonlyArray<A>, SqlError> & {
+  readonly sql: string
+  readonly parameters: ReadonlyArray<unknown>
+}
+
+export interface Connection {
+  /**
+   * Execute a parameterized query via tagged template literal
+   */
+  <A extends object = SqlRow>(
+    strings: TemplateStringsArray,
+    ...values: Array<unknown>
+  ): SqlEffect<A>
+  /**
+   * Create a safely-escaped SQL identifier from a string
+   */
+  (name: string): unknown
+  /**
+   * Build a VALUES clause from an object or array of objects,
+   * optionally picking specific columns
+   */
+  <T extends Record<string, unknown>, K extends keyof T>(
+    obj: T | ReadonlyArray<T>,
+    columns?: [K, ...Array<K>],
+  ): unknown
+  /**
+   * Build an IN-list from an array of primitive values
+   */
+  (values: ReadonlyArray<string | number | boolean | null>): unknown
+
+  /**
+   * Execute a raw SQL string without tagged template escaping
+   */
+  readonly unsafe: <A extends object = SqlRow>(
+    query: string,
+    values?: Array<unknown>,
+  ) => SqlEffect<A>
+}
+
+export type UnsafeQuery = <A extends object = SqlRow>(
+  query: string,
+  values?: Array<unknown>,
+) => Effect.Effect<ReadonlyArray<A>, SqlError>
+
+export interface SqlClient extends Connection {
+  /**
+   * Run an effect inside a transaction
+   */
+  readonly withTransaction: <A, E, R>(
+    self: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, SqlError | E, R>
+
+  /**
+   * Reserve a dedicated connection from the pool
+   */
+  readonly reserve: Effect.Effect<Connection, SqlError, Scope.Scope>
+
+  /**
+   * Access the underlying database driver directly
+   */
+  readonly use: <T>(fn: (driver: any) => Promise<T> | T) => Effect.Effect<T, SqlError>
+}
+
+export const SqlClient: Context.Tag<SqlClient, SqlClient> = Context.GenericTag<SqlClient>(
+  "effect-start/Sql/SqlClient",
+)
+
+export type TaggedQuery = <A extends object = SqlRow>(
+  strings: TemplateStringsArray,
+  ...values: Array<unknown>
+) => Effect.Effect<ReadonlyArray<A>, SqlError>
+
+export interface MakeOptions {
+  readonly withTransaction: SqlClient["withTransaction"]
+  readonly reserve: SqlClient["reserve"]
+  readonly use: SqlClient["use"]
+  readonly unsafe: UnsafeQuery
+  readonly query: TaggedQuery
+  readonly spanAttributes: ReadonlyArray<readonly [string, unknown]>
+  readonly dialect: DialectConfig
+}
+
+export function make(options: MakeOptions): SqlClient {
+  const trace = makeTraceOptions(options.spanAttributes, options.dialect)
+  const baseQuery = withExecuteSpan(options.query, trace)
+  const baseUnsafe = withUnsafeExecuteSpan(options.unsafe, trace)
+  const withTransaction = withTransactionSpan(options.withTransaction, trace.spanAttributes)
+
+  const query: TaggedQuery = <A extends object = SqlRow>(
+    strings: TemplateStringsArray,
+    ...values: Array<unknown>
+  ): SqlEffect<A> =>
+    Object.assign(baseQuery<A>(strings, ...values), {
+      sql: renderTemplateSql(trace.dialect, strings, values),
+      parameters: values,
+    }) as SqlEffect<A>
+
+  const unsafe: Connection["unsafe"] = <A extends object = SqlRow>(
+    queryStr: string,
+    values?: Array<unknown>,
+  ): SqlEffect<A> =>
+    Object.assign(baseUnsafe<A>(queryStr, values), {
+      sql: queryStr,
+      parameters: values ?? [],
+    }) as SqlEffect<A>
+
+  return Object.assign(dispatchCallable(query), {
+    ...options,
+    query,
+    unsafe,
+    withTransaction,
+  }) as unknown as SqlClient
+}
+
+export function connection(
+  query: TaggedQuery,
+  unsafe: UnsafeQuery,
+  options?: {
+    readonly spanAttributes?: ReadonlyArray<readonly [string, unknown]>
+    readonly dialect?: DialectConfig
+  },
+): Connection {
+  const trace = makeTraceOptions(options?.spanAttributes, options?.dialect)
+  const tracedQuery = withExecuteSpan(query, trace)
+  const tracedUnsafe = withUnsafeExecuteSpan(unsafe, trace)
+
+  const wrappedQuery: TaggedQuery = <A extends object = SqlRow>(
+    strings: TemplateStringsArray,
+    ...values: Array<unknown>
+  ): SqlEffect<A> =>
+    Object.assign(tracedQuery<A>(strings, ...values), {
+      sql: renderTemplateSql(trace.dialect, strings, values),
+      parameters: values,
+    }) as SqlEffect<A>
+
+  const wrappedUnsafe: Connection["unsafe"] = <A extends object = SqlRow>(
+    query: string,
+    values?: Array<unknown>,
+  ): SqlEffect<A> =>
+    Object.assign(tracedUnsafe<A>(query, values), {
+      sql: query,
+      parameters: values ?? [],
+    }) as SqlEffect<A>
+
+  return Object.assign(dispatchCallable(wrappedQuery), {
+    unsafe: wrappedUnsafe,
+  }) as unknown as Connection
+}
+
+function dispatchCallable(query: TaggedQuery) {
+  return (first: any, ...rest: Array<any>) => {
+    if (Values.isTemplateStringsArray(first)) return query(first, ...rest)
+    if (typeof first === "string") return makeIdentifier(first)
+    if (
+      Array.isArray(first) &&
+      (first.length === 0 || typeof first[0] !== "object" || first[0] === null)
+    )
+      return makeList(first)
+    return makeValues(first, rest[0])
+  }
+}
+
+/**
+ * Interpolate fragments into a SQL string and parameter array.
+ **/
+export function interpolate(
+  dialect: DialectConfig,
+  strings: TemplateStringsArray,
+  interpolations: Array<unknown>,
+): { readonly sql: string; readonly parameters: Array<unknown> } {
+  const parts: Array<string> = []
+  const parameters: Array<unknown> = []
+  let pi = 1
+
+  const pushItems = (items: ReadonlyArray<unknown>) => {
+    const ph: Array<string> = []
+    for (const item of items) {
+      ph.push(dialect.placeholder(pi++))
+      parameters.push(item)
+    }
+    return ph.join(", ")
+  }
+
+  parts.push(strings[0])
+  for (let i = 0; i < interpolations.length; i++) {
+    const frag = isSqlFragment(interpolations[i])
+    if (frag) {
+      const tag = frag[SqlFragmentTag]
+      if (tag === "Identifier") parts.push(dialect.identifier(frag.name))
+      else if (tag === "List") parts.push(`(${pushItems(frag.items)})`)
+      else if (tag === "Values") {
+        const cols = frag.columns.map((c) => dialect.identifier(c as string)).join(", ")
+        const rows = frag.value
+          .map((row) => `(${pushItems(frag.columns.map((c) => row[c as string]))})`)
+          .join(", ")
+        parts.push(`(${cols}) VALUES ${rows}`)
+      }
+    } else {
+      parts.push(dialect.placeholder(pi++))
+      parameters.push(interpolations[i])
+    }
+    parts.push(strings[i + 1])
+  }
+  return { sql: parts.join(""), parameters }
+}
+
+export function hasFragments(values: Array<unknown>): boolean {
+  return values.some((v) => isSqlFragment(v) !== undefined)
+}
+
+export const postgresDialect: DialectConfig = {
+  placeholder: (i) => `$${i}`,
+  identifier: (name) => `"${name.replace(/"/g, '""')}"`,
+}
+
+export const sqliteDialect: DialectConfig = {
+  placeholder: () => "?",
+  identifier: (name) => `"${name.replace(/"/g, '""')}"`,
+}
+
+export const mssqlDialect: DialectConfig = {
+  placeholder: (i) => `@p${i}`,
+  identifier: (name) => `[${name.replace(/\]/g, "]]")}]`,
+}
+
+const SqlFragmentTag = Symbol.for("effect-start/Sql/SqlFragment")
+
+type SqlFragment =
+  | { readonly [SqlFragmentTag]: "Identifier"; readonly name: string }
+  | {
+      readonly [SqlFragmentTag]: "Values"
+      readonly value: ReadonlyArray<Record<string, unknown>>
+      readonly columns: ReadonlyArray<string>
+    }
+  | { readonly [SqlFragmentTag]: "List"; readonly items: ReadonlyArray<unknown> }
+
+const makeIdentifier = (name: string): SqlFragment => ({ [SqlFragmentTag]: "Identifier", name })
+
+const makeValues = <T extends Record<string, unknown>>(
+  obj: T | ReadonlyArray<T>,
+  columns?: Array<keyof T & string>,
+): SqlFragment => {
+  const items = Array.isArray(obj) ? obj : [obj]
+  const cols = columns && columns.length > 0 ? columns : (Object.keys(items[0]) as Array<string>)
+  return { [SqlFragmentTag]: "Values", value: items, columns: cols }
+}
+
+const makeList = (items: ReadonlyArray<unknown>): SqlFragment => ({
+  [SqlFragmentTag]: "List",
+  items,
+})
+
+const isSqlFragment = (value: unknown): SqlFragment | undefined =>
+  value !== null && typeof value === "object" && SqlFragmentTag in value
+    ? (value as SqlFragment)
+    : undefined
+
+const currentTransactionDepth = GlobalValue.globalValue(
+  Symbol.for("effect-start/sql/currentTransactionDepth"),
+  () => FiberRef.unsafeMake(0),
+)
+
+const withExecuteSpan =
+  (
+    query: TaggedQuery,
+    options: {
+      readonly spanAttributes: Record<string, unknown>
+      readonly dialect: DialectConfig
+    },
+  ): TaggedQuery =>
+  <A extends object = SqlRow>(
+    strings: TemplateStringsArray,
+    ...values: Array<unknown>
+  ): Effect.Effect<ReadonlyArray<A>, SqlError> =>
+    query<A>(strings, ...values).pipe(
+      Effect.withSpan("sql.execute", {
+        kind: "client",
+        attributes: {
+          ...options.spanAttributes,
+          "db.operation.name": "execute",
+          "db.query.text": renderTemplateSql(options.dialect, strings, values),
+        },
+        captureStackTrace: false,
+      }),
+    )
+
+const withUnsafeExecuteSpan =
+  (
+    unsafe: UnsafeQuery,
+    options: {
+      readonly spanAttributes: Record<string, unknown>
+    },
+  ): UnsafeQuery =>
+  <A extends object = SqlRow>(
+    query: string,
+    values?: Array<unknown>,
+  ): Effect.Effect<ReadonlyArray<A>, SqlError> =>
+    unsafe<A>(query, values).pipe(
+      Effect.withSpan("sql.execute", {
+        kind: "client",
+        attributes: {
+          ...options.spanAttributes,
+          "db.operation.name": "executeRaw",
+          "db.query.text": query,
+        },
+        captureStackTrace: false,
+      }),
+    )
+
+const withTransactionSpan =
+  (
+    withTransaction: SqlClient["withTransaction"],
+    spanAttributes: Record<string, unknown>,
+  ): SqlClient["withTransaction"] =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, SqlError | E, R> =>
+    Effect.flatMap(FiberRef.get(currentTransactionDepth), (depth) =>
+      Effect.useSpan(
+        "sql.transaction",
+        {
+          kind: "client",
+          attributes: spanAttributes,
+          captureStackTrace: false,
+        },
+        (span) =>
+          Effect.flatMap(
+            Effect.exit(
+              Effect.withParentSpan(
+                Effect.locally(withTransaction(self), currentTransactionDepth, depth + 1),
+                span,
+              ),
+            ),
+            (exit) =>
+              Effect.flatMap(Clock.currentTimeNanos, (timestamp) =>
+                Effect.zipRight(
+                  Effect.sync(() =>
+                    span.event(
+                      Exit.isSuccess(exit)
+                        ? depth === 0
+                          ? "db.transaction.commit"
+                          : "db.transaction.savepoint"
+                        : "db.transaction.rollback",
+                      timestamp,
+                    ),
+                  ),
+                  exit,
+                ),
+              ),
+          ),
+      ),
+    )
+
+const makeTraceOptions = (
+  spanAttributes: ReadonlyArray<readonly [string, unknown]> | undefined,
+  dialect: DialectConfig | undefined,
+): {
+  readonly spanAttributes: Record<string, unknown>
+  readonly dialect: DialectConfig
+} => ({
+  spanAttributes: spanAttributes ? Object.fromEntries(spanAttributes) : {},
+  dialect: dialect ?? sqliteDialect,
+})
+
+const renderTemplateSql = (
+  dialect: DialectConfig,
+  strings: TemplateStringsArray,
+  values: Array<unknown>,
+): string => {
+  if (hasFragments(values)) {
+    return interpolate(dialect, strings, values).sql
+  }
+
+  let sql = strings[0]
+  for (let i = 0; i < values.length; i++) {
+    sql += dialect.placeholder(i + 1) + strings[i + 1]
+  }
+  return sql
+}

package/src/sql/bun/index.ts

@@ -4,7 +4,8 @@ import * as FiberRef from "effect/FiberRef"
 import * as GlobalValue from "effect/GlobalValue"
 import * as Layer from "effect/Layer"
 import * as Option from "effect/Option"
-import * as Sql from "../Sql.ts"
+import * as SqlClient from "../SqlClient.ts"
+import * as Values from "../../Values.ts"
 
 const errorCode = (error: unknown): string => {
   const e = error as any
@@ -12,42 +13,104 @@ const errorCode = (error: unknown): string => {
   return e?.code ?? "UNKNOWN"
 }
 
-const wrapError = (error: unknown): Sql.SqlError =>
-  new Sql.SqlError({
+const wrapError = (error: unknown): SqlClient.SqlError =>
+  new SqlClient.SqlError({
     code: errorCode(error),
     message: error instanceof Error ? error.message : String(error),
     cause: error,
   })
 
-const wrap = <T>(fn: () => PromiseLike<T>): Effect.Effect<T, Sql.SqlError> =>
+const wrap = <T>(fn: () => PromiseLike<T>): Effect.Effect<T, SqlClient.SqlError> =>
   Effect.tryPromise({ try: () => Promise.resolve(fn()), catch: wrapError })
 
-const makeValues: Sql.SqlQuery["values"] = (obj: any, ...columns: Array<string>) => {
-  const items = Array.isArray(obj) ? obj : [obj]
-  const cols = columns.length > 0 ? columns : Object.keys(items[0])
-  return { value: items, columns: cols }
-}
-
-interface TxState {
+interface TransactionConnection {
   readonly conn: any
   readonly depth: number
 }
 
 const currentTransaction = GlobalValue.globalValue(
   Symbol.for("effect-start/sql/bun/currentTransaction"),
-  () => FiberRef.unsafeMake<Option.Option<TxState>>(Option.none()),
+  () => FiberRef.unsafeMake<Option.Option<TransactionConnection>>(Option.none()),
 )
 
 const makeRun =
   (bunSql: any) =>
-  <T>(fn: (conn: any) => PromiseLike<T>): Effect.Effect<T, Sql.SqlError> =>
+  <T>(fn: (conn: any) => PromiseLike<T>): Effect.Effect<T, SqlClient.SqlError> =>
     Effect.flatMap(FiberRef.get(currentTransaction), (txOpt) =>
       wrap(() => fn(Option.isSome(txOpt) ? txOpt.value.conn : bunSql)),
     )
 
+const detectDialect = (bunSql: any): SqlClient.DialectConfig => {
+  const adapter = bunSql?.options?.adapter ?? bunSql?.adapter
+  if (adapter === "sqlite") return SqlClient.sqliteDialect
+  return SqlClient.postgresDialect
+}
+
+const makeSpanAttributes = (
+  config: ConstructorParameters<typeof Bun.SQL>[0],
+): Record<string, unknown> => {
+  const c = config as Record<string, unknown>
+  const adapter = c.adapter
+  if (adapter === "sqlite") {
+    return Values.compact({
+      ...(c.spanAttributes as Record<string, unknown> | undefined),
+      "db.system.name": "sqlite",
+    })
+  }
+
+  const parsed = (() => {
+    if (typeof c.url !== "string") return undefined
+    try {
+      return new URL(c.url)
+    } catch {
+      return undefined
+    }
+  })()
+  const dbFromPath = parsed?.pathname.replace(/^\/+/, "") || undefined
+  const parsedPort = parsed?.port ? Number(parsed.port) : undefined
+
+  return Values.compact({
+    ...(c.spanAttributes as Record<string, unknown> | undefined),
+    "db.system.name": "postgresql",
+    "db.namespace": (c.database as string | undefined) ?? dbFromPath,
+    "server.address": ((c.hostname ?? c.host) as string | undefined) ?? parsed?.hostname,
+    "server.port": (c.port as number | undefined) ?? parsedPort,
+  })
+}
+
+const makeTaggedTemplate = (
+  run: <T>(fn: (conn: any) => PromiseLike<T>) => Effect.Effect<T, SqlClient.SqlError>,
+  dialect: SqlClient.DialectConfig,
+) => {
+  const unsafeFn = <T = any>(query: string, values?: Array<unknown>) =>
+    run<ReadonlyArray<T>>((conn) => conn.unsafe(query, values))
+
+  return <T = any>(
+    strings: TemplateStringsArray,
+    ...values: Array<unknown>
+  ): Effect.Effect<ReadonlyArray<T>, SqlClient.SqlError> => {
+    if (SqlClient.hasFragments(values)) {
+      const compiled = SqlClient.interpolate(dialect, strings, values)
+      return unsafeFn<T>(compiled.sql, compiled.parameters)
+    }
+    return run<ReadonlyArray<T>>((conn) => conn(strings, ...values))
+  }
+}
+
+const makeQuery = (
+  run: <T>(fn: (conn: any) => PromiseLike<T>) => Effect.Effect<T, SqlClient.SqlError>,
+  dialect: SqlClient.DialectConfig,
+  spanAttributes: ReadonlyArray<readonly [string, unknown]>,
+): SqlClient.Connection => {
+  const query = makeTaggedTemplate(run, dialect)
+  const unsafe: SqlClient.UnsafeQuery = <T = any>(query: string, values?: Array<unknown>) =>
+    run<ReadonlyArray<T>>((conn) => conn.unsafe(query, values))
+  return SqlClient.connection(query, unsafe, { spanAttributes, dialect })
+}
+
 const makeWithTransaction =
   (bunSql: any) =>
-  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, Sql.SqlError | E, R> =>
+  <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, SqlClient.SqlError | E, R> =>
     Effect.uninterruptibleMask((restore) =>
       Effect.flatMap(FiberRef.get(currentTransaction), (txOpt) => {
         if (Option.isSome(txOpt)) {
@@ -98,50 +161,56 @@ const makeWithTransaction =
     )
 
 export const layer = (
-  config: ConstructorParameters<typeof Bun.SQL>[0],
-): Layer.Layer<Sql.SqlClient, Sql.SqlError> =>
+  config: ConstructorParameters<typeof Bun.SQL>[0] & {
+    readonly spanAttributes?: Record<string, unknown>
+  },
+): Layer.Layer<SqlClient.SqlClient, SqlClient.SqlError> =>
   Layer.scoped(
-    Sql.SqlClient,
-    Effect.acquireRelease(
-      Effect.try({
-        try: () => {
-          const bunSql = new Bun.SQL(config as any)
-          const run = makeRun(bunSql)
-          const use: Sql.SqlClient["use"] = (fn) =>
-            Effect.tryPromise({ try: () => Promise.resolve(fn(bunSql)), catch: wrapError })
-          return Object.assign(
-            <T = any>(strings: TemplateStringsArray, ...values: Array<unknown>) =>
-              run<ReadonlyArray<T>>((conn) => conn(strings, ...values)),
-            {
-              unsafe: <T = any>(query: string, values?: Array<unknown>) =>
-                run<ReadonlyArray<T>>((conn) => conn.unsafe(query, values)),
-              values: makeValues,
-              withTransaction: makeWithTransaction(bunSql),
-              reserve: Effect.acquireRelease(
-                wrap(() => bunSql.reserve()),
-                (reserved: any) => Effect.sync(() => reserved.release()),
-              ).pipe(
-                Effect.map(
-                  (reserved: any): Sql.SqlQuery =>
-                    Object.assign(
-                      <T = any>(strings: TemplateStringsArray, ...values: Array<unknown>) =>
-                        wrap<ReadonlyArray<T>>(() => reserved(strings, ...values)),
-                      {
-                        unsafe: <T = any>(query: string, values?: Array<unknown>) =>
-                          wrap<ReadonlyArray<T>>(() => reserved.unsafe(query, values)),
-                        values: makeValues,
-                      },
-                    ),
+    SqlClient.SqlClient,
+    Effect.map(
+      Effect.acquireRelease(
+        Effect.try({
+          try: () => {
+            const driverConfig = { ...config } as Record<string, unknown>
+            delete driverConfig.spanAttributes
+            const bunSql = new Bun.SQL(driverConfig as any)
+            const run = makeRun(bunSql)
+            const dialect = detectDialect(bunSql)
+            const spanAttributes = Object.entries(makeSpanAttributes(config))
+            const unsafeFn: SqlClient.UnsafeQuery = <T = any>(
+              query: string,
+              values?: Array<unknown>,
+            ) => run<ReadonlyArray<T>>((conn) => conn.unsafe(query, values))
+            const query = makeTaggedTemplate(run, dialect)
+            const use: SqlClient.SqlClient["use"] = (fn) =>
+              Effect.tryPromise({ try: () => Promise.resolve(fn(bunSql)), catch: wrapError })
+
+            return {
+              client: SqlClient.make({
+                query,
+                unsafe: unsafeFn,
+                withTransaction: makeWithTransaction(bunSql),
+                spanAttributes,
+                dialect,
+                reserve: Effect.acquireRelease(
+                  wrap(() => bunSql.reserve()),
+                  (reserved: any) => Effect.sync(() => reserved.release()),
+                ).pipe(
+                  Effect.map((reserved: any): SqlClient.Connection => {
+                    const reservedRun = <T>(fn: (conn: any) => PromiseLike<T>) =>
+                      wrap<T>(() => fn(reserved))
+                    return makeQuery(reservedRun, dialect, spanAttributes)
+                  }),
                 ),
-              ),
-              close: (options?: { readonly timeout?: number }) =>
-                use((bunSql) => bunSql.close(options)),
-              use,
-            },
-          ) satisfies Sql.SqlClient
-        },
-        catch: wrapError,
-      }),
-      (client) => client.close().pipe(Effect.orDie),
+                use,
+              }),
+              close: use((bunSql) => bunSql.close()),
+            }
+          },
+          catch: wrapError,
+        }),
+        (handle) => handle.close.pipe(Effect.orDie),
+      ),
+      (handle) => handle.client,
     ),
   )

package/src/sql/index.ts

@@ -1 +1,2 @@
-export * as Sql from "./Sql.ts"
+export * as SqlCache from "./SqlCache.ts"
+export * as SqlClient from "./SqlClient.ts"