effect-qb 0.21.0 → 0.22.0

package/src/postgres/function/numeric.ts

@@ -0,0 +1,246 @@
+import * as Numeric from "../../internal/dialect-numeric.js"
+import * as Expression from "../../internal/scalar.js"
+import { postgresDatatypes, postgresDatatypeFamilies } from "../datatypes/index.js"
+
+type PgNumericDb<
+  Kind extends "int2" | "int4" | "int8" | "numeric" | "float8",
+  Runtime extends "number" | "bigintString" | "decimalString"
+> = Expression.DbType.Base<"postgres", Kind> & {
+  readonly family: "numeric"
+  readonly runtime: Runtime
+  readonly compareGroup: "numeric"
+  readonly castTargets: typeof postgresDatatypeFamilies.numeric.castTargets
+  readonly implicitTargets: readonly []
+  readonly traits: { readonly ordered: true }
+}
+
+type PgInt2 = PgNumericDb<"int2", "number">
+type PgInt4 = PgNumericDb<"int4", "number">
+type PgInt8 = PgNumericDb<"int8", "bigintString">
+type PgNumeric = PgNumericDb<"numeric", "decimalString">
+type PgFloat8 = PgNumericDb<"float8", "number">
+
+type IsAny<Value> = 0 extends (1 & Value) ? true : false
+
+type BaseDb<Db extends Expression.DbType.Any> =
+  Db extends Expression.DbType.Domain<any, infer Base extends Expression.DbType.Any, any>
+    ? BaseDb<Base>
+    : Db
+
+type PgModuloCategory<Db extends Expression.DbType.Any> =
+  BaseDb<Db> extends infer Base extends Expression.DbType.Any
+    ? Base["dialect"] extends "standard"
+      ? Base["kind"] extends "int" | "integer" ? "int4"
+        : Base["kind"] extends "bigint" ? "int8"
+          : Base["kind"] extends "numeric" | "decimal" ? "numeric"
+            : never
+      : Base["dialect"] extends "postgres"
+        ? Base["kind"] extends "int2" | "int4" | "int8" | "numeric"
+          ? Base["kind"]
+          : never
+        : never
+    : never
+
+type PgRoundCategory<Db extends Expression.DbType.Any> =
+  BaseDb<Db> extends infer Base extends Expression.DbType.Any
+    ? Base["dialect"] extends "standard"
+      ? Base["kind"] extends "numeric" | "decimal" ? "exact"
+        : Base["kind"] extends "int" | "integer" | "bigint" ? "integer"
+          : Base["kind"] extends "real" ? "approximate"
+            : never
+      : Base["dialect"] extends "postgres"
+        ? Base["kind"] extends "numeric" ? "exact"
+          : Base["kind"] extends "int2" | "int4" | "int8" ? "integer"
+            : Base["kind"] extends "float4" | "float8" ? "approximate"
+              : never
+        : never
+    : never
+
+type NumericInputError<
+  Operation extends "modulo" | "round",
+  Db extends Expression.DbType.Any,
+  Expected extends string
+> = {
+  readonly __effect_qb_error__: "effect-qb: unsupported postgres numeric input"
+  readonly __effect_qb_operation__: Operation
+  readonly __effect_qb_db_type__: Db
+  readonly __effect_qb_expected__: Expected
+  readonly __effect_qb_hint__: "Use Cast.to(...) with a supported Type or Pg.Type witness"
+}
+
+type IntegerLiteralError<Value extends number> = {
+  readonly __effect_qb_error__: "effect-qb: postgres modulo number literals must be integers"
+  readonly __effect_qb_value__: Value
+  readonly __effect_qb_hint__: "Use Cast.to(value, Type.numeric()) for exact fractional modulo"
+}
+
+type PgModuloConstraint<Value extends Numeric.Input> =
+  IsAny<Value> extends true ? unknown
+    : Numeric.DialectConstraint<Value, PgInt4, "postgres"> & (
+      Value extends number
+        ? number extends Value
+          ? IntegerLiteralError<Value>
+          : `${Value}` extends `${bigint}` ? unknown : IntegerLiteralError<Value>
+        : PgModuloCategory<Numeric.DbTypeOfInput<Value, PgInt4, "postgres">> extends never
+          ? NumericInputError<
+              "modulo",
+              Numeric.DbTypeOfInput<Value, PgInt4, "postgres">,
+              "smallint, integer, bigint, or numeric"
+            >
+          : unknown
+    )
+
+type PgRoundConstraint<Value extends Numeric.Input> =
+  IsAny<Value> extends true ? unknown
+    : Numeric.DialectConstraint<Value, PgFloat8, "postgres"> & (
+      PgRoundCategory<Numeric.DbTypeOfInput<Value, PgFloat8, "postgres">> extends never
+        ? NumericInputError<
+            "round",
+            Numeric.DbTypeOfInput<Value, PgFloat8, "postgres">,
+            "smallint, integer, bigint, numeric, real, or double precision"
+          >
+        : unknown
+    )
+
+type PgScaledRoundConstraint<Value extends Numeric.Input> =
+  PgRoundConstraint<Value> &
+    (PgRoundCategory<Numeric.DbTypeOfInput<Value, PgFloat8, "postgres">> extends "approximate"
+      ? NumericInputError<
+          "round",
+          Numeric.DbTypeOfInput<Value, PgFloat8, "postgres">,
+          "numeric or integer when a scale is provided"
+        >
+      : unknown)
+
+type PgModuloResultCategory<
+  Left extends Numeric.Input,
+  Right extends Numeric.Input
+> =
+  PgModuloCategory<Numeric.DbTypeOfInput<Left, PgInt4, "postgres">> extends infer LeftCategory
+    ? PgModuloCategory<Numeric.DbTypeOfInput<Right, PgInt4, "postgres">> extends infer RightCategory
+      ? "numeric" extends LeftCategory | RightCategory ? "numeric"
+        : "int8" extends LeftCategory | RightCategory ? "int8"
+          : "int4" extends LeftCategory | RightCategory ? "int4"
+            : "int2"
+      : never
+    : never
+
+type PgModuloResultDb<
+  Left extends Numeric.Input,
+  Right extends Numeric.Input
+> = PgModuloResultCategory<Left, Right> extends "numeric" ? PgNumeric
+  : PgModuloResultCategory<Left, Right> extends "int8" ? PgInt8
+    : PgModuloResultCategory<Left, Right> extends "int4" ? PgInt4
+      : PgInt2
+
+type PgRoundResultDb<Value extends Numeric.Input> =
+  PgRoundCategory<Numeric.DbTypeOfInput<Value, PgFloat8, "postgres">> extends "exact"
+    ? PgNumeric
+    : PgFloat8
+
+type PgModuloResult<
+  Left extends Numeric.Input,
+  Right extends Numeric.Input
+> = Numeric.BinaryResult<
+  Left,
+  Right,
+  PgInt4,
+  PgModuloResultDb<Left, Right>,
+  Numeric.BinaryNullability<Left, Right, PgInt4, "postgres">,
+  "postgres"
+>
+
+type PgRoundResult<
+  Value extends Numeric.Input,
+  ResultDb extends Expression.DbType.Any,
+  WithScale extends boolean
+> = Numeric.RoundResult<
+  Value,
+  PgFloat8,
+  ResultDb,
+  Value extends Expression.Any ? Expression.NullabilityOf<Value> : "never",
+  "postgres",
+  WithScale
+>
+
+const baseDb = (db: Expression.DbType.Any): Expression.DbType.Any =>
+  "base" in db ? baseDb(db.base) : db
+
+const moduloCategory = (value: Numeric.Input): "int2" | "int4" | "int8" | "numeric" => {
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < -2_147_483_648 || value > 2_147_483_647) {
+      throw new Error("postgres modulo number literals must fit a signed int4")
+    }
+    return "int4"
+  }
+  const db = baseDb(value[Expression.TypeId].dbType)
+  if (db.dialect === "standard") {
+    if (db.kind === "bigint") return "int8"
+    if (db.kind === "numeric" || db.kind === "decimal") return "numeric"
+    return "int4"
+  }
+  return db.kind as "int2" | "int4" | "int8" | "numeric"
+}
+
+const moduloResultDb = (left: Numeric.Input, right: Numeric.Input) => {
+  const categories = [moduloCategory(left), moduloCategory(right)]
+  if (categories.includes("numeric")) return postgresDatatypes.numeric()
+  if (categories.includes("int8")) return postgresDatatypes.int8()
+  if (categories.includes("int4")) return postgresDatatypes.int4()
+  return postgresDatatypes.int2()
+}
+
+const roundCategory = (value: Numeric.Input): "exact" | "integer" | "approximate" => {
+  if (typeof value === "number") return "approximate"
+  const db = baseDb(value[Expression.TypeId].dbType)
+  if (db.kind === "numeric" || db.kind === "decimal") return "exact"
+  if (db.kind === "int" || db.kind === "integer" || db.kind === "bigint" ||
+    db.kind === "int2" || db.kind === "int4" || db.kind === "int8") {
+    return "integer"
+  }
+  return "approximate"
+}
+
+export const modulo = <
+  Left extends Numeric.Input,
+  Right extends Numeric.Input
+>(
+  left: Left & PgModuloConstraint<NoInfer<Left>>,
+  right: Right & PgModuloConstraint<NoInfer<Right>>
+): PgModuloResult<Left, Right> =>
+  (Numeric.modulo as any)(left, right, {
+    dialect: "postgres",
+    literalDb: postgresDatatypes.int4(),
+    resultDb: moduloResultDb(left, right) as PgModuloResultDb<Left, Right>,
+    nullability: Numeric.binaryInputNullability(left, right) as Numeric.BinaryNullability<Left, Right, PgInt4, "postgres">
+  }) as PgModuloResult<Left, Right>
+
+const roundRuntime = (
+  value: Numeric.Input,
+  scale?: number
+): Expression.Any => {
+  const category = roundCategory(value)
+  if (scale !== undefined && category === "approximate") {
+    throw new Error("postgres round with a scale requires a numeric or integer input")
+  }
+  const resultDb = scale !== undefined || category === "exact"
+    ? postgresDatatypes.numeric()
+    : postgresDatatypes.float8()
+  return Numeric.round(value, scale, {
+    dialect: "postgres",
+    literalDb: postgresDatatypes.float8(),
+    scaleDb: postgresDatatypes.int4(),
+    resultDb,
+    nullability: typeof value === "number" ? "never" : value[Expression.TypeId].nullability
+  }) as Expression.Any
+}
+
+export const round: {
+  <Value extends Numeric.Input>(
+    value: Value & PgRoundConstraint<NoInfer<Value>>
+  ): PgRoundResult<Value, PgRoundResultDb<Value>, false>
+  <Value extends Numeric.Input>(
+    value: Value & PgScaledRoundConstraint<NoInfer<Value>>,
+    scale: number
+  ): PgRoundResult<Value, PgNumeric, true>
+} = roundRuntime as any

