@sqg/sqg 0.21.0 → 0.21.1

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { LRParser } from "@lezer/lr";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, relative, resolve } from "node:path";
-import { camelCase, pascalCase, snakeCase } from "es-toolkit/string";
+import { camelCase, escapeRegExp, pascalCase, snakeCase } from "es-toolkit/string";
 import Handlebars from "handlebars";
 import YAML from "yaml";
 import { z } from "zod";
@@ -1931,8 +1931,20 @@ async function preparePostgresSources(sources, queries, reporter) {
 	};
 	try {
 		for (const source of sources) {
+			if (source.url) {
+				attachments.push({
+					alias: source.name,
+					connectionUri: source.url
+				});
+				continue;
+			}
 			reporter?.onContainerStarting?.();
-			const container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			let container;
+			try {
+				container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			} catch (e) {
+				throw new DatabaseError(`Could not start a Postgres container for source '${source.name}': ${e.message}`, "postgres", "Postgres sources need Docker to introspect schema. Start Docker, or set 'url' on the source to point at an existing Postgres database (e.g. url: $DATABASE_URL).");
+			}
 			containers.push(container);
 			const connectionUri = container.getConnectionUri();
 			reporter?.onContainerStarted?.(connectionUri);
@@ -2178,15 +2190,16 @@ const ProjectSchema = z.object({
 			template: z.string().optional().describe("Custom Handlebars template path"),
 			output: z.string().min(1, "Output path is required").describe("Output file or directory path"),
 			config: z.any().optional().describe("Generator-specific configuration")
-		})).min(1, "At least one generator is required").describe("Code generators to run")
-	})).min(1, "At least one SQL configuration is required").describe("SQL file configurations"),
+		}).strict()).min(1, "At least one generator is required").describe("Code generators to run")
+	}).strict()).min(1, "At least one SQL configuration is required").describe("SQL file configurations"),
 	sources: z.array(z.object({
 		type: z.enum(["file", "postgres"]).optional().describe("Source type: 'file' (default) or 'postgres'"),
 		path: z.string().optional().describe("Path to source file for file sources (supports $HOME)"),
 		name: z.string().optional().describe("Variable name (file sources) or DuckDB attach alias (postgres sources)"),
-		image: z.string().optional().describe("Docker image for postgres sources (default: postgres:16-alpine)")
-	}).refine((s) => s.type === "postgres" ? !!s.name : !!s.path, { message: "file sources require 'path'; postgres sources require 'name'" })).optional().describe("External sources: files inlined as variables, or postgres databases attached for introspection")
-});
+		image: z.string().optional().describe("Docker image for postgres sources (default: postgres:16-alpine)"),
+		url: z.string().optional().describe("Postgres source: connect to this existing database for introspection instead of starting a container. Use a literal DSN or '$ENV_VAR' to read from the environment. When set, ':source=' BASELINE blocks are not applied (the live schema is used), which avoids schema drift.")
+	}).strict().refine((s) => s.type === "postgres" ? !!s.name : !!s.path, { message: "file sources require 'path'; postgres sources require 'name'" })).optional().describe("External sources: files inlined as variables, or postgres databases attached for introspection")
+}).strict();
 var ExtraVariable = class {
 	constructor(name, value) {
 		this.name = name;
@@ -2202,11 +2215,25 @@ function createExtraVariables(sources, suppressLogging = false) {
 		return new ExtraVariable(varName, `'${resolvedPath}'`);
 	});
 }
+/**
+* Resolve a postgres source `url`. A value of the form `$VAR` or `${VAR}` is
+* read from the environment (so credentials need not live in sqg.yaml); any
+* other value is treated as a literal DSN.
+*/
+function resolveSourceUrl(url, sourceName) {
+	const match = url.match(/^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/);
+	if (!match) return url;
+	const envName = match[1];
+	const value = process.env[envName];
+	if (!value) throw new SqgError(`Postgres source '${sourceName}' references environment variable '${envName}' which is not set`, "CONFIG_VALIDATION_ERROR", `Set ${envName} to the database connection string, or use a literal DSN in the 'url' field`);
+	return value;
+}
 /** Postgres sources resolved from the project config (with image defaulted). */
 function getPostgresSources(sources) {
 	return sources.filter((source) => source.type === "postgres").map((source) => ({
 		name: source.name,
-		image: source.image ?? "postgres:16-alpine"
+		image: source.image ?? "postgres:16-alpine",
+		url: source.url ? resolveSourceUrl(source.url, source.name) : void 0
 	}));
 }
 function buildProjectFromCliOptions(options) {
@@ -2535,6 +2562,11 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					if (e instanceof SqgError) throw e;
 					throw SqgError.inFile(`Failed to parse SQL file: ${e.message}`, "SQL_PARSE_ERROR", sqlFile, { suggestion: "Check SQL syntax and annotation format" });
 				}
