@xylex-group/athena 2.0.0 → 2.1.2

package/dist/cli/index.cjs

@@ -4,7 +4,6 @@ var promises = require('fs/promises');
 var path = require('path');
 var fs = require('fs');
 var url = require('url');
-var pg = require('pg');
 
 // src/generator/pipeline.ts
 
@@ -149,9 +148,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);
@@ -348,8 +351,30 @@ var AthenaGatewayError = class _AthenaGatewayError extends Error {
     });
   }
 };
+function isAthenaGatewayError(error) {
+  return error instanceof AthenaGatewayError;
+}
 
 // src/auxiliaries.ts
+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();
@@ -361,6 +386,203 @@ function parseBooleanFlag(rawValue, fallback) {
   }
   return fallback;
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isAthenaErrorKind(value) {
+  return value === "unique_violation" || value === "not_found" || value === "validation" || value === "auth" || value === "rate_limit" || value === "transient" || value === "unknown";
+}
+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 isAthenaErrorCategory(value) {
+  return value === "transport" || value === "client" || value === "server" || value === "database" || value === "unknown";
+}
+function isNormalizedAthenaError(value) {
+  return isRecord(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
+  };
+}
+function resolveAttachedNormalizedError(resultOrError) {
+  if (!isRecord(resultOrError)) return void 0;
+  if (!("__athenaNormalizedError" in resultOrError)) return void 0;
+  const candidate = resultOrError.__athenaNormalizedError;
+  return isNormalizedAthenaError(candidate) ? candidate : void 0;
+}
+function isAthenaResultLike(value) {
+  return isRecord(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 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 = isRecord(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
+  };
+}
 
 // src/generator/schema-selection.ts
 var DEFAULT_POSTGRES_SCHEMAS = ["public"];
@@ -392,6 +614,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",
@@ -421,6 +644,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 = path.resolve(cwd, filename);
+    if (!fs.existsSync(absolutePath)) {
+      continue;
+    }
+    const content = fs.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;
@@ -466,9 +834,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)
     };
   }