package/src/postgres/function/window.ts

@@ -1,2 +1,14 @@
+import {
+  makeDialectFirstValue,
+  makeDialectLastValue
+} from "../../internal/analytics.js"
+export type { WindowSpec } from "../../internal/analytics.js"
+
 /** Postgres window functions. */
 export { over, rowNumber, rank, denseRank } from "../internal/dsl.js"
+
+/** First value in a PostgreSQL window frame. */
+export const firstValue = makeDialectFirstValue("postgres")
+
+/** Last value in a PostgreSQL window frame. */
+export const lastValue = makeDialectLastValue("postgres")

package/src/postgres/internal/dsl.ts

@@ -4,6 +4,7 @@ import * as Schema from "effect/Schema"
 import { postgresDatatypes } from "../datatypes/index.js"
 
 import * as Expression from "../../internal/scalar.js"
+import type * as FunctionConstraint from "../../internal/function-constraints.js"
 import * as Plan from "../../internal/row-set.js"
 import * as Table from "../../internal/table.js"
 import type {
@@ -135,6 +136,7 @@ import type { FormulaOfPredicate } from "../../internal/predicate/normalize.js"
 import type { TrueFormula } from "../../internal/predicate/formula.js"
 import { assumeFormulaTrue, formulaOfExpression as formulaOfExpressionRuntime, trueFormula } from "../../internal/predicate/runtime.js"
 import { dedupeGroupedExpressions } from "../../internal/grouping-key.js"
+import { validateWindowFrame } from "../../internal/window-frame.js"
 import { makeDslMutationRuntime } from "../../internal/dsl-mutation-runtime.js"
 import { makeDslPlanRuntime } from "../../internal/dsl-plan-runtime.js"
 import { makeDslQueryRuntime } from "../../internal/dsl-query-runtime.js"
@@ -1421,6 +1423,7 @@ type WindowSpecInput<
 > = {
   readonly partitionBy?: PartitionBy
   readonly orderBy?: OrderBy
+  readonly frame?: ExpressionAst.WindowFrameNode
 }
 
 type OrderedWindowSpecInput<
@@ -1429,6 +1432,7 @@ type OrderedWindowSpecInput<
 > = {
   readonly partitionBy?: PartitionBy
   readonly orderBy: OrderBy
+  readonly frame?: never
 }
 
 type WindowOrderExpressionTuple<
@@ -1501,8 +1505,8 @@ type NumberWindowExpression<
   PartitionBy extends readonly WindowPartitionInput[],
   OrderBy extends NonEmptyWindowOrderTerms
 > = AstBackedExpression<
-  number,
-  Expression.DbType.Any,
+  RuntimeOfDbType<ReturnType<typeof postgresDatatypes.int8>>,
+  ReturnType<typeof postgresDatatypes.int8>,
   "never",
   NumberWindowDialectOf<PartitionBy, OrderBy>,
   "window",
@@ -1793,6 +1797,7 @@ const profile: QueryDialectProfile<Dialect, TextDb, NumericDb, BoolDb, Timestamp
   >(
     spec: WindowSpecInput<PartitionBy, OrderBy> | OrderedWindowSpecInput<PartitionBy, Extract<OrderBy, NonEmptyWindowOrderTerms>> | undefined
   ) => {
+    validateWindowFrame(spec?.frame)
     const partitionBy = [...(spec?.partitionBy ?? [])] as unknown as PartitionBy
     const orderBy = (spec?.orderBy ?? []).map((term) => {
       const direction = term.direction ?? "asc"
@@ -1807,7 +1812,8 @@ const profile: QueryDialectProfile<Dialect, TextDb, NumericDb, BoolDb, Timestamp
     } & readonly { readonly value: WindowOrderInput; readonly direction: OrderDirection }[]
     return {
       partitionBy,
-      orderBy
+      orderBy,
+      frame: spec?.frame
     }
   }
 
@@ -2137,12 +2143,17 @@ type BinaryPredicateExpression<
   }
 
   const upper = <Value extends ExpressionInput>(
-    value: Value
+    value: Value & FunctionConstraint.CaseConversionInput<
+      NoInfer<Value>,
+      DialectDbTypeOfInput<NoInfer<Value>, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
+      Dialect,
+      "upper"
+    >
   ): AstBackedExpression<
     string,
     TextDb,
     NullabilityOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
-    DialectOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
+    Dialect,
     KindOf<DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>,
     DependenciesOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
     ExpressionAst.UnaryNode<"upper", DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>
@@ -2152,7 +2163,7 @@ type BinaryPredicateExpression<
       runtime: "" as string,
       dbType: profile.textDb as TextDb,
       nullability: expression[Expression.TypeId].nullability as NullabilityOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
-      dialect: expression[Expression.TypeId].dialect,
+      dialect: profile.dialect as Dialect,
       kind: expression[Expression.TypeId].kind as KindOf<DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>,
 
       dependencies: expression[Expression.TypeId].dependencies
@@ -2163,12 +2174,17 @@ type BinaryPredicateExpression<
   }
 
   const lower = <Value extends ExpressionInput>(
-    value: Value
+    value: Value & FunctionConstraint.CaseConversionInput<
+      NoInfer<Value>,
+      DialectDbTypeOfInput<NoInfer<Value>, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
+      Dialect,
+      "lower"
+    >
   ): AstBackedExpression<
     string,
     TextDb,
     NullabilityOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