+				const referencedPgSources = pgSources.filter((source) => {
+					const catalogRef = new RegExp(`\\b${escapeRegExp(source.name)}\\.`);
+					return queries.some((q) => q.sourceTarget === source.name || catalogRef.test(q.rawQuery));
+				});
+				const referencedPgSourceNames = referencedPgSources.map((s) => s.name);
 				for (const [engine, gens] of gensByEngine) {
 					const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 					const reporterAny = reporter;
@@ -2543,9 +2575,9 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					try {
 						const dbEngine = getDatabaseEngine(engine);
 						let attachments;
-						if (engine === "duckdb" && pgSources.length > 0) {
+						if (engine === "duckdb" && referencedPgSources.length > 0) {
 							ui?.startPhase("Starting postgres source containers...");
-							preparedSources = await preparePostgresSources(pgSources, queries, reporter);
+							preparedSources = await preparePostgresSources(referencedPgSources, queries, reporter);
 							attachments = preparedSources.attachments;
 						}
 						ui?.startPhase(`Initializing ${engine} database...`);
@@ -2576,7 +2608,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 						const outputPath = await writeGeneratedFile(projectDir, {
 							...gen,
 							projectName: project.name
-						}, generator, sqlFile, queries, tables, engine, writeToStdout, pgSources.map((s) => s.name));
+						}, generator, sqlFile, queries, tables, engine, writeToStdout, referencedPgSourceNames);
 						if (outputPath !== null) {
 							files.push(outputPath);
 							results.push({
@@ -2813,8 +2845,12 @@ function parseSQLQueries(filePath, extraVariables) {
 					});
 				}
 				trim() {
-					const lastPart = this.sqlParts.length > 0 ? this.sqlParts[this.sqlParts.length - 1] : null;
-					if (lastPart && typeof lastPart === "string") this.sqlParts[this.sqlParts.length - 1] = lastPart.trimEnd();
+					const isBlankString = (p) => typeof p === "string" && p.trim() === "";
+					while (this.sqlParts.length > 0 && isBlankString(this.sqlParts[0])) this.sqlParts.shift();
+					if (this.sqlParts.length > 0 && typeof this.sqlParts[0] === "string") this.sqlParts[0] = this.sqlParts[0].trimStart();
+					while (this.sqlParts.length > 0 && isBlankString(this.sqlParts[this.sqlParts.length - 1])) this.sqlParts.pop();
+					const lastIdx = this.sqlParts.length - 1;
+					if (lastIdx >= 0 && typeof this.sqlParts[lastIdx] === "string") this.sqlParts[lastIdx] = this.sqlParts[lastIdx].trimEnd();
 				}
 				parameters() {
 					return this.sqlParts.filter((part) => typeof part !== "string" && !part.name.startsWith("sources_"));

package/dist/sqg.mjs

@@ -13,7 +13,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import YAML from "yaml";
-import { camelCase, pascalCase, snakeCase } from "es-toolkit/string";
+import { camelCase, escapeRegExp, pascalCase, snakeCase } from "es-toolkit/string";
 import Handlebars from "handlebars";
 import { z } from "zod";
 import { DuckDBEnumType, DuckDBInstance, DuckDBListType, DuckDBMapType, DuckDBStructType } from "@duckdb/node-api";
@@ -949,8 +949,12 @@ function parseSQLQueries(filePath, extraVariables) {
 					});
 				}
 				trim() {
-					const lastPart = this.sqlParts.length > 0 ? this.sqlParts[this.sqlParts.length - 1] : null;
-					if (lastPart && typeof lastPart === "string") this.sqlParts[this.sqlParts.length - 1] = lastPart.trimEnd();
+					const isBlankString = (p) => typeof p === "string" && p.trim() === "";
+					while (this.sqlParts.length > 0 && isBlankString(this.sqlParts[0])) this.sqlParts.shift();
+					if (this.sqlParts.length > 0 && typeof this.sqlParts[0] === "string") this.sqlParts[0] = this.sqlParts[0].trimStart();
+					while (this.sqlParts.length > 0 && isBlankString(this.sqlParts[this.sqlParts.length - 1])) this.sqlParts.pop();
+					const lastIdx = this.sqlParts.length - 1;
+					if (lastIdx >= 0 && typeof this.sqlParts[lastIdx] === "string") this.sqlParts[lastIdx] = this.sqlParts[lastIdx].trimEnd();
 				}
 				parameters() {
 					return this.sqlParts.filter((part) => typeof part !== "string" && !part.name.startsWith("sources_"));
@@ -3179,8 +3183,20 @@ async function preparePostgresSources(sources, queries, reporter) {
 	};
 	try {
 		for (const source of sources) {
+			if (source.url) {
+				attachments.push({
+					alias: source.name,
+					connectionUri: source.url
+				});
+				continue;
+			}
 			reporter?.onContainerStarting?.();
-			const container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			let container;
+			try {
+				container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			} catch (e) {
+				throw new DatabaseError(`Could not start a Postgres container for source '${source.name}': ${e.message}`, "postgres", "Postgres sources need Docker to introspect schema. Start Docker, or set 'url' on the source to point at an existing Postgres database (e.g. url: $DATABASE_URL).");
+			}
 			containers.push(container);
 			const connectionUri = container.getConnectionUri();
 			reporter?.onContainerStarted?.(connectionUri);
@@ -3426,15 +3442,16 @@ const ProjectSchema = z.object({
 			template: z.string().optional().describe("Custom Handlebars template path"),
 			output: z.string().min(1, "Output path is required").describe("Output file or directory path"),
 			config: z.any().optional().describe("Generator-specific configuration")
-		})).min(1, "At least one generator is required").describe("Code generators to run")
-	})).min(1, "At least one SQL configuration is required").describe("SQL file configurations"),
+		}).strict()).min(1, "At least one generator is required").describe("Code generators to run")
+	}).strict()).min(1, "At least one SQL configuration is required").describe("SQL file configurations"),
 	sources: z.array(z.object({
 		type: z.enum(["file", "postgres"]).optional().describe("Source type: 'file' (default) or 'postgres'"),
 		path: z.string().optional().describe("Path to source file for file sources (supports $HOME)"),
 		name: z.string().optional().describe("Variable name (file sources) or DuckDB attach alias (postgres sources)"),
-		image: z.string().optional().describe("Docker image for postgres sources (default: postgres:16-alpine)")
-	}).refine((s) => s.type === "postgres" ? !!s.name : !!s.path, { message: "file sources require 'path'; postgres sources require 'name'" })).optional().describe("External sources: files inlined as variables, or postgres databases attached for introspection")
-});
+		image: z.string().optional().describe("Docker image for postgres sources (default: postgres:16-alpine)"),
+		url: z.string().optional().describe("Postgres source: connect to this existing database for introspection instead of starting a container. Use a literal DSN or '$ENV_VAR' to read from the environment. When set, ':source=' BASELINE blocks are not applied (the live schema is used), which avoids schema drift.")
+	}).strict().refine((s) => s.type === "postgres" ? !!s.name : !!s.path, { message: "file sources require 'path'; postgres sources require 'name'" })).optional().describe("External sources: files inlined as variables, or postgres databases attached for introspection")
+}).strict();
 var ExtraVariable = class {
 	constructor(name, value) {
 		this.name = name;
@@ -3450,11 +3467,25 @@ function createExtraVariables(sources, suppressLogging = false) {
 		return new ExtraVariable(varName, `'${resolvedPath}'`);
 	});
 }
