@malloy-publisher/server 0.0.235 → 0.0.236

package/src/controller/connection.controller.ts

@@ -1,901 +0,0 @@
-import { Connection, RunSQLOptions, TableSourceDef } from "@malloydata/malloy";
-import { PersistSQLResults } from "@malloydata/malloy/connection";
-import { components } from "../api";
-import {
-   getMaxQueryRows,
-   getMaxResponseBytes,
-   getQueryTimeoutMs,
-} from "../config";
-import {
-   BadRequestError,
-   ConnectionError,
-   PayloadTooLargeError,
-} from "../errors";
-import { recordQueryCapExceeded } from "../query_cap_metrics";
-import { logger } from "../logger";
-import { runWithQueryTimeout } from "../query_timeout";
-import { testConnectionConfig } from "../service/connection";
-import { validateDuckdbApiSurface } from "../service/connection_config";
-import { ConnectionService } from "../service/connection_service";
-import {
-   getSchemasForConnection,
-   listTablesForSchema,
-} from "../service/db_utils";
-import {
-   mergeQueryMetadata,
-   mintCorrelationId,
-   parseQueryClass,
-   parseSuppliedQueryMetadata,
-   queryMetadataViolations,
-   type QueryClass,
-   type QueryMetadata,
-} from "../service/query_metadata";
-import type { Environment } from "../service/environment";
-import { EnvironmentStore } from "../service/environment_store";
-import { isStreamingConnection, streamSqlWithBudget } from "../stream_helpers";
-
-type ApiConnection = components["schemas"]["Connection"];
-type ApiConnectionStatus = components["schemas"]["ConnectionStatus"];
-type ApiSqlSource = components["schemas"]["SqlSource"];
-type ApiTable = components["schemas"]["Table"];
-type ApiQueryData = components["schemas"]["QueryData"];
-type ApiTemporaryTable = components["schemas"]["TemporaryTable"];
-type ApiSchema = components["schemas"]["Schema"];
-const AZURE_SUPPORTED_SCHEMES = ["https://", "http://", "abfss://", "az://"];
-const AZURE_DATA_EXTENSIONS = [
-   ".parquet",
-   ".csv",
-   ".json",
-   ".jsonl",
-   ".ndjson",
-];
-
-/**
- * Validates an Azure URL against the three supported patterns:
- *   1. Single file:         path/file.parquet
- *   2. Directory glob:      path/*.ext   (direct children only, no sub-dirs)
- *   3. Recursive:           path/**      (all data files recursively)
- */
-function validateAzureUrl(url: string, fieldName: string): void {
-   if (!AZURE_SUPPORTED_SCHEMES.some((s) => url.startsWith(s))) {
-      throw new BadRequestError(
-         `Azure ${fieldName} must use one of: ${AZURE_SUPPORTED_SCHEMES.join(", ")}`,
-      );
-   }
-
-   const pathWithoutQuery = url.split("?")[0];
-   const stars = (pathWithoutQuery.match(/\*/g) || []).length;
-
-   if (stars === 0) {
-      // Single file — must end with a data extension
-      const lower = pathWithoutQuery.toLowerCase();
-      if (!AZURE_DATA_EXTENSIONS.some((ext) => lower.endsWith(ext))) {
-         throw new BadRequestError(
-            `Azure ${fieldName}: a single-file URL must end with a data file extension (${AZURE_DATA_EXTENSIONS.join(", ")})`,
-         );
-      }
-   } else if (pathWithoutQuery.endsWith("**")) {
-      // Recursive — valid, no further checks needed
-   } else {
-      // Must be exactly path/*.ext — one star, in the last path segment only
-      const lastSegment = pathWithoutQuery.split("/").pop() || "";
-      if (stars !== 1 || !lastSegment.startsWith("*")) {
-         throw new BadRequestError(
-            `Azure ${fieldName}: only three URL patterns are supported:\n` +
-               `  • Single file:      path/file.parquet\n` +
-               `  • Directory glob:   path/*.ext  (direct children only)\n` +
-               `  • Recursive:        path/**     (all data files in subtree)\n` +
-               `Multi-level globs such as "sub_dir/*/*.parquet" are not supported.`,
-         );
-      }
-   }
-}
-
-function validateAzureAttachedDatabases(connectionConfig: ApiConnection): void {
-   if (connectionConfig.type !== "duckdb") return;
-   const attachedDbs =
-      connectionConfig.duckdbConnection?.attachedDatabases || [];
-   for (const db of attachedDbs) {
-      if (db.type !== "azure" || !db.azureConnection) continue;
-      const { authType, sasUrl, fileUrl } = db.azureConnection;
-      if (authType === "sas_token" && sasUrl) {
-         validateAzureUrl(sasUrl, `"${db.name}" sasUrl`);
-      } else if (authType === "service_principal" && fileUrl) {
-         validateAzureUrl(fileUrl, `"${db.name}" fileUrl`);
-      }
-   }
-}
-
-function validateAdminAuthoredConnection(
-   connectionName: string,
-   connectionConfig: ApiConnection,
-): void {
-   if (connectionName === "duckdb" || connectionConfig.name === "duckdb") {
-      throw new BadRequestError(
-         "Connection name 'duckdb' is reserved for per-package sandboxes. Choose a different name for environment-level DuckDB connections (e.g. 'shared_duckdb').",
-      );
-   }
-
-   try {
-      validateDuckdbApiSurface(connectionConfig);
-   } catch (error) {
-      throw new BadRequestError((error as Error).message);
-   }
-
-   // The connection is the one metadata layer whose author is right here, so it
-   // is the one that can be told. A property the contract rejects (a hyphen in
-   // `cost-centre` is the natural spelling and the first thing anyone tries)
-   // would otherwise be dropped at dispatch and only ever surface as a metric —
-   // every statement on the connection missing the property its operator
-   // believes they configured. Config LOAD warns instead of throwing (see
-   // assembleEnvironmentConnections): a tag must never fail an environment.
-   for (const field of ["queryMetadata", "queryMetadataEnforced"] as const) {
-      const violations = queryMetadataViolations(connectionConfig[field]);
-      if (violations.length > 0) {
-         throw new BadRequestError(
-            `Connection "${connectionName}" ${field} is invalid: ${violations.join("; ")}`,
-         );
-      }
-   }
-}
-
-export class ConnectionController {
-   private environmentStore: EnvironmentStore;
-   private connectionService: ConnectionService;
-   constructor(environmentStore: EnvironmentStore) {
-      this.environmentStore = environmentStore;
-      this.connectionService = new ConnectionService(environmentStore);
-   }
-
-   /**
-    * Gets the appropriate Malloy connection for a given connection name.
-    * For DuckDB connections, retrieves from package level; for others, from environment level.
-    */
-   private getApiConnectionForLookup(
-      environment: Environment,
-      connectionName: string,
-   ): ApiConnection {
-      if (connectionName === "duckdb") {
-         return {
-            name: "duckdb",
-            type: "duckdb",
-            duckdbConnection: { attachedDatabases: [] },
-         };
-      }
-      return environment.getApiConnection(connectionName);
-   }
-
-   /**
-    * A connection's default per-query metadata, or null when it declares none.
-    * Fails open: metadata is observability, so a connection whose config can't be
-    * read contributes no default rather than failing the query the caller asked
-    * for.
-    */
-   private async connectionQueryMetadata(
-      environmentName: string,
-      connectionName: string,
-   ): Promise<{
-      default: QueryMetadata | null;
-      enforced: QueryMetadata | null;
-   }> {
-      try {
-         const environment = await this.environmentStore.getEnvironment(
-            environmentName,
-            false,
-         );
-         const connection = this.getApiConnectionForLookup(
-            environment,
-            connectionName,
-         );
-         return {
-            default: connection.queryMetadata ?? null,
-            enforced: connection.queryMetadataEnforced ?? null,
-         };
-      } catch (error) {
-         // Fails open like every other metadata path, but not invisibly: the
-         // layer lost here is the enforced one, and no metric covers it.
-         logger.debug("No query-metadata layers for connection", {
-            connectionName,
-            error,
-         });
-         return { default: null, enforced: null };
-      }
-   }
-
-   private async getMalloyConnection(
-      environmentName: string,
-      connectionName: string,
-      packageName?: string,
-   ): Promise<Connection> {
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-
-      // "duckdb" is the per-package sandbox; its rootDirectory is the
-      // package's directory. There is no environment-level "duckdb" — the name is
-      // reserved at config time. So the lookup is intrinsically per-package
-      // and the caller must say which package to use.
-      if (connectionName === "duckdb") {
-         const packages = await environment.listPackages();
-         if (packages.length === 0) {
-            // Fall through to environment; this will surface the standard
-            // "connection not found" rather than silently inventing one.
-            return await environment.getMalloyConnection(connectionName);
-         }
-         if (packageName) {
-            const known = packages.some((p) => p.name === packageName);
-            if (!known) {
-               throw new BadRequestError(
-                  `Package "${packageName}" not found in environment "${environmentName}"`,
-               );
-            }
-            const pkg = await environment.getPackage(packageName);
-            return await pkg.getMalloyConnection(connectionName);
-         }
-         if (packages.length === 1) {
-            const onlyPackage = packages[0].name;
-            if (!onlyPackage) {
-               throw new ConnectionError("Package name is undefined");
-            }
-            const pkg = await environment.getPackage(onlyPackage);
-            return await pkg.getMalloyConnection(connectionName);
-         }
-         throw new BadRequestError(
-            `Ambiguous "duckdb" connection lookup: environment "${environmentName}" has multiple packages. ` +
-               `Use /environments/${environmentName}/packages/{packageName}/connections/duckdb/... to disambiguate.`,
-         );
-      } else {
-         return await environment.getMalloyConnection(connectionName);
-      }
-   }
-
-   /**
-    * Fetches a table's schema via the Malloy connection's fetchTableSchema,
-    * returning an ApiTable with columns and the raw source JSON.
-    */
-   private async fetchTable(
-      malloyConnection: Connection,
-      tableKey: string,
-      tablePath: string,
-   ): Promise<ApiTable> {
-      try {
-         const source = await (
-            malloyConnection as Connection & {
-               fetchTableSchema: (
-                  tableKey: string,
-                  tablePath: string,
-               ) => Promise<TableSourceDef | string | undefined>;
-            }
-         ).fetchTableSchema(tableKey, tablePath);
-         if (!source) {
-            throw new ConnectionError(`Table ${tablePath} not found`);
-         }
-         // BigQueryConnection returns `error.message` as a string on failure instead of throwing.
-         if (typeof source === "string") {
-            throw new ConnectionError(source);
-         }
-
-         return {
-            source: JSON.stringify(source),
-            resource: tablePath,
-            columns: (source.fields || []).map((f) => ({
-               name: f.name,
-               type: f.type,
-            })),
-         };
-      } catch (error) {
-         const errorMessage =
-            error instanceof Error
-               ? error.message
-               : typeof error === "string"
-                 ? error
-                 : JSON.stringify(error);
-         logger.error("fetchTableSchema error", {
-            error,
-            tableKey,
-            tablePath,
-         });
-         throw new ConnectionError(errorMessage);
-      }
-   }
-
-   public async getConnection(
-      environmentName: string,
-      connectionName: string,
-   ): Promise<ApiConnection> {
-      if (!environmentName || !connectionName) {
-         throw new BadRequestError("Connection payload is required");
-      }
-      // Prefer the in-memory API connection (which was materialized by the
-      // environment on load and carries `attributes`). The DB row stores the
-      // raw config and FK columns, which aren't the ApiConnection shape.
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      return environment.getApiConnection(connectionName);
-   }
-
-   public async listConnections(
-      environmentName: string,
-   ): Promise<ApiConnection[]> {
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      return environment.listApiConnections();
-   }
-
-   // Lists schemas (namespaces) available in a connection.
-   // For "duckdb", the per-package sandbox, packageName disambiguates which
-   // package's DuckDB to browse in a multi-package environment.
-   public async listSchemas(
-      environmentName: string,
-      connectionName: string,
-      packageName?: string,
-   ): Promise<ApiSchema[]> {
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      const connection = this.getApiConnectionForLookup(
-         environment,
-         connectionName,
-      );
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-
-      return getSchemasForConnection(connection, malloyConnection);
-   }
-
-   // Lists tables available in a schema. For postgres the schema is usually "public".
-   // packageName disambiguates per-package "duckdb" lookups (see listSchemas).
-   public async listTables(
-      environmentName: string,
-      connectionName: string,
-      schemaName: string,
-      tableNames?: string[],
-      packageName?: string,
-   ): Promise<ApiTable[]> {
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      const connection = this.getApiConnectionForLookup(
-         environment,
-         connectionName,
-      );
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-
-      return listTablesForSchema(
-         connection,
-         schemaName,
-         malloyConnection,
-         tableNames,
-      );
-   }
-
-   public async getConnectionSqlSource(
-      environmentName: string,
-      connectionName: string,
-      sqlStatement: string,
-      packageName?: string,
-   ): Promise<ApiSqlSource> {
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-      try {
-         const schema = await (
-            malloyConnection as Connection & {
-               fetchSelectSchema: (params: {
-                  connection: string;
-                  selectStr: string;
-               }) => Promise<unknown>;
-            }
-         ).fetchSelectSchema({
-            connection: connectionName,
-            selectStr: sqlStatement,
-         });
-
-         // BigQueryConnection returns `error.message` as a string on failure instead of throwing.
-         if (typeof schema === "string") {
-            throw new ConnectionError(schema);
-         }
-
-         return {
-            source: JSON.stringify(schema),
-         };
-      } catch (error) {
-         throw new ConnectionError((error as Error).message);
-      }
-   }
-
-   public async getTable(
-      environmentName: string,
-      connectionName: string,
-      schemaName: string,
-      tablePath: string,
-      packageName?: string,
-   ): Promise<ApiTable> {
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-      // Use getApiConnection to get the unwrapped ApiConnection config, consistent with listSchemas and listTables.
-      const environment = await this.environmentStore.getEnvironment(
-         environmentName,
-         false,
-      );
-      const connection = this.getApiConnectionForLookup(
-         environment,
-         connectionName,
-      );
-
-      // TODO: Move this database connection logic to the db_utils.ts file -- and
-      // ultimately into a connection-specific class.
-      if (connection.type === "ducklake") {
-         if (tablePath.split(".").length === 1) {
-            // tablePath is just the table name, construct full path
-            tablePath = `${connectionName}.${schemaName}.${tablePath}`;
-         } else if (
-            tablePath.split(".").length === 2 &&
-            !tablePath.startsWith(connectionName)
-         ) {
-            // tablePath is schemaName.tableName but missing connection prefix
-            tablePath = `${connectionName}.${tablePath}`;
-         }
-         // If tablePath already has 3+ parts or starts with connection name, use as-is
-      }
-
-      // Check if this is an Azure attached database
-      if (connection.type === "duckdb") {
-         const attachedDbs =
-            connection.duckdbConnection?.attachedDatabases || [];
-         const azureDb = attachedDbs.find(
-            (db) =>
-               db.type === "azure" &&
-               db.name === schemaName &&
-               db.azureConnection,
-         );
-         if (azureDb && azureDb.azureConnection) {
-            // Reconstruct the full SAS URL for the specific file
-            const azureConn = azureDb.azureConnection;
-            const baseUrl =
-               azureConn.authType === "sas_token"
-                  ? azureConn.sasUrl
-                  : azureConn.fileUrl;
-            if (baseUrl) {
-               // Extract the file name from tablePath (e.g., "a.aircraft.parquet" -> "aircraft.parquet")
-               const fileName = tablePath.includes(".")
-                  ? tablePath.split(".").slice(1).join(".")
-                  : tablePath;
-               // Replace the file portion in the base URL with the specific file name
-               const urlParts = baseUrl.split("?");
-               const basePath = urlParts[0];
-               const queryString = urlParts[1] ? `?${urlParts[1]}` : "";
-               // Replace the last path segment (or glob) with the actual file name
-               const dirPath = basePath.substring(
-                  0,
-                  basePath.lastIndexOf("/") + 1,
-               );
-               const fullFileUrl = `${dirPath}${fileName}${queryString}`;
-
-               const table = await this.fetchTable(
-                  malloyConnection,
-                  fileName,
-                  fullFileUrl,
-               );
-               return { ...table, resource: tablePath };
-            }
-         }
-      }
-
-      const tableKey = tablePath.split(".").pop();
-      if (!tableKey) {
-         throw new Error(`Invalid tablePath: ${tablePath}`);
-      }
-
-      return this.fetchTable(malloyConnection, tableKey, tablePath);
-   }
-
-   public async getConnectionQueryData(
-      environmentName: string,
-      connectionName: string,
-      sqlStatement: string,
-      options: string,
-      packageName?: string,
-      /**
-       * The request's per-query metadata fields, unvalidated — this controller is
-       * the boundary that turns a bad bag into a 400 rather than letting the
-       * connector refuse the statement at dispatch.
-       */
-      metadata?: { queryMetadata?: unknown; queryClass?: unknown },
-   ): Promise<ApiQueryData> {
-      // Express parses repeated query parameters (?sqlStatement=a&sqlStatement=b)
-      // and array-shaped JSON bodies as `string[]`, not `string`. The route
-      // handlers up-cast for TypeScript's benefit, so re-validate here at the
-      // controller boundary before forwarding to the connector.
-      if (typeof sqlStatement !== "string") {
-         throw new BadRequestError("sqlStatement must be a string");
-      }
-      if (
-         options !== undefined &&
-         options !== null &&
-         typeof options !== "string"
-      ) {
-         throw new BadRequestError("options must be a string");
-      }
-
-      // Shed load before any disk / DB work; same rationale as
-      // QueryController. The env-fetch is cached so this is effectively
-      // a single O(1) boolean read on the hot path.
-      const environmentForAdmission =
-         await this.environmentStore.getEnvironment(environmentName, false);
-      environmentForAdmission.assertCanAdmitQuery();
-
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-
-      let runSQLOptions: RunSQLOptions = {};
-      if (options) {
-         // JSON.parse happily produces `null`, `42`, `"foo"`, `[1,2,3]`, etc.
-         // Anything that isn't a plain object would either crash later when
-         // we touch `.abortSignal` / `.rowLimit` (null), or mutate a caller
-         // string / array and pass it to the connector. Reject at the
-         // boundary alongside the other CodeQL type guards above.
-         let parsed: unknown;
-         try {
-            parsed = JSON.parse(options);
-         } catch {
-            throw new BadRequestError("options must be valid JSON");
-         }
-         if (
-            parsed === null ||
-            typeof parsed !== "object" ||
-            Array.isArray(parsed)
-         ) {
-            throw new BadRequestError(
-               'options must be a JSON object (e.g. {"rowLimit": 100})',
-            );
-         }
-         runSQLOptions = parsed as RunSQLOptions;
-      }
-      if (runSQLOptions.abortSignal) {
-         // Add support for abortSignal in the future
-         logger.info("Clearing unsupported abortSignal");
-         runSQLOptions.abortSignal = undefined;
-      }
-
-      // Per-query metadata. Validated here, not clamped: a raw-SQL caller gets a
-      // 400 telling it which property is wrong instead of a statement the
-      // connector refuses at dispatch. `options` is forwarded as RunSQLOptions, so
-      // a bag can also arrive inside it — validate that one too, and let the
-      // documented field win.
-      const suppliedMetadata =
-         metadata?.queryMetadata ?? runSQLOptions.queryMetadata;
-      let requestMetadata: QueryMetadata | undefined;
-      let queryClass: QueryClass | undefined;
-      try {
-         requestMetadata = parseSuppliedQueryMetadata(suppliedMetadata);
-         queryClass = parseQueryClass(metadata?.queryClass);
-      } catch (error) {
-         throw new BadRequestError((error as Error).message);
-      }
-      const connectionLayers = await this.connectionQueryMetadata(
-         environmentName,
-         connectionName,
-      );
-      const resolvedMetadata = mergeQueryMetadata({
-         connection: connectionLayers.default,
-         enforced: connectionLayers.enforced,
-         request: requestMetadata,
-         context: {
-            // Raw SQL against a connection is platform maintenance unless the
-            // caller says otherwise — it is not a modeled query.
-            queryClass: queryClass ?? "ops",
-            environment: environmentName,
-            package: packageName,
-            correlationId: mintCorrelationId(),
-         },
-      });
-      runSQLOptions.queryMetadata = resolvedMetadata.metadata;
-      const queryCorrelationId = resolvedMetadata.metadata?.query_id ?? null;
-
-      // Bound the response with two layered caps:
-      //
-      //   - Row cap (PUBLISHER_MAX_QUERY_ROWS) — pushed to the driver as
-      //     RunSQLOptions.rowLimit = min(callerLimit, cap+1). The +1 is a
-      //     sentinel: a response of cap+1 rows means the original would have
-      //     overflowed, so we fail the request with HTTP 413 rather than
-      //     serializing it. A caller-supplied rowLimit lower than cap+1 is
-      //     kept; we only enforce the ceiling. Cap of 0 disables the bound.
-      //
-      //   - Byte cap (PUBLISHER_MAX_RESPONSE_BYTES) — the actual memory
-      //     bound, since a single 10 MB JSON column can blow past the
-      //     row cap's safe envelope. Only enforceable on streaming
-      //     connections; row-buffered `runSQL` has already done the
-      //     damage by the time we'd count bytes.
-      //
-      // We trust connectors to honor RunSQLOptions.rowLimit; connectors
-      // that don't are upstream bugs.
-      const maxRows = getMaxQueryRows();
-      const maxBytes = getMaxResponseBytes();
-      if (maxRows > 0) {
-         runSQLOptions.rowLimit = Math.min(
-            runSQLOptions.rowLimit ?? maxRows + 1,
-            maxRows + 1,
-         );
-      }
-
-      // Streaming-capable connections (Postgres, DuckDB, ...) go through
-      // streamSqlWithBudget so the byte cap can fire mid-stream. Other
-      // connections fall back to the buffered path; client-side byte
-      // counting there would be security theatre.
-      //
-      // The whole driver call is wrapped in runWithQueryTimeout so a
-      // hung query is surfaced as HTTP 504 instead of holding the
-      // HTTP socket open until the load balancer cuts the connection.
-      // The timeout signal is plumbed into RunSQLOptions.abortSignal
-      // so the abort actually cancels the underlying network call —
-      // not just unblocks the awaiter.
-      if (isStreamingConnection(malloyConnection)) {
-         const streamed = await runWithQueryTimeout(async (signal) => {
-            const optionsWithSignal: RunSQLOptions = {
-               ...runSQLOptions,
-               abortSignal: signal,
-            };
-            try {
-               return await streamSqlWithBudget(
-                  malloyConnection,
-                  sqlStatement,
-                  optionsWithSignal,
-                  { maxRows, maxBytes },
-               );
-            } catch (error) {
-               if (error instanceof PayloadTooLargeError) throw error;
-               // If runWithQueryTimeout is about to wrap this in a
-               // QueryTimeoutError (because the timer fired), the
-               // ConnectionError we'd throw here is discarded — the
-               // timeout verdict wins. So this branch only matters
-               // for genuine driver failures.
-               throw new ConnectionError((error as Error).message);
-            }
-         }, getQueryTimeoutMs());
-         return { data: JSON.stringify(streamed), queryCorrelationId };
-      }
-
-      const result = await runWithQueryTimeout(async (signal) => {
-         const optionsWithSignal: RunSQLOptions = {
-            ...runSQLOptions,
-            abortSignal: signal,
-         };
-         try {
-            return await malloyConnection.runSQL(
-               sqlStatement,
-               optionsWithSignal,
-            );
-         } catch (error) {
-            throw new ConnectionError((error as Error).message);
-         }
-      }, getQueryTimeoutMs());
-
-      if (maxRows > 0 && result.rows.length > maxRows) {
-         // Tick the cap-exceeded counter on the buffered path too
-         // so `publisher_query_cap_exceeded_total{cap_type="rows",
-         // source="connection_sql"}` captures rejections from
-         // *all* connectors, not just streaming-capable ones.
-         recordQueryCapExceeded("rows", "connection_sql");
-         throw new PayloadTooLargeError(
-            `Query returned more than ${maxRows} rows. Refine the query (add a LIMIT or more selective WHERE) or raise PUBLISHER_MAX_QUERY_ROWS.`,
-         );
-      }
-
-      return { data: JSON.stringify(result), queryCorrelationId };
-   }
-
-   public async getConnectionTemporaryTable(
-      environmentName: string,
-      connectionName: string,
-      sqlStatement: string,
-      packageName?: string,
-   ): Promise<ApiTemporaryTable> {
-      // Express parses repeated query parameters / array-shaped JSON
-      // bodies as `string[]`. The route handlers up-cast for
-      // TypeScript's benefit; re-validate here at the controller
-      // boundary before forwarding to the connector — same pattern
-      // as `getConnectionQueryData`.
-      if (typeof sqlStatement !== "string") {
-         throw new BadRequestError("sqlStatement must be a string");
-      }
-
-      // Shed load before any disk / DB work; same rationale as
-      // `getConnectionQueryData`. `manifestTemporaryTable` issues a
-      // real `CREATE TEMPORARY TABLE AS (<sql>)` against the
-      // connector, so a back-pressured publisher must reject these
-      // with HTTP 503 just like ad-hoc SELECTs.
-      const environmentForAdmission =
-         await this.environmentStore.getEnvironment(environmentName, false);
-      environmentForAdmission.assertCanAdmitQuery();
-
-      const malloyConnection = await this.getMalloyConnection(
-         environmentName,
-         connectionName,
-         packageName,
-      );
-
-      // `manifestTemporaryTable(sqlCommand: string): Promise<string>`
-      // does not accept an `abortSignal`, so we cannot push
-      // cancellation down to the driver. Instead we race the call
-      // against the publisher's timeout signal so the HTTP response
-      // unblocks at the wall-clock deadline regardless of whether
-      // the underlying DDL responds. The DDL continues running in
-      // the database — the publisher just stops waiting and
-      // returns HTTP 504. This is strictly better than holding the
-      // socket and concurrency slot open until the load balancer
-      // kills the connection, but it does mean a runaway DDL is
-      // not actually cancelled (driver-side enhancement needed in
-      // `@malloydata/db-*` to plumb abort through).
-      //
-      // The `runWithQueryTimeout` wrapper's catch handler checks its
-      // `timedOut` flag at error time, so any rejection that
-      // propagates after the timer has fired is re-emitted as
-      // `QueryTimeoutError` regardless of its shape — that's why
-      // we re-throw the abort reason here unwrapped.
-      return await runWithQueryTimeout(async (signal) => {
-         try {
-            const tableName = await Promise.race([
-               (malloyConnection as PersistSQLResults).manifestTemporaryTable(
-                  sqlStatement,
-               ),
-               new Promise<never>((_resolve, reject) => {
-                  if (signal.aborted) {
-                     reject(signal.reason);
-                     return;
-                  }
-                  signal.addEventListener(
-                     "abort",
-                     () => reject(signal.reason),
-                     { once: true },
-                  );
-               }),
-            ]);
-            return { table: JSON.stringify(tableName) };
-         } catch (error) {
-            // If the abort fired first, the timeout wrapper above
-            // will convert this to QueryTimeoutError on its own
-            // — don't bury the reason in ConnectionError.
-            if (signal.aborted) throw error;
-            throw new ConnectionError((error as Error).message);
-         }
-      }, getQueryTimeoutMs());
-   }
-
-   public async testConnectionConfiguration(
-      input: ApiConnection & { config?: ApiConnection },
-   ): Promise<ApiConnectionStatus> {
-      // Some clients wrap the payload as { config: <connection> }; unwrap.
-      const connectionConfig: ApiConnection =
-         input.config && typeof input.config === "object"
-            ? input.config
-            : input;
-
-      if (
-         !connectionConfig ||
-         typeof connectionConfig !== "object" ||
-         Object.keys(connectionConfig).length === 0
-      ) {
-         throw new BadRequestError(
-            "Connection configuration is required and cannot be empty",
-         );
-      }
-
-      if (!connectionConfig.type || typeof connectionConfig.type !== "string") {
-         throw new BadRequestError(
-            "Connection type is required and must be a string",
-         );
-      }
-
-      try {
-         return await testConnectionConfig(connectionConfig);
-      } catch (error) {
-         return {
-            status: "failed",
-            errorMessage: `Connection test failed: ${(error as Error).message}`,
-         };
-      }
-   }
-
-   public async addConnection(
-      environmentName: string,
-      connectionName: string,
-      connectionConfig: ApiConnection,
-   ): Promise<{ message: string }> {
-      if (!connectionConfig || typeof connectionConfig !== "object") {
-         throw new BadRequestError("Connection configuration is required");
-      }
-
-      if (!connectionConfig) {
-         throw new BadRequestError("Connection name is required");
-      }
-
-      if (!connectionConfig.type) {
-         throw new BadRequestError("Connection type is required");
-      }
-
-      validateAzureAttachedDatabases(connectionConfig);
-      validateAdminAuthoredConnection(connectionName, connectionConfig);
-
-      logger.info(
-         `Creating connection "${connectionName}" in environment "${environmentName}"`,
-      );
-
-      await this.connectionService.addConnection(
-         environmentName,
-         connectionName,
-         connectionConfig,
-      );
-
-      return {
-         message: `Connection "${connectionName}" created successfully`,
-      };
-   }
-
-   public async updateConnection(
-      environmentName: string,
-      connectionName: string,
-      connection: Partial<ApiConnection>,
-   ): Promise<{ message: string }> {
-      if (!connection || typeof connection !== "object") {
-         throw new BadRequestError("Connection payload is required");
-      }
-
-      validateAzureAttachedDatabases(connection);
-      validateAdminAuthoredConnection(connectionName, connection);
-
-      logger.info(
-         `Updating connection "${connectionName}" in environment "${environmentName}"`,
-      );
-
-      await this.connectionService.updateConnection(
-         environmentName,
-         connectionName,
-         connection,
-      );
-
-      return {
-         message: `Connection "${connectionName}" updated successfully`,
-      };
-   }
-
-   public async deleteConnection(
-      environmentName: string,
-      connectionName: string,
-   ): Promise<{ message: string }> {
-      logger.info(
-         `Deleting connection "${connectionName}" from environment "${environmentName}"`,
-      );
-
-      await this.connectionService.deleteConnection(
-         environmentName,
-         connectionName,
-      );
-
-      return {
-         message: `Connection "${connectionName}" deleted successfully`,
-      };
-   }
-}