-    DialectOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
+    Dialect,
     KindOf<DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>,
     DependenciesOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
     ExpressionAst.UnaryNode<"lower", DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>
@@ -2178,7 +2194,7 @@ type BinaryPredicateExpression<
       runtime: "" as string,
       dbType: profile.textDb as TextDb,
       nullability: expression[Expression.TypeId].nullability as NullabilityOfDialectStringInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
-      dialect: expression[Expression.TypeId].dialect,
+      dialect: profile.dialect as Dialect,
       kind: expression[Expression.TypeId].kind as KindOf<DialectAsStringExpression<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>,
 
       dependencies: expression[Expression.TypeId].dependencies
@@ -3496,8 +3512,8 @@ type BinaryPredicateExpression<
   const count = <Value extends ExpressionInput>(
     value: Value
   ): AstBackedExpression<
-    number,
-    NumericDb,
+    RuntimeOfDbType<ReturnType<typeof postgresDatatypes.int8>>,
+    ReturnType<typeof postgresDatatypes.int8>,
     "never",
     DialectOfDialectInput<Value, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>,
     "aggregate",
@@ -3506,8 +3522,8 @@ type BinaryPredicateExpression<
   > => {
     const expression = toDialectExpression(value)
     return makeExpression({
-      runtime: 0 as number,
-      dbType: profile.numericDb as NumericDb,
+      runtime: undefined as unknown as RuntimeOfDbType<ReturnType<typeof postgresDatatypes.int8>>,
+      dbType: postgresDatatypes.int8(),
       nullability: "never",
       dialect: expression[Expression.TypeId].dialect,
       kind: "aggregate",
@@ -3719,7 +3735,8 @@ type BinaryPredicateExpression<
       function: "over",
       value,
       partitionBy: normalized.partitionBy,
-      orderBy: normalized.orderBy
+      orderBy: normalized.orderBy,
+      frame: normalized.frame
     })
   }
 