+/**
+* Resolve a postgres source `url`. A value of the form `$VAR` or `${VAR}` is
+* read from the environment (so credentials need not live in sqg.yaml); any
+* other value is treated as a literal DSN.
+*/
+function resolveSourceUrl(url, sourceName) {
+	const match = url.match(/^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/);
+	if (!match) return url;
+	const envName = match[1];
+	const value = process.env[envName];
+	if (!value) throw new SqgError(`Postgres source '${sourceName}' references environment variable '${envName}' which is not set`, "CONFIG_VALIDATION_ERROR", `Set ${envName} to the database connection string, or use a literal DSN in the 'url' field`);
+	return value;
+}
 /** Postgres sources resolved from the project config (with image defaulted). */
 function getPostgresSources(sources) {
 	return sources.filter((source) => source.type === "postgres").map((source) => ({
 		name: source.name,
-		image: source.image ?? "postgres:16-alpine"
+		image: source.image ?? "postgres:16-alpine",
+		url: source.url ? resolveSourceUrl(source.url, source.name) : void 0
 	}));
 }
 function buildProjectFromCliOptions(options) {
@@ -3783,6 +3814,11 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					if (e instanceof SqgError) throw e;
 					throw SqgError.inFile(`Failed to parse SQL file: ${e.message}`, "SQL_PARSE_ERROR", sqlFile, { suggestion: "Check SQL syntax and annotation format" });
 				}
