effect-qb 0.16.0 → 0.17.0

package/src/postgres/internal/sql-expression-renderer.ts

@@ -1,19 +1,25 @@
+import * as Schema from "effect/Schema"
+
 import * as Query from "../../internal/query.js"
 import * as Expression from "../../internal/scalar.js"
 import * as Table from "../../internal/table.js"
 import * as QueryAst from "../../internal/query-ast.js"
-import type { RenderState, SqlDialect } from "../../internal/dialect.js"
+import type { RenderState, RenderValueContext, SqlDialect } from "../../internal/dialect.js"
 import * as ExpressionAst from "../../internal/expression-ast.js"
 import * as JsonPath from "../../internal/json/path.js"
+import { renderSelectLockMode } from "../../internal/dsl-plan-runtime.js"
+import { expectConflictClause, expectInsertSourceKind } from "../../internal/dsl-mutation-runtime.js"
+import { expectDdlClauseKind, expectTruncateClause, renderTransactionIsolationLevel } from "../../internal/dsl-transaction-ddl-runtime.js"
 import {
   renderJsonSelectSql,
   renderSelectSql,
   toDriverValue
 } from "../../internal/runtime/driver-value-mapping.js"
+import { normalizeDbValue } from "../../internal/runtime/normalize.js"
 import { flattenSelection, type Projection } from "../../internal/projections.js"
 import { type SelectionValue, validateAggregationSelection } from "../../internal/aggregation-validation.js"
 import * as SchemaExpression from "../../internal/schema-expression.js"
-import type { DdlExpressionLike } from "../../internal/table-options.js"
+import { renderReferentialAction, type DdlExpressionLike } from "../../internal/table-options.js"
 
 const renderDbType = (
   dialect: SqlDialect,
@@ -51,14 +57,59 @@ const renderCastType = (
   }
 }
 
+const renderPostgresDdlString = (value: string): string =>
+  `'${value.replaceAll("'", "''")}'`
+
+const renderPostgresDdlBytes = (value: Uint8Array): string =>
+  `decode('${Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("")}', 'hex')`
+
+const renderPostgresDdlLiteral = (
+  value: unknown,
+  state: RenderState,
+  context: RenderValueContext = {}
+): string => {
+  const driverValue = toDriverValue(value, {
+    dialect: "postgres",
+    valueMappings: state.valueMappings,
+    ...context
+  })
+  if (driverValue === null) {
+    return "null"
+  }
+  switch (typeof driverValue) {
+    case "boolean":
+      return driverValue ? "true" : "false"
+    case "number":
+      if (!Number.isFinite(driverValue)) {
+        throw new Error("Expected a finite numeric value")
+      }
+      return String(driverValue)
+    case "bigint":
+      return driverValue.toString()
+    case "string":
+      return renderPostgresDdlString(driverValue)
+    case "object":
+      if (driverValue instanceof Uint8Array) {
+        return renderPostgresDdlBytes(driverValue)
+      }
+      break
+  }
+  throw new Error("Unsupported postgres DDL literal value")
+}
+
 const renderDdlExpression = (
   expression: DdlExpressionLike,
   state: RenderState,
   dialect: SqlDialect
-): string =>
-  SchemaExpression.isSchemaExpression(expression)
-    ? SchemaExpression.render(expression)
-    : renderExpression(expression, state, dialect)
+): string => {
+  if (SchemaExpression.isSchemaExpression(expression)) {
+    return SchemaExpression.render(expression)
+  }
+  return renderExpression(expression, state, {
+    ...dialect,
+    renderLiteral: renderPostgresDdlLiteral
+  })
+}
 
 const renderColumnDefinition = (
   dialect: SqlDialect,
@@ -105,17 +156,19 @@ const renderCreateTableSql = (
       case "foreignKey": {
         const reference = option.references()
         definitions.push(
-          `${option.name ? `constraint ${dialect.quoteIdentifier(option.name)} ` : ""}foreign key (${option.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")}) references ${dialect.renderTableReference(reference.tableName, reference.tableName, reference.schemaName)} (${reference.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")})${option.onDelete ? ` on delete ${option.onDelete.replace(/[A-Z]/g, (value) => ` ${value.toLowerCase()}`).trim()}` : ""}${option.onUpdate ? ` on update ${option.onUpdate.replace(/[A-Z]/g, (value) => ` ${value.toLowerCase()}`).trim()}` : ""}${option.deferrable ? ` deferrable${option.initiallyDeferred ? " initially deferred" : ""}` : ""}`
+          `${option.name ? `constraint ${dialect.quoteIdentifier(option.name)} ` : ""}foreign key (${option.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")}) references ${dialect.renderTableReference(reference.tableName, reference.tableName, reference.schemaName)} (${reference.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")})${option.onDelete !== undefined ? ` on delete ${renderReferentialAction(option.onDelete)}` : ""}${option.onUpdate !== undefined ? ` on update ${renderReferentialAction(option.onUpdate)}` : ""}${option.deferrable ? ` deferrable${option.initiallyDeferred ? " initially deferred" : ""}` : ""}`
         )
         break
       }
       case "check":
         definitions.push(
-          `constraint ${dialect.quoteIdentifier(option.name)} check (${renderDdlExpression(option.predicate, state, dialect)})${option.noInherit ? " no inherit" : ""}`
+          `constraint ${dialect.quoteIdentifier(option.name)} check (${renderDdlExpression(option.predicate, { ...state, rowLocalColumns: true }, dialect)})${option.noInherit ? " no inherit" : ""}`
         )
         break
       case "index":
         break
+      default:
+        throw new Error("Unsupported table option kind")
     }
   }
   return `create table${ifNotExists ? " if not exists" : ""} ${renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)} (${definitions.join(", ")})`