@@ -3734,8 +3751,8 @@ type BinaryPredicateExpression<
     const normalized = normalizeWindowSpec(spec)
     const expressions = mergeWindowExpressions(undefined, normalized.partitionBy, normalized.orderBy)
     return makeExpression({
-      runtime: 0 as number,
-      dbType: profile.numericDb as Expression.DbType.Any,
+      runtime: undefined as unknown as RuntimeOfDbType<ReturnType<typeof postgresDatatypes.int8>>,
+      dbType: postgresDatatypes.int8(),
       nullability: "never",
       dialect: (expressions.find((expression) => expression[Expression.TypeId].dialect !== undefined)?.[Expression.TypeId].dialect ?? profile.dialect) as NumberWindowDialectOf<PartitionBy, OrderBy>,
       kind: "window",
@@ -3745,7 +3762,8 @@ type BinaryPredicateExpression<
       kind: "window",
       function: kind,
       partitionBy: normalized.partitionBy,
-      orderBy: normalized.orderBy
+      orderBy: normalized.orderBy,
+      frame: normalized.frame
     })
   }
 
@@ -3774,7 +3792,7 @@ type BinaryPredicateExpression<
     buildNumberWindow("denseRank", spec)
 
   const max = <Value extends Expression.Any>(
-    value: Value
+    value: Value & FunctionConstraint.OrderedInput<NoInfer<Value>, Dialect, "max">
   ): AstBackedExpression<
     Expression.RuntimeOf<Value>,
     Expression.DbTypeOf<Value>,
