@sqg/sqg 0.20.0 → 0.21.0

package/README.md

@@ -117,12 +117,15 @@ console.log(user?.name);
 | Annotation | Description |
 |------------|-------------|
 | `-- MIGRATE name` | Schema migration (CREATE TABLE, etc.) |
+| `-- BASELINE name` | Schema created outside SQG (ETL, sibling service). Runs before migrations for type-checking; **not** emitted in `getMigrations()` |
+| `-- BASELINE name :source=pg` | Schema of a `type: postgres` source. Applied natively to a managed testcontainer and attached into DuckDB for introspection (DuckDB generators; needs Docker) |
 | `-- QUERY name` | SELECT query returning rows |
 | `-- QUERY name :one` | Query returning single row or undefined |
 | `-- QUERY name :pluck` | Return single (first) column value |
 | `-- QUERY name :result=Foo` | Name the row type (Java). Add it to ONE query and every same-shape query shares it. Full-table `SELECT *` reuses the `TABLE` row type without annotation. |
 | `-- EXEC name` | INSERT/UPDATE/DELETE (no result rows) |
 | `-- TESTDATA name` | Test data, runs after migrations |
+| `-- TABLE name :appender` | Generate a type-safe bulk insert appender (DuckDB, PostgreSQL) |
 | `@set var = value` | Define parameter with sample value |
 | `${var}` | Reference parameter in query |
 

package/dist/index.mjs

@@ -229,6 +229,7 @@ SQL Annotation Syntax:
   -- QUERY <name> [:one] [:pluck]   Select query (returns rows)
   -- EXEC <name> [:batch]           Execute statement (INSERT/UPDATE/DELETE)
   -- BASELINE <name>                Schema created outside SQG (runs before migrations, not tracked)
+  -- BASELINE <name> :source=<src>  Schema of a 'type: postgres' source (applied to a managed testcontainer, attached into DuckDB)
   -- MIGRATE <name>                 Schema migration (runs in source order; name is any identifier, e.g. "1" or "add_email")
   -- TESTDATA <name>                Test data setup (not generated)
   -- TABLE <name> :appender         Table for bulk insert appender (DuckDB, PostgreSQL)
@@ -242,6 +243,7 @@ Modifiers:
   :all          Return all rows (default)
   :batch        Generate a JDBC batch method for an EXEC (Java only)
   :appender     Generate bulk insert appender for TABLE annotation
+  :source=Name  Mark a BASELINE block as the schema of a postgres source (Name)
   :result=Name  Name (and share) the row type (Java only). Annotate ONE query
                 with :result=Name — every other query in the same file with the
                 same column shape automatically gets the same name; you do NOT
@@ -1496,6 +1498,19 @@ var PythonGenerator = class extends BaseGenerator {
 			if (value.includes("\n") || value.includes("'") || value.includes("\"")) return `"""\\\n${value}"""`;
 			return `"${value}"`;
 		});
+		Handlebars.registerHelper("sqlExpr", (queryHelper) => {
+			const parts = queryHelper.sqlQueryParts;
+			if (!parts.some((p) => typeof p !== "string" && p.name.startsWith("sources_"))) {
+				const value = queryHelper.sqlQuery;
+				if (value.includes("\n") || value.includes("'") || value.includes("\"")) return `"""\\\n${value}"""`;
+				return `"${value}"`;
+			}
+			let out = "f\"\"\"";
+			for (const part of parts) if (typeof part === "string") out += part.replace(/\\/g, "\\\\").replace(/\{/g, "{{").replace(/\}/g, "}}");
+			else if (part.name.startsWith("sources_")) out += ` '{${part.name}}'`;
+			else out += "?";
+			return `${out}"""`;
+		});
 		Handlebars.registerHelper("pyType", (column) => {
 			return this.getPyType(column);
 		});
@@ -1620,6 +1635,7 @@ var TsGenerator = class extends BaseGenerator {
 	async beforeGenerate(_projectDir, gen, _queries, _tables) {
 		if (this.typeMapper instanceof TypeScriptTypeMapper) this.typeMapper.safeIntegers = !!gen.config?.safeIntegers;
 		Handlebars.registerHelper("quote", (value) => this.quote(value));
+		Handlebars.registerHelper("sqlExpr", (queryHelper) => this.sqlExpr(queryHelper));
 		Handlebars.registerHelper("appendMethod", (column) => {
 			if (column.type instanceof ListType) return "List";
 			const typeStr = column.type?.toString().toUpperCase() || "";
@@ -1772,6 +1788,22 @@ var TsGenerator = class extends BaseGenerator {
 	quote(value) {
 		return value.includes("\n") || value.includes("'") ? `\`${value}\`` : `'${value}'`;
 	}
+	/**
+	* Build the SQL expression for a query. Without file `sources`, this is the
+	* plain quoted SQL string (unchanged). When a `${sources_x}` reference is
+	* present it is interpolated into a template literal as a runtime argument
+	* (the value is supplied by the caller, not bound), mirroring the Java
+	* generator — `ATTACH '` + arg + `'` style.
+	*/
+	sqlExpr(queryHelper) {
+		const parts = queryHelper.sqlQueryParts;
+		if (!parts.some((p) => typeof p !== "string" && p.name.startsWith("sources_"))) return this.quote(queryHelper.sqlQuery);
+		let out = "`";
+		for (const part of parts) if (typeof part === "string") out += part.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+		else if (part.name.startsWith("sources_")) out += ` '\${${part.name}}'`;
+		else out += "?";
+		return `${out}\``;
+	}
 };
 //#endregion
 //#region src/generators/typescript-duckdb-generator.ts
@@ -1878,6 +1910,57 @@ function getGenerator(generator) {
 	}
 }
 //#endregion
+//#region src/sources.ts
+/**
+* For each `type: postgres` source: start a throwaway Postgres testcontainer,
+* run the source's schema (the BASELINE blocks tagged `:source=<name>`) natively
+* against it so introspection sees true Postgres types, and return the connection
+* info to ATTACH into DuckDB.
+*
+* The synthesized ATTACH (done by the DuckDB adapter) and these schema blocks are
+* not emitted into generated code — at runtime the application attaches the real
+* production database under the same alias.
+*/
+async function preparePostgresSources(sources, queries, reporter) {
+	const containers = [];
+	const attachments = [];
+	const teardown = async () => {
+		for (const container of containers) try {
+			await container.stop();
+		} catch {}
+	};
+	try {
+		for (const source of sources) {
+			reporter?.onContainerStarting?.();
+			const container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			containers.push(container);
+			const connectionUri = container.getConnectionUri();
+			reporter?.onContainerStarted?.(connectionUri);
+			const schemaBlocks = queries.filter((q) => q.isBaseline && q.sourceTarget === source.name);
+			const client = new Client({ connectionString: connectionUri });
+			await client.connect();
+			try {
+				for (const block of schemaBlocks) await client.query(block.rawQuery);
+			} catch (e) {
+				throw new DatabaseError(`Failed to apply schema for postgres source '${source.name}': ${e.message}`, "postgres", `Check that the BASELINE blocks tagged ':source=${source.name}' are valid PostgreSQL.`);
+			} finally {
+				await client.end();
+			}
+			attachments.push({
+				alias: source.name,
+				connectionUri
+			});
+		}
+	} catch (e) {
+		await teardown();
+		throw e;
+	}
+	return {
+		attachments,
+		teardown
+	};
+}
+//#endregion
 //#region src/sqltool.ts
 const GENERATED_FILE_COMMENT = "This file is generated by SQG (https://sqg.dev). Do not edit manually.";
 const configSchema = z.object({ result: z.record(z.string(), z.string()).optional() });
@@ -2054,18 +2137,23 @@ var TableHelper = class {
 		return this.generator.typeMapper;
 	}
 };
-function generateSourceFile(name, queries, tables, templatePath, generator, engine, projectName, config) {
+function generateSourceFile(name, queries, tables, templatePath, generator, engine, projectName, config, postgresSourceNames = []) {
 	const templateSrc = readFileSync(templatePath, "utf-8");
 	const template = Handlebars.compile(templateSrc);
 	Handlebars.registerHelper("mapType", (column) => generator.mapType(column));
 	Handlebars.registerHelper("plusOne", (value) => value + 1);
 	const migrations = queries.filter((q) => q.isMigrate).map((q) => new SqlQueryHelper(q, generator, generator.getStatement(q)));
 	const tableHelpers = generator.supportsAppenders(engine) ? tables.filter((t) => !t.skipGenerateFunction).map((t) => new TableHelper(t, generator)) : [];
+	const attachers = engine === "duckdb" ? postgresSourceNames.map((sourceName) => ({
+		alias: sourceName,
+		functionName: generator.getFunctionName(`attach_${sourceName}`)
+	})) : [];
 	return template({
 		generatedComment: GENERATED_FILE_COMMENT,
 		migrations,
 		queries: queries.map((q) => new SqlQueryHelper(q, generator, generator.getStatement(q))),
 		tables: tableHelpers,
+		attachers,
 		className: generator.getClassName(name),
 		projectName,
 		config
@@ -2093,9 +2181,11 @@ const ProjectSchema = z.object({
 		})).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"),
 	sources: z.array(z.object({
-		path: z.string().describe("Path to source file (supports $HOME)"),
-		name: z.string().optional().describe("Variable name override")
-	})).optional().describe("External source files to include as variables")
+		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")
 });
 var ExtraVariable = class {
 	constructor(name, value) {
@@ -2104,7 +2194,7 @@ var ExtraVariable = class {
 	}
 };
 function createExtraVariables(sources, suppressLogging = false) {
-	return sources.map((source) => {
+	return sources.filter((source) => source.type !== "postgres").map((source) => {
 		const path = source.path;
 		const resolvedPath = path.replace("$HOME", homedir());
 		const varName = `sources_${(source.name ?? basename(path, extname(resolvedPath))).replace(/\s+/g, "_")}`;
@@ -2112,6 +2202,13 @@ function createExtraVariables(sources, suppressLogging = false) {
 		return new ExtraVariable(varName, `'${resolvedPath}'`);
 	});
 }
+/** 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"
+	}));
+}
 function buildProjectFromCliOptions(options) {
 	if (!isValidGenerator(options.generator)) {
 		const similar = findSimilarGenerators(options.generator);
@@ -2250,7 +2347,7 @@ function assignResultTypeNames(queries, tables, projectDir = process.cwd()) {
 		}
 		const fullMatch = tryFullTableMatch(group.queries[0], tablesByName);
 		if (fullMatch) {
-			claim(fullMatch, shape, group.queries[0], `full-table match`);
+			claim(fullMatch, shape, group.queries[0], "full-table match");
 			for (const q of group.queries) q.resultTypeName = fullMatch;
 			continue;
 		}
@@ -2303,14 +2400,14 @@ function validateQueries(queries) {
 		};
 	}
 }
-async function writeGeneratedFile(projectDir, gen, generator, file, queries, tables, engine, writeToStdout = false) {
+async function writeGeneratedFile(projectDir, gen, generator, file, queries, tables, engine, writeToStdout = false, postgresSourceNames = []) {
 	await generator.beforeGenerate(projectDir, gen, queries, tables);
 	const templatePath = join(dirname(new URL(import.meta.url).pathname), gen.template ?? generator.template);
 	const name = gen.name ?? basename(file, extname(file));
 	const sourceFile = generateSourceFile(name, queries, tables, templatePath, generator, engine, gen.projectName ?? name, {
 		migrations: true,
 		...gen.config
-	});
+	}, postgresSourceNames);
 	if (writeToStdout) {
 		process.stdout.write(sourceFile);
 		if (!sourceFile.endsWith("\n")) process.stdout.write("\n");
@@ -2411,6 +2508,11 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 	const results = [];
 	try {
 		const extraVariables = createExtraVariables(project.sources ?? [], writeToStdout);
+		const pgSources = getPostgresSources(project.sources ?? []);
+		const pgSourceNames = new Set(pgSources.map((s) => s.name));
+		if (pgSources.length > 0) {
+			if (!project.sql.some((sql) => sql.gen.some((gen) => getGeneratorEngine(gen.generator) === "duckdb"))) throw new SqgError("Postgres sources require a DuckDB generator (they are attached into DuckDB for introspection)", "CONFIG_VALIDATION_ERROR", "Add a 'typescript/duckdb' or 'java/duckdb' generator, or remove the postgres sources");
+		}
 		const files = [];
 		for (const sql of project.sql) {
 			const gensByEngine = /* @__PURE__ */ new Map();
@@ -2428,6 +2530,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					const parseResult = parseSQLQueries(fullPath, extraVariables);
 					queries = parseResult.queries;
 					tables = parseResult.tables;
+					for (const q of queries) if (q.sourceTarget && !pgSourceNames.has(q.sourceTarget)) throw SqgError.inQuery(`BASELINE block targets unknown postgres source '${q.sourceTarget}'`, "CONFIG_VALIDATION_ERROR", q.id, sqlFile, { suggestion: `Declare a source with 'type: postgres, name: ${q.sourceTarget}' in sqg.yaml` });
 				} catch (e) {
 					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" });
@@ -2436,10 +2539,17 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 					const reporterAny = reporter;
 					if (reporterAny?.setQueryTotal) reporterAny.setQueryTotal(executableQueries.length);
+					let preparedSources;
 					try {
 						const dbEngine = getDatabaseEngine(engine);
+						let attachments;
+						if (engine === "duckdb" && pgSources.length > 0) {
+							ui?.startPhase("Starting postgres source containers...");
+							preparedSources = await preparePostgresSources(pgSources, queries, reporter);
+							attachments = preparedSources.attachments;
+						}
 						ui?.startPhase(`Initializing ${engine} database...`);
-						await dbEngine.initializeDatabase(queries, reporter);
+						await dbEngine.initializeDatabase(queries, reporter, { attachments });
 						ui?.startPhase(`Introspecting ${executableQueries.length} queries...`);
 						await dbEngine.executeQueries(queries, reporter);
 						if (tables.length > 0) await dbEngine.introspectTables(tables, reporter);
@@ -2456,6 +2566,8 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 							file: sqlFile,
 							engine
 						});
+					} finally {
+						if (preparedSources) await preparedSources.teardown();
 					}
 					ui?.startPhase("Generating code...");
 					const genStart = performance.now();
@@ -2464,7 +2576,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 						const outputPath = await writeGeneratedFile(projectDir, {
 							...gen,
 							projectName: project.name
-						}, generator, sqlFile, queries, tables, engine, writeToStdout);
+						}, generator, sqlFile, queries, tables, engine, writeToStdout, pgSources.map((s) => s.name));
 						if (outputPath !== null) {
 							files.push(outputPath);
 							results.push({
@@ -2537,6 +2649,13 @@ var SQLQuery = class {
 	parameterTypes;
 	/** Explicit row-type name from `:result=Name` modifier, when present. */
 	resultTypeOverride;
+	/**
+	* Name of the postgres `source` this block targets, from a `:source=name`
+	* modifier on a BASELINE block. Such blocks define the schema of an external
+	* postgres source and run natively against that source's container during
+	* generation (not against the DuckDB introspection connection).
+	*/
+	sourceTarget;
 	/** Final row-type identifier assigned by assignResultTypeNames (after introspection). */
 	resultTypeName;
 	constructor(filename, id, rawQuery, queryAnonymous, queryNamed, queryPositional, type, isOne, isPluck, isBatch, variables, config, line) {
@@ -2653,6 +2772,8 @@ function parseSQLQueries(filePath, extraVariables) {
 			const isPluck = modifiers.includes(":pluck");
 			const isBatch = modifiers.includes(":batch");
 			const resultTypeOverride = modifiers.find((m) => m.startsWith(":result="))?.slice(8);
+			const sourceTarget = modifiers.find((m) => m.startsWith(":source="))?.slice(8);
+			if (sourceTarget && queryType !== "BASELINE") throw SqgError.inQuery(`The ':source=' modifier is only valid on BASELINE blocks, not ${queryType}`, "SQL_PARSE_ERROR", name, filePath, { suggestion: "Move the schema for a postgres source into a '-- BASELINE <name> :source=<source>' block" });
 			let configStr = getStr("Config", true);
 			if (configStr?.endsWith("*/")) configStr = configStr.slice(0, -2);
 			let config = null;
@@ -2808,6 +2929,7 @@ function parseSQLQueries(filePath, extraVariables) {
 			});
 			const query = new SQLQuery(filePath, name, sqlContentStr, sql.toSqlWithAnonymousPlaceholders(), sql.toSqlWithNamedPlaceholders(), sql.toSqlWithPositionalPlaceholders(), queryType, isOne, isPluck, isBatch, variables, config, annotationLine);
 			query.resultTypeOverride = resultTypeOverride;
+			query.sourceTarget = sourceTarget;
 			checkDuplicate(queryType, name);
 			queries.push(query);
 			consola.debug(`Added query: ${name} (${queryType})`);
@@ -2824,7 +2946,7 @@ function parseSQLQueries(filePath, extraVariables) {
 //#endregion
 //#region src/db/types.ts
 async function initializeDatabase(queries, execQueries, reporter) {
-	const baselineQueries = queries.filter((q) => q.isBaseline);
+	const baselineQueries = queries.filter((q) => q.isBaseline && !q.sourceTarget);
 	for (const query of baselineQueries) try {
 		await execQueries(query);
 	} catch (error) {
@@ -2880,9 +3002,17 @@ function convertType(type) {
 const duckdb = new class {
 	db;
 	connection;
-	async initializeDatabase(queries, reporter) {
+	async initializeDatabase(queries, reporter, options) {
 		this.db = await DuckDBInstance.create(":memory:");
 		this.connection = await this.db.connect();
+		for (const attachment of options?.attachments ?? []) {
+			const sql = `ATTACH '${attachment.connectionUri}' AS ${attachment.alias} (TYPE postgres)`;
+			try {
+				await this.connection.run(sql);
+			} catch (e) {
+				throw new DatabaseError(`Failed to attach source '${attachment.alias}': ${e.message}`, "duckdb", "Check that the postgres source container started and is reachable.");
+			}
+		}
 		await initializeDatabase(queries, async (query) => {
 			try {
 				await this.connection.run(query.rawQuery);

package/dist/sqg.mjs

@@ -221,6 +221,7 @@ SQL Annotation Syntax:
   -- QUERY <name> [:one] [:pluck]   Select query (returns rows)
   -- EXEC <name> [:batch]           Execute statement (INSERT/UPDATE/DELETE)
   -- BASELINE <name>                Schema created outside SQG (runs before migrations, not tracked)
+  -- BASELINE <name> :source=<src>  Schema of a 'type: postgres' source (applied to a managed testcontainer, attached into DuckDB)
   -- MIGRATE <name>                 Schema migration (runs in source order; name is any identifier, e.g. "1" or "add_email")
   -- TESTDATA <name>                Test data setup (not generated)
   -- TABLE <name> :appender         Table for bulk insert appender (DuckDB, PostgreSQL)
@@ -234,6 +235,7 @@ Modifiers:
   :all          Return all rows (default)
   :batch        Generate a JDBC batch method for an EXEC (Java only)
   :appender     Generate bulk insert appender for TABLE annotation
+  :source=Name  Mark a BASELINE block as the schema of a postgres source (Name)
   :result=Name  Name (and share) the row type (Java only). Annotate ONE query
                 with :result=Name — every other query in the same file with the
                 same column shape automatically gets the same name; you do NOT
@@ -783,6 +785,13 @@ var SQLQuery = class {
 	parameterTypes;
 	/** Explicit row-type name from `:result=Name` modifier, when present. */
 	resultTypeOverride;
+	/**
+	* Name of the postgres `source` this block targets, from a `:source=name`
+	* modifier on a BASELINE block. Such blocks define the schema of an external
+	* postgres source and run natively against that source's container during
+	* generation (not against the DuckDB introspection connection).
+	*/
+	sourceTarget;
 	/** Final row-type identifier assigned by assignResultTypeNames (after introspection). */
 	resultTypeName;
 	constructor(filename, id, rawQuery, queryAnonymous, queryNamed, queryPositional, type, isOne, isPluck, isBatch, variables, config, line) {
@@ -899,6 +908,8 @@ function parseSQLQueries(filePath, extraVariables) {
 			const isPluck = modifiers.includes(":pluck");
 			const isBatch = modifiers.includes(":batch");
 			const resultTypeOverride = modifiers.find((m) => m.startsWith(":result="))?.slice(8);
+			const sourceTarget = modifiers.find((m) => m.startsWith(":source="))?.slice(8);
+			if (sourceTarget && queryType !== "BASELINE") throw SqgError.inQuery(`The ':source=' modifier is only valid on BASELINE blocks, not ${queryType}`, "SQL_PARSE_ERROR", name, filePath, { suggestion: "Move the schema for a postgres source into a '-- BASELINE <name> :source=<source>' block" });
 			let configStr = getStr("Config", true);
 			if (configStr?.endsWith("*/")) configStr = configStr.slice(0, -2);
 			let config = null;
@@ -1054,6 +1065,7 @@ function parseSQLQueries(filePath, extraVariables) {
 			});
 			const query = new SQLQuery(filePath, name, sqlContentStr, sql.toSqlWithAnonymousPlaceholders(), sql.toSqlWithNamedPlaceholders(), sql.toSqlWithPositionalPlaceholders(), queryType, isOne, isPluck, isBatch, variables, config, annotationLine);
 			query.resultTypeOverride = resultTypeOverride;
+			query.sourceTarget = sourceTarget;
 			checkDuplicate(queryType, name);
 			queries.push(query);
 			consola.debug(`Added query: ${name} (${queryType})`);
@@ -1070,7 +1082,7 @@ function parseSQLQueries(filePath, extraVariables) {
 //#endregion
 //#region src/db/types.ts
 async function initializeDatabase(queries, execQueries, reporter) {
-	const baselineQueries = queries.filter((q) => q.isBaseline);
+	const baselineQueries = queries.filter((q) => q.isBaseline && !q.sourceTarget);
 	for (const query of baselineQueries) try {
 		await execQueries(query);
 	} catch (error) {
@@ -1126,9 +1138,17 @@ function convertType(type) {
 const duckdb = new class {
 	db;
 	connection;
-	async initializeDatabase(queries, reporter) {
+	async initializeDatabase(queries, reporter, options) {
 		this.db = await DuckDBInstance.create(":memory:");
 		this.connection = await this.db.connect();
+		for (const attachment of options?.attachments ?? []) {
+			const sql = `ATTACH '${attachment.connectionUri}' AS ${attachment.alias} (TYPE postgres)`;
+			try {
+				await this.connection.run(sql);
+			} catch (e) {
+				throw new DatabaseError(`Failed to attach source '${attachment.alias}': ${e.message}`, "duckdb", "Check that the postgres source container started and is reachable.");
+			}
+		}
 		await initializeDatabase(queries, async (query) => {
 			try {
 				await this.connection.run(query.rawQuery);
@@ -2726,6 +2746,19 @@ var PythonGenerator = class extends BaseGenerator {
 			if (value.includes("\n") || value.includes("'") || value.includes("\"")) return `"""\\\n${value}"""`;
 			return `"${value}"`;
 		});
+		Handlebars.registerHelper("sqlExpr", (queryHelper) => {
+			const parts = queryHelper.sqlQueryParts;
+			if (!parts.some((p) => typeof p !== "string" && p.name.startsWith("sources_"))) {
+				const value = queryHelper.sqlQuery;
+				if (value.includes("\n") || value.includes("'") || value.includes("\"")) return `"""\\\n${value}"""`;
+				return `"${value}"`;
+			}
+			let out = "f\"\"\"";
+			for (const part of parts) if (typeof part === "string") out += part.replace(/\\/g, "\\\\").replace(/\{/g, "{{").replace(/\}/g, "}}");
+			else if (part.name.startsWith("sources_")) out += ` '{${part.name}}'`;
+			else out += "?";
+			return `${out}"""`;
+		});
 		Handlebars.registerHelper("pyType", (column) => {
 			return this.getPyType(column);
 		});
@@ -2850,6 +2883,7 @@ var TsGenerator = class extends BaseGenerator {
 	async beforeGenerate(_projectDir, gen, _queries, _tables) {
 		if (this.typeMapper instanceof TypeScriptTypeMapper) this.typeMapper.safeIntegers = !!gen.config?.safeIntegers;
 		Handlebars.registerHelper("quote", (value) => this.quote(value));
+		Handlebars.registerHelper("sqlExpr", (queryHelper) => this.sqlExpr(queryHelper));
 		Handlebars.registerHelper("appendMethod", (column) => {
 			if (column.type instanceof ListType) return "List";
 			const typeStr = column.type?.toString().toUpperCase() || "";
@@ -3002,6 +3036,22 @@ var TsGenerator = class extends BaseGenerator {
 	quote(value) {
 		return value.includes("\n") || value.includes("'") ? `\`${value}\`` : `'${value}'`;
 	}
+	/**
+	* Build the SQL expression for a query. Without file `sources`, this is the
+	* plain quoted SQL string (unchanged). When a `${sources_x}` reference is
+	* present it is interpolated into a template literal as a runtime argument
+	* (the value is supplied by the caller, not bound), mirroring the Java
+	* generator — `ATTACH '` + arg + `'` style.
+	*/
+	sqlExpr(queryHelper) {
+		const parts = queryHelper.sqlQueryParts;
+		if (!parts.some((p) => typeof p !== "string" && p.name.startsWith("sources_"))) return this.quote(queryHelper.sqlQuery);
+		let out = "`";
+		for (const part of parts) if (typeof part === "string") out += part.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+		else if (part.name.startsWith("sources_")) out += ` '\${${part.name}}'`;
+		else out += "?";
+		return `${out}\``;
+	}
 };
 //#endregion
 //#region src/generators/typescript-duckdb-generator.ts
@@ -3108,6 +3158,57 @@ function getGenerator(generator) {
 	}
 }
 //#endregion
+//#region src/sources.ts
+/**
+* For each `type: postgres` source: start a throwaway Postgres testcontainer,
+* run the source's schema (the BASELINE blocks tagged `:source=<name>`) natively
+* against it so introspection sees true Postgres types, and return the connection
+* info to ATTACH into DuckDB.
+*
+* The synthesized ATTACH (done by the DuckDB adapter) and these schema blocks are
+* not emitted into generated code — at runtime the application attaches the real
+* production database under the same alias.
+*/
+async function preparePostgresSources(sources, queries, reporter) {
+	const containers = [];
+	const attachments = [];
+	const teardown = async () => {
+		for (const container of containers) try {
+			await container.stop();
+		} catch {}
+	};
+	try {
+		for (const source of sources) {
+			reporter?.onContainerStarting?.();
+			const container = await new PostgreSqlContainer(source.image).withDatabase("sqg-db").withUsername("sqg").withPassword("secret").start();
+			containers.push(container);
+			const connectionUri = container.getConnectionUri();
+			reporter?.onContainerStarted?.(connectionUri);
+			const schemaBlocks = queries.filter((q) => q.isBaseline && q.sourceTarget === source.name);
+			const client = new Client({ connectionString: connectionUri });
+			await client.connect();
+			try {
+				for (const block of schemaBlocks) await client.query(block.rawQuery);
+			} catch (e) {
+				throw new DatabaseError(`Failed to apply schema for postgres source '${source.name}': ${e.message}`, "postgres", `Check that the BASELINE blocks tagged ':source=${source.name}' are valid PostgreSQL.`);
+			} finally {
+				await client.end();
+			}
+			attachments.push({
+				alias: source.name,
+				connectionUri
+			});
+		}
+	} catch (e) {
+		await teardown();
+		throw e;
+	}
+	return {
+		attachments,
+		teardown
+	};
+}
+//#endregion
 //#region src/sqltool.ts
 const GENERATED_FILE_COMMENT = "This file is generated by SQG (https://sqg.dev). Do not edit manually.";
 const configSchema = z.object({ result: z.record(z.string(), z.string()).optional() });
@@ -3284,18 +3385,23 @@ var TableHelper = class {
 		return this.generator.typeMapper;
 	}
 };
-function generateSourceFile(name, queries, tables, templatePath, generator, engine, projectName, config) {
+function generateSourceFile(name, queries, tables, templatePath, generator, engine, projectName, config, postgresSourceNames = []) {
 	const templateSrc = readFileSync(templatePath, "utf-8");
 	const template = Handlebars.compile(templateSrc);
 	Handlebars.registerHelper("mapType", (column) => generator.mapType(column));
 	Handlebars.registerHelper("plusOne", (value) => value + 1);
 	const migrations = queries.filter((q) => q.isMigrate).map((q) => new SqlQueryHelper(q, generator, generator.getStatement(q)));
 	const tableHelpers = generator.supportsAppenders(engine) ? tables.filter((t) => !t.skipGenerateFunction).map((t) => new TableHelper(t, generator)) : [];
+	const attachers = engine === "duckdb" ? postgresSourceNames.map((sourceName) => ({
+		alias: sourceName,
+		functionName: generator.getFunctionName(`attach_${sourceName}`)
+	})) : [];
 	return template({
 		generatedComment: GENERATED_FILE_COMMENT,
 		migrations,
 		queries: queries.map((q) => new SqlQueryHelper(q, generator, generator.getStatement(q))),
 		tables: tableHelpers,
+		attachers,
 		className: generator.getClassName(name),
 		projectName,
 		config
@@ -3323,9 +3429,11 @@ const ProjectSchema = z.object({
 		})).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"),
 	sources: z.array(z.object({
-		path: z.string().describe("Path to source file (supports $HOME)"),
-		name: z.string().optional().describe("Variable name override")
-	})).optional().describe("External source files to include as variables")
+		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")
 });
 var ExtraVariable = class {
 	constructor(name, value) {
@@ -3334,7 +3442,7 @@ var ExtraVariable = class {
 	}
 };
 function createExtraVariables(sources, suppressLogging = false) {
-	return sources.map((source) => {
+	return sources.filter((source) => source.type !== "postgres").map((source) => {
 		const path = source.path;
 		const resolvedPath = path.replace("$HOME", homedir());
 		const varName = `sources_${(source.name ?? basename(path, extname(resolvedPath))).replace(/\s+/g, "_")}`;
@@ -3342,6 +3450,13 @@ function createExtraVariables(sources, suppressLogging = false) {
 		return new ExtraVariable(varName, `'${resolvedPath}'`);
 	});
 }
+/** 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"
+	}));
+}
 function buildProjectFromCliOptions(options) {
 	if (!isValidGenerator(options.generator)) {
 		const similar = findSimilarGenerators(options.generator);
@@ -3480,7 +3595,7 @@ function assignResultTypeNames(queries, tables, projectDir = process.cwd()) {
 		}
 		const fullMatch = tryFullTableMatch(group.queries[0], tablesByName);
 		if (fullMatch) {
-			claim(fullMatch, shape, group.queries[0], `full-table match`);
+			claim(fullMatch, shape, group.queries[0], "full-table match");
 			for (const q of group.queries) q.resultTypeName = fullMatch;
 			continue;
 		}
@@ -3533,14 +3648,14 @@ function validateQueries(queries) {
 		};
 	}
 }
-async function writeGeneratedFile(projectDir, gen, generator, file, queries, tables, engine, writeToStdout = false) {
+async function writeGeneratedFile(projectDir, gen, generator, file, queries, tables, engine, writeToStdout = false, postgresSourceNames = []) {
 	await generator.beforeGenerate(projectDir, gen, queries, tables);
 	const templatePath = join(dirname(new URL(import.meta.url).pathname), gen.template ?? generator.template);
 	const name = gen.name ?? basename(file, extname(file));
 	const sourceFile = generateSourceFile(name, queries, tables, templatePath, generator, engine, gen.projectName ?? name, {
 		migrations: true,
 		...gen.config
-	});
+	}, postgresSourceNames);
 	if (writeToStdout) {
 		process.stdout.write(sourceFile);
 		if (!sourceFile.endsWith("\n")) process.stdout.write("\n");
@@ -3641,6 +3756,11 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 	const results = [];
 	try {
 		const extraVariables = createExtraVariables(project.sources ?? [], writeToStdout);
+		const pgSources = getPostgresSources(project.sources ?? []);
+		const pgSourceNames = new Set(pgSources.map((s) => s.name));
+		if (pgSources.length > 0) {
+			if (!project.sql.some((sql) => sql.gen.some((gen) => getGeneratorEngine(gen.generator) === "duckdb"))) throw new SqgError("Postgres sources require a DuckDB generator (they are attached into DuckDB for introspection)", "CONFIG_VALIDATION_ERROR", "Add a 'typescript/duckdb' or 'java/duckdb' generator, or remove the postgres sources");
+		}
 		const files = [];
 		for (const sql of project.sql) {
 			const gensByEngine = /* @__PURE__ */ new Map();
@@ -3658,6 +3778,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					const parseResult = parseSQLQueries(fullPath, extraVariables);
 					queries = parseResult.queries;
 					tables = parseResult.tables;
+					for (const q of queries) if (q.sourceTarget && !pgSourceNames.has(q.sourceTarget)) throw SqgError.inQuery(`BASELINE block targets unknown postgres source '${q.sourceTarget}'`, "CONFIG_VALIDATION_ERROR", q.id, sqlFile, { suggestion: `Declare a source with 'type: postgres, name: ${q.sourceTarget}' in sqg.yaml` });
 				} catch (e) {
 					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" });
@@ -3666,10 +3787,17 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 					const executableQueries = queries.filter((q) => !q.skipGenerateFunction);
 					const reporterAny = reporter;
 					if (reporterAny?.setQueryTotal) reporterAny.setQueryTotal(executableQueries.length);
+					let preparedSources;
 					try {
 						const dbEngine = getDatabaseEngine(engine);
+						let attachments;
+						if (engine === "duckdb" && pgSources.length > 0) {
+							ui?.startPhase("Starting postgres source containers...");
+							preparedSources = await preparePostgresSources(pgSources, queries, reporter);
+							attachments = preparedSources.attachments;
+						}
 						ui?.startPhase(`Initializing ${engine} database...`);
-						await dbEngine.initializeDatabase(queries, reporter);
+						await dbEngine.initializeDatabase(queries, reporter, { attachments });
 						ui?.startPhase(`Introspecting ${executableQueries.length} queries...`);
 						await dbEngine.executeQueries(queries, reporter);
 						if (tables.length > 0) await dbEngine.introspectTables(tables, reporter);
@@ -3686,6 +3814,8 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 							file: sqlFile,
 							engine
 						});
+					} finally {
+						if (preparedSources) await preparedSources.teardown();
 					}
 					ui?.startPhase("Generating code...");
 					const genStart = performance.now();
@@ -3694,7 +3824,7 @@ async function processProjectFromConfig(project, projectDir, writeToStdout = fal
 						const outputPath = await writeGeneratedFile(projectDir, {
 							...gen,
 							projectName: project.name
-						}, generator, sqlFile, queries, tables, engine, writeToStdout);
+						}, generator, sqlFile, queries, tables, engine, writeToStdout, pgSources.map((s) => s.name));
 						if (outputPath !== null) {
 							files.push(outputPath);
 							results.push({
@@ -3728,7 +3858,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.20.0"
+	version: process.env.npm_package_version ?? "0.21.0"
 }, { capabilities: {
 	tools: {},
 	resources: {}
@@ -4199,7 +4329,7 @@ function formatMs(ms) {
 }
 //#endregion
 //#region src/sqg.ts
-const version = process.env.npm_package_version ?? "0.20.0";
+const version = process.env.npm_package_version ?? "0.21.0";
 updateNotifier({ pkg: {
 	name: "@sqg/sqg",
 	version

package/dist/templates/better-sqlite3.hbs

@@ -69,7 +69,7 @@ export class {{className}} {
     {{#unless skipGenerateFunction}}
     {{functionName}}({{#each variables}}{{name}}: {{type}}{{#unless @last}}, {{/unless}}{{/each}}): {{> returnType }} {
         const stmt = this.prepare<[{{> paramTypes}}], {{> resultType}}>('{{id}}', 
-            {{{quote sqlQuery}}}{{#if isPluck}}, true{{/if}});
+            {{{sqlExpr this}}}{{#if isPluck}}, true{{/if}});
         {{> execute}}
     }
     {{/unless}}

package/dist/templates/java-jdbc.hbs

@@ -223,6 +223,15 @@ public class {{className}} {
 
     {{{declareEnums queries}}}
 
+    {{#each attachers}}
+    /** Attach the "{{alias}}" postgres source under the same alias used during generation. */
+    public void {{functionName}}(String connectionString) throws SQLException {
+        try (var stmt = connection.createStatement()) {
+            stmt.execute("ATTACH '" + connectionString + "' AS {{alias}} (TYPE postgres)");
+        }
+    }
+
+    {{/each}}
     {{#each queries}}
     {{#unless skipGenerateFunction}}
     {{>columnTypesRecord}}

package/dist/templates/python.hbs

@@ -135,6 +135,12 @@ class {{className}}:
 {{/if}}
 {{/if}}
 
+{{#each attachers}}
+    def {{functionName}}(self, connection_string: str) -> None:
+        """Attach the "{{alias}}" postgres source under the same alias used during generation."""
+        self._conn.execute(f"ATTACH '{connection_string}' AS {{alias}} (TYPE postgres)")
+
+{{/each}}
 {{#each queries}}
 {{#unless skipGenerateFunction}}
 {{#if isQuery}}
@@ -142,7 +148,7 @@ class {{className}}:
 {{#if isOne}}
     def {{functionName}}(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> {{{pyTypeOrNone (lookup columns 0)}}}:
         row = self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchone()
         if row is None:
             return None
@@ -150,19 +156,19 @@ class {{className}}:
 
     def {{functionName}}_raw(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> tuple[Any, ...] | None:
         return self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchone()
 
 {{else}}
     def {{functionName}}(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> list[{{{pyType (lookup columns 0)}}}]:
         rows = self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchall()
         return [r[0] for r in rows]
 
     def {{functionName}}_raw(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> list[tuple[Any, ...]]:
         return self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchall()
 
 {{/if}}
@@ -170,7 +176,7 @@ class {{className}}:
 {{#if isOne}}
     def {{functionName}}(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> {{{rowType}}} | None:
         row = self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchone()
         if row is None:
             return None
@@ -178,19 +184,19 @@ class {{className}}:
 
     def {{functionName}}_raw(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> tuple[Any, ...] | None:
         return self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchone()
 
 {{else}}
     def {{functionName}}(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> list[{{{rowType}}}]:
         rows = self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchall()
         return [{{{constructRow this}}} for row in rows]
 
     def {{functionName}}_raw(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> list[tuple[Any, ...]]:
         return self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         ).fetchall()
 
 {{/if}}
@@ -198,7 +204,7 @@ class {{className}}:
 {{else}}
     def {{functionName}}(self{{#each variables}}, {{name}}: {{{type}}}{{/each}}) -> None:
         self._conn.execute(
-            {{{quote sqlQuery}}}, {{> params}}
+            {{{sqlExpr this}}}, {{> params}}
         )
 
 {{/if}}

package/dist/templates/typescript-duckdb.hbs

@@ -58,10 +58,17 @@ export class {{className}} {
         );
     }
 
+    {{#each attachers}}
+    /** Attach the "{{alias}}" postgres source under the same alias used during generation. */
+    async {{functionName}}(connectionString: string): Promise<void> {
+        await this.conn.run(`ATTACH '${connectionString}' AS {{alias}} (TYPE postgres)`);
+    }
+
+    {{/each}}
     {{#each queries}}
     {{#unless skipGenerateFunction}}
     async {{functionName}}({{#each variables}}{{name}}: {{type}}{{#unless @last}}, {{/unless}}{{/each}}): Promise<{{> returnType }}> {
-        const sql = {{{quote sqlQuery}}};
+        const sql = {{{sqlExpr this}}};
         {{#if (hasListParams this)}}
         const stmt = await this.conn.prepare(sql);
         {{{bindStatements this}}}

package/package.json

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