@@ -136,20 +189,74 @@ const renderDropIndexSql = (
   ddl: Extract<QueryAst.DdlClause, { readonly kind: "dropIndex" }>,
   state: RenderState,
   dialect: SqlDialect
-): string =>
-  dialect.name === "postgres"
-    ? `drop index${ddl.ifExists ? " if exists" : ""} ${dialect.quoteIdentifier(ddl.name)}`
-    : `drop index ${dialect.quoteIdentifier(ddl.name)} on ${renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)}`
+): string => {
+  if (dialect.name === "postgres") {
+    const schemaName = typeof targetSource.source === "object" &&
+      targetSource.source !== null &&
+      Table.TypeId in targetSource.source
+      ? (targetSource.source as Table.AnyTable)[Table.TypeId].schemaName
+      : undefined
+    const indexName = schemaName === undefined || schemaName === "public"
+      ? dialect.quoteIdentifier(ddl.name)
+      : `${dialect.quoteIdentifier(schemaName)}.${dialect.quoteIdentifier(ddl.name)}`
+    return `drop index${ddl.ifExists ? " if exists" : ""} ${indexName}`
+  }
+  return `drop index ${dialect.quoteIdentifier(ddl.name)} on ${renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)}`
+}
 
 const isExpression = (value: unknown): value is Expression.Any =>
   value !== null && typeof value === "object" && Expression.TypeId in value
 
-const isJsonDbType = (dbType: Expression.DbType.Any): boolean =>
-  dbType.kind === "jsonb" || dbType.kind === "json" || ("variant" in dbType && dbType.variant === "json")
+const isJsonDbType = (dbType: Expression.DbType.Any): boolean => {
+  if (dbType.kind === "jsonb" || dbType.kind === "json") {
+    return true
+  }
+  if (!("variant" in dbType)) {
+    return false
+  }
+  const variant = dbType.variant as string
+  return variant === "json" || variant === "jsonb"
+}
 
 const isJsonExpression = (value: unknown): value is Expression.Any =>
   isExpression(value) && isJsonDbType(value[Expression.TypeId].dbType)
 