@@ -3798,7 +3816,7 @@ type BinaryPredicateExpression<
     })
 
   const min = <Value extends Expression.Any>(
-    value: Value
+    value: Value & FunctionConstraint.OrderedInput<NoInfer<Value>, Dialect, "min">
   ): AstBackedExpression<
     Expression.RuntimeOf<Value>,
     Expression.DbTypeOf<Value>,
@@ -3833,7 +3851,7 @@ type BinaryPredicateExpression<
   const coalesce = <
     Values extends readonly [ExpressionInput, ExpressionInput, ...ExpressionInput[]]
   >(
-    ...values: Values
+    ...values: Values & FunctionConstraint.CoalesceConstraint<DialectExpressionTuple<Values, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>, Dialect>
   ): AstBackedExpression<
     CoalesceRuntimeTuple<DialectExpressionTuple<Values, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>>,
     Expression.DbTypeOf<DialectExpressionTuple<Values, Dialect, TextDb, NumericDb, BoolDb, TimestampDb, NullDb>[number]>,

package/src/sqlite/executor.ts

@@ -39,20 +39,36 @@ export type SqliteExecutorError = SqliteDriverError | RowDecodeError
 export type SqliteQueryError<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>> =
   Exclude<CoreQuery.CapabilitiesOfPlan<PlanValue>, "read"> extends never ? SqliteReadQueryError : SqliteExecutorError
 