@@ -527,6 +927,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`."
@@ -541,19 +946,24 @@ function importConfigModule(moduleSpecifier) {
 }
 async function loadGeneratorConfig(options = {}) {
   const cwd = options.cwd ?? process.cwd();
+  const restoreProjectEnv = applyProjectEnv(cwd);
   const resolvedPath = options.configPath ? path.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 = url.pathToFileURL(resolvedPath);
-  const module = await importConfigModule(`${moduleUrl.href}?cacheBust=${Date.now()}`);
-  const rawConfig = extractConfigExport(module);
-  return {
-    configPath: resolvedPath,
-    config: normalizeGeneratorConfig(rawConfig)
-  };
+  try {
+    const moduleUrl = url.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/renderer.ts
@@ -695,13 +1105,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 = path.posix.parse(normalizedPath);
+  const schemaSegment = applyNamingStyle(schemaName, "kebab");
+  if (!schemaSegment) {
+    return normalizedPath;
+  }
+  const dir = parsedPath.dir.length > 0 ? `${parsedPath.dir}/${schemaSegment}` : schemaSegment;
+  return normalizePath(path.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;
@@ -740,7 +1202,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,
@@ -758,9 +1221,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,
@@ -780,7 +1244,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) {
@@ -844,14 +1308,14 @@ function parseResponseBody(rawText, contentType) {
 function normalizeHeaderValue(value) {
   return value ? value : void 0;
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function resolveRequestId(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage(payload, fallback) {
-  if (isRecord(payload)) {
+  if (isRecord2(payload)) {
     const messageCandidates = [payload.error, payload.message, payload.details];
     for (const candidate of messageCandidates) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
@@ -1041,7 +1505,7 @@ async function callAthena(config, endpoint, method, payload, options) {
       };
     }
     const parsed = parsedBody.parsed;
-    const parsedPayload = isRecord(parsed) ? parsed : null;
+    const parsedPayload = isRecord2(parsed) ? parsed : null;
     if (!response.ok) {
       const httpError = new AthenaGatewayError({
         code: "HTTP_ERROR",
@@ -1249,7 +1713,7 @@ var SDK_HEADER_VALUE2 = `${SDK_NAME2} ${SDK_VERSION2}`;
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeHeaderValue2(value) {
@@ -1274,7 +1738,7 @@ function resolveRequestId2(headers) {
   return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
 }
 function resolveErrorMessage2(payload, fallback) {
-  if (isRecord2(payload)) {
+  if (isRecord3(payload)) {
     const messageCandidates = [payload.error, payload.message, payload.details];
     for (const candidate of messageCandidates) {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
@@ -1627,7 +2091,7 @@ function createAuthClient(config = {}) {
         data: null
       };
     }
-    const fallbackStatus = isRecord2(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
+    const fallbackStatus = isRecord3(fallback.data) && typeof fallback.data.ok === "boolean" ? fallback.data.ok ? "ok" : "error" : "ok";
     return {
       ...fallback,
       data: {
@@ -2278,10 +2742,42 @@ function createAuthClient(config = {}) {
   };
 }
 
+// src/db/module.ts
+function createDbModule(input) {
+  const db = {
+    from(table) {
+      return input.from(table);
+    },
+    select(table, columns, options) {
+      return input.from(table).select(columns, options);
+    },
+    insert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).insert(values, options) : input.from(table).insert(values, options);
+    },
+    upsert(table, values, options) {
+      return Array.isArray(values) ? input.from(table).upsert(values, options) : input.from(table).upsert(values, options);
+    },
+    update(table, values, options) {
+      return input.from(table).update(values, options);
+    },
+    delete(table, options) {
+      return input.from(table).delete(options);
+    },
+    rpc(fn, args, options) {
+      return input.rpc(fn, args, options);
+    },
+    query(query, options) {
+      return input.query(query, options);
+    }
+  };
+  return db;
+}
+
 // 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,
@@ -2295,6 +2791,28 @@ function formatResult(response) {
   }
   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;
@@ -2669,7 +3187,7 @@ function createRpcFilterMethods(filters, self) {
     }
   };
 }
-function createRpcBuilder(functionName, args, baseOptions, client) {
+function createRpcBuilder(functionName, args, baseOptions, client, formatGatewayResult) {
   const state = {
     filters: []
   };
@@ -2691,7 +3209,7 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
       order: state.order
     };
     const response = await client.rpcGateway(payload, mergedOptions);
-    return formatResult(response);
+    return formatGatewayResult(response, { operation: "rpc" });
   };
   const run = (columns, options) => {
     const payloadColumns = columns ?? selectedColumns;
@@ -2745,7 +3263,7 @@ function createRpcBuilder(functionName, args, baseOptions, client) {
   });
   return builder;
 }
-function createTableBuilder(tableName, client) {
+function createTableBuilder(tableName, client, formatGatewayResult) {
   const state = {
     conditions: []
   };
@@ -2802,7 +3320,7 @@ function createTableBuilder(tableName, client) {
       });
       if (query) {
         const queryResponse = await client.queryGateway({ query }, options);
-        return formatResult(queryResponse);
+        return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
       }
     }
     const payload = {
@@ -2820,7 +3338,7 @@ function createTableBuilder(tableName, client) {
       head: options?.head
     };
     const response = await client.fetchGateway(payload, options);
-    return formatResult(response);
+    return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
   };
   const createSelectChain = (columns, options) => {
     const chain = {};
@@ -2875,7 +3393,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);
       }
@@ -2893,7 +3411,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);
     },
@@ -2915,7 +3433,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);
       }
@@ -2935,7 +3453,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);
     },
@@ -2956,7 +3474,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 = {};
@@ -2984,7 +3502,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);
     },
@@ -2998,14 +3516,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) {
@@ -3016,24 +3534,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
   };
 }
@@ -3042,77 +3565,16 @@ function toBackendConfig(b) {
   if (!b) return DEFAULT_BACKEND;
   return typeof b === "string" ? { type: b } : 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;
+  return createClientFromConfig({
+    baseUrl: url,
+    apiKey,
+    client: options?.client,
+    backend: toBackendConfig(options?.backend),
+    headers: options?.headers,
+    auth: options?.auth,
+    experimental: options?.experimental
+  });
 }
 
 // src/schema/postgres-introspection-core.ts
@@ -3462,6 +3924,23 @@ var PostgresCatalogSnapshotAssembler = class {
     table.relations[key] = relation;
   }
 };
+
+// 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;
@@ -3501,7 +3980,8 @@ var PostgresIntrospectionProvider = class {
   }
   async inspect(options) {
     const schemas = options?.schemas && options.schemas.length > 0 ? normalizePostgresCatalogSchemas(options.schemas) : this.schemas;
-    const pool = new pg.Pool({
+    const PoolConstructor = await loadPgPoolConstructor();
+    const pool = new PoolConstructor({
       connectionString: this.connectionString
     });
     const catalogClient = new PgCatalogClient(pool);