+const postgresRangeSubtypeByKind: Readonly<Record<string, string>> = {
+  int4range: "int4",
+  int8range: "int8",
+  numrange: "numeric",
+  tsrange: "timestamp",
+  tstzrange: "timestamptz",
+  daterange: "date",
+  int4multirange: "int4",
+  int8multirange: "int8",
+  nummultirange: "numeric",
+  tsmultirange: "timestamp",
+  tstzmultirange: "timestamptz",
+  datemultirange: "date"
+}
+
+const postgresRangeSubtypeKey = (dbType: Expression.DbType.Any): string | undefined => {
+  if ("base" in dbType) {
+    return postgresRangeSubtypeKey(dbType.base)
+  }
+  if ("subtype" in dbType) {
+    return postgresRangeSubtypeKey(dbType.subtype) ?? dbType.subtype.kind
+  }
+  return postgresRangeSubtypeByKind[dbType.kind]
+}
+
+const assertCompatiblePostgresRangeOperands = (
+  left: Expression.Any,
+  right: Expression.Any
+): void => {
+  const leftKey = postgresRangeSubtypeKey(left[Expression.TypeId].dbType)
+  const rightKey = postgresRangeSubtypeKey(right[Expression.TypeId].dbType)
+  if (leftKey !== undefined && rightKey !== undefined && leftKey !== rightKey) {
+    throw new Error("Incompatible postgres range operands")
+  }
+}
+
 const unsupportedJsonFeature = (
   dialect: SqlDialect,
   feature: string
@@ -207,19 +314,19 @@ const extractJsonValue = (node: Record<string, unknown>): unknown =>
   node.newValue ?? node.insert ?? node.right
 
 const renderJsonPathSegment = (segment: JsonPath.AnySegment | string | number): string => {
+  const renderKey = (value: string): string =>
+    /^[A-Za-z_][A-Za-z0-9_]*$/.test(value)
+      ? `.${value}`
+      : `.${JSON.stringify(value)}`
   if (typeof segment === "string") {
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(segment)
-      ? `.${segment}`
-      : `."${segment.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+    return renderKey(segment)
   }
   if (typeof segment === "number") {
     return `[${segment}]`
   }
   switch (segment.kind) {
     case "key":
-      return /^[A-Za-z_][A-Za-z0-9_]*$/.test(segment.key)
-        ? `.${segment.key}`
-        : `."${segment.key.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+      return renderKey(segment.key)
     case "index":
       return `[${segment.index}]`
     case "wildcard":
@@ -284,7 +391,7 @@ const renderPostgresJsonAccessStep = (
     case "key":
       return `${textMode ? "->>" : "->"} ${dialect.renderLiteral(segment.key, state)}`
     case "index":
-      return `${textMode ? "->>" : "->"} ${dialect.renderLiteral(String(segment.index), state)}`
+      return `${textMode ? "->>" : "->"} ${dialect.renderLiteral(segment.index, state)}`
     default:
       throw new Error("Postgres exact JSON access requires key/index segments")
   }
@@ -338,14 +445,26 @@ const encodeArrayValues = (
   state: RenderState,
   dialect: SqlDialect
 ): readonly unknown[] =>
-  values.map((value) =>
-    toDriverValue(value, {
+  values.map((value) => {
+    if (value === null && column.metadata.nullable) {
+      return null
+    }
+    const runtimeSchemaAccepts = column.schema !== undefined &&
+      (Schema.is(column.schema) as (candidate: unknown) => boolean)(value)
+    const normalizedValue = runtimeSchemaAccepts
+      ? value
+      : normalizeDbValue(column.metadata.dbType, value)
+    const encodedValue = column.schema === undefined || runtimeSchemaAccepts
+      ? normalizedValue
+      : (Schema.decodeUnknownSync as any)(column.schema)(normalizedValue)
+    return toDriverValue(encodedValue, {
       dialect: dialect.name,
       valueMappings: state.valueMappings,
       dbType: column.metadata.dbType,
       runtimeSchema: column.schema,
       driverValueMapping: column.metadata.driverValueMapping
-    }))
+    })
+  })
 
 const renderPostgresJsonKind = (
   value: Expression.Any
@@ -588,7 +707,7 @@ const renderJsonExpression = (
         const baseSql = renderExpression(base, state, dialect)
         const typeOf = `${postgresBaseKind === "jsonb" ? "jsonb" : "json"}_typeof`
         const objectKeys = `${postgresBaseKind === "jsonb" ? "jsonb" : "json"}_object_keys`
-        return `(case when ${typeOf}(${baseSql}) = 'object' then array(select ${objectKeys}(${baseSql})) else null end)`
+        return `(case when ${typeOf}(${baseSql}) = 'object' then to_json(array(select ${objectKeys}(${baseSql}))) else null end)`
       }
       if (dialect.name === "mysql") {
         return `json_keys(${renderExpression(base, state, dialect)})`
@@ -615,7 +734,7 @@ const renderJsonExpression = (
           const segment = segments[0]!
           return `(${baseSql} - ${segment.kind === "key"
             ? dialect.renderLiteral(segment.key, state)
-            : dialect.renderLiteral(String(segment.index), state)})`
+            : dialect.renderLiteral(segment.index, state)})`
         }
         return `(${baseSql} #- ${renderPostgresJsonPathArray(segments, state, dialect)})`
       }
@@ -739,6 +858,15 @@ const renderDeleteTargets = (
   dialect: SqlDialect
 ): string => targets.map((target) => dialect.quoteIdentifier(target.tableName)).join(", ")
 
+const assertMergeActionKind = (
+  kind: unknown,
+  allowed: readonly string[]
+): void => {
+  if (typeof kind !== "string" || !allowed.includes(kind)) {
+    throw new Error("Unsupported merge action kind")
+  }
+}
+
 const renderMysqlMutationLock = (
   lock: QueryAst.LockClause | undefined,
   statement: "update" | "delete"
@@ -765,8 +893,9 @@ const renderTransactionClause = (
   switch (clause.kind) {
     case "transaction": {
       const modes: string[] = []
-      if (clause.isolationLevel) {
-        modes.push(`isolation level ${clause.isolationLevel}`)
+      const isolationLevel = renderTransactionIsolationLevel(clause.isolationLevel)
+      if (isolationLevel) {
+        modes.push(isolationLevel)
       }
       if (clause.readOnly === true) {
         modes.push("read only")
@@ -786,7 +915,7 @@ const renderTransactionClause = (
     case "releaseSavepoint":
       return `release savepoint ${dialect.quoteIdentifier(clause.name)}`
   }
-  return ""
+  throw new Error("Unsupported transaction statement kind")
 }
 
 const renderSelectionList = (
@@ -799,6 +928,9 @@ const renderSelectionList = (
     validateAggregationSelection(selection as SelectionValue, [])
   }
   const flattened = flattenSelection(selection)
+  if (dialect.name === "mysql" && flattened.length === 0) {
+    throw new Error("mysql select statements require at least one selected expression")
+  }
   const projections = selectionProjections(selection)
   const sql = flattened.map(({ expression, alias }) =>
     `${renderSelectSql(renderExpression(expression, state, dialect), expressionDriverContext(expression, state, dialect))} as ${dialect.quoteIdentifier(alias)}`).join(", ")
@@ -808,10 +940,105 @@ const renderSelectionList = (
   }
 }
 
+const nestedRenderState = (state: RenderState): RenderState => ({
+  params: state.params,
+  valueMappings: state.valueMappings,
+  ctes: [],
+  cteNames: new Set(state.cteNames),
+  cteSources: new Map(state.cteSources)
+})
+
+const assertMatchingSetProjections = (
+  left: readonly Projection[],
+  right: readonly Projection[]
+): void => {
+  const leftKeys = left.map((projection) => JSON.stringify(projection.path))
+  const rightKeys = right.map((projection) => JSON.stringify(projection.path))
+  if (leftKeys.length !== rightKeys.length || leftKeys.some((key, index) => key !== rightKeys[index])) {
+    throw new Error("set operator operands must have matching result rows")
+  }
+}
+
+const assertNoGroupedMutationClauses = (
+  ast: Pick<QueryAst.Ast, "groupBy" | "having">,
+  statement: string
+): void => {
+  if (ast.groupBy.length > 0) {
+    throw new Error(`groupBy(...) is not supported for ${statement} statements`)
+  }
+  if (ast.having.length > 0) {
+    throw new Error(`having(...) is not supported for ${statement} statements`)
+  }
+}
+
+const assertNoInsertQueryClauses = (
+  ast: Pick<QueryAst.Ast, "where" | "joins" | "orderBy" | "limit" | "offset" | "lock">
+): void => {
+  if (ast.where.length > 0) {
+    throw new Error("where(...) is not supported for insert statements")
+  }
+  if (ast.joins.length > 0) {
+    throw new Error("join(...) is not supported for insert statements")
+  }
+  if (ast.orderBy.length > 0) {
+    throw new Error("orderBy(...) is not supported for insert statements")
+  }
+  if (ast.limit) {
+    throw new Error("limit(...) is not supported for insert statements")
+  }
+  if (ast.offset) {
+    throw new Error("offset(...) is not supported for insert statements")
+  }
+  if (ast.lock) {
+    throw new Error("lock(...) is not supported for insert statements")
+  }
+}
+
+const assertNoStatementQueryClauses = (
+  ast: QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
+  statement: string,
+  options: { readonly allowSelection?: boolean } = {}
+): void => {
+  if (ast.distinct) {
+    throw new Error(`distinct(...) is not supported for ${statement} statements`)
+  }
+  if (ast.where.length > 0) {
+    throw new Error(`where(...) is not supported for ${statement} statements`)
+  }
+  if ((ast.fromSources?.length ?? 0) > 0 || ast.from) {
+    throw new Error(`from(...) is not supported for ${statement} statements`)
+  }
+  if (ast.joins.length > 0) {
+    throw new Error(`join(...) is not supported for ${statement} statements`)
+  }
+  if (ast.groupBy.length > 0) {
+    throw new Error(`groupBy(...) is not supported for ${statement} statements`)
+  }
+  if (ast.having.length > 0) {
+    throw new Error(`having(...) is not supported for ${statement} statements`)
+  }
+  if (ast.orderBy.length > 0) {
+    throw new Error(`orderBy(...) is not supported for ${statement} statements`)
+  }
+  if (ast.limit) {
+    throw new Error(`limit(...) is not supported for ${statement} statements`)
+  }
+  if (ast.offset) {
+    throw new Error(`offset(...) is not supported for ${statement} statements`)
+  }
+  if (ast.lock) {
+    throw new Error(`lock(...) is not supported for ${statement} statements`)
+  }
+  if (options.allowSelection !== true && Object.keys(ast.select).length > 0) {
+    throw new Error(`returning(...) is not supported for ${statement} statements`)
+  }
+}
+
 export const renderQueryAst = (
   ast: QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
   state: RenderState,
-  dialect: SqlDialect
+  dialect: SqlDialect,
+  options: { readonly emitCtes?: boolean } = {}
 ): RenderedQueryAst => {
   let sql = ""
   let projections: readonly Projection[] = []
@@ -821,10 +1048,11 @@ export const renderQueryAst = (
       validateAggregationSelection(ast.select as SelectionValue, ast.groupBy)
       const rendered = renderSelectionList(ast.select as Record<string, unknown>, state, dialect, false)
       projections = rendered.projections
+      const selectList = rendered.sql.length > 0 ? ` ${rendered.sql}` : ""
       const clauses = [
         ast.distinctOn && ast.distinctOn.length > 0
-          ? `select distinct on (${ast.distinctOn.map((value) => renderExpression(value, state, dialect)).join(", ")}) ${rendered.sql}`
-          : `select${ast.distinct ? " distinct" : ""} ${rendered.sql}`
+          ? `select distinct on (${ast.distinctOn.map((value) => renderExpression(value, state, dialect)).join(", ")})${selectList}`
+          : `select${ast.distinct ? " distinct" : ""}${selectList}`
       ]
       if (ast.from) {
         clauses.push(`from ${renderSourceReference(ast.from.source, ast.from.tableName, ast.from.baseTableName, state, dialect)}`)
@@ -856,8 +1084,11 @@ export const renderQueryAst = (
         clauses.push(`offset ${renderExpression(ast.offset, state, dialect)}`)
       }
       if (ast.lock) {
+        if (ast.lock.nowait && ast.lock.skipLocked) {
+          throw new Error("lock(...) cannot specify both nowait and skipLocked")
+        }
         clauses.push(
-          `${ast.lock.mode === "update" ? "for update" : "for share"}${ast.lock.nowait ? " nowait" : ""}${ast.lock.skipLocked ? " skip locked" : ""}`
+          `${renderSelectLockMode(ast.lock.mode)}${ast.lock.nowait ? " nowait" : ""}${ast.lock.skipLocked ? " skip locked" : ""}`
         )
       }
       sql = clauses.join(" ")
@@ -865,6 +1096,7 @@ export const renderQueryAst = (
     }
     case "set": {
       const setAst = ast as QueryAst.Ast<Record<string, unknown>, any, "set">
+      assertNoStatementQueryClauses(setAst, "set", { allowSelection: true })
       const base = renderQueryAst(
         Query.getAst(setAst.setBase as Query.Plan.Any) as QueryAst.Ast<
           Record<string, unknown>,
@@ -875,6 +1107,7 @@ export const renderQueryAst = (
         dialect
       )
       projections = selectionProjections(setAst.select as Record<string, unknown>)
+      assertMatchingSetProjections(projections, base.projections)
       sql = [
         `(${base.sql})`,
         ...(setAst.setOperations ?? []).map((entry) => {
@@ -887,6 +1120,7 @@ export const renderQueryAst = (
             state,
             dialect
           )
+          assertMatchingSetProjections(projections, rendered.projections)
           return `${entry.kind}${entry.all ? " all" : ""} (${rendered.sql})`
         })
       ].join(" ")
@@ -894,19 +1128,26 @@ export const renderQueryAst = (
     }
     case "insert": {
       const insertAst = ast as QueryAst.Ast<Record<string, unknown>, any, "insert">
+      if (insertAst.distinct) {
+        throw new Error("distinct(...) is not supported for insert statements")
+      }
+      assertNoGroupedMutationClauses(insertAst, "insert")
+      assertNoInsertQueryClauses(insertAst)
       const targetSource = insertAst.into!
       const target = renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)
+      const insertSource = expectInsertSourceKind(insertAst.insertSource)
+      const conflict = expectConflictClause(insertAst.conflict)
       sql = `insert into ${target}`
-      if (insertAst.insertSource?.kind === "values") {
-        const columns = insertAst.insertSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
-        const rows = insertAst.insertSource.rows.map((row) =>
+      if (insertSource?.kind === "values") {
+        const columns = insertSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
+        const rows = insertSource.rows.map((row) =>
           `(${row.values.map((entry) => renderExpression(entry.value, state, dialect)).join(", ")})`
         ).join(", ")
         sql += ` (${columns}) values ${rows}`
-      } else if (insertAst.insertSource?.kind === "query") {
-        const columns = insertAst.insertSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
+      } else if (insertSource?.kind === "query") {
+        const columns = insertSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
         const renderedQuery = renderQueryAst(
-          Query.getAst(insertAst.insertSource.query as Query.Plan.Any) as QueryAst.Ast<
+          Query.getAst(insertSource.query as Query.Plan.Any) as QueryAst.Ast<
             Record<string, unknown>,
             any,
             QueryAst.QueryStatement
@@ -915,20 +1156,19 @@ export const renderQueryAst = (
           dialect
         )
         sql += ` (${columns}) ${renderedQuery.sql}`
-      } else if (insertAst.insertSource?.kind === "unnest") {
-        const unnestSource = insertAst.insertSource
-        const columns = unnestSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
+      } else if (insertSource?.kind === "unnest") {
+        const columns = insertSource.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")
         if (dialect.name === "postgres") {
           const table = targetSource.source as Table.AnyTable
           const fields = table[Table.TypeId].fields
-          const rendered = unnestSource.values.map((entry) =>
+          const rendered = insertSource.values.map((entry) =>
             `cast(${dialect.renderLiteral(encodeArrayValues(entry.values, fields[entry.columnName]!, state, dialect), state)} as ${renderCastType(dialect, fields[entry.columnName]!.metadata.dbType)}[])`
           ).join(", ")
           sql += ` (${columns}) select * from unnest(${rendered})`
         } else {
-          const rowCount = unnestSource.values[0]?.values.length ?? 0
+          const rowCount = insertSource.values[0]?.values.length ?? 0
           const rows = Array.from({ length: rowCount }, (_, index) =>
-            `(${unnestSource.values.map((entry) =>
+            `(${insertSource.values.map((entry) =>
               dialect.renderLiteral(
                 entry.values[index],
                 state,
@@ -947,21 +1187,24 @@ export const renderQueryAst = (
           sql += " default values"
         }
       }
-      if (insertAst.conflict) {
-        const updateValues = (insertAst.conflict.values ?? []).map((entry) =>
+      if (conflict) {
+        if (conflict.action === "doNothing" && conflict.where) {
+          throw new Error("conflict action predicates require update assignments")
+        }
+        const updateValues = (conflict.values ?? []).map((entry) =>
           `${dialect.quoteIdentifier(entry.columnName)} = ${renderExpression(entry.value, state, dialect)}`
         ).join(", ")
         if (dialect.name === "postgres") {
-          const targetSql = insertAst.conflict.target?.kind === "constraint"
-            ? ` on conflict on constraint ${dialect.quoteIdentifier(insertAst.conflict.target.name)}`
-            : insertAst.conflict.target?.kind === "columns"
-              ? ` on conflict (${insertAst.conflict.target.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")})${insertAst.conflict.target.where ? ` where ${renderExpression(insertAst.conflict.target.where, state, dialect)}` : ""}`
+          const targetSql = conflict.target?.kind === "constraint"
+            ? ` on conflict on constraint ${dialect.quoteIdentifier(conflict.target.name)}`
+            : conflict.target?.kind === "columns"
+              ? ` on conflict (${conflict.target.columns.map((column) => dialect.quoteIdentifier(column)).join(", ")})${conflict.target.where ? ` where ${renderExpression(conflict.target.where, state, dialect)}` : ""}`
               : " on conflict"
           sql += targetSql
-          sql += insertAst.conflict.action === "doNothing"
+          sql += conflict.action === "doNothing"
             ? " do nothing"
-            : ` do update set ${updateValues}${insertAst.conflict.where ? ` where ${renderExpression(insertAst.conflict.where, state, dialect)}` : ""}`
-        } else if (insertAst.conflict.action === "doNothing") {
+            : ` do update set ${updateValues}${conflict.where ? ` where ${renderExpression(conflict.where, state, dialect)}` : ""}`
+        } else if (conflict.action === "doNothing") {
           sql = sql.replace(/^insert/, "insert ignore")
         } else {
           sql += ` on duplicate key update ${updateValues}`
@@ -976,10 +1219,29 @@ export const renderQueryAst = (
     }
     case "update": {
       const updateAst = ast as QueryAst.Ast<Record<string, unknown>, any, "update">
+      if (updateAst.distinct) {
+        throw new Error("distinct(...) is not supported for update statements")
+      }
+      assertNoGroupedMutationClauses(updateAst, "update")
+      if (updateAst.orderBy.length > 0) {
+        throw new Error("orderBy(...) is not supported for update statements")
+      }
+      if (updateAst.limit) {
+        throw new Error("limit(...) is not supported for update statements")
+      }
+      if (updateAst.offset) {
+        throw new Error("offset(...) is not supported for update statements")
+      }
+      if (updateAst.lock) {
+        throw new Error("lock(...) is not supported for update statements")
+      }
       const targetSource = updateAst.target!
       const target = renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)
       const targets = updateAst.targets ?? [targetSource]
       const fromSources = updateAst.fromSources ?? []
+      if ((updateAst.set ?? []).length === 0) {
+        throw new Error("update statements require at least one assignment")
+      }
       const assignments = updateAst.set!.map((entry) =>
         renderMutationAssignment(entry, state, dialect)).join(", ")
       if (dialect.name === "mysql") {
@@ -1029,6 +1291,22 @@ export const renderQueryAst = (
     }
     case "delete": {
       const deleteAst = ast as QueryAst.Ast<Record<string, unknown>, any, "delete">
+      if (deleteAst.distinct) {
+        throw new Error("distinct(...) is not supported for delete statements")
+      }
+      assertNoGroupedMutationClauses(deleteAst, "delete")
+      if (deleteAst.orderBy.length > 0 && dialect.name === "postgres") {
+        throw new Error("orderBy(...) is not supported for delete statements")
+      }
+      if (deleteAst.limit && dialect.name === "postgres") {
+        throw new Error("limit(...) is not supported for delete statements")
+      }
+      if (deleteAst.offset) {
+        throw new Error("offset(...) is not supported for delete statements")
+      }
+      if (deleteAst.lock) {
+        throw new Error("lock(...) is not supported for delete statements")
+      }
       const targetSource = deleteAst.target!
       const target = renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)
       const targets = deleteAst.targets ?? [targetSource]
@@ -1075,12 +1353,14 @@ export const renderQueryAst = (
     }
     case "truncate": {
       const truncateAst = ast as QueryAst.Ast<Record<string, unknown>, any, "truncate">
+      assertNoStatementQueryClauses(truncateAst, "truncate")
+      const truncate = expectTruncateClause(truncateAst.truncate)
       const targetSource = truncateAst.target!
       sql = `truncate table ${renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)}`
-      if (truncateAst.truncate?.restartIdentity) {
+      if (truncate.restartIdentity) {
         sql += " restart identity"
       }
-      if (truncateAst.truncate?.cascade) {
+      if (truncate.cascade) {
         sql += " cascade"
       }
       break
@@ -1093,8 +1373,18 @@ export const renderQueryAst = (
       const targetSource = mergeAst.target!
       const usingSource = mergeAst.using!
       const merge = mergeAst.merge!
+      if (merge.kind !== "merge") {
+        throw new Error("Unsupported merge statement kind")
+      }
+      if (Object.keys(mergeAst.select as Record<string, unknown>).length > 0) {
+        throw new Error("returning(...) is not supported for merge statements")
+      }
+      if (!merge.whenMatched && !merge.whenNotMatched) {
+        throw new Error("merge statements require at least one action")
+      }
       sql = `merge into ${renderSourceReference(targetSource.source, targetSource.tableName, targetSource.baseTableName, state, dialect)} using ${renderSourceReference(usingSource.source, usingSource.tableName, usingSource.baseTableName, state, dialect)} on ${renderExpression(merge.on, state, dialect)}`
       if (merge.whenMatched) {
+        assertMergeActionKind(merge.whenMatched.kind, ["update", "delete"])
         sql += " when matched"
         if (merge.whenMatched.predicate) {
           sql += ` and ${renderExpression(merge.whenMatched.predicate, state, dialect)}`
@@ -1102,16 +1392,23 @@ export const renderQueryAst = (
         if (merge.whenMatched.kind === "delete") {
           sql += " then delete"
         } else {
+          if (merge.whenMatched.values.length === 0) {
+            throw new Error("merge update actions require at least one assignment")
+          }
           sql += ` then update set ${merge.whenMatched.values.map((entry) =>
             `${dialect.quoteIdentifier(entry.columnName)} = ${renderExpression(entry.value, state, dialect)}`
           ).join(", ")}`
         }
       }
       if (merge.whenNotMatched) {
+        assertMergeActionKind(merge.whenNotMatched.kind, ["insert"])
         sql += " when not matched"
         if (merge.whenNotMatched.predicate) {
           sql += ` and ${renderExpression(merge.whenNotMatched.predicate, state, dialect)}`
         }
+        if (merge.whenNotMatched.values.length === 0) {
+          throw new Error("merge insert actions require at least one value")
+        }
         sql += ` then insert (${merge.whenNotMatched.values.map((entry) => dialect.quoteIdentifier(entry.columnName)).join(", ")}) values (${merge.whenNotMatched.values.map((entry) => renderExpression(entry.value, state, dialect)).join(", ")})`
       }
       break
@@ -1122,25 +1419,30 @@ export const renderQueryAst = (
     case "savepoint":
     case "rollbackTo":
     case "releaseSavepoint": {
+      assertNoStatementQueryClauses(ast, ast.kind)
       sql = renderTransactionClause(ast.transaction!, dialect)
       break
     }
     case "createTable": {
       const createTableAst = ast as QueryAst.Ast<Record<string, unknown>, any, "createTable">
-      sql = renderCreateTableSql(createTableAst.target!, state, dialect, createTableAst.ddl?.kind === "createTable" && createTableAst.ddl.ifNotExists)
+      assertNoStatementQueryClauses(createTableAst, "createTable")
+      const ddl = expectDdlClauseKind(createTableAst.ddl, "createTable")
+      sql = renderCreateTableSql(createTableAst.target!, state, dialect, ddl.ifNotExists)
       break
     }
     case "dropTable": {
       const dropTableAst = ast as QueryAst.Ast<Record<string, unknown>, any, "dropTable">
-      const ifExists = dropTableAst.ddl?.kind === "dropTable" && dropTableAst.ddl.ifExists
-      sql = `drop table${ifExists ? " if exists" : ""} ${renderSourceReference(dropTableAst.target!.source, dropTableAst.target!.tableName, dropTableAst.target!.baseTableName, state, dialect)}`
+      assertNoStatementQueryClauses(dropTableAst, "dropTable")
+      const ddl = expectDdlClauseKind(dropTableAst.ddl, "dropTable")
+      sql = `drop table${ddl.ifExists ? " if exists" : ""} ${renderSourceReference(dropTableAst.target!.source, dropTableAst.target!.tableName, dropTableAst.target!.baseTableName, state, dialect)}`
       break
     }
     case "createIndex": {
       const createIndexAst = ast as QueryAst.Ast<Record<string, unknown>, any, "createIndex">
+      assertNoStatementQueryClauses(createIndexAst, "createIndex")
       sql = renderCreateIndexSql(
         createIndexAst.target!,
-        createIndexAst.ddl as Extract<QueryAst.DdlClause, { readonly kind: "createIndex" }>,
+        expectDdlClauseKind(createIndexAst.ddl, "createIndex"),
         state,
         dialect
       )
@@ -1148,17 +1450,20 @@ export const renderQueryAst = (
     }
     case "dropIndex": {
       const dropIndexAst = ast as QueryAst.Ast<Record<string, unknown>, any, "dropIndex">
+      assertNoStatementQueryClauses(dropIndexAst, "dropIndex")
       sql = renderDropIndexSql(
         dropIndexAst.target!,
-        dropIndexAst.ddl as Extract<QueryAst.DdlClause, { readonly kind: "dropIndex" }>,
+        expectDdlClauseKind(dropIndexAst.ddl, "dropIndex"),
         state,
         dialect
       )
       break
     }
+    default:
+      throw new Error("Unsupported query statement kind")
   }
 
-  if (state.ctes.length === 0) {
+  if (state.ctes.length === 0 || options.emitCtes === false) {
     return {
       sql,
       projections
@@ -1206,9 +1511,19 @@ const renderSourceReference = (
       readonly plan: Query.Plan.Any
       readonly recursive?: boolean
     }
+    const registeredCteSource = state.cteSources.get(cte.name)
+    if (registeredCteSource !== undefined && registeredCteSource !== cte.plan) {
+      throw new Error(`common table expression name is already registered with a different plan: ${cte.name}`)
+    }
     if (!state.cteNames.has(cte.name)) {
       state.cteNames.add(cte.name)
-      const rendered = renderQueryAst(Query.getAst(cte.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>, state, dialect)
+      state.cteSources.set(cte.name, cte.plan)
+      const rendered = renderQueryAst(
+        Query.getAst(cte.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
+        state,
+        dialect,
+        { emitCtes: false }
+      )
       state.ctes.push({
         name: cte.name,
         sql: rendered.sql,
@@ -1225,14 +1540,14 @@ const renderSourceReference = (
     if (!state.cteNames.has(derived.name)) {
       // derived tables are inlined, so no CTE registration is needed
     }
-    return `(${renderQueryAst(Query.getAst(derived.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>, state, dialect).sql}) as ${dialect.quoteIdentifier(derived.name)}`
+    return `(${renderQueryAst(Query.getAst(derived.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>, nestedRenderState(state), dialect).sql}) as ${dialect.quoteIdentifier(derived.name)}`
   }
   if (typeof source === "object" && source !== null && "kind" in source && (source as { readonly kind?: string }).kind === "lateral") {
     const lateral = source as unknown as {
       readonly name: string
       readonly plan: Query.Plan.Any
     }
-    return `lateral (${renderQueryAst(Query.getAst(lateral.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>, state, dialect).sql}) as ${dialect.quoteIdentifier(lateral.name)}`
+    return `lateral (${renderQueryAst(Query.getAst(lateral.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>, nestedRenderState(state), dialect).sql}) as ${dialect.quoteIdentifier(lateral.name)}`
   }
   if (typeof source === "object" && source !== null && (source as { readonly kind?: string }).kind === "values") {
     const values = source as unknown as {
@@ -1267,6 +1582,22 @@ const renderSourceReference = (
   return dialect.renderTableReference(tableName, baseTableName, schemaName)
 }
 
+const renderSubqueryExpressionPlan = (
+  plan: Query.Plan.Any,
+  state: RenderState,
+  dialect: SqlDialect
+): string => {
+  const statement = Query.getQueryState(plan).statement
+  if (statement !== "select" && statement !== "set") {
+    throw new Error("subquery expressions only accept select-like query plans")
+  }
+  return renderQueryAst(
+    Query.getAst(plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
+    state,
+    dialect
+  ).sql
+}
+
 /**
  * Renders a scalar expression AST into SQL text.
  *
@@ -1301,10 +1632,13 @@ export const renderExpression = (
               : ">="
     switch (ast.kind) {
     case "column":
-      return ast.tableName.length === 0
+      return state.rowLocalColumns || ast.tableName.length === 0
         ? dialect.quoteIdentifier(ast.columnName)
         : `${dialect.quoteIdentifier(ast.tableName)}.${dialect.quoteIdentifier(ast.columnName)}`
     case "literal":
+      if (typeof ast.value === "number" && !Number.isFinite(ast.value)) {
+        throw new Error("Expected a finite numeric value")
+      }
       return dialect.renderLiteral(ast.value, state, expression[Expression.TypeId])
     case "excluded":
       return dialect.name === "mysql"
@@ -1360,6 +1694,7 @@ export const renderExpression = (
         : `(${renderExpression(ast.left, state, dialect)} is not distinct from ${renderExpression(ast.right, state, dialect)})`
     case "contains":
       if (dialect.name === "postgres") {
+        assertCompatiblePostgresRangeOperands(ast.left, ast.right)
         const left = isJsonExpression(ast.left)
           ? renderPostgresJsonValue(ast.left, state, dialect)
           : renderExpression(ast.left, state, dialect)
@@ -1374,6 +1709,7 @@ export const renderExpression = (
       throw new Error("Unsupported container operator for SQL rendering")
     case "containedBy":
       if (dialect.name === "postgres") {
+        assertCompatiblePostgresRangeOperands(ast.left, ast.right)
         const left = isJsonExpression(ast.left)
           ? renderPostgresJsonValue(ast.left, state, dialect)
           : renderExpression(ast.left, state, dialect)
@@ -1388,6 +1724,7 @@ export const renderExpression = (
       throw new Error("Unsupported container operator for SQL rendering")
     case "overlaps":
       if (dialect.name === "postgres") {
+        assertCompatiblePostgresRangeOperands(ast.left, ast.right)
         const left = isJsonExpression(ast.left)
           ? renderPostgresJsonValue(ast.left, state, dialect)
           : renderExpression(ast.left, state, dialect)
@@ -1417,14 +1754,26 @@ export const renderExpression = (
     case "min":
       return `min(${renderExpression(ast.value, state, dialect)})`
     case "and":
+      if (ast.values.length === 0) {
+        throw new Error("and(...) requires at least one predicate")
+      }
       return `(${ast.values.map((value: Expression.Any) => renderExpression(value, state, dialect)).join(" and ")})`
     case "or":
+      if (ast.values.length === 0) {
+        throw new Error("or(...) requires at least one predicate")
+      }
       return `(${ast.values.map((value: Expression.Any) => renderExpression(value, state, dialect)).join(" or ")})`
     case "coalesce":
       return `coalesce(${ast.values.map((value: Expression.Any) => renderExpression(value, state, dialect)).join(", ")})`
     case "in":
+      if (ast.values.length < 2) {
+        throw new Error("in(...) requires at least one candidate value")
+      }
       return `(${renderExpression(ast.values[0]!, state, dialect)} in (${ast.values.slice(1).map((value: Expression.Any) => renderExpression(value, state, dialect)).join(", ")}))`
     case "notIn":
+      if (ast.values.length < 2) {
+        throw new Error("notIn(...) requires at least one candidate value")
+      }
       return `(${renderExpression(ast.values[0]!, state, dialect)} not in (${ast.values.slice(1).map((value: Expression.Any) => renderExpression(value, state, dialect)).join(", ")}))`
     case "between":
       return `(${renderExpression(ast.values[0]!, state, dialect)} between ${renderExpression(ast.values[1]!, state, dialect)} and ${renderExpression(ast.values[2]!, state, dialect)})`
@@ -1435,35 +1784,15 @@ export const renderExpression = (
         `when ${renderExpression(branch.when, state, dialect)} then ${renderExpression(branch.then, state, dialect)}`
       ).join(" ")} else ${renderExpression(ast.else, state, dialect)} end`
     case "exists":
-      return `exists (${renderQueryAst(
-        Query.getAst(ast.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
-        state,
-        dialect
-      ).sql})`
+      return `exists (${renderSubqueryExpressionPlan(ast.plan, state, dialect)})`
     case "scalarSubquery":
-      return `(${renderQueryAst(
-        Query.getAst(ast.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
-        state,
-        dialect
-      ).sql})`
+      return `(${renderSubqueryExpressionPlan(ast.plan, state, dialect)})`
     case "inSubquery":
-      return `(${renderExpression(ast.left, state, dialect)} in (${renderQueryAst(
-        Query.getAst(ast.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
-        state,
-        dialect
-      ).sql}))`
+      return `(${renderExpression(ast.left, state, dialect)} in (${renderSubqueryExpressionPlan(ast.plan, state, dialect)}))`
     case "comparisonAny":
-      return `(${renderExpression(ast.left, state, dialect)} ${renderComparisonOperator(ast.operator)} any (${renderQueryAst(
-        Query.getAst(ast.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
-        state,
-        dialect
-      ).sql}))`
+      return `(${renderExpression(ast.left, state, dialect)} ${renderComparisonOperator(ast.operator)} any (${renderSubqueryExpressionPlan(ast.plan, state, dialect)}))`
     case "comparisonAll":
-      return `(${renderExpression(ast.left, state, dialect)} ${renderComparisonOperator(ast.operator)} all (${renderQueryAst(
-        Query.getAst(ast.plan) as QueryAst.Ast<Record<string, unknown>, any, QueryAst.QueryStatement>,
-        state,
-        dialect
-      ).sql}))`
+      return `(${renderExpression(ast.left, state, dialect)} ${renderComparisonOperator(ast.operator)} all (${renderSubqueryExpressionPlan(ast.plan, state, dialect)}))`
     case "window": {
       if (!Array.isArray(ast.partitionBy) || !Array.isArray(ast.orderBy) || typeof ast.function !== "string") {
         break