+/** Pipeable execution cardinality helpers. */
+export const atMostOne = CoreExecutor.atMostOne
+export const exactlyOne = CoreExecutor.exactlyOne
+export const nonEmpty = CoreExecutor.nonEmpty
+
 /** Runs an effect within the ambient SQLite SQL transaction service. */
 export const withTransaction = CoreExecutor.withTransaction
 
 /** SQLite executor whose error channel narrows based on the query plan. */
-export interface QueryExecutor<Context = never> {
+export interface QueryExecutor<Context = never> extends CoreExecutor.Executor<"sqlite", SqliteQueryError<any>, Context> {
   readonly dialect: "sqlite"
   execute<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
     plan: CoreQuery.DialectCompatiblePlan<PlanValue, "sqlite">
   ): Effect.Effect<CoreQuery.ResultRows<PlanValue>, SqliteQueryError<PlanValue>, Context>
+  executeResult<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+    plan: CoreQuery.DialectCompatiblePlan<PlanValue, "sqlite">
+  ): Effect.Effect<CoreExecutor.ExecutionResult<CoreQuery.ResultRow<PlanValue>>, SqliteQueryError<PlanValue>, Context>
+  prepare<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+    plan: CoreQuery.DialectCompatiblePlan<PlanValue, "sqlite">
+  ): CoreExecutor.PreparedQuery<CoreQuery.ResultRow<PlanValue>, SqliteQueryError<PlanValue>, Context>
   stream<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
     plan: Exclude<CoreQuery.CapabilitiesOfPlan<PlanValue>, "read" | "locking"> extends never
       ? CoreQuery.DialectCompatiblePlan<PlanValue, "sqlite">
       : never
   ): Stream.Stream<CoreQuery.ResultRow<PlanValue>, SqliteQueryError<PlanValue>, Context>
+  explain<PlanValue extends CoreQuery.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+    plan: Exclude<CoreQuery.CapabilitiesOfPlan<PlanValue>, "read" | "locking"> extends never
+      ? CoreQuery.DialectCompatiblePlan<PlanValue, "sqlite">
+      : never
+  ): Effect.Effect<ReadonlyArray<FlatRow>, SqliteQueryError<PlanValue>, Context>
 }
 
 type DriverExecute<Error, Context> = <Row>(
@@ -61,6 +77,9 @@ type DriverExecute<Error, Context> = <Row>(
 
 type DriverHandlers<Error, Context> = {
   readonly execute: DriverExecute<Error, Context>
+  readonly executeResult?: <Row>(
+    query: CoreRenderer.RenderedQuery<Row, "sqlite">
+  ) => Effect.Effect<CoreExecutor.DriverResult, Error, Context>
   readonly stream: <Row>(
     query: CoreRenderer.RenderedQuery<Row, "sqlite">
   ) => Stream.Stream<FlatRow, Error, Context>
@@ -114,51 +133,83 @@ const fromDriver = <
   sqlDriver: Driver<Error, Context>,
   driverMode: CoreExecutor.DriverMode = "raw",
   valueMappings?: Expression.DriverValueMappings
-): QueryExecutor<Context> => ({
-  dialect: "sqlite",
-  execute(plan) {
-    const rendered = renderer.render(plan)
-    return Effect.mapError(
-      Effect.flatMap(
-        sqlDriver.execute(rendered),
-        (rows) => Effect.try({
-          try: () => CoreExecutor.decodeRows(rendered, plan, rows, { driverMode, valueMappings }),
-          catch: (error) => error as RowDecodeError
-        })
-      ),
-      (error) => {
-        if (typeof error === "object" && error !== null && "_tag" in error && error._tag === "RowDecodeError") {
-          return error as RowDecodeError
-        }
-        const normalized = normalizeSqliteDriverError(error, rendered)
-        return CoreExecutor.hasWriteCapability(plan)
-          ? normalized
-          : narrowSqliteDriverErrorForReadQuery(normalized)
-      }
-    ) as Effect.Effect<any, any, Context>
-  },
-  stream(plan) {
-    const rendered = renderer.render(plan)
-    return Stream.mapError(
-      Stream.mapArrayEffect(
-        sqlDriver.stream(rendered),
-        (rows) => Effect.try({
-          try: () => CoreExecutor.decodeRows(rendered, plan, rows, { driverMode, valueMappings }) as never,
-          catch: (error) => error as RowDecodeError
-        })
-      ),
-      (error) => {
-        if (typeof error === "object" && error !== null && "_tag" in error && error._tag === "RowDecodeError") {
-          return error as RowDecodeError
-        }
-        const normalized = normalizeSqliteDriverError(error, rendered)
-        return CoreExecutor.hasWriteCapability(plan)
-          ? normalized
-          : narrowSqliteDriverErrorForReadQuery(normalized)
-      }
-    ) as Stream.Stream<any, any, Context>
+): QueryExecutor<Context> => {
+  const renderedCache = new WeakMap<object, CoreRenderer.RenderedQuery<any, "sqlite">>()
+  const render = (plan: CoreQuery.Plan.Any) => {
+    const cached = renderedCache.get(plan)
+    if (cached !== undefined) {
+      return cached
+    }
+    const rendered = renderer.render(plan as any)
+    renderedCache.set(plan, rendered)
+    return rendered
+  }
+  const mapExecutionError = (
+    error: unknown,
+    rendered: CoreRenderer.RenderedQuery<any, "sqlite">,
+    plan: CoreQuery.Plan.Any
+  ) => {
+    if (typeof error === "object" && error !== null && "_tag" in error && error._tag === "RowDecodeError") {
+      return error as RowDecodeError
+    }
+    const normalized = normalizeSqliteDriverError(error, rendered)
+    return CoreExecutor.hasWriteCapability(plan)
+      ? normalized
+      : narrowSqliteDriverErrorForReadQuery(normalized)
   }
-})
+  return CoreExecutor.withResultContracts({
+    dialect: "sqlite",
+    execute(plan) {
+      const rendered = render(plan)
+      return Effect.mapError(
+        Effect.flatMap(
+          sqlDriver.execute(rendered),
+          (rows) => Effect.try({
+            try: () => CoreExecutor.decodeRows(rendered, plan, rows, { driverMode, valueMappings }),
+            catch: (error) => error as RowDecodeError
+          })
+        ),
+        (error) => mapExecutionError(error, rendered, plan)
+      ) as Effect.Effect<any, any, Context>
+    },
+    executeResult(plan) {
+      const rendered = render(plan)
+      const result = sqlDriver.executeResult
+        ? sqlDriver.executeResult(rendered)
+        : Effect.map(sqlDriver.execute(rendered), (rows) => ({ rows }))
+      return Effect.mapError(
+        Effect.flatMap(result, ({ rows, ...metadata }) => Effect.try({
+          try: () => ({
+            ...metadata,
+            rows: CoreExecutor.decodeRows(rendered, plan, rows, { driverMode, valueMappings })
+          }),
+          catch: (error) => error as RowDecodeError
+        })),
+        (error) => mapExecutionError(error, rendered, plan)
+      ) as Effect.Effect<any, any, Context>
+    },
+    stream(plan) {
+      const rendered = render(plan)
+      return Stream.mapError(
+        Stream.mapArrayEffect(
+          sqlDriver.stream(rendered),
+          (rows) => Effect.try({
+            try: () => CoreExecutor.decodeRows(rendered, plan, rows, { driverMode, valueMappings }) as never,
+            catch: (error) => error as RowDecodeError
+          })
+        ),
+        (error) => mapExecutionError(error, rendered, plan)
+      ) as Stream.Stream<any, any, Context>
+    },
+    explain(plan, options) {
+      const rendered = CoreExecutor.explainQuery(render(plan), options)
+      return Effect.mapError(
+        sqlDriver.execute(rendered),
+        (error) => mapExecutionError(error, rendered, plan)
+      ) as Effect.Effect<any, any, Context>
+    }
+  }) as QueryExecutor<Context>
+}
 
 const sqlClientDriver = (): Driver<any, SqlClient.SqlClient> =>
   driver({