+				const referencedPgSources = pgSources.filter((source) => {
+					const catalogRef = new RegExp(`\\b${escapeRegExp(source.name)}\\.`);
+					return queries.some((q) => q.sourceTarget === source.name || catalogRef.test(q.rawQuery));
+				});
+				const referencedPgSourceNames = referencedPgSources.map((s) => s.name);
 				for (const [engine, gens] of gensByEngine) {
 					const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 					const reporterAny = reporter;
@@ -3791,9 +3827,9 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					try {
 						const dbEngine = getDatabaseEngine(engine);
 						let attachments;
-						if (engine === "duckdb" && pgSources.length > 0) {
+						if (engine === "duckdb" && referencedPgSources.length > 0) {
 							ui?.startPhase("Starting postgres source containers...");
-							preparedSources = await preparePostgresSources(pgSources, queries, reporter);
+							preparedSources = await preparePostgresSources(referencedPgSources, queries, reporter);
 							attachments = preparedSources.attachments;
 						}
 						ui?.startPhase(`Initializing ${engine} database...`);
@@ -3824,7 +3860,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 						const outputPath = await writeGeneratedFile(projectDir, {
 							...gen,
 							projectName: project.name
-						}, generator, sqlFile, queries, tables, engine, writeToStdout, pgSources.map((s) => s.name));
+						}, generator, sqlFile, queries, tables, engine, writeToStdout, referencedPgSourceNames);
 						if (outputPath !== null) {
 							files.push(outputPath);
 							results.push({
@@ -3858,7 +3894,7 @@ async function processProject(projectPath, ui) {
 //#region src/mcp-server.ts
 const server = new Server({
 	name: "sqg-mcp",
-	version: process.env.npm_package_version ?? "0.21.0"
+	version: process.env.npm_package_version ?? "0.21.1"
 }, { capabilities: {
 	tools: {},
 	resources: {}
@@ -4329,7 +4365,7 @@ function formatMs(ms) {
 }
 //#endregion
 //#region src/sqg.ts
-const version = process.env.npm_package_version ?? "0.21.0";
+const version = process.env.npm_package_version ?? "0.21.1";
 updateNotifier({ pkg: {
 	name: "@sqg/sqg",
 	version

package/dist/templates/java-jdbc.hbs

@@ -224,9 +224,11 @@ public class {{className}} {
     {{{declareEnums queries}}}
 
     {{#each attachers}}
-    /** Attach the "{{alias}}" postgres source under the same alias used during generation. */
+    /** Attach the "{{alias}}" postgres source under the same alias used during generation. Loads the postgres extension (idempotent) so callers need not rely on DuckDB autoloading. */
     public void {{functionName}}(String connectionString) throws SQLException {
         try (var stmt = connection.createStatement()) {
+            stmt.execute("INSTALL postgres");
+            stmt.execute("LOAD postgres");
             stmt.execute("ATTACH '" + connectionString + "' AS {{alias}} (TYPE postgres)");
         }
     }

package/dist/templates/python.hbs

@@ -137,7 +137,13 @@ class {{className}}:
 
 {{#each attachers}}
     def {{functionName}}(self, connection_string: str) -> None:
-        """Attach the "{{alias}}" postgres source under the same alias used during generation."""
+        """Attach the "{{alias}}" postgres source under the same alias used during generation.
+
+        Loads the postgres extension (idempotent) so callers need not rely on
+        DuckDB autoloading.
+        """
+        self._conn.execute("INSTALL postgres")
+        self._conn.execute("LOAD postgres")
         self._conn.execute(f"ATTACH '{connection_string}' AS {{alias}} (TYPE postgres)")
 
 {{/each}}

package/dist/templates/typescript-duckdb.hbs

@@ -59,8 +59,10 @@ export class {{className}} {
     }
 
     {{#each attachers}}
-    /** Attach the "{{alias}}" postgres source under the same alias used during generation. */
+    /** Attach the "{{alias}}" postgres source under the same alias used during generation. Loads the postgres extension (idempotent) so callers need not rely on DuckDB autoloading. */
     async {{functionName}}(connectionString: string): Promise<void> {
+        await this.conn.run("INSTALL postgres");
+        await this.conn.run("LOAD postgres");
         await this.conn.run(`ATTACH '${connectionString}' AS {{alias}} (TYPE postgres)`);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqg/sqg",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "SQG - SQL Query Generator - Type-safe code generation from SQL (https://sqg.dev)",
   "type": "module",
   "main": "dist/index.mjs",