@xylex-group/athena 2.0.0 → 2.1.2

package/dist/index.js

@@ -1,5 +1,4 @@
-import { Pool } from 'pg';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve, dirname, posix } from 'path';
 import { pathToFileURL } from 'url';
 import { mkdir, writeFile } from 'fs/promises';
@@ -1539,460 +1538,588 @@ function createAuthClient(config = {}) {
   };
 }
 
-// src/client.ts
-var DEFAULT_COLUMNS = "*";
-var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
-function formatResult(response) {
-  const result = {
-    data: response.data ?? null,
-    error: response.error ?? null,
-    errorDetails: response.errorDetails ?? null,
-    status: response.status,
-    raw: response.raw
-  };
-  if (response.count !== void 0) {
-    result.count = response.count;
+// src/auxiliaries.ts
+var AthenaErrorKind = {
+  UniqueViolation: "unique_violation",
+  NotFound: "not_found",
+  Validation: "validation",
+  Auth: "auth",
+  RateLimit: "rate_limit",
+  Transient: "transient",
+  Unknown: "unknown"
+};
+var AthenaErrorCode = {
+  UniqueViolation: "UNIQUE_VIOLATION",
+  NotFound: "NOT_FOUND",
+  ValidationFailed: "VALIDATION_FAILED",
+  AuthUnauthorized: "AUTH_UNAUTHORIZED",
+  AuthForbidden: "AUTH_FORBIDDEN",
+  RateLimited: "RATE_LIMITED",
+  NetworkUnavailable: "NETWORK_UNAVAILABLE",
+  TransientFailure: "TRANSIENT_FAILURE",
+  HttpFailure: "HTTP_FAILURE",
+  Unknown: "UNKNOWN"
+};
+var AthenaErrorCategory = {
+  Transport: "transport",
+  Client: "client",
+  Server: "server",
+  Database: "database",
+  Unknown: "unknown"
+};
+function parseBooleanFlag(rawValue, fallback) {
+  if (!rawValue) return fallback;
+  const normalized = rawValue.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
   }
-  return result;
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return fallback;
 }
-function toSingleResult(response) {
-  const payload = response.data;
-  const singleData = Array.isArray(payload) ? payload.length ? payload[0] : null : payload ?? null;
-  return {
-    ...response,
-    data: singleData
-  };
+var AthenaError = class extends Error {
+  code;
+  kind;
+  category;
+  status;
+  retryable;
+  requestId;
+  context;
+  raw;
+  constructor(input) {
+    super(input.message);
+    this.name = "AthenaError";
+    this.code = input.code;
+    this.kind = input.kind;
+    this.category = input.category;
+    this.status = input.status;
+    this.retryable = input.retryable ?? false;
+    this.requestId = input.requestId;
+    this.context = input.context;
+    this.raw = input.raw;
+  }
+};
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function mergeOptions(...options) {
-  return options.reduce((acc, next) => {
-    if (!next) return acc;
-    return { ...acc, ...next };
-  }, void 0);
+function isAthenaErrorKind(value) {
+  return value === "unique_violation" || value === "not_found" || value === "validation" || value === "auth" || value === "rate_limit" || value === "transient" || value === "unknown";
 }
-function asAthenaJsonObject(value) {
-  return value;
+function isAthenaErrorCode(value) {
+  return value === "UNIQUE_VIOLATION" || value === "NOT_FOUND" || value === "VALIDATION_FAILED" || value === "AUTH_UNAUTHORIZED" || value === "AUTH_FORBIDDEN" || value === "RATE_LIMITED" || value === "NETWORK_UNAVAILABLE" || value === "TRANSIENT_FAILURE" || value === "HTTP_FAILURE" || value === "UNKNOWN";
 }
-function asAthenaJsonObjectArray(values) {
-  return values;
+function isAthenaErrorCategory(value) {
+  return value === "transport" || value === "client" || value === "server" || value === "database" || value === "unknown";
 }
-function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
-  let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
-  let selectedOptions;
-  let promise = null;
-  const run = (columns, options) => {
-    const payloadColumns = columns ?? selectedColumns;
-    const payloadOptions = options ?? selectedOptions;
-    if (!promise) {
-      promise = executor(payloadColumns, payloadOptions);
-    }
-    return promise;
-  };
-  const mutationQuery = {
-    select(columns = selectedColumns, options) {
-      selectedColumns = columns;
-      selectedOptions = options ?? selectedOptions;
-      return run(columns, options);
-    },
-    returning(columns = selectedColumns, options) {
-      return mutationQuery.select(columns, options);
-    },
-    single(columns = selectedColumns, options) {
-      selectedColumns = columns;
-      selectedOptions = options ?? selectedOptions;
-      return run(columns, options).then(toSingleResult);
-    },
-    maybeSingle(columns = selectedColumns, options) {
-      return mutationQuery.single(columns, options);
-    },
-    then(onfulfilled, onrejected) {
-      return run(selectedColumns, selectedOptions).then(onfulfilled, onrejected);
-    },
-    catch(onrejected) {
-      return run(selectedColumns, selectedOptions).catch(onrejected);
-    },
-    finally(onfinally) {
-      return run(selectedColumns, selectedOptions).finally(onfinally);
-    }
+function isNormalizedAthenaError(value) {
+  return isRecord3(value) && isAthenaErrorKind(value.kind) && isAthenaErrorCode(value.code) && isAthenaErrorCategory(value.category) && typeof value.retryable === "boolean" && typeof value.message === "string" && "raw" in value;
+}
+function withContextOverrides(normalized, context) {
+  if (!context?.table && !context?.operation) {
+    return normalized;
+  }
+  return {
+    ...normalized,
+    table: context.table ?? normalized.table,
+    operation: context.operation ?? normalized.operation
   };
-  return mutationQuery;
 }
-function getResourceId(state) {
-  const candidate = state.conditions.find(
-    (condition) => condition.operator === "eq" && (condition.column === "resource_id" || condition.column === "id")
-  );
-  return candidate?.value?.toString();
+function resolveAttachedNormalizedError(resultOrError) {
+  if (!isRecord3(resultOrError)) return void 0;
+  if (!("__athenaNormalizedError" in resultOrError)) return void 0;
+  const candidate = resultOrError.__athenaNormalizedError;
+  return isNormalizedAthenaError(candidate) ? candidate : void 0;
 }
-function stringifyFilterValue(value) {
-  if (Array.isArray(value)) {
-    return value.join(",");
+function safeStringify(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized ?? String(value);
+  } catch {
+    return "[unserializable]";
   }
-  return String(value);
 }
-function isUuidString(value) {
-  return UUID_PATTERN.test(value.trim());
+function contextHint(context) {
+  if (!context?.identity) return void 0;
+  const identity = typeof context.identity === "string" ? context.identity : safeStringify(context.identity);
+  return `Identity: ${identity}`;
 }
-function isUuidIdentifierColumn(column) {
-  return column === "id" || /(?:^|_)uuid(?:_|$)/i.test(column) || /_id$/i.test(column);
+function isAthenaResultLike(value) {
+  return isRecord3(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
 }
-function shouldUseUuidTextComparison(column, value) {
-  return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
+function operationFromDetails(details) {
+  if (!details?.endpoint) return void 0;
+  if (details.endpoint === "/gateway/fetch" || details.endpoint === "/gateway/query") return "select";
+  if (details.endpoint === "/gateway/insert") return "insert";
+  if (details.endpoint === "/gateway/update") return "update";
+  if (details.endpoint === "/gateway/delete") return "delete";
+  if (details.endpoint === "/gateway/rpc" || details.endpoint.startsWith("/rpc/")) return "rpc";
+  return void 0;
 }
-function normalizeCast(cast) {
-  const normalized = cast.trim().toLowerCase();
-  if (!SAFE_CAST_PATTERN.test(normalized)) {
-    throw new Error(`Invalid cast type "${cast}"`);
+function matchRegex(input, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(input);
+    if (match?.[1]) return match[1];
   }
-  return normalized;
-}
-function escapeSqlStringLiteral(value) {
-  return value.replace(/'/g, "''");
+  return void 0;
 }
-function toSqlLiteral(value) {
-  if (value === null) return "NULL";
-  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "NULL";
-  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
-  return `'${escapeSqlStringLiteral(value)}'`;
+function extractConstraint(message) {
+  return matchRegex(message, [
+    /unique constraint\s+["'`]([^"'`]+)["'`]/i,
+    /constraint\s+["'`]([^"'`]+)["'`]/i
+  ]);
 }
-function withCast(expression, cast) {
-  if (!cast) return expression;
-  return `${expression}::${normalizeCast(cast)}`;
+function extractTable(message) {
+  return matchRegex(message, [
+    /(?:table|relation)\s+["'`]([^"'`]+)["'`]/i,
+    /on\s+table\s+([a-zA-Z0-9_.]+)/i
+  ]);
 }
-function buildSelectColumnsClause(columns) {
-  if (Array.isArray(columns)) {
-    return columns.map((column) => quoteQualifiedIdentifier(column)).join(", ");
+function classifyKind(status, code, message) {
+  const lower = message.toLowerCase();
+  const hasUniquePattern = lower.includes("unique constraint") || lower.includes("duplicate key") || lower.includes("already exists") || lower.includes("duplicate");
+  const hasNotFoundPattern = lower.includes("not found") || lower.includes("no rows");
+  const hasValidationPattern = lower.includes("validation") || lower.includes("invalid") || lower.includes("malformed");
+  const hasAuthPattern = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("auth");
+  const hasRateLimitPattern = lower.includes("rate limit") || lower.includes("too many requests");
+  const hasTransientPattern = lower.includes("timeout") || lower.includes("temporar") || lower.includes("connection reset") || lower.includes("socket") || lower.includes("deadlock");
+  if (status === 409 || hasUniquePattern) return "unique_violation";
+  if (status === 404 || hasNotFoundPattern) return "not_found";
+  if (status === 401 || status === 403 || hasAuthPattern) return "auth";
+  if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (status === 400 || status === 422 || hasValidationPattern) return "validation";
+  if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
+    return "transient";
   }
-  return quoteSelectColumnsExpression(columns);
+  return "unknown";
 }
-function resolveTableNameForCall(tableName, schema) {
-  if (!schema) return tableName;
-  const normalizedSchema = schema.trim();
-  if (!normalizedSchema) {
-    throw new Error("schema option must be a non-empty string");
+function toAthenaErrorCode(kind, status, gatewayCode) {
+  if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
+    return AthenaErrorCode.NetworkUnavailable;
   }
-  if (tableName.includes(".")) {
-    if (tableName.startsWith(`${normalizedSchema}.`)) {
-      return tableName;
-    }
-    throw new Error(
-      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${tableName}"`
-    );
+  switch (kind) {
+    case "unique_violation":
+      return AthenaErrorCode.UniqueViolation;
+    case "not_found":
+      return AthenaErrorCode.NotFound;
+    case "validation":
+      return AthenaErrorCode.ValidationFailed;
+    case "rate_limit":
+      return AthenaErrorCode.RateLimited;
+    case "auth":
+      if (status === 403) {
+        return AthenaErrorCode.AuthForbidden;
+      }
+      return AthenaErrorCode.AuthUnauthorized;
+    case "transient":
+      return status !== void 0 && status >= 500 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.TransientFailure;
+    case "unknown":
+    default:
+      return status !== void 0 && status >= 400 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.Unknown;
   }
-  return `${normalizedSchema}.${tableName}`;
 }
-function conditionToSqlClause(condition) {
-  if (!condition.column) return null;
-  const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
-  const value = condition.value;
-  const sqlOperator = {
-    eq: "=",
-    neq: "!=",
-    gt: ">",
-    gte: ">=",
-    lt: "<",
-    lte: "<=",
-    like: "LIKE",
-    ilike: "ILIKE"
+function toAthenaErrorCategory(kind, status) {
+  if (kind === "transient" && (status === 0 || status === void 0)) {
+    return AthenaErrorCategory.Transport;
+  }
+  if (kind === "unique_violation") return AthenaErrorCategory.Database;
+  if (kind === "validation" || kind === "auth" || kind === "not_found") return AthenaErrorCategory.Client;
+  if (kind === "rate_limit" || kind === "transient") return AthenaErrorCategory.Server;
+  return AthenaErrorCategory.Unknown;
+}
+function isRetryable(kind, status) {
+  if (kind === "rate_limit" || kind === "transient") return true;
+  return status !== void 0 && status >= 500;
+}
+function toGatewayCode(kind, status) {
+  if (kind === "transient" && (status === 0 || status === void 0)) return "NETWORK_ERROR";
+  if (kind === "validation") return "INVALID_JSON";
+  if (status !== void 0 && status >= 400) return "HTTP_ERROR";
+  return "UNKNOWN_ERROR";
+}
+function toAthenaGatewayError(source, fallbackMessage, context) {
+  if (isAthenaGatewayError(source)) {
+    return source;
+  }
+  if (isAthenaResultLike(source) && source.errorDetails) {
+    return new AthenaGatewayError({
+      code: source.errorDetails.code,
+      message: source.error ?? source.errorDetails.message,
+      status: source.status,
+      endpoint: source.errorDetails.endpoint,
+      method: source.errorDetails.method,
+      requestId: source.errorDetails.requestId,
+      hint: source.errorDetails.hint,
+      cause: source.errorDetails.cause
+    });
+  }
+  const normalized = normalizeAthenaError(source, context);
+  const message = isAthenaResultLike(source) && source.error == null && source.errorDetails == null ? fallbackMessage : normalized.message || fallbackMessage;
+  return new AthenaGatewayError({
+    code: toGatewayCode(normalized.kind, normalized.status),
+    message,
+    status: normalized.status ?? 0,
+    hint: normalized.constraint != null ? `Constraint: ${normalized.constraint}` : contextHint(context),
+    cause: typeof normalized.raw === "string" ? normalized.raw : safeStringify(normalized.raw)
+  });
+}
+function isOk(result) {
+  return result.error == null && result.status >= 200 && result.status < 300;
+}
+function normalizeAthenaError(resultOrError, context) {
+  const attached = resolveAttachedNormalizedError(resultOrError);
+  if (attached) {
+    return withContextOverrides(attached, context);
+  }
+  if (isAthenaResultLike(resultOrError)) {
+    const details = resultOrError.errorDetails;
+    const message2 = resultOrError.error ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(message2);
+    const constraint = extractConstraint(message2);
+    const kind2 = classifyKind(resultOrError.status, details?.code, message2);
+    const code = toAthenaErrorCode(kind2, resultOrError.status, details?.code);
+    const category = toAthenaErrorCategory(kind2, resultOrError.status);
+    return {
+      kind: kind2,
+      code,
+      category,
+      retryable: isRetryable(kind2, resultOrError.status),
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: message2,
+      raw: resultOrError.raw
+    };
+  }
+  if (isAthenaGatewayError(resultOrError)) {
+    const details = resultOrError.toDetails();
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(resultOrError.message);
+    const constraint = extractConstraint(resultOrError.message);
+    const kind2 = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
+    const code = toAthenaErrorCode(kind2, resultOrError.status, resultOrError.code);
+    const category = toAthenaErrorCategory(kind2, resultOrError.status);
+    return {
+      kind: kind2,
+      code,
+      category,
+      retryable: isRetryable(kind2, resultOrError.status),
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  if (resultOrError instanceof Error) {
+    const maybeStatus = isRecord3(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
+    const kind2 = classifyKind(maybeStatus, void 0, resultOrError.message);
+    return {
+      kind: kind2,
+      code: toAthenaErrorCode(kind2, maybeStatus),
+      category: toAthenaErrorCategory(kind2, maybeStatus),
+      retryable: isRetryable(kind2, maybeStatus),
+      status: maybeStatus,
+      constraint: extractConstraint(resultOrError.message),
+      table: context?.table ?? extractTable(resultOrError.message),
+      operation: context?.operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  const message = typeof resultOrError === "string" ? resultOrError : "Unknown Athena error";
+  const kind = classifyKind(void 0, void 0, message);
+  return {
+    kind,
+    code: toAthenaErrorCode(kind, void 0),
+    category: toAthenaErrorCategory(kind, void 0),
+    retryable: isRetryable(kind, void 0),
+    status: void 0,
+    constraint: extractConstraint(message),
+    table: context?.table ?? extractTable(message),
+    operation: context?.operation,
+    message,
+    raw: resultOrError
   };
-  switch (condition.operator) {
-    case "eq":
-    case "neq":
-    case "gt":
-    case "gte":
-    case "lt":
-    case "lte":
-    case "like":
-    case "ilike": {
-      if (Array.isArray(value) || value === void 0) return null;
-      const rhs = withCast(toSqlLiteral(value), condition.value_cast);
-      return `${column} ${sqlOperator[condition.operator]} ${rhs}`;
-    }
-    case "is": {
-      if (value === null) return `${column} IS NULL`;
-      if (value === true) return `${column} IS TRUE`;
-      if (value === false) return `${column} IS FALSE`;
-      return null;
-    }
-    case "in": {
-      if (!Array.isArray(value)) return null;
-      if (value.length === 0) return "FALSE";
-      const values = value.map((item) => withCast(toSqlLiteral(item), condition.value_cast));
-      return `${column} IN (${values.join(", ")})`;
-    }
-    default:
-      return null;
+}
+function unwrapRows(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
   }
+  if (result.data == null) return [];
+  return Array.isArray(result.data) ? result.data : [result.data];
 }
-function buildTypedSelectQuery(input) {
-  const whereClauses = [];
-  for (const condition of input.conditions) {
-    const clause = conditionToSqlClause(condition);
-    if (!clause) return null;
-    whereClauses.push(clause);
+function unwrap(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
   }
-  let limit = input.limit;
-  let offset = input.offset;
-  if (limit === void 0 && input.pageSize !== void 0) {
-    limit = input.pageSize;
+  if (result.data == null && !options?.allowNull) {
+    throw toAthenaGatewayError(result, "Expected data but received null", options?.context);
   }
-  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
-    offset = (input.currentPage - 1) * input.pageSize;
+  return result.data;
+}
+function unwrapOne(result, options) {
+  const rows = unwrapRows(result, options);
+  if (!rows.length) {
+    if (options?.allowNull) return null;
+    throw toAthenaGatewayError(result, "Expected one row but received none", options?.context);
   }
-  const sqlParts = [
-    `SELECT ${buildSelectColumnsClause(input.columns)} FROM ${quoteQualifiedIdentifier(input.tableName)}`
-  ];
-  if (whereClauses.length > 0) {
-    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  if (options?.requireExactlyOne && rows.length !== 1) {
+    throw toAthenaGatewayError(
+      result,
+      `Expected exactly one row but received ${rows.length}`,
+      options.context
+    );
   }
-  if (input.order?.field) {
-    const direction = input.order.direction === "descending" ? "DESC" : "ASC";
-    sqlParts.push(`ORDER BY ${quoteQualifiedIdentifier(input.order.field)} ${direction}`);
+  return rows[0];
+}
+function requireSuccess(result, context) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(
+      result,
+      `Athena ${context?.operation ?? "request"} failed`,
+      context
+    );
   }
-  if (limit !== void 0) {
-    sqlParts.push(`LIMIT ${Math.max(0, Math.trunc(limit))}`);
+  return result;
+}
+function requireAffected(result, options, context) {
+  requireSuccess(result, context);
+  const minimum = options?.min ?? 1;
+  const count = result.count;
+  if (count == null) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: "Expected affected row count but response.count is missing",
+      hint: 'Set call option { count: "exact" } for mutation postcondition checks.',
+      cause: safeStringify(result.raw)
+    });
   }
-  if (offset !== void 0) {
-    sqlParts.push(`OFFSET ${Math.max(0, Math.trunc(offset))}`);
+  if (count < minimum) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: `Expected at least ${minimum} affected rows but received ${count}`,
+      hint: contextHint(context),
+      cause: safeStringify(result.raw)
+    });
   }
-  return `${sqlParts.join(" ")};`;
+  return count;
 }
-function createFilterMethods(state, addCondition, self) {
-  return {
-    eq(column, value) {
-      const columnName = String(column);
-      if (shouldUseUuidTextComparison(columnName, value)) {
-        addCondition("eq", columnName, value, { columnCast: "text" });
-      } else {
-        addCondition("eq", columnName, value);
-      }
-      return self;
-    },
-    eqCast(column, value, cast) {
-      addCondition("eq", String(column), value, { valueCast: cast });
-      return self;
-    },
-    eqUuid(column, value) {
-      addCondition("eq", String(column), value, { valueCast: "uuid" });
-      return self;
-    },
-    match(filters) {
-      Object.entries(filters).forEach(([column, value]) => {
-        if (value === void 0) {
-          return;
-        }
-        if (shouldUseUuidTextComparison(column, value)) {
-          addCondition("eq", column, value, { columnCast: "text" });
-        } else {
-          addCondition("eq", column, value);
-        }
-      });
-      return self;
-    },
-    range(from, to) {
-      state.offset = from;
-      state.limit = to - from + 1;
-      return self;
-    },
-    limit(count) {
-      state.limit = count;
-      return self;
-    },
-    offset(count) {
-      state.offset = count;
-      return self;
-    },
-    currentPage(value) {
-      state.currentPage = value;
-      return self;
-    },
-    pageSize(value) {
-      state.pageSize = value;
-      return self;
-    },
-    totalPages(value) {
-      state.totalPages = value;
-      return self;
-    },
-    order(column, options) {
-      state.order = {
-        field: String(column),
-        direction: options?.ascending === false ? "descending" : "ascending"
-      };
-      return self;
-    },
-    gt(column, value) {
-      addCondition("gt", String(column), value);
-      return self;
-    },
-    gte(column, value) {
-      addCondition("gte", String(column), value);
-      return self;
-    },
-    lt(column, value) {
-      addCondition("lt", String(column), value);
-      return self;
-    },
-    lte(column, value) {
-      addCondition("lte", String(column), value);
-      return self;
-    },
-    neq(column, value) {
-      addCondition("neq", String(column), value);
-      return self;
-    },
-    like(column, value) {
-      addCondition("like", String(column), value);
-      return self;
-    },
-    ilike(column, value) {
-      addCondition("ilike", String(column), value);
-      return self;
-    },
-    is(column, value) {
-      addCondition("is", String(column), value);
-      return self;
-    },
-    in(column, values) {
-      addCondition("in", String(column), values);
-      return self;
-    },
-    contains(column, values) {
-      addCondition("contains", String(column), values);
-      return self;
-    },
-    containedBy(column, values) {
-      addCondition("containedBy", String(column), values);
-      return self;
-    },
-    not(columnOrExpression, operator, value) {
-      const expression = String(columnOrExpression);
-      if (operator != null && value !== void 0) {
-        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue(value)}`);
-      } else {
-        addCondition("not", void 0, expression);
+function applyBounds(value, options) {
+  if (options?.min !== void 0 && value < options.min) return null;
+  if (options?.max !== void 0 && value > options.max) return null;
+  return value;
+}
+function parseIntegerString(value) {
+  const normalized = value.trim();
+  if (!/^[-+]?\d+$/.test(normalized)) return null;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+  return parsed;
+}
+function coerceInt(value, options) {
+  if (value == null) return null;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) return null;
+    return applyBounds(value, options);
+  }
+  if (typeof value === "string") {
+    const parsed = parseIntegerString(value);
+    if (parsed == null) return null;
+    return applyBounds(parsed, options);
+  }
+  if (typeof value === "bigint") {
+    if (options?.strictBigInt) {
+      if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+        return null;
       }
-      return self;
-    },
-    or(expression) {
-      addCondition("or", void 0, expression);
-      return self;
     }
-  };
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+    return applyBounds(parsed, options);
+  }
+  return null;
 }
-function toRpcSelect(columns) {
-  if (!columns) return void 0;
-  return Array.isArray(columns) ? columns.join(",") : columns;
+function assertInt(value, label = "value", options) {
+  const parsed = coerceInt(value, options);
+  if (parsed == null) {
+    throw new TypeError(`${label} must be a finite integer`);
+  }
+  return parsed;
 }
-function createRpcFilterMethods(filters, self) {
-  const addFilter = (operator, column, value) => {
-    filters.push({ column, operator, value });
+function defaultShouldRetry(error) {
+  const normalized = normalizeAthenaError(error);
+  return normalized.kind === "transient" || normalized.kind === "rate_limit";
+}
+function computeDelayMs(attempt, error, config) {
+  const baseDelay = config.baseDelayMs;
+  const rawDelay = typeof config.backoff === "function" ? config.backoff(attempt, error) : config.backoff === "linear" ? baseDelay * attempt : baseDelay * Math.pow(2, attempt - 1);
+  const safeDelay = Number.isFinite(rawDelay) ? Math.max(0, rawDelay) : 0;
+  const clamped = Math.min(config.maxDelayMs, safeDelay);
+  const jitterFactor = typeof config.jitter === "number" ? Math.max(0, Math.min(1, config.jitter)) : config.jitter ? 0.2 : 0;
+  if (!jitterFactor) return clamped;
+  const deviation = clamped * jitterFactor;
+  const offset = (Math.random() * 2 - 1) * deviation;
+  return Math.max(0, clamped + offset);
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve3) => {
+    setTimeout(resolve3, ms);
+  });
+}
+async function withRetry(config, fn) {
+  const retries = Math.max(0, Math.trunc(config.retries));
+  const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
+  const resolvedConfig = {
+    baseDelayMs: config.baseDelayMs ?? 100,
+    maxDelayMs: config.maxDelayMs ?? 1e4,
+    backoff: config.backoff ?? "exponential",
+    jitter: config.jitter ?? false
   };
-  return {
-    eq(column, value) {
-      addFilter("eq", column, value);
-      return self;
-    },
-    neq(column, value) {
-      addFilter("neq", column, value);
-      return self;
-    },
-    gt(column, value) {
-      addFilter("gt", column, value);
-      return self;
+  for (let attempts = 0; attempts <= retries; attempts += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempts >= retries) {
+        throw error;
+      }
+      const currentAttempt = attempts + 1;
+      const retry = await shouldRetry(error, currentAttempt);
+      if (!retry) {
+        throw error;
+      }
+      const delay = computeDelayMs(currentAttempt, error, resolvedConfig);
+      await sleep(delay);
+    }
+  }
+  throw new Error("withRetry reached an unexpected state");
+}
+
+// src/db/module.ts
+function createDbModule(input) {
+  const db = {
+    from(table) {
+      return input.from(table);
     },
-    gte(column, value) {
-      addFilter("gte", column, value);
-      return self;
+    select(table, columns, options) {
+      return input.from(table).select(columns, options);
     },
-    lt(column, value) {
-      addFilter("lt", column, value);
-      return self;
+    insert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).insert(values, options) : input.from(table).insert(values, options);
     },
-    lte(column, value) {
-      addFilter("lte", column, value);
-      return self;
+    upsert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).upsert(values, options) : input.from(table).upsert(values, options);
     },
-    like(column, value) {
-      addFilter("like", column, value);
-      return self;
+    update(table, values, options) {
+      return input.from(table).update(values, options);
     },
-    ilike(column, value) {
-      addFilter("ilike", column, value);
-      return self;
+    delete(table, options) {
+      return input.from(table).delete(options);
     },
-    is(column, value) {
-      addFilter("is", column, value);
-      return self;
+    rpc(fn, args, options) {
+      return input.rpc(fn, args, options);
     },
-    in(column, values) {
-      addFilter("in", column, values);
-      return self;
+    query(query, options) {
+      return input.query(query, options);
     }
   };
+  return db;
 }
-function createRpcBuilder(functionName, args, baseOptions, client) {
-  const state = {
-    filters: []
+
+// src/client.ts
+var DEFAULT_COLUMNS = "*";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
+var ATHENA_NORMALIZED_ERROR_KEY = "__athenaNormalizedError";
+function formatResult(response) {
+  const result = {
+    data: response.data ?? null,
+    error: response.error ?? null,
+    errorDetails: response.errorDetails ?? null,
+    status: response.status,
+    raw: response.raw
   };
-  let selectedColumns;
-  let selectedOptions;
-  let promise = null;
-  const executeRpc = async (columns, options) => {
-    const mergedOptions = mergeOptions(baseOptions, options);
-    const payload = {
-      function: functionName,
-      args,
-      schema: mergedOptions?.schema,
-      select: toRpcSelect(columns),
-      filters: state.filters.length ? [...state.filters] : void 0,
-      count: mergedOptions?.count,
-      head: mergedOptions?.head,
-      limit: state.limit,
-      offset: state.offset,
-      order: state.order
-    };
-    const response = await client.rpcGateway(payload, mergedOptions);
-    return formatResult(response);
+  if (response.count !== void 0) {
+    result.count = response.count;
+  }
+  return result;
+}
+function attachNormalizedError(result, normalizedError) {
+  Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
+    value: normalizedError,
+    enumerable: false,
+    configurable: true,
+    writable: false
+  });
+}
+function createResultFormatter(experimental) {
+  if (!experimental?.enableErrorNormalization) {
+    return formatResult;
+  }
+  return (response, context) => {
+    const result = formatResult(response);
+    if (result.error == null) {
+      return result;
+    }
+    const normalizedError = normalizeAthenaError(result, context);
+    attachNormalizedError(result, normalizedError);
+    return result;
+  };
+}
+function toSingleResult(response) {
+  const payload = response.data;
+  const singleData = Array.isArray(payload) ? payload.length ? payload[0] : null : payload ?? null;
+  return {
+    ...response,
+    data: singleData
   };
+}
+function mergeOptions(...options) {
+  return options.reduce((acc, next) => {
+    if (!next) return acc;
+    return { ...acc, ...next };
+  }, void 0);
+}
+function asAthenaJsonObject(value) {
+  return value;
+}
+function asAthenaJsonObjectArray(values) {
+  return values;
+}
+function createMutationQuery(executor, defaultColumns = DEFAULT_COLUMNS) {
+  let selectedColumns = defaultColumns === null ? void 0 : defaultColumns;
+  let selectedOptions;
+  let promise = null;
   const run = (columns, options) => {
     const payloadColumns = columns ?? selectedColumns;
     const payloadOptions = options ?? selectedOptions;
     if (!promise) {
-      promise = executeRpc(payloadColumns, payloadOptions);
+      promise = executor(payloadColumns, payloadOptions);
     }
     return promise;
   };
-  const builder = {};
-  const filterMethods = createRpcFilterMethods(state.filters, builder);
-  Object.assign(builder, filterMethods, {
+  const mutationQuery = {
     select(columns = selectedColumns, options) {
       selectedColumns = columns;
       selectedOptions = options ?? selectedOptions;
       return run(columns, options);
     },
-    async single(columns, options) {
-      const result = await run(columns, options);
-      return toSingleResult(result);
-    },
-    maybeSingle(columns, options) {
-      return builder.single(columns, options);
-    },
-    order(column, options) {
-      state.order = { column, ascending: options?.ascending ?? true };
-      return builder;
-    },
-    limit(count) {
-      state.limit = count;
-      return builder;
+    returning(columns = selectedColumns, options) {
+      return mutationQuery.select(columns, options);
     },
-    offset(count) {
-      state.offset = count;
-      return builder;
+    single(columns = selectedColumns, options) {
+      selectedColumns = columns;
+      selectedOptions = options ?? selectedOptions;
+      return run(columns, options).then(toSingleResult);
     },
-    range(from, to) {
-      state.offset = from;
-      state.limit = to - from + 1;
-      return builder;
+    maybeSingle(columns = selectedColumns, options) {
+      return mutationQuery.single(columns, options);
     },
     then(onfulfilled, onrejected) {
       return run(selectedColumns, selectedOptions).then(onfulfilled, onrejected);
@@ -2003,122 +2130,511 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
     finally(onfinally) {
       return run(selectedColumns, selectedOptions).finally(onfinally);
     }
-  });
-  return builder;
+  };
+  return mutationQuery;
 }
-function createTableBuilder(tableName, client) {
-  const state = {
-    conditions: []
+function getResourceId(state) {
+  const candidate = state.conditions.find(
+    (condition) => condition.operator === "eq" && (condition.column === "resource_id" || condition.column === "id")
+  );
+  return candidate?.value?.toString();
+}
+function stringifyFilterValue(value) {
+  if (Array.isArray(value)) {
+    return value.join(",");
+  }
+  return String(value);
+}
+function isUuidString(value) {
+  return UUID_PATTERN.test(value.trim());
+}
+function isUuidIdentifierColumn(column) {
+  return column === "id" || /(?:^|_)uuid(?:_|$)/i.test(column) || /_id$/i.test(column);
+}
+function shouldUseUuidTextComparison(column, value) {
+  return typeof value === "string" && isUuidString(value) && isUuidIdentifierColumn(column);
+}
+function normalizeCast(cast) {
+  const normalized = cast.trim().toLowerCase();
+  if (!SAFE_CAST_PATTERN.test(normalized)) {
+    throw new Error(`Invalid cast type "${cast}"`);
+  }
+  return normalized;
+}
+function escapeSqlStringLiteral(value) {
+  return value.replace(/'/g, "''");
+}
+function toSqlLiteral(value) {
+  if (value === null) return "NULL";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "NULL";
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  return `'${escapeSqlStringLiteral(value)}'`;
+}
+function withCast(expression, cast) {
+  if (!cast) return expression;
+  return `${expression}::${normalizeCast(cast)}`;
+}
+function buildSelectColumnsClause(columns) {
+  if (Array.isArray(columns)) {
+    return columns.map((column) => quoteQualifiedIdentifier(column)).join(", ");
+  }
+  return quoteSelectColumnsExpression(columns);
+}
+function resolveTableNameForCall(tableName, schema) {
+  if (!schema) return tableName;
+  const normalizedSchema = schema.trim();
+  if (!normalizedSchema) {
+    throw new Error("schema option must be a non-empty string");
+  }
+  if (tableName.includes(".")) {
+    if (tableName.startsWith(`${normalizedSchema}.`)) {
+      return tableName;
+    }
+    throw new Error(
+      `schema option "${normalizedSchema}" conflicts with schema-qualified table "${tableName}"`
+    );
+  }
+  return `${normalizedSchema}.${tableName}`;
+}
+function conditionToSqlClause(condition) {
+  if (!condition.column) return null;
+  const column = withCast(quoteQualifiedIdentifier(condition.column), condition.column_cast);
+  const value = condition.value;
+  const sqlOperator = {
+    eq: "=",
+    neq: "!=",
+    gt: ">",
+    gte: ">=",
+    lt: "<",
+    lte: "<=",
+    like: "LIKE",
+    ilike: "ILIKE"
   };
-  const addCondition = (operator, column, value, hints) => {
-    const condition = { operator };
-    if (column) {
-      condition.column = column;
-      if (operator === "eq") {
-        condition.eq_column = column;
-      }
+  switch (condition.operator) {
+    case "eq":
+    case "neq":
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+    case "like":
+    case "ilike": {
+      if (Array.isArray(value) || value === void 0) return null;
+      const rhs = withCast(toSqlLiteral(value), condition.value_cast);
+      return `${column} ${sqlOperator[condition.operator]} ${rhs}`;
     }
-    if (value !== void 0) {
-      condition.value = value;
-      if (operator === "eq") {
-        condition.eq_value = value;
-      }
+    case "is": {
+      if (value === null) return `${column} IS NULL`;
+      if (value === true) return `${column} IS TRUE`;
+      if (value === false) return `${column} IS FALSE`;
+      return null;
     }
-    if (hints?.valueCast) {
-      condition.value_cast = hints.valueCast;
-      if (operator === "eq") {
-        condition.eq_value_cast = hints.valueCast;
-      }
+    case "in": {
+      if (!Array.isArray(value)) return null;
+      if (value.length === 0) return "FALSE";
+      const values = value.map((item) => withCast(toSqlLiteral(item), condition.value_cast));
+      return `${column} IN (${values.join(", ")})`;
     }
-    if (hints?.columnCast) {
-      condition.column_cast = hints.columnCast;
-      if (operator === "eq") {
-        condition.eq_column_cast = hints.columnCast;
+    default:
+      return null;
+  }
+}
+function buildTypedSelectQuery(input) {
+  const whereClauses = [];
+  for (const condition of input.conditions) {
+    const clause = conditionToSqlClause(condition);
+    if (!clause) return null;
+    whereClauses.push(clause);
+  }
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = input.pageSize;
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (input.currentPage - 1) * input.pageSize;
+  }
+  const sqlParts = [
+    `SELECT ${buildSelectColumnsClause(input.columns)} FROM ${quoteQualifiedIdentifier(input.tableName)}`
+  ];
+  if (whereClauses.length > 0) {
+    sqlParts.push(`WHERE ${whereClauses.join(" AND ")}`);
+  }
+  if (input.order?.field) {
+    const direction = input.order.direction === "descending" ? "DESC" : "ASC";
+    sqlParts.push(`ORDER BY ${quoteQualifiedIdentifier(input.order.field)} ${direction}`);
+  }
+  if (limit !== void 0) {
+    sqlParts.push(`LIMIT ${Math.max(0, Math.trunc(limit))}`);
+  }
+  if (offset !== void 0) {
+    sqlParts.push(`OFFSET ${Math.max(0, Math.trunc(offset))}`);
+  }
+  return `${sqlParts.join(" ")};`;
+}
+function createFilterMethods(state, addCondition, self) {
+  return {
+    eq(column, value) {
+      const columnName = String(column);
+      if (shouldUseUuidTextComparison(columnName, value)) {
+        addCondition("eq", columnName, value, { columnCast: "text" });
+      } else {
+        addCondition("eq", columnName, value);
       }
-    }
-    state.conditions.push(condition);
-  };
-  const builder = {};
-  const filterMethods = createFilterMethods(
-    state,
-    addCondition,
-    builder
-  );
-  const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
-    const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
-    const conditions = state.conditions.length ? state.conditions.map((condition) => ({ ...condition })) : void 0;
-    const hasTypedEqualityComparison = conditions?.some(
-      (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
-    ) ?? false;
-    if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
-      const query = buildTypedSelectQuery({
-        tableName: resolvedTableName,
-        columns,
-        conditions,
-        limit: state.limit,
-        offset: state.offset,
-        currentPage: state.currentPage,
-        pageSize: state.pageSize,
-        order: state.order
+      return self;
+    },
+    eqCast(column, value, cast) {
+      addCondition("eq", String(column), value, { valueCast: cast });
+      return self;
+    },
+    eqUuid(column, value) {
+      addCondition("eq", String(column), value, { valueCast: "uuid" });
+      return self;
+    },
+    match(filters) {
+      Object.entries(filters).forEach(([column, value]) => {
+        if (value === void 0) {
+          return;
+        }
+        if (shouldUseUuidTextComparison(column, value)) {
+          addCondition("eq", column, value, { columnCast: "text" });
+        } else {
+          addCondition("eq", column, value);
+        }
       });
-      if (query) {
-        const queryResponse = await client.queryGateway({ query }, options);
-        return formatResult(queryResponse);
+      return self;
+    },
+    range(from, to) {
+      state.offset = from;
+      state.limit = to - from + 1;
+      return self;
+    },
+    limit(count) {
+      state.limit = count;
+      return self;
+    },
+    offset(count) {
+      state.offset = count;
+      return self;
+    },
+    currentPage(value) {
+      state.currentPage = value;
+      return self;
+    },
+    pageSize(value) {
+      state.pageSize = value;
+      return self;
+    },
+    totalPages(value) {
+      state.totalPages = value;
+      return self;
+    },
+    order(column, options) {
+      state.order = {
+        field: String(column),
+        direction: options?.ascending === false ? "descending" : "ascending"
+      };
+      return self;
+    },
+    gt(column, value) {
+      addCondition("gt", String(column), value);
+      return self;
+    },
+    gte(column, value) {
+      addCondition("gte", String(column), value);
+      return self;
+    },
+    lt(column, value) {
+      addCondition("lt", String(column), value);
+      return self;
+    },
+    lte(column, value) {
+      addCondition("lte", String(column), value);
+      return self;
+    },
+    neq(column, value) {
+      addCondition("neq", String(column), value);
+      return self;
+    },
+    like(column, value) {
+      addCondition("like", String(column), value);
+      return self;
+    },
+    ilike(column, value) {
+      addCondition("ilike", String(column), value);
+      return self;
+    },
+    is(column, value) {
+      addCondition("is", String(column), value);
+      return self;
+    },
+    in(column, values) {
+      addCondition("in", String(column), values);
+      return self;
+    },
+    contains(column, values) {
+      addCondition("contains", String(column), values);
+      return self;
+    },
+    containedBy(column, values) {
+      addCondition("containedBy", String(column), values);
+      return self;
+    },
+    not(columnOrExpression, operator, value) {
+      const expression = String(columnOrExpression);
+      if (operator != null && value !== void 0) {
+        addCondition("not", void 0, `${expression}.${operator}.${stringifyFilterValue(value)}`);
+      } else {
+        addCondition("not", void 0, expression);
       }
+      return self;
+    },
+    or(expression) {
+      addCondition("or", void 0, expression);
+      return self;
+    }
+  };
+}
+function toRpcSelect(columns) {
+  if (!columns) return void 0;
+  return Array.isArray(columns) ? columns.join(",") : columns;
+}
+function createRpcFilterMethods(filters, self) {
+  const addFilter = (operator, column, value) => {
+    filters.push({ column, operator, value });
+  };
+  return {
+    eq(column, value) {
+      addFilter("eq", column, value);
+      return self;
+    },
+    neq(column, value) {
+      addFilter("neq", column, value);
+      return self;
+    },
+    gt(column, value) {
+      addFilter("gt", column, value);
+      return self;
+    },
+    gte(column, value) {
+      addFilter("gte", column, value);
+      return self;
+    },
+    lt(column, value) {
+      addFilter("lt", column, value);
+      return self;
+    },
+    lte(column, value) {
+      addFilter("lte", column, value);
+      return self;
+    },
+    like(column, value) {
+      addFilter("like", column, value);
+      return self;
+    },
+    ilike(column, value) {
+      addFilter("ilike", column, value);
+      return self;
+    },
+    is(column, value) {
+      addFilter("is", column, value);
+      return self;
+    },
+    in(column, values) {
+      addFilter("in", column, values);
+      return self;
     }
+  };
+}
+function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult) {
+  const state = {
+    filters: []
+  };
+  let selectedColumns;
+  let selectedOptions;
+  let promise = null;
+  const executeRpc = async (columns, options) => {
+    const mergedOptions = mergeOptions(baseOptions, options);
     const payload = {
-      table_name: resolvedTableName,
-      columns,
-      conditions,
+      function: functionName,
+      args,
+      schema: mergedOptions?.schema,
+      select: toRpcSelect(columns),
+      filters: state.filters.length ? [...state.filters] : void 0,
+      count: mergedOptions?.count,
+      head: mergedOptions?.head,
       limit: state.limit,
       offset: state.offset,
-      current_page: state.currentPage,
-      page_size: state.pageSize,
-      total_pages: state.totalPages,
-      sort_by: state.order,
-      strip_nulls: options?.stripNulls ?? true,
-      count: options?.count,
-      head: options?.head
+      order: state.order
     };
-    const response = await client.fetchGateway(payload, options);
-    return formatResult(response);
+    const response = await client.rpcGateway(payload, mergedOptions);
+    return formatGatewayResult(response, { operation: "rpc" });
   };
-  const createSelectChain = (columns, options) => {
-    const chain = {};
-    const filterMethods2 = createFilterMethods(state, addCondition, chain);
-    Object.assign(chain, filterMethods2, {
-      async single(cols, opts) {
-        const r = await runSelect(cols ?? columns, opts ?? options);
-        return toSingleResult(r);
-      },
-      maybeSingle(cols, opts) {
-        return chain.single(cols, opts);
-      },
-      then(onfulfilled, onrejected) {
-        return runSelect(columns, options).then(onfulfilled, onrejected);
-      },
-      catch(onrejected) {
-        return runSelect(columns, options).catch(onrejected);
-      },
-      finally(onfinally) {
-        return runSelect(columns, options).finally(onfinally);
-      }
-    });
-    return chain;
+  const run = (columns, options) => {
+    const payloadColumns = columns ?? selectedColumns;
+    const payloadOptions = options ?? selectedOptions;
+    if (!promise) {
+      promise = executeRpc(payloadColumns, payloadOptions);
+    }
+    return promise;
   };
+  const builder = {};
+  const filterMethods = createRpcFilterMethods(state.filters, builder);
   Object.assign(builder, filterMethods, {
-    reset() {
-      state.conditions = [];
-      state.limit = void 0;
-      state.offset = void 0;
-      state.order = void 0;
-      state.currentPage = void 0;
-      state.pageSize = void 0;
-      state.totalPages = void 0;
-      return builder;
+    select(columns = selectedColumns, options) {
+      selectedColumns = columns;
+      selectedOptions = options ?? selectedOptions;
+      return run(columns, options);
     },
-    select(columns = DEFAULT_COLUMNS, options) {
-      return createSelectChain(columns, options);
+    async single(columns, options) {
+      const result = await run(columns, options);
+      return toSingleResult(result);
+    },
+    maybeSingle(columns, options) {
+      return builder.single(columns, options);
+    },
+    order(column, options) {
+      state.order = { column, ascending: options?.ascending ?? true };
+      return builder;
+    },
+    limit(count) {
+      state.limit = count;
+      return builder;
+    },
+    offset(count) {
+      state.offset = count;
+      return builder;
+    },
+    range(from, to) {
+      state.offset = from;
+      state.limit = to - from + 1;
+      return builder;
+    },
+    then(onfulfilled, onrejected) {
+      return run(selectedColumns, selectedOptions).then(onfulfilled, onrejected);
+    },
+    catch(onrejected) {
+      return run(selectedColumns, selectedOptions).catch(onrejected);
+    },
+    finally(onfinally) {
+      return run(selectedColumns, selectedOptions).finally(onfinally);
+    }
+  });
+  return builder;
+}
+function createTableBuilder(tableName, client, formatGatewayResult) {
+  const state = {
+    conditions: []
+  };
+  const addCondition = (operator, column, value, hints) => {
+    const condition = { operator };
+    if (column) {
+      condition.column = column;
+      if (operator === "eq") {
+        condition.eq_column = column;
+      }
+    }
+    if (value !== void 0) {
+      condition.value = value;
+      if (operator === "eq") {
+        condition.eq_value = value;
+      }
+    }
+    if (hints?.valueCast) {
+      condition.value_cast = hints.valueCast;
+      if (operator === "eq") {
+        condition.eq_value_cast = hints.valueCast;
+      }
+    }
+    if (hints?.columnCast) {
+      condition.column_cast = hints.columnCast;
+      if (operator === "eq") {
+        condition.eq_column_cast = hints.columnCast;
+      }
+    }
+    state.conditions.push(condition);
+  };
+  const builder = {};
+  const filterMethods = createFilterMethods(
+    state,
+    addCondition,
+    builder
+  );
+  const runSelect = async (columns = DEFAULT_COLUMNS, options) => {
+    const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
+    const conditions = state.conditions.length ? state.conditions.map((condition) => ({ ...condition })) : void 0;
+    const hasTypedEqualityComparison = conditions?.some(
+      (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
+    ) ?? false;
+    if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
+      const query = buildTypedSelectQuery({
+        tableName: resolvedTableName,
+        columns,
+        conditions,
+        limit: state.limit,
+        offset: state.offset,
+        currentPage: state.currentPage,
+        pageSize: state.pageSize,
+        order: state.order
+      });
+      if (query) {
+        const queryResponse = await client.queryGateway({ query }, options);
+        return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
+      }
+    }
+    const payload = {
+      table_name: resolvedTableName,
+      columns,
+      conditions,
+      limit: state.limit,
+      offset: state.offset,
+      current_page: state.currentPage,
+      page_size: state.pageSize,
+      total_pages: state.totalPages,
+      sort_by: state.order,
+      strip_nulls: options?.stripNulls ?? true,
+      count: options?.count,
+      head: options?.head
+    };
+    const response = await client.fetchGateway(payload, options);
+    return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+  };
+  const createSelectChain = (columns, options) => {
+    const chain = {};
+    const filterMethods2 = createFilterMethods(state, addCondition, chain);
+    Object.assign(chain, filterMethods2, {
+      async single(cols, opts) {
+        const r = await runSelect(cols ?? columns, opts ?? options);
+        return toSingleResult(r);
+      },
+      maybeSingle(cols, opts) {
+        return chain.single(cols, opts);
+      },
+      then(onfulfilled, onrejected) {
+        return runSelect(columns, options).then(onfulfilled, onrejected);
+      },
+      catch(onrejected) {
+        return runSelect(columns, options).catch(onrejected);
+      },
+      finally(onfinally) {
+        return runSelect(columns, options).finally(onfinally);
+      }
+    });
+    return chain;
+  };
+  Object.assign(builder, filterMethods, {
+    reset() {
+      state.conditions = [];
+      state.limit = void 0;
+      state.offset = void 0;
+      state.order = void 0;
+      state.currentPage = void 0;
+      state.pageSize = void 0;
+      state.totalPages = void 0;
+      return builder;
+    },
+    select(columns = DEFAULT_COLUMNS, options) {
+      return createSelectChain(columns, options);
     },
     insert(values, options) {
       if (Array.isArray(values)) {
@@ -2136,7 +2652,7 @@ function createTableBuilder(tableName, client) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
           const response = await client.insertGateway(payload, mergedOptions);
-          return formatResult(response);
+          return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
         };
         return createMutationQuery(executeInsertMany);
       }
@@ -2154,7 +2670,7 @@ function createTableBuilder(tableName, client) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
         const response = await client.insertGateway(payload, mergedOptions);
-        return formatResult(response);
+        return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
       };
       return createMutationQuery(executeInsertOne);
     },
@@ -2176,7 +2692,7 @@ function createTableBuilder(tableName, client) {
             payload.default_to_null = mergedOptions.defaultToNull;
           }
           const response = await client.insertGateway(payload, mergedOptions);
-          return formatResult(response);
+          return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
         };
         return createMutationQuery(executeUpsertMany);
       }
@@ -2196,7 +2712,7 @@ function createTableBuilder(tableName, client) {
           payload.default_to_null = mergedOptions.defaultToNull;
         }
         const response = await client.insertGateway(payload, mergedOptions);
-        return formatResult(response);
+        return formatGatewayResult(response, { table: resolvedTableName, operation: "insert" });
       };
       return createMutationQuery(executeUpsertOne);
     },
@@ -2217,7 +2733,7 @@ function createTableBuilder(tableName, client) {
         if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.updateGateway(payload, mergedOptions);
-        return formatResult(response);
+        return formatGatewayResult(response, { table: resolvedTableName, operation: "update" });
       };
       const mutation = createMutationQuery(executeUpdate, null);
       const updateChain = {};
@@ -2245,7 +2761,7 @@ function createTableBuilder(tableName, client) {
         if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.deleteGateway(payload, mergedOptions);
-        return formatResult(response);
+        return formatGatewayResult(response, { table: resolvedTableName, operation: "delete" });
       };
       return createMutationQuery(executeDelete, null);
     },
@@ -2259,14 +2775,14 @@ function createTableBuilder(tableName, client) {
   });
   return builder;
 }
-function createQueryBuilder(client) {
+function createQueryBuilder(client, formatGatewayResult) {
   return async function query(query, options) {
     const normalizedQuery = query.trim();
     if (!normalizedQuery) {
       throw new Error("query requires a non-empty string");
     }
     const response = await client.queryGateway({ query: normalizedQuery }, options);
-    return formatResult(response);
+    return formatGatewayResult(response, { operation: "query" });
   };
 }
 function createClientFromConfig(config) {
@@ -2277,24 +2793,29 @@ function createClientFromConfig(config) {
     backend: config.backend,
     headers: config.headers
   });
+  const formatGatewayResult = createResultFormatter(config.experimental);
   const auth = createAuthClient(config.auth);
+  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult);
+  const rpc = (fn, args, options) => {
+    const normalizedFn = fn.trim();
+    if (!normalizedFn) {
+      throw new Error("rpc requires a function name");
+    }
+    return createRpcBuilder(
+      normalizedFn,
+      args,
+      options,
+      gateway,
+      formatGatewayResult
+    );
+  };
+  const query = createQueryBuilder(gateway, formatGatewayResult);
+  const db = createDbModule({ from, rpc, query });
   return {
-    from(table) {
-      return createTableBuilder(table, gateway);
-    },
-    rpc(fn, args, options) {
-      const normalizedFn = fn.trim();
-      if (!normalizedFn) {
-        throw new Error("rpc requires a function name");
-      }
-      return createRpcBuilder(
-        normalizedFn,
-        args,
-        options,
-        gateway
-      );
-    },
-    query: createQueryBuilder(gateway),
+    from,
+    db,
+    rpc,
+    query,
     auth: auth.auth
   };
 }
@@ -2305,516 +2826,86 @@ function toBackendConfig(b) {
 }
 var AthenaClientBuilderImpl = class {
   baseUrl;
-  apiKey;
-  backendConfig = DEFAULT_BACKEND;
-  clientName;
-  defaultHeaders;
-  isHealthTrackingEnabled = false;
-  url(url) {
-    this.baseUrl = url;
-    return this;
-  }
-  key(apiKey) {
-    this.apiKey = apiKey;
-    return this;
-  }
-  backend(backend) {
-    this.backendConfig = toBackendConfig(backend);
-    return this;
-  }
-  client(clientName) {
-    this.clientName = clientName;
-    return this;
-  }
-  headers(headers) {
-    this.defaultHeaders = headers;
-    return this;
-  }
-  healthTracking(enabled) {
-    this.isHealthTrackingEnabled = enabled;
-    return this;
-  }
-  build() {
-    if (!this.baseUrl || !this.apiKey) {
-      throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
-    }
-    return createClientFromConfig({
-      baseUrl: this.baseUrl,
-      apiKey: this.apiKey,
-      client: this.clientName,
-      backend: this.backendConfig,
-      headers: this.defaultHeaders,
-      healthTracking: this.isHealthTrackingEnabled
-    });
-  }
-};
-var AthenaClient = class _AthenaClient {
-  /** Create a fluent builder for a strongly-typed Athena SDK client. */
-  static builder() {
-    return new AthenaClientBuilderImpl();
-  }
-  /** Build a client from process environment variables. */
-  static fromEnvironment() {
-    const url = process.env.ATHENA_URL ?? process.env.ATHENA_GATEWAY_URL;
-    const key = process.env.ATHENA_API_KEY ?? process.env.ATHENA_GATEWAY_API_KEY;
-    if (!url || !key) {
-      throw new Error(
-        "ATHENA_URL and ATHENA_API_KEY (or ATHENA_GATEWAY_URL and ATHENA_GATEWAY_API_KEY) are required"
-      );
-    }
-    return _AthenaClient.builder().url(url).key(key).build();
-  }
-};
-function createClient(url, apiKey, options) {
-  const b = AthenaClient.builder().url(url).key(apiKey).backend(toBackendConfig(options?.backend));
-  if (options?.client) b.client(options.client);
-  if (options?.headers && Object.keys(options.headers).length > 0) b.headers(options.headers);
-  const client = b.build();
-  if (options?.auth) {
-    client.auth = createAuthClient(options.auth).auth;
-  }
-  return client;
-}
-
-// src/gateway/types.ts
-var Backend = {
-  Athena: { type: "athena" },
-  Postgrest: { type: "postgrest" },
-  PostgreSQL: { type: "postgresql" },
-  ScyllaDB: { type: "scylladb" }
-};
-
-// src/auxiliaries.ts
-var AthenaErrorKind = {
-  UniqueViolation: "unique_violation",
-  NotFound: "not_found",
-  Validation: "validation",
-  Auth: "auth",
-  RateLimit: "rate_limit",
-  Transient: "transient",
-  Unknown: "unknown"
-};
-var AthenaErrorCode = {
-  UniqueViolation: "UNIQUE_VIOLATION",
-  NotFound: "NOT_FOUND",
-  ValidationFailed: "VALIDATION_FAILED",
-  AuthUnauthorized: "AUTH_UNAUTHORIZED",
-  AuthForbidden: "AUTH_FORBIDDEN",
-  RateLimited: "RATE_LIMITED",
-  NetworkUnavailable: "NETWORK_UNAVAILABLE",
-  TransientFailure: "TRANSIENT_FAILURE",
-  HttpFailure: "HTTP_FAILURE",
-  Unknown: "UNKNOWN"
-};
-var AthenaErrorCategory = {
-  Transport: "transport",
-  Client: "client",
-  Server: "server",
-  Database: "database",
-  Unknown: "unknown"
-};
-function parseBooleanFlag(rawValue, fallback) {
-  if (!rawValue) return fallback;
-  const normalized = rawValue.trim().toLowerCase();
-  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
-    return true;
-  }
-  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
-    return false;
-  }
-  return fallback;
-}
-var AthenaError = class extends Error {
-  code;
-  kind;
-  category;
-  status;
-  retryable;
-  requestId;
-  context;
-  raw;
-  constructor(input) {
-    super(input.message);
-    this.name = "AthenaError";
-    this.code = input.code;
-    this.kind = input.kind;
-    this.category = input.category;
-    this.status = input.status;
-    this.retryable = input.retryable ?? false;
-    this.requestId = input.requestId;
-    this.context = input.context;
-    this.raw = input.raw;
-  }
-};
-function isRecord3(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function safeStringify(value) {
-  try {
-    const serialized = JSON.stringify(value);
-    return serialized ?? String(value);
-  } catch {
-    return "[unserializable]";
-  }
-}
-function contextHint(context) {
-  if (!context?.identity) return void 0;
-  const identity = typeof context.identity === "string" ? context.identity : safeStringify(context.identity);
-  return `Identity: ${identity}`;
-}
-function isAthenaResultLike(value) {
-  return isRecord3(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
-}
-function operationFromDetails(details) {
-  if (!details?.endpoint) return void 0;
-  if (details.endpoint === "/gateway/fetch" || details.endpoint === "/gateway/query") return "select";
-  if (details.endpoint === "/gateway/insert") return "insert";
-  if (details.endpoint === "/gateway/update") return "update";
-  if (details.endpoint === "/gateway/delete") return "delete";
-  if (details.endpoint === "/gateway/rpc" || details.endpoint.startsWith("/rpc/")) return "rpc";
-  return void 0;
-}
-function matchRegex(input, patterns) {
-  for (const pattern of patterns) {
-    const match = pattern.exec(input);
-    if (match?.[1]) return match[1];
-  }
-  return void 0;
-}
-function extractConstraint(message) {
-  return matchRegex(message, [
-    /unique constraint\s+["'`]([^"'`]+)["'`]/i,
-    /constraint\s+["'`]([^"'`]+)["'`]/i
-  ]);
-}
-function extractTable(message) {
-  return matchRegex(message, [
-    /(?:table|relation)\s+["'`]([^"'`]+)["'`]/i,
-    /on\s+table\s+([a-zA-Z0-9_.]+)/i
-  ]);
-}
-function classifyKind(status, code, message) {
-  const lower = message.toLowerCase();
-  const hasUniquePattern = lower.includes("unique constraint") || lower.includes("duplicate key") || lower.includes("already exists") || lower.includes("duplicate");
-  const hasNotFoundPattern = lower.includes("not found") || lower.includes("no rows");
-  const hasValidationPattern = lower.includes("validation") || lower.includes("invalid") || lower.includes("malformed");
-  const hasAuthPattern = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("auth");
-  const hasRateLimitPattern = lower.includes("rate limit") || lower.includes("too many requests");
-  const hasTransientPattern = lower.includes("timeout") || lower.includes("temporar") || lower.includes("connection reset") || lower.includes("socket") || lower.includes("deadlock");
-  if (status === 409 || hasUniquePattern) return "unique_violation";
-  if (status === 404 || hasNotFoundPattern) return "not_found";
-  if (status === 401 || status === 403 || hasAuthPattern) return "auth";
-  if (status === 429 || hasRateLimitPattern) return "rate_limit";
-  if (status === 400 || status === 422 || hasValidationPattern) return "validation";
-  if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
-    return "transient";
-  }
-  return "unknown";
-}
-function toAthenaErrorCode(kind, status, gatewayCode) {
-  if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
-    return AthenaErrorCode.NetworkUnavailable;
-  }
-  switch (kind) {
-    case "unique_violation":
-      return AthenaErrorCode.UniqueViolation;
-    case "not_found":
-      return AthenaErrorCode.NotFound;
-    case "validation":
-      return AthenaErrorCode.ValidationFailed;
-    case "rate_limit":
-      return AthenaErrorCode.RateLimited;
-    case "auth":
-      if (status === 403) {
-        return AthenaErrorCode.AuthForbidden;
-      }
-      return AthenaErrorCode.AuthUnauthorized;
-    case "transient":
-      return status !== void 0 && status >= 500 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.TransientFailure;
-    case "unknown":
-    default:
-      return status !== void 0 && status >= 400 ? AthenaErrorCode.HttpFailure : AthenaErrorCode.Unknown;
-  }
-}
-function toAthenaErrorCategory(kind, status) {
-  if (kind === "transient" && (status === 0 || status === void 0)) {
-    return AthenaErrorCategory.Transport;
-  }
-  if (kind === "unique_violation") return AthenaErrorCategory.Database;
-  if (kind === "validation" || kind === "auth" || kind === "not_found") return AthenaErrorCategory.Client;
-  if (kind === "rate_limit" || kind === "transient") return AthenaErrorCategory.Server;
-  return AthenaErrorCategory.Unknown;
-}
-function isRetryable(kind, status) {
-  if (kind === "rate_limit" || kind === "transient") return true;
-  return status !== void 0 && status >= 500;
-}
-function toGatewayCode(kind, status) {
-  if (kind === "transient" && (status === 0 || status === void 0)) return "NETWORK_ERROR";
-  if (kind === "validation") return "INVALID_JSON";
-  if (status !== void 0 && status >= 400) return "HTTP_ERROR";
-  return "UNKNOWN_ERROR";
-}
-function toAthenaGatewayError(source, fallbackMessage, context) {
-  if (isAthenaGatewayError(source)) {
-    return source;
-  }
-  if (isAthenaResultLike(source) && source.errorDetails) {
-    return new AthenaGatewayError({
-      code: source.errorDetails.code,
-      message: source.error ?? source.errorDetails.message,
-      status: source.status,
-      endpoint: source.errorDetails.endpoint,
-      method: source.errorDetails.method,
-      requestId: source.errorDetails.requestId,
-      hint: source.errorDetails.hint,
-      cause: source.errorDetails.cause
-    });
-  }
-  const normalized = normalizeAthenaError(source, context);
-  const message = isAthenaResultLike(source) && source.error == null && source.errorDetails == null ? fallbackMessage : normalized.message || fallbackMessage;
-  return new AthenaGatewayError({
-    code: toGatewayCode(normalized.kind, normalized.status),
-    message,
-    status: normalized.status ?? 0,
-    hint: normalized.constraint != null ? `Constraint: ${normalized.constraint}` : contextHint(context),
-    cause: typeof normalized.raw === "string" ? normalized.raw : safeStringify(normalized.raw)
-  });
-}
-function isOk(result) {
-  return result.error == null && result.status >= 200 && result.status < 300;
-}
-function normalizeAthenaError(resultOrError, context) {
-  if (isAthenaResultLike(resultOrError)) {
-    const details = resultOrError.errorDetails;
-    const message2 = resultOrError.error ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
-    const operation = context?.operation ?? operationFromDetails(details);
-    const table = context?.table ?? extractTable(message2);
-    const constraint = extractConstraint(message2);
-    const kind2 = classifyKind(resultOrError.status, details?.code, message2);
-    const code = toAthenaErrorCode(kind2, resultOrError.status, details?.code);
-    const category = toAthenaErrorCategory(kind2, resultOrError.status);
-    return {
-      kind: kind2,
-      code,
-      category,
-      retryable: isRetryable(kind2, resultOrError.status),
-      status: resultOrError.status,
-      constraint,
-      table,
-      operation,
-      message: message2,
-      raw: resultOrError.raw
-    };
-  }
-  if (isAthenaGatewayError(resultOrError)) {
-    const details = resultOrError.toDetails();
-    const operation = context?.operation ?? operationFromDetails(details);
-    const table = context?.table ?? extractTable(resultOrError.message);
-    const constraint = extractConstraint(resultOrError.message);
-    const kind2 = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
-    const code = toAthenaErrorCode(kind2, resultOrError.status, resultOrError.code);
-    const category = toAthenaErrorCategory(kind2, resultOrError.status);
-    return {
-      kind: kind2,
-      code,
-      category,
-      retryable: isRetryable(kind2, resultOrError.status),
-      status: resultOrError.status,
-      constraint,
-      table,
-      operation,
-      message: resultOrError.message,
-      raw: resultOrError
-    };
-  }
-  if (resultOrError instanceof Error) {
-    const maybeStatus = isRecord3(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
-    const kind2 = classifyKind(maybeStatus, void 0, resultOrError.message);
-    return {
-      kind: kind2,
-      code: toAthenaErrorCode(kind2, maybeStatus),
-      category: toAthenaErrorCategory(kind2, maybeStatus),
-      retryable: isRetryable(kind2, maybeStatus),
-      status: maybeStatus,
-      constraint: extractConstraint(resultOrError.message),
-      table: context?.table ?? extractTable(resultOrError.message),
-      operation: context?.operation,
-      message: resultOrError.message,
-      raw: resultOrError
-    };
-  }
-  const message = typeof resultOrError === "string" ? resultOrError : "Unknown Athena error";
-  const kind = classifyKind(void 0, void 0, message);
-  return {
-    kind,
-    code: toAthenaErrorCode(kind, void 0),
-    category: toAthenaErrorCategory(kind, void 0),
-    retryable: isRetryable(kind, void 0),
-    status: void 0,
-    constraint: extractConstraint(message),
-    table: context?.table ?? extractTable(message),
-    operation: context?.operation,
-    message,
-    raw: resultOrError
-  };
-}
-function unwrapRows(result, options) {
-  if (!isOk(result)) {
-    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
-  }
-  if (result.data == null) return [];
-  return Array.isArray(result.data) ? result.data : [result.data];
-}
-function unwrap(result, options) {
-  if (!isOk(result)) {
-    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
-  }
-  if (result.data == null && !options?.allowNull) {
-    throw toAthenaGatewayError(result, "Expected data but received null", options?.context);
-  }
-  return result.data;
-}
-function unwrapOne(result, options) {
-  const rows = unwrapRows(result, options);
-  if (!rows.length) {
-    if (options?.allowNull) return null;
-    throw toAthenaGatewayError(result, "Expected one row but received none", options?.context);
-  }
-  if (options?.requireExactlyOne && rows.length !== 1) {
-    throw toAthenaGatewayError(
-      result,
-      `Expected exactly one row but received ${rows.length}`,
-      options.context
-    );
+  apiKey;
+  backendConfig = DEFAULT_BACKEND;
+  clientName;
+  defaultHeaders;
+  isHealthTrackingEnabled = false;
+  url(url) {
+    this.baseUrl = url;
+    return this;
   }
-  return rows[0];
-}
-function requireSuccess(result, context) {
-  if (!isOk(result)) {
-    throw toAthenaGatewayError(
-      result,
-      `Athena ${context?.operation ?? "request"} failed`,
-      context
-    );
+  key(apiKey) {
+    this.apiKey = apiKey;
+    return this;
   }
-  return result;
-}
-function requireAffected(result, options, context) {
-  requireSuccess(result, context);
-  const minimum = options?.min ?? 1;
-  const count = result.count;
-  if (count == null) {
-    throw new AthenaGatewayError({
-      code: "UNKNOWN_ERROR",
-      status: result.status,
-      message: "Expected affected row count but response.count is missing",
-      hint: 'Set call option { count: "exact" } for mutation postcondition checks.',
-      cause: safeStringify(result.raw)
-    });
+  backend(backend) {
+    this.backendConfig = toBackendConfig(backend);
+    return this;
   }
-  if (count < minimum) {
-    throw new AthenaGatewayError({
-      code: "UNKNOWN_ERROR",
-      status: result.status,
-      message: `Expected at least ${minimum} affected rows but received ${count}`,
-      hint: contextHint(context),
-      cause: safeStringify(result.raw)
-    });
+  client(clientName) {
+    this.clientName = clientName;
+    return this;
   }
-  return count;
-}
-function applyBounds(value, options) {
-  if (options?.min !== void 0 && value < options.min) return null;
-  if (options?.max !== void 0 && value > options.max) return null;
-  return value;
-}
-function parseIntegerString(value) {
-  const normalized = value.trim();
-  if (!/^[-+]?\d+$/.test(normalized)) return null;
-  const parsed = Number(normalized);
-  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
-  return parsed;
-}
-function coerceInt(value, options) {
-  if (value == null) return null;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value) || !Number.isInteger(value)) return null;
-    return applyBounds(value, options);
+  headers(headers) {
+    this.defaultHeaders = headers;
+    return this;
   }
-  if (typeof value === "string") {
-    const parsed = parseIntegerString(value);
-    if (parsed == null) return null;
-    return applyBounds(parsed, options);
+  healthTracking(enabled) {
+    this.isHealthTrackingEnabled = enabled;
+    return this;
   }
-  if (typeof value === "bigint") {
-    if (options?.strictBigInt) {
-      if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
-        return null;
-      }
+  build() {
+    if (!this.baseUrl || !this.apiKey) {
+      throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
     }
-    const parsed = Number(value);
-    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
-    return applyBounds(parsed, options);
+    return createClientFromConfig({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      client: this.clientName,
+      backend: this.backendConfig,
+      headers: this.defaultHeaders,
+      healthTracking: this.isHealthTrackingEnabled
+    });
   }
-  return null;
-}
-function assertInt(value, label = "value", options) {
-  const parsed = coerceInt(value, options);
-  if (parsed == null) {
-    throw new TypeError(`${label} must be a finite integer`);
+};
+var AthenaClient = class _AthenaClient {
+  /** Create a fluent builder for a strongly-typed Athena SDK client. */
+  static builder() {
+    return new AthenaClientBuilderImpl();
   }
-  return parsed;
-}
-function defaultShouldRetry(error) {
-  const normalized = normalizeAthenaError(error);
-  return normalized.kind === "transient" || normalized.kind === "rate_limit";
-}
-function computeDelayMs(attempt, error, config) {
-  const baseDelay = config.baseDelayMs;
-  const rawDelay = typeof config.backoff === "function" ? config.backoff(attempt, error) : config.backoff === "linear" ? baseDelay * attempt : baseDelay * Math.pow(2, attempt - 1);
-  const safeDelay = Number.isFinite(rawDelay) ? Math.max(0, rawDelay) : 0;
-  const clamped = Math.min(config.maxDelayMs, safeDelay);
-  const jitterFactor = typeof config.jitter === "number" ? Math.max(0, Math.min(1, config.jitter)) : config.jitter ? 0.2 : 0;
-  if (!jitterFactor) return clamped;
-  const deviation = clamped * jitterFactor;
-  const offset = (Math.random() * 2 - 1) * deviation;
-  return Math.max(0, clamped + offset);
-}
-function sleep(ms) {
-  if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve3) => {
-    setTimeout(resolve3, ms);
-  });
-}
-async function withRetry(config, fn) {
-  const retries = Math.max(0, Math.trunc(config.retries));
-  const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
-  const resolvedConfig = {
-    baseDelayMs: config.baseDelayMs ?? 100,
-    maxDelayMs: config.maxDelayMs ?? 1e4,
-    backoff: config.backoff ?? "exponential",
-    jitter: config.jitter ?? false
-  };
-  for (let attempts = 0; attempts <= retries; attempts += 1) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (attempts >= retries) {
-        throw error;
-      }
-      const currentAttempt = attempts + 1;
-      const retry = await shouldRetry(error, currentAttempt);
-      if (!retry) {
-        throw error;
-      }
-      const delay = computeDelayMs(currentAttempt, error, resolvedConfig);
-      await sleep(delay);
+  /** Build a client from process environment variables. */
+  static fromEnvironment() {
+    const url = process.env.ATHENA_URL ?? process.env.ATHENA_GATEWAY_URL;
+    const key = process.env.ATHENA_API_KEY ?? process.env.ATHENA_GATEWAY_API_KEY;
+    if (!url || !key) {
+      throw new Error(
+        "ATHENA_URL and ATHENA_API_KEY (or ATHENA_GATEWAY_URL and ATHENA_GATEWAY_API_KEY) are required"
+      );
     }
+    return _AthenaClient.builder().url(url).key(key).build();
   }
-  throw new Error("withRetry reached an unexpected state");
+};
+function createClient(url, apiKey, options) {
+  return createClientFromConfig({
+    baseUrl: url,
+    apiKey,
+    client: options?.client,
+    backend: toBackendConfig(options?.backend),
+    headers: options?.headers,
+    auth: options?.auth,
+    experimental: options?.experimental
+  });
 }
 
+// src/gateway/types.ts
+var Backend = {
+  Athena: { type: "athena" },
+  Postgrest: { type: "postgrest" },
+  PostgreSQL: { type: "postgresql" },
+  ScyllaDB: { type: "scylladb" }
+};
+
 // src/schema/definitions.ts
 function defineModel(input) {
   return input;
@@ -2880,6 +2971,7 @@ var TypedAthenaClientImpl = class _TypedAthenaClientImpl {
   registry;
   tenantKeyMap;
   tenantContext;
+  db;
   baseClient;
   registryNavigator;
   tenantHeaderMapper;
@@ -2906,6 +2998,7 @@ var TypedAthenaClientImpl = class _TypedAthenaClientImpl {
       client: this.clientOptions.client,
       headers: this.tenantHeaderMapper.apply(this.clientOptions.headers, tenantContext)
     });
+    this.db = this.baseClient.db;
   }
   from(table) {
     return this.baseClient.from(table);
@@ -3295,6 +3388,21 @@ var PostgresCatalogSnapshotAssembler = class {
 };
 
 // src/schema/postgres-provider.ts
+var pgPoolConstructorPromise;
+async function loadPgPoolConstructor() {
+  if (!pgPoolConstructorPromise) {
+    pgPoolConstructorPromise = import('pg').then((module) => {
+      const poolConstructor = module.Pool ?? module.default?.Pool;
+      if (!poolConstructor) {
+        throw new Error(
+          '@xylex-group/athena: Unable to load the PostgreSQL driver. Ensure "pg" is installed and this API runs in a Node.js server runtime.'
+        );
+      }
+      return poolConstructor;
+    });
+  }
+  return pgPoolConstructorPromise;
+}
 var PgCatalogClient = class {
   constructor(pool) {
     this.pool = pool;
@@ -3334,7 +3442,8 @@ var PostgresIntrospectionProvider = class {
   }
   async inspect(options) {
     const schemas = options?.schemas && options.schemas.length > 0 ? normalizePostgresCatalogSchemas(options.schemas) : this.schemas;
-    const pool = new Pool({
+    const PoolConstructor = await loadPgPoolConstructor();
+    const pool = new PoolConstructor({
       connectionString: this.connectionString
     });
     const catalogClient = new PgCatalogClient(pool);
@@ -3456,6 +3565,7 @@ function resolveProviderSchemas(providerConfig) {
 }
 
 // src/generator/config.ts
+var POSTGRES_PROTOCOLS = /* @__PURE__ */ new Set(["postgres:", "postgresql:"]);
 var DEFAULT_CONFIG_CANDIDATES = [
   "athena.config.ts",
   "athena.config.js",
@@ -3485,6 +3595,151 @@ var DEFAULT_EXPERIMENTAL_FLAGS = {
   postgresGatewayIntrospection: false,
   scyllaProviderContracts: true
 };
+var PROJECT_ENV_FILENAMES = [".env", ".env.local"];
+var DIRECT_CONNECTION_STRING_ENV_KEYS = [
+  "ATHENA_GENERATOR_PG_URL",
+  "DATABASE_URL",
+  "PG_URL",
+  "POSTGRES_URL",
+  "POSTGRESQL_URL"
+];
+var POSTGRES_DATABASE_ENV_KEYS = ["ATHENA_GENERATOR_DB", "ATHENA_DATABASE", "PGDATABASE"];
+var POSTGRES_PASSWORD_ENV_KEYS = ["ATHENA_GENERATOR_PG_PASSWORD", "PGPASSWORD"];
+var GATEWAY_URL_ENV_KEYS = ["ATHENA_URL", "ATHENA_GATEWAY_URL", "ATHENA_GENERATOR_URL"];
+var GATEWAY_API_KEY_ENV_KEYS = [
+  "ATHENA_API_KEY",
+  "ATHENA_GATEWAY_API_KEY",
+  "ATHENA_GENERATOR_API_KEY"
+];
+function normalizeRawEnvValue(rawValue) {
+  if (rawValue.startsWith('"') && rawValue.endsWith('"') && rawValue.length >= 2) {
+    const inner = rawValue.slice(1, -1);
+    return inner.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  if (rawValue.startsWith("'") && rawValue.endsWith("'") && rawValue.length >= 2) {
+    return rawValue.slice(1, -1);
+  }
+  const commentIndex = rawValue.search(/\s+#/);
+  const withoutComment = commentIndex >= 0 ? rawValue.slice(0, commentIndex) : rawValue;
+  return withoutComment.trim();
+}
+function parseEnvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) {
+    return void 0;
+  }
+  const match = trimmed.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+  if (!match) {
+    return void 0;
+  }
+  const [, key, rawValue] = match;
+  return [key, normalizeRawEnvValue(rawValue.trim())];
+}
+function readProjectEnvEntries(cwd) {
+  const nodeEnv = process.env.NODE_ENV?.trim();
+  const filenames = [
+    ...PROJECT_ENV_FILENAMES,
+    ...nodeEnv ? [`.env.${nodeEnv}`, `.env.${nodeEnv}.local`] : []
+  ];
+  const entries = /* @__PURE__ */ new Map();
+  for (const filename of filenames) {
+    const absolutePath = resolve(cwd, filename);
+    if (!existsSync(absolutePath)) {
+      continue;
+    }
+    const content = readFileSync(absolutePath, "utf8");
+    const lines = content.split(/\r?\n/g);
+    for (const line of lines) {
+      const parsed = parseEnvLine(line);
+      if (!parsed) {
+        continue;
+      }
+      const [key, value] = parsed;
+      entries.set(key, value);
+    }
+  }
+  return entries;
+}
+function applyProjectEnv(cwd) {
+  const envEntries = readProjectEnvEntries(cwd);
+  if (envEntries.size === 0) {
+    return () => {
+    };
+  }
+  const initialKeys = new Set(
+    Object.keys(process.env).filter((key) => process.env[key] !== void 0)
+  );
+  const staged = /* @__PURE__ */ new Map();
+  for (const [key, value] of envEntries.entries()) {
+    if (initialKeys.has(key)) {
+      continue;
+    }
+    staged.set(key, value);
+  }
+  for (const [key, value] of staged.entries()) {
+    process.env[key] = value;
+  }
+  return () => {
+    for (const key of staged.keys()) {
+      delete process.env[key];
+    }
+  };
+}
+function readEnvStringValue(key) {
+  const value = process.env[key];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveFallbackValue(fallbackKeys) {
+  for (const key of fallbackKeys) {
+    const value = readEnvStringValue(key);
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function normalizeOptionalString(value, fallbackKeys) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      return trimmed;
+    }
+  }
+  return resolveFallbackValue(fallbackKeys);
+}
+function normalizeRequiredString(value, fieldLabel, fallbackKeys) {
+  const resolved = normalizeOptionalString(value, fallbackKeys);
+  if (resolved) {
+    return resolved;
+  }
+  throw new Error(
+    `Generator config is missing ${fieldLabel}. Set ${fieldLabel} directly or provide one of: ${fallbackKeys.join(", ")}.`
+  );
+}
+function applyPostgresPasswordFallback(connectionString) {
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(connectionString);
+  } catch {
+    return connectionString;
+  }
+  if (!POSTGRES_PROTOCOLS.has(parsedUrl.protocol)) {
+    return connectionString;
+  }
+  if (!parsedUrl.username || parsedUrl.password) {
+    return connectionString;
+  }
+  const fallbackPassword = resolveFallbackValue(POSTGRES_PASSWORD_ENV_KEYS);
+  if (!fallbackPassword) {
+    return connectionString;
+  }
+  parsedUrl.password = fallbackPassword;
+  return parsedUrl.toString();
+}
 function normalizeBooleanFlag(rawValue, fallback) {
   if (typeof rawValue === "boolean") {
     return rawValue;
@@ -3530,9 +3785,41 @@ function normalizeOutputConfig(output) {
   };
 }
 function normalizeProviderConfig(provider) {
-  if (provider.kind === "postgres") {
+  if (provider.kind === "postgres" && provider.mode === "direct") {
+    const connectionString = normalizeRequiredString(
+      provider.connectionString,
+      "provider.connectionString",
+      DIRECT_CONNECTION_STRING_ENV_KEYS
+    );
+    const database = normalizeOptionalString(provider.database, POSTGRES_DATABASE_ENV_KEYS);
     return {
       ...provider,
+      connectionString: applyPostgresPasswordFallback(connectionString),
+      database,
+      schemas: normalizeSchemaSelection(provider.schemas)
+    };
+  }
+  if (provider.kind === "postgres" && provider.mode === "gateway") {
+    const gatewayUrl = normalizeRequiredString(
+      provider.gatewayUrl,
+      "provider.gatewayUrl",
+      GATEWAY_URL_ENV_KEYS
+    );
+    const apiKey = normalizeRequiredString(
+      provider.apiKey,
+      "provider.apiKey",
+      GATEWAY_API_KEY_ENV_KEYS
+    );
+    const database = normalizeRequiredString(
+      provider.database,
+      "provider.database",
+      POSTGRES_DATABASE_ENV_KEYS
+    );
+    return {
+      ...provider,
+      gatewayUrl,
+      apiKey,
+      database,
       schemas: normalizeSchemaSelection(provider.schemas)
     };
   }
@@ -3594,6 +3881,11 @@ function extractConfigExport(module) {
     if (moduleExports && typeof moduleExports === "object") {
       queue.push(moduleExports);
     }
+    for (const value of Object.values(record)) {
+      if (value && typeof value === "object") {
+        queue.push(value);
+      }
+    }
   }
   throw new Error(
     "Generator config file must export a config object as default export or `config`."
@@ -3608,19 +3900,24 @@ function importConfigModule(moduleSpecifier) {
 }
 async function loadGeneratorConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
+  const restoreProjectEnv = applyProjectEnv(cwd);
   const resolvedPath = options.configPath ? resolve(cwd, options.configPath) : findGeneratorConfigPath(cwd);
   if (!resolvedPath) {
     throw new Error(
       `No generator config found in ${cwd}. Expected one of: ${DEFAULT_CONFIG_CANDIDATES.join(", ")}`
     );
   }
-  const moduleUrl = pathToFileURL(resolvedPath);
-  const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
-  const rawConfig = extractConfigExport(module);
-  return {
-    configPath: resolvedPath,
-    config: normalizeGeneratorConfig(rawConfig)
-  };
+  try {
+    const moduleUrl = pathToFileURL(resolvedPath);
+    const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
+    const rawConfig = extractConfigExport(module);
+    return {
+      configPath: resolvedPath,
+      config: normalizeGeneratorConfig(rawConfig)
+    };
+  } finally {
+    restoreProjectEnv();
+  }
 }
 
 // src/generator/naming.ts
@@ -3764,9 +4061,13 @@ function resolvePlaceholderMap(baseTokens, outputConfig) {
   const resolved = {
     ...baseTokens
   };
+  const reservedTokenKeys = new Set(Object.keys(baseTokens));
   const entries = Object.entries(outputConfig.placeholderMap ?? {});
   for (let index = 0; index < entries.length; index += 1) {
     const [key, value] = entries[index];
+    if (reservedTokenKeys.has(key)) {
+      continue;
+    }
     let current = value;
     for (let depth = 0; depth < 8; depth += 1) {
       const next = renderTemplate(current, resolved);
@@ -4046,13 +4347,65 @@ function assertNoDuplicatePaths(files) {
         [
           `Generator output collision detected for path: ${file.path}`,
           `Collision: ${existing.kind} and ${file.kind}.`,
-          "When syncing multiple schemas, include a schema placeholder such as {schema} or {schema_kebab} in model/schema output targets."
+          "Use explicit placeholders such as {model}, {model_kebab}, {schema}, or {schema_kebab} in output targets so each artifact resolves to a unique path."
         ].join(" ")
       );
     }
     seen.set(file.path, file);
   }
 }
+function addSchemaSegmentToPath(pathValue, schemaName) {
+  const normalizedPath = normalizePath(pathValue);
+  const parsedPath = posix.parse(normalizedPath);
+  const schemaSegment = applyNamingStyle(schemaName, "kebab");
+  if (!schemaSegment) {
+    return normalizedPath;
+  }
+  const dir = parsedPath.dir.length > 0 ? `${parsedPath.dir}/${schemaSegment}` : schemaSegment;
+  return normalizePath(posix.join(dir, parsedPath.base));
+}
+function scopeDuplicateDescriptorPathsBySchema(descriptors) {
+  const nextDescriptors = descriptors.map((descriptor) => ({ ...descriptor }));
+  const duplicates = /* @__PURE__ */ new Map();
+  for (let index = 0; index < nextDescriptors.length; index += 1) {
+    const descriptor = nextDescriptors[index];
+    const indexes = duplicates.get(descriptor.filePath) ?? [];
+    indexes.push(index);
+    duplicates.set(descriptor.filePath, indexes);
+  }
+  let appliedSchemaScoping = false;
+  for (const indexes of duplicates.values()) {
+    if (indexes.length <= 1) {
+      continue;
+    }
+    const schemaNames = new Set(indexes.map((index) => nextDescriptors[index].schemaName));
+    if (schemaNames.size <= 1) {
+      continue;
+    }
+    for (const index of indexes) {
+      const descriptor = nextDescriptors[index];
+      descriptor.filePath = addSchemaSegmentToPath(descriptor.filePath, descriptor.schemaName);
+    }
+    appliedSchemaScoping = true;
+  }
+  if (!appliedSchemaScoping) {
+    return nextDescriptors;
+  }
+  const normalizedPaths = /* @__PURE__ */ new Set();
+  for (const descriptor of nextDescriptors) {
+    if (normalizedPaths.has(descriptor.filePath)) {
+      throw new Error(
+        [
+          `Generator output collision detected for path: ${descriptor.filePath}`,
+          "Automatic schema path scoping was applied but collisions remain.",
+          "Add explicit placeholders such as {model}, {model_kebab}, {schema}, or {schema_kebab} to your output targets."
+        ].join(" ")
+      );
+    }
+    normalizedPaths.add(descriptor.filePath);
+  }
+  return nextDescriptors;
+}
 var ArtifactComposer = class {
   constructor(snapshot, config) {
     this.snapshot = snapshot;
@@ -4091,7 +4444,8 @@ var ArtifactComposer = class {
         });
       }
     }
-    const schemaDescriptors = Object.keys(this.snapshot.schemas).sort().map((schemaName) => {
+    const scopedModelDescriptors = scopeDuplicateDescriptorPathsBySchema(modelDescriptors);
+    let schemaDescriptors = Object.keys(this.snapshot.schemas).sort().map((schemaName) => {
       const schemaPath = normalizePath(
         renderOutputPath(this.config.output.targets.schema, {
           provider: providerName,
@@ -4109,9 +4463,10 @@ var ArtifactComposer = class {
           this.config.naming.schemaConst,
           "schema"
         ),
-        models: modelDescriptors.filter((model) => model.schemaName === schemaName)
+        models: scopedModelDescriptors.filter((model) => model.schemaName === schemaName)
       };
     });
+    schemaDescriptors = scopeDuplicateDescriptorPathsBySchema(schemaDescriptors);
     const databasePath = normalizePath(
       renderOutputPath(this.config.output.targets.database, {
         provider: providerName,
@@ -4131,7 +4486,7 @@ var ArtifactComposer = class {
       schemas: schemaDescriptors
     };
     const files = [];
-    for (const modelDescriptor of modelDescriptors) {
+    for (const modelDescriptor of scopedModelDescriptors) {
       files.push(renderModelArtifact(this.snapshot, modelDescriptor, this.config));
     }
     for (const schemaDescriptor of schemaDescriptors) {