@malloy-publisher/server 0.0.231 → 0.0.233

package/src/service/connection.ts

@@ -52,6 +52,7 @@ import {
 } from "./connection_config";
 import { CloudStorageCredentials } from "./gcs_s3_utils";
 import { openProxy, type ProxyEndpoint } from "./proxy";
+import { quoteIdentifier } from "./quoting";
 
 type AttachedDatabase = components["schemas"]["AttachedDatabase"];
 type ApiConnection = components["schemas"]["Connection"];
@@ -148,7 +149,7 @@ export async function applyExtensionSessionSettings(
    }
 }
 
-async function installAndLoadExtension(
+export async function installAndLoadExtension(
    connection: DuckDBConnection,
    extensionName: string,
    fromCommunity = false,
@@ -232,7 +233,7 @@ function sanitizeSecretName(name: string): string {
    return `secret_${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
 }
 
-function escapeSQL(value: string): string {
+export function escapeSQL(value: string): string {
    return value.replace(/'/g, "''");
 }
 
@@ -476,33 +477,72 @@ function runSQLRows(result: unknown): Record<string, unknown>[] {
  * the fixed name (which would make every later preflight for this connection
  * fail its ATTACH with "already exists" and silently skip), and so two
  * concurrent first-touch lookups can't cross-DETACH each other.
+ *
+ * {@link metadataSchema} must be the catalog's configured
+ * `catalog.metadataSchema`, because `ducklake_metadata` lives in that schema
+ * rather than the catalog connection's default one. Getting this wrong is not
+ * loud: the read would simply miss, the catch below would log and return, and the
+ * range check would stop protecting precisely the catalogs that set the option.
  */
 let ducklakePreflightSeq = 0;
 async function preflightDuckLakeCatalogFormat(
    connection: DuckDBConnection,
    dbName: string,
    pgConnString: string,
+   metadataSchema?: string,
 ): Promise<void> {
    const tempDb = `${dbName}_fmt_preflight_${++ducklakePreflightSeq}`;
+   // Identifier position, not a string literal, so the schema is double-quoted.
+   // Measured: with today's validator this is belt-and-braces rather than a fix —
+   // every name the regex admits resolves correctly unquoted, including reserved
+   // words (DuckDB parses them fine here) and mixed case (matching is
+   // case-insensitive). It is quoted anyway because this preflight fails SOFT: a
+   // read that misses logs and returns, silently disabling format range-checking
+   // for that connection, so the cost of ever getting this wrong is invisible.
+   // Quoting makes correctness local to this line instead of contingent on the
+   // validator's accept-set, so widening that regex later cannot break it. Safe
+   // by construction: the regex admits no quote character to break out with.
+   const metadataRef = metadataSchema
+      ? `${tempDb}."${metadataSchema}".ducklake_metadata`
+      : `${tempDb}.ducklake_metadata`;
    let catalogFormat: string | undefined;
    try {
       await connection.runSQL(
          `ATTACH '${escapeSQL(pgConnString)}' AS ${tempDb} (TYPE postgres, READ_ONLY);`,
       );
       const result = await connection.runSQL(
-         `SELECT value FROM ${tempDb}.ducklake_metadata WHERE key = 'version' LIMIT 1;`,
+         `SELECT value FROM ${metadataRef} WHERE key = 'version' LIMIT 1;`,
       );
       const value = runSQLRows(result)[0]?.value;
       catalogFormat = typeof value === "string" ? value : undefined;
    } catch (error) {
+      const message = redactPgSecrets(
+         error instanceof Error ? error.message : String(error),
+      );
+      // A named metadata schema holding no catalog has two very different causes,
+      // and the preflight cannot tell them apart: it is the NORMAL state before the
+      // first read-write attach creates the catalog, and it is also what a typo (or
+      // adding `metadataSchema` to a catalog whose metadata lives elsewhere) looks
+      // like. Neither is loud on its own — a read-write attach CREATES an empty
+      // catalog there and materializes into it, and a read-only attach fails with an
+      // error that says nothing about the schema — so name the schema and say both,
+      // rather than implying a mistake on a path that is expected to hit this once
+      // per catalog. The message also has to hedge on the cause: `does not exist`
+      // matches a missing database or role too, not only a missing table.
+      if (metadataSchema !== undefined && /does not exist/i.test(message)) {
+         logger.warn(
+            "No DuckLake catalog found in the configured metadata schema. This is " +
+               "expected the first time a catalog is created there: a read-write " +
+               "attach will create it, and a read-only attach will fail until it " +
+               "exists. Otherwise check the schema name, and the catalog database " +
+               "and role, against the error.",
+            { dbName, metadataSchema, error: message },
+         );
+         return;
+      }
       logger.warn(
          "DuckLake catalog-format preflight read failed; falling back to ATTACH",
-         {
-            dbName,
-            error: redactPgSecrets(
-               error instanceof Error ? error.message : String(error),
-            ),
-         },
+         { dbName, error: message },
       );
       return;
    } finally {
@@ -574,10 +614,21 @@ async function preflightDuckLakeCatalogFormat(
    );
 }
 
-async function attachDuckLake(
+/**
+ * Attach a DuckLake catalog in a given access mode. `readOnly: true` (the live
+ * user-facing connection path) attaches with `READ_ONLY true`; `readOnly: false`
+ * produces the read-WRITE build variant used only on a transient, build-scoped
+ * session so a materialization can `CREATE TABLE` into the catalog. Both keep
+ * `OVERRIDE_DATA_PATH true` and NEVER pass `AUTOMATIC_MIGRATION` — catalog-format
+ * migration is a coordinated fleet cutover, never an implicit side effect of a
+ * build attach. Both range-preflight the catalog format first (see
+ * {@link preflightDuckLakeCatalogFormat}).
+ */
+async function attachDuckLakeWithMode(
    connection: DuckDBConnection,
    dbName: string,
    ducklakeConfig: components["schemas"]["DucklakeConnection"],
+   options: { readOnly: boolean },
 ): Promise<void> {
    // Tier build/serve DuckLake sessions never implicitly auto-install (Publisher
    // installs the DuckLake stack explicitly below) — regardless of the policy.
@@ -618,26 +669,54 @@ async function attachDuckLake(
 
    const pg = ducklakeConfig.catalog.postgresConnection;
    const pgConnString: string = buildPgConnectionString(pg);
-   // Attach DuckLake with Postgres catalog and cloud storage data path in READ_ONLY mode
-   // The client manages metadata - we only read from the catalogs
-   logger.info(`pgConnString: ${redactPgSecrets(pgConnString)}`);
+   const mode = options.readOnly ? "READ_ONLY" : "READ_WRITE";
+   // READ_ONLY: the client manages metadata, we only read the catalog.
+   // READ_WRITE (build only): a build-scoped session materializes into it.
+   // Debug, not info. These three lines — this one, the escaped form below, and the
+   // assembled ATTACH — are per-attach diagnostics that between them print the catalog
+   // host and database twice and the storage path once. `redactPgSecrets` removes the
+   // password and any URI userinfo, but a DATA_PATH is not a secret it knows about, so
+   // logging the assembled command at info discloses the bucket and whatever the prefix
+   // encodes to every reader of the logs. What an operator watching a healthy fleet
+   // needs is the mode and the outcome, which stay at info below.
+   logger.debug(`pgConnString: ${redactPgSecrets(pgConnString)}`);
    const escapedPgConnString = escapeSQL(pgConnString);
-   logger.info(
+   logger.debug(
       `Final escaped connection string: ${redactPgSecrets(escapedPgConnString)}`,
    );
    const escapedBucketUrl = escapeSQL(ducklakeConfig.storage.bucketUrl);
-   logger.info(`escapedBucketUrl: ${escapedBucketUrl}`);
+   // Optional metadata schema: which schema in the catalog database holds this
+   // DuckLake's `ducklake_*` tables. Absent keeps DuckLake's default (the catalog
+   // connection's default schema), so the emitted command is unchanged for every
+   // existing config. Validated to a plain identifier at config load, because it
+   // reaches a quoted literal here and an identifier position in the preflight.
+   const metadataSchema = ducklakeConfig.catalog.metadataSchema;
    // Range-preflight the catalog's recorded format version so an unsupported
-   // catalog fails as a clean, actionable 422 rather than a deep DuckDB 500.
-   await preflightDuckLakeCatalogFormat(connection, dbName, pgConnString);
-   const attachCommand = `ATTACH OR REPLACE 'ducklake:postgres:${escapedPgConnString}' AS ${dbName} (DATA_PATH '${escapedBucketUrl}', OVERRIDE_DATA_PATH true, READ_ONLY true);`;
-   logger.info(
+   // catalog fails as a clean, actionable 422 rather than a deep DuckDB 500. The
+   // schema must be threaded through: the preflight reads `ducklake_metadata`, so
+   // when the metadata does not live in the catalog's default schema an unqualified
+   // read misses it — and the preflight fails SOFT (logs and returns), so the range
+   // check would silently stop protecting exactly the catalogs using this option.
+   await preflightDuckLakeCatalogFormat(
+      connection,
+      dbName,
+      pgConnString,
+      metadataSchema,
+   );
+   // READ_ONLY is stated explicitly; read-write omits the flag (DuckLake's
+   // default is writable). AUTOMATIC_MIGRATION is never set in either mode.
+   const readOnlyClause = options.readOnly ? ", READ_ONLY true" : "";
+   const metadataSchemaClause = metadataSchema
+      ? `, METADATA_SCHEMA '${escapeSQL(metadataSchema)}'`
+      : "";
+   const attachCommand = `ATTACH OR REPLACE 'ducklake:postgres:${escapedPgConnString}' AS ${dbName} (DATA_PATH '${escapedBucketUrl}', OVERRIDE_DATA_PATH true${readOnlyClause}${metadataSchemaClause});`;
+   logger.debug(
       `Attaching DuckLake database using command: ${redactPgSecrets(attachCommand)}`,
    );
    try {
       await connection.runSQL(attachCommand);
       logger.info(
-         `Successfully attached DuckLake database in READ_ONLY mode: ${dbName}`,
+         `Successfully attached DuckLake database in ${mode} mode: ${dbName}`,
       );
    } catch (error) {
       // Handle case where DuckLake database is already attached
@@ -655,6 +734,246 @@ async function attachDuckLake(
    }
 }
 
+async function attachDuckLake(
+   connection: DuckDBConnection,
+   dbName: string,
+   ducklakeConfig: components["schemas"]["DucklakeConnection"],
+): Promise<void> {
+   await attachDuckLakeWithMode(connection, dbName, ducklakeConfig, {
+      readOnly: true,
+   });
+}
+
+/**
+ * Read-WRITE DuckLake attach for a materialization build. Identical to the
+ * read-only user-facing attach except the catalog is writable, so a build-scoped
+ * session can `CREATE TABLE ... AS` into it. Least privilege: this variant is
+ * only ever used on a transient build session (never the serve connection), for
+ * the duration of one build. Like the read-only attach it is lazy and never on
+ * the worker boot path.
+ */
+export async function attachDuckLakeReadWrite(
+   connection: DuckDBConnection,
+   dbName: string,
+   ducklakeConfig: components["schemas"]["DucklakeConnection"],
+): Promise<void> {
+   await attachDuckLakeWithMode(connection, dbName, ducklakeConfig, {
+      readOnly: false,
+   });
+}
+
+/** A source warehouse type that exposes a native DuckDB query-passthrough. */
+export type FederatedSourceType = "bigquery" | "snowflake" | "postgres";
+
+/**
+ * The result of federating a source connection onto a build session: the
+ * `handle` a passthrough table function needs to reach it —
+ *  - bigquery: the resolved project id (`bigquery_query('<project>', '<sql>')`),
+ *  - snowflake: the created secret name (`snowflake_query('<sql>', '<secret>')`),
+ *  - postgres: the ATTACH alias (`postgres_query('<alias>', '<sql>')`).
+ */
+export interface FederatedHandle {
+   handle: string;
+   sourceType: FederatedSourceType;
+}
+
+/**
+ * The source connection's configuration needed to federate it onto a build
+ * session. `name` is a caller-supplied, already-safe base for the secret/alias
+ * identifiers; the type-specific config carries the credentials.
+ */
+export interface FederationConfig {
+   name: string;
+   bigqueryConnection?: components["schemas"]["BigqueryConnection"];
+   snowflakeConnection?: components["schemas"]["SnowflakeConnection"];
+   postgresConnection?: components["schemas"]["PostgresConnection"];
+}
+
+/**
+ * Establish a SOURCE warehouse's credentials on a build-scoped DuckDB session so
+ * a native query-passthrough (`bigquery_query`/`snowflake_query`/`postgres_query`)
+ * can push the compiled SELECT to that warehouse and stream back result rows.
+ * This is the credential-federation half of the build path: it runs ONLY on the
+ * transient build session, on demand, for the build's duration — the source
+ * creds are never established on the serve connection and never persisted into a
+ * connection config. It mirrors the existing read-only attach handlers but
+ * targets the passthrough functions (bigquery/snowflake need only a SECRET, no
+ * ATTACH; postgres needs an ATTACH whose alias the function references).
+ *
+ * @returns the {@link FederatedHandle} the caller passes to `wrapPassthrough`.
+ * @throws for a source type without a native passthrough, or missing/invalid
+ *   credentials, so a build fails loud rather than producing a wrong table.
+ */
+export async function federateSourceForPassthrough(
+   connection: DuckDBConnection,
+   sourceType: FederatedSourceType,
+   config: FederationConfig,
+): Promise<FederatedHandle> {
+   switch (sourceType) {
+      case "bigquery":
+         return federateBigQuery(connection, config);
+      case "snowflake":
+         return federateSnowflake(connection, config);
+      case "postgres":
+         return federatePostgres(connection, config);
+      default: {
+         // Exhaustiveness guard: a new FederatedSourceType must add a branch.
+         const exhaustive: never = sourceType;
+         throw new Error(
+            `No native query-passthrough for source type '${String(exhaustive)}'`,
+         );
+      }
+   }
+}
+
+async function federateBigQuery(
+   connection: DuckDBConnection,
+   config: FederationConfig,
+): Promise<FederatedHandle> {
+   const bq = config.bigqueryConnection;
+   if (!bq) {
+      throw new Error(
+         `BigQuery connection configuration missing for: ${config.name}`,
+      );
+   }
+
+   let projectId = bq.defaultProjectId;
+   let serviceAccountJson: string | undefined;
+   if (bq.serviceAccountKeyJson) {
+      const keyData = JSON.parse(bq.serviceAccountKeyJson as string);
+      const requiredFields = [
+         "type",
+         "project_id",
+         "private_key",
+         "client_email",
+      ];
+      for (const field of requiredFields) {
+         if (!keyData[field]) {
+            throw new Error(
+               `Invalid service account key: missing "${field}" field`,
+            );
+         }
+      }
+      if (keyData.type !== "service_account") {
+         throw new Error('Invalid service account key: incorrect "type" field');
+      }
+      projectId = keyData.project_id || bq.defaultProjectId;
+      serviceAccountJson = bq.serviceAccountKeyJson as string;
+   }
+
+   if (!projectId || !serviceAccountJson) {
+      throw new Error(
+         `BigQuery project_id and service account key required for: ${config.name}`,
+      );
+   }
+
+   await installAndLoadExtension(connection, "bigquery", true);
+
+   const secretName = sanitizeSecretName(`bigquery_${config.name}`);
+   const escapedJson = escapeSQL(serviceAccountJson);
+   await connection.runSQL(`
+      CREATE OR REPLACE SECRET ${secretName} (
+         TYPE BIGQUERY,
+         SCOPE 'bq://${projectId}',
+         SERVICE_ACCOUNT_JSON '${escapedJson}'
+      );
+   `);
+   logger.info(
+      `Federated BigQuery source for passthrough: project ${projectId}`,
+   );
+   // bigquery_query resolves credentials from the secret scoped to bq://<project>
+   // — the project id is the passthrough handle; no ATTACH is needed.
+   return { handle: projectId, sourceType: "bigquery" };
+}
+
+async function federateSnowflake(
+   connection: DuckDBConnection,
+   config: FederationConfig,
+): Promise<FederatedHandle> {
+   const sf = config.snowflakeConnection;
+   if (!sf) {
+      throw new Error(
+         `Snowflake connection configuration missing for: ${config.name}`,
+      );
+   }
+   const required = {
+      account: sf.account,
+      username: sf.username,
+      password: sf.password,
+   };
+   for (const [field, value] of Object.entries(required)) {
+      if (!value) {
+         throw new Error(`Snowflake ${field} is required for: ${config.name}`);
+      }
+   }
+
+   await installAndLoadExtension(connection, "snowflake", true);
+
+   const params = {
+      account: escapeSQL(sf.account || ""),
+      user: escapeSQL(sf.username || ""),
+      password: escapeSQL(sf.password || ""),
+      database: sf.database ? escapeSQL(sf.database) : undefined,
+      warehouse: sf.warehouse ? escapeSQL(sf.warehouse) : undefined,
+   };
+   const secretName = sanitizeSecretName(`snowflake_${config.name}`);
+   // DATABASE/WAREHOUSE are optional — emit them only when supplied, so an
+   // absent one doesn't interpolate the literal string 'undefined' into the
+   // secret (which Snowflake would then try to use as a real db/warehouse name).
+   const secretLines = [
+      `   TYPE snowflake`,
+      `   ACCOUNT '${params.account}'`,
+      `   USER '${params.user}'`,
+      `   PASSWORD '${params.password}'`,
+      ...(params.database ? [`   DATABASE '${params.database}'`] : []),
+      ...(params.warehouse ? [`   WAREHOUSE '${params.warehouse}'`] : []),
+   ];
+   await connection.runSQL(
+      `CREATE OR REPLACE SECRET ${secretName} (\n${secretLines.join(",\n")}\n);`,
+   );
+   logger.info(`Federated Snowflake source for passthrough: ${secretName}`);
+   // snowflake_query takes the SQL first and the secret name second — the secret
+   // name is the passthrough handle; no ATTACH is needed.
+   return { handle: secretName, sourceType: "snowflake" };
+}
+
+async function federatePostgres(
+   connection: DuckDBConnection,
+   config: FederationConfig,
+): Promise<FederatedHandle> {
+   const pg = config.postgresConnection;
+   if (!pg) {
+      throw new Error(
+         `PostgreSQL connection configuration missing for: ${config.name}`,
+      );
+   }
+
+   await installAndLoadExtension(connection, "postgres");
+
+   const attachString = buildPgConnectionString(pg);
+   // `name` is the ATTACH alias AND (verbatim) the postgres_query handle, so the
+   // handle stays the raw name while the ATTACH identifier is dialect-quoted —
+   // a name needing quoting (e.g. a hyphen) would otherwise be a parser error.
+   const alias = config.name;
+   logger.info(
+      `Federating Postgres source for passthrough as alias '${alias}': ${redactPgSecrets(attachString)}`,
+   );
+   // OR REPLACE for within-session idempotency. The cross-build/cross-tenant
+   // alias-collision boundary is the build session's PRIVATE DuckDB instance
+   // (see createIsolatedBuildSession): each build runs on its own instance, so
+   // its postgres attach cannot collide with another build's or another tenant's
+   // on a shared instance. OR REPLACE is kept as belt-and-suspenders for a
+   // re-attach of the identical source within one session (the alias is the
+   // connection name, the config is that connection's, so replacing is a no-op
+   // rebind to the same source). (bigquery/snowflake federate via CREATE OR
+   // REPLACE SECRET with no ATTACH; secrets are instance-scoped, so isolation
+   // covers them too.)
+   await connection.runSQL(
+      `ATTACH OR REPLACE '${escapeSQL(attachString)}' AS ${quoteIdentifier(alias, "duckdb")} (TYPE postgres, READ_ONLY);`,
+   );
+   return { handle: alias, sourceType: "postgres" };
+}
+
 async function attachCloudStorage(
    connection: DuckDBConnection,
    attachedDb: AttachedDatabase,

package/src/service/connection_config.spec.ts

@@ -624,3 +624,111 @@ describe("SSH proxy validation", () => {
       );
    });
 });
+
+describe("ducklake shape validation", () => {
+   // A DuckLake destination is only attached at its first BUILD, so without an
+   // eager check a missing catalog or bucketUrl surfaced hours after the config
+   // change that caused it. Validated at load like its duckdb-family siblings.
+   const valid: ApiConnection = {
+      name: "lake",
+      type: "ducklake",
+      ducklakeConnection: {
+         catalog: {
+            postgresConnection: {
+               host: "127.0.0.1",
+               port: 5432,
+               databaseName: "catalog",
+               userName: "u",
+               password: "p",
+            },
+         },
+         storage: { bucketUrl: "/tmp/lake" },
+      },
+   };
+
+   it("accepts a fully configured destination", () => {
+      expect(() =>
+         assembleEnvironmentConnections([valid], "/tmp/env"),
+      ).not.toThrow();
+   });
+
+   it("rejects a missing catalog connection at load", () => {
+      const c = {
+         ...valid,
+         ducklakeConnection: { storage: { bucketUrl: "/tmp/lake" } },
+      } as ApiConnection;
+      expect(() => assembleEnvironmentConnections([c], "/tmp/env")).toThrow(
+         /PostgreSQL connection configuration is required for DuckLake catalog/i,
+      );
+   });
+
+   it("rejects a missing bucketUrl at load", () => {
+      const c = {
+         ...valid,
+         ducklakeConnection: { catalog: valid.ducklakeConnection!.catalog },
+      } as ApiConnection;
+      expect(() => assembleEnvironmentConnections([c], "/tmp/env")).toThrow(
+         /Storage bucketUrl is required for DuckLake/i,
+      );
+   });
+
+   // metadataSchema reaches TWO grammars: a quoted string literal in the ATTACH,
+   // and a quoted identifier in the catalog-format preflight's table reference.
+   // Restricting it to a plain identifier at load is what keeps one value valid in
+   // both, so these pin the accept/reject boundary rather than trusting escaping.
+   const withSchema = (metadataSchema: unknown): ApiConnection =>
+      ({
+         ...valid,
+         ducklakeConnection: {
+            ...valid.ducklakeConnection,
+            catalog: {
+               ...valid.ducklakeConnection!.catalog,
+               metadataSchema,
+            },
+         },
+      }) as ApiConnection;
+
+   it("accepts an absent metadataSchema", () => {
+      // Optional: absence keeps DuckLake's default schema, the prior behavior.
+      expect(() =>
+         assembleEnvironmentConnections([valid], "/tmp/env"),
+      ).not.toThrow();
+   });
+
+   it("accepts a plain identifier metadataSchema", () => {
+      for (const ok of ["org_a", "_private", "Lake1", "a"]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(ok)], "/tmp/env"),
+         ).not.toThrow();
+      }
+   });
+
+   it("rejects a metadataSchema that is not a plain identifier", () => {
+      for (const bad of [
+         "foo'; DROP TABLE x; --",
+         "has space",
+         "dotted.name",
+         "1leading_digit",
+         "",
+         '"quoted"',
+      ]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(bad)], "/tmp/env"),
+         ).toThrow(/metadataSchema must be a plain identifier/i);
+      }
+   });
+
+   it("rejects a non-string metadataSchema rather than coercing it", () => {
+      // The value comes from untyped JSON and RegExp.test() coerces, so `true` and
+      // `null` match the identifier pattern as "true"/"null" and would pass a
+      // pattern-only check — then reach escapeSQL's String.replace as a non-string
+      // and throw TypeError at the connection's first attach. That runtime failure is
+      // the thing this load-time check exists to prevent, so the type is part of the
+      // contract, not a formality.
+      for (const bad of [true, false, 0, 1, null, {}, [], ["org_a"]]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(bad)], "/tmp/env"),
+         ).toThrow(/metadataSchema must be a plain identifier/i);
+      }
+   });
+});

package/src/service/connection_config.ts

@@ -425,6 +425,52 @@ function validateConnectionShape(connection: ApiConnection): void {
             throw new Error("MotherDuck access token is required.");
          }
          break;
+      case "ducklake":
+         // Every field the ATTACH demands (see attachDuckLakeWithMode), checked
+         // together here rather than split between this validator and the pojo
+         // assembler below. `bucketUrl` was the one nobody checked: a destination
+         // is only attached at its first BUILD, so a missing bucket surfaced
+         // hours after the config change that caused it.
+         if (!connection.ducklakeConnection) {
+            throw new Error("DuckLake connection configuration is missing.");
+         }
+         if (!connection.ducklakeConnection.catalog?.postgresConnection) {
+            throw new Error(
+               `PostgreSQL connection configuration is required for DuckLake catalog: ${connection.name}`,
+            );
+         }
+         if (!connection.ducklakeConnection.storage?.bucketUrl) {
+            throw new Error(
+               `Storage bucketUrl is required for DuckLake: ${connection.name}`,
+            );
+         }
+         // metadataSchema is optional, but when present it reaches the ATTACH as a
+         // quoted string literal AND the catalog-format preflight as a quoted
+         // identifier. Rather than escape one value for two grammars, restrict it
+         // to a plain identifier here — a deterministic config error, caught at
+         // load instead of at the connection's first attach.
+         //
+         // The typeof check is load-bearing, not defensive: the value arrives from
+         // untyped JSON, and RegExp.test() coerces its argument, so `true` and `null`
+         // both satisfy the pattern as "true"/"null" and would reach escapeSQL's
+         // String.replace as a non-string — a TypeError at the first attach, which is
+         // exactly the failure this check exists to turn into a config error.
+         if (
+            connection.ducklakeConnection.catalog.metadataSchema !== undefined
+         ) {
+            const schema = connection.ducklakeConnection.catalog.metadataSchema;
+            if (
+               typeof schema !== "string" ||
+               !/^[A-Za-z_][A-Za-z0-9_]*$/.test(schema)
+            ) {
+               throw new Error(
+                  `DuckLake catalog metadataSchema must be a plain identifier ` +
+                     `([A-Za-z_][A-Za-z0-9_]*), got '${schema}' for connection: ` +
+                     `${connection.name}`,
+               );
+            }
+         }
+         break;
       case "trino":
          if (!connection.trinoConnection) {
             throw new Error("Trino connection configuration is missing.");
@@ -725,14 +771,7 @@ export function assembleEnvironmentConnections(
          }
 
          case "ducklake": {
-            if (!connection.ducklakeConnection) {
-               throw new Error("DuckLake connection configuration is missing.");
-            }
-            if (!connection.ducklakeConnection.catalog?.postgresConnection) {
-               throw new Error(
-                  `PostgreSQL connection configuration is required for DuckLake catalog: ${connection.name}`,
-               );
-            }
+            // Shape is validated up front by validateConnectionShape.
             pojo.connections[connection.name] = buildDuckdbEntry(
                connection.name,
                environmentPath,