The open-source agent harness - the runtime layer that turns an LLM into a working agent.
feat: Make Postgres app schema configurable via POSTGRES_SCHEMA (#781)
Sujai Kumar Gupta1222563b9ddd
diff --git a/.changeset/pre/configurable-trueforge-schema.md b/.changeset/pre/configurable-trueforge-schema.mdnew file mode 100644index 000000000..6701d0a35--- /dev/null+++ b/.changeset/pre/configurable-trueforge-schema.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge": minor+---++Make the Postgres app schema configurable via `POSTGRES_SCHEMA` (default `trueforge`) for `search_path`, migrations, and schema bootstrap.diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.exampleindex f3d164ece..e3ccf1885 100644--- a/packages/trueforge/.env.example+++ b/packages/trueforge/.env.example@@ -162,7 +162,9 @@ POSTGRES_PORT=5432# POSTGRES_SSL_KEY_PATH=/path/to/client.key# POSTGRES_SSL_CA_PATH=/path/to/ca.crt-## When set, automatically move TrueForge tables from the public schema to the trueforge schema.+## Postgres schema for app tables + Kysely migration bookkeeping (default: trueforge).+# POSTGRES_SCHEMA=trueforge+## When set, automatically move TrueForge tables from the public schema to POSTGRES_SCHEMA.# AUTOMATICALLY_MOVE_TRUEFORGE_TABLES_FROM_PUBLIC_TO_TRUEFORGE_SCHEMA=true## ---------------------------------------------------------------------------diff --git a/packages/trueforge/package.json b/packages/trueforge/package.jsonindex 39acc0742..779ef25a5 100644--- a/packages/trueforge/package.json+++ b/packages/trueforge/package.json@@ -50,7 +50,7 @@"predev": "pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen","pretypecheck": "pnpm -w run sdk:types","test:eventsub": "jest --config jest.eventsub.config.cjs",- "test:store:postgres": "jest --config jest.store.postgres.config.cjs",+ "test:store:postgres": "cross-env STANDALONE=false TRUEFORGE_API_KEY=test-store-postgres jest --config jest.store.postgres.config.cjs","test:store:sqlite": "jest --config jest.store.sqlite.config.cjs","test": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs","test:local-sandbox:contract": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.local-sandbox.contract.config.cjs",diff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.tsindex cc9f1e8a7..c4b7fe5e5 100644--- a/packages/trueforge/src/config.ts+++ b/packages/trueforge/src/config.ts@@ -38,7 +38,11 @@ const DEFAULT_POSTGRES_PASSWORD = 'trueforge';const DEFAULT_POSTGRES_DB = 'trueforge';const DEFAULT_POSTGRES_HOST = 'localhost';const DEFAULT_POSTGRES_PORT = 5432;+/** Default Postgres schema for app tables + Kysely migration bookkeeping. */+export const DEFAULT_POSTGRES_SCHEMA = 'trueforge';const DEFAULT_REDIS_URL = 'redis://localhost:6379';+/** Unquoted Postgres identifier: letter/underscore start, then alnum/underscore, ≤63 chars. */+const POSTGRES_SCHEMA_NAME_RE = /^[a-z_][a-z0-9_]{0,62}$/;/*** Fixed local service credential when `STANDALONE=true` and `TRUEFORGE_API_KEY` is unset.* Local testing only — not for distributed deployments.@@ -183,6 +187,20 @@ function parseBoolean(options: { envKey: string; raw: string | undefined; defaulthrow new Error(`Environment variable ${envKey} must be "true" or "false", got "${raw}"`);}+function parsePostgresSchema(raw: string | undefined): string {+ if (raw === undefined || raw.trim() === '') {+ return DEFAULT_POSTGRES_SCHEMA;+ }+ const schema = raw.trim();+ if (!POSTGRES_SCHEMA_NAME_RE.test(schema)) {+ throw new Error(+ `Environment variable POSTGRES_SCHEMA must be a lowercase Postgres identifier ` ++ `(letter/underscore, then alnum/underscore, max 63 chars); got "${raw}"`,+ );+ }+ return schema;+}+/*** Empty stays empty. Otherwise parse as a URL, store without a trailing slash* (callers join with `/`), and reject query/hash or `.` / `..` path segments.@@ -664,6 +682,11 @@ export type DistributedServerConfiguration = SharedServerConfiguration & {* Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.*/POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;+ /**+ * Postgres schema for app tables and Kysely migration bookkeeping (`search_path`, Migrator).+ * Env: `POSTGRES_SCHEMA`. Default `trueforge`.+ */+ POSTGRES_SCHEMA: string;/** Peering URL shared by all replicas. Env: `REDIS_URL`. Default `redis://localhost:6379`. */REDIS_URL: string;/**@@ -677,7 +700,7 @@ export type DistributedServerConfiguration = SharedServerConfiguration & {* Env: `TRUEFOUNDRY_SERVICEFOUNDRY_SERVER_URL`.*//**- * When set, automatically move public TrueForge tables to the TrueForge schema.+ * When set, automatically move public TrueForge tables into `POSTGRES_SCHEMA` on first bootstrap.* Env: `AUTOMATICALLY_MOVE_TRUEFORGE_TABLES_FROM_PUBLIC_TO_TRUEFORGE_SCHEMA`. Default true.*/AUTOMATICALLY_MOVE_TRUEFORGE_TABLES_FROM_PUBLIC_TO_TRUEFORGE_SCHEMA: boolean;@@ -884,6 +907,7 @@ const configuration: ServerConfiguration = standaloneraw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),defaultValue: 60_000,}),+ POSTGRES_SCHEMA: parsePostgresSchema(getEnv('POSTGRES_SCHEMA')),REDIS_URL: resolveRedisUrl(),OIDC: resolveOIDCConfig(),AUTOMATICALLY_MOVE_TRUEFORGE_TABLES_FROM_PUBLIC_TO_TRUEFORGE_SCHEMA: parseBoolean({diff --git a/packages/trueforge/src/db/migratePostgres.ts b/packages/trueforge/src/db/migratePostgres.tsindex 3294fc8d0..a0d83d85b 100644--- a/packages/trueforge/src/db/migratePostgres.ts+++ b/packages/trueforge/src/db/migratePostgres.ts@@ -4,7 +4,7 @@ import path from 'node:path';import type { Kysely } from 'kysely';import { FileMigrationProvider, Migrator } from 'kysely/migration';import { importAbsoluteModule } from '../util/crossPlatform';-import { ensureTrueforgeSchema, TRUEFORGE_SCHEMA } from './postgres/schema';+import { ensureTrueforgeSchema, getTrueForgePostgresSchema } from './postgres/schema';import type { Database } from './postgres/types';function createMigrator(db: Kysely<Database>): Migrator {@@ -16,7 +16,7 @@ function createMigrator(db: Kysely<Database>): Migrator {import: importAbsoluteModule,migrationFolder: path.join(import.meta.dirname, 'postgres', 'migrations'),}),- migrationTableSchema: TRUEFORGE_SCHEMA,+ migrationTableSchema: getTrueForgePostgresSchema(),});}diff --git a/packages/trueforge/src/db/postgres/AGENTS.md b/packages/trueforge/src/db/postgres/AGENTS.mdindex 2999d0170..a4d8202e6 100644--- a/packages/trueforge/src/db/postgres/AGENTS.md+++ b/packages/trueforge/src/db/postgres/AGENTS.md@@ -2,4 +2,4 @@- Application timestamps MUST be treated as UTC instants. Serialize with `Date.prototype.toISOString()` (always `...Z` with milliseconds).- Do not run DB queries inside loops (N+1). Prefer a single batched query, a join, or an `IN`/`ANY` lookup over per-item round-trips.- Postgres migrations MUST start `up`/`down` with `SET LOCAL lock_timeout = '5s'` so waiting DDL fails fast instead of blocking later queries (including `SELECT`s) behind it in the lock queue.-- All app tables and Kysely migration bookkeeping live in the `trueforge` schema (not `public`). The init migration owns `CREATE SCHEMA` (the Migrator also creates it for `migrationTableSchema`); `createDb` sets `search_path=trueforge`.+- All app tables and Kysely migration bookkeeping live in the configured Postgres schema (`POSTGRES_SCHEMA`, default `trueforge` — not `public`). The init migration owns `CREATE SCHEMA` (the Migrator also creates it for `migrationTableSchema`); `createDb` sets `search_path` to that schema.diff --git a/packages/trueforge/src/db/postgres/client.ts b/packages/trueforge/src/db/postgres/client.tsindex e83e6f77b..7c9a07d93 100644--- a/packages/trueforge/src/db/postgres/client.ts+++ b/packages/trueforge/src/db/postgres/client.ts@@ -2,7 +2,7 @@ import { Kysely, PostgresDialect } from 'kysely';import pg, { Pool } from 'pg';import type { PostgresSslConfig } from '../../config';-import { TRUEFORGE_SCHEMA } from './schema';+import { getTrueForgePostgresSchema } from './schema';import type { Database } from './types';const INT8_OID = 20;@@ -46,6 +46,7 @@ export function createDb(options: {ssl?: boolean | PostgresSslConfig | undefined;}): Kysely<Database> {const { connectionString, poolMax, statementTimeoutMs, idleInTransactionSessionTimeoutMs, ssl } = options;+ const schema = getTrueForgePostgresSchema();configurePgTypeParsers();const pool = new Pool({connectionString,@@ -54,7 +55,7 @@ export function createDb(options: {connectionTimeoutMillis: 10_000,statement_timeout: statementTimeoutMs,idle_in_transaction_session_timeout: idleInTransactionSessionTimeoutMs,- options: `-c search_path=${TRUEFORGE_SCHEMA}`,+ options: `-c search_path=${schema}`,...(ssl !== undefined ? { ssl } : {}),});// Idle clients emit 'error' when the backend closes; without a listener Node exits.diff --git a/packages/trueforge/src/db/postgres/migrations/20260727_000001_init.ts b/packages/trueforge/src/db/postgres/migrations/20260727_000001_init.tsindex eb7bff33f..cccc97643 100644--- a/packages/trueforge/src/db/postgres/migrations/20260727_000001_init.ts+++ b/packages/trueforge/src/db/postgres/migrations/20260727_000001_init.ts@@ -1,10 +1,10 @@import { type Kysely, sql } from 'kysely';-import { TRUEFORGE_SCHEMA } from '../schema';+import { getTrueForgePostgresSchema } from '../schema';export async function up(db: Kysely<unknown>): Promise<void> {await sql`SET LOCAL lock_timeout = '5s'`.execute(db);- await sql`CREATE SCHEMA IF NOT EXISTS ${sql.id(TRUEFORGE_SCHEMA)}`.execute(db);+ await sql`CREATE SCHEMA IF NOT EXISTS ${sql.id(getTrueForgePostgresSchema())}`.execute(db);}// No-op: dropping the schema would take the Migrator's own bookkeeping table with it.diff --git a/packages/trueforge/src/db/postgres/schema.ts b/packages/trueforge/src/db/postgres/schema.tsindex 992fca6c0..d73381109 100644--- a/packages/trueforge/src/db/postgres/schema.ts+++ b/packages/trueforge/src/db/postgres/schema.ts@@ -3,7 +3,12 @@ import { type Kysely, sql } from 'kysely';import configuration from '../../config';import type { Database } from './types';-export const TRUEFORGE_SCHEMA = 'trueforge';+export function getTrueForgePostgresSchema(): string {+ if (configuration.STANDALONE) {+ throw new Error('unreachable');+ }+ return configuration.POSTGRES_SCHEMA;+}const TABLES_TO_MOVE = ['kysely_migration',@@ -26,29 +31,30 @@ const TABLES_TO_MOVE = [] as const;export async function ensureTrueforgeSchema(db: Kysely<Database>): Promise<void> {+ const schema = getTrueForgePostgresSchema();await db.transaction().execute(async txn => {await sql`SET LOCAL lock_timeout = '5s'`.execute(txn);- await sql`SELECT pg_advisory_xact_lock(hashtext('trueforge_schema_bootstrap'))`.execute(txn);+ await sql`SELECT pg_advisory_xact_lock(hashtext(${`trueforge_schema_bootstrap:${schema}`}))`.execute(txn);const result = await sql<{ exists: boolean }>`SELECT EXISTS (SELECT 1FROM pg_namespace- WHERE nspname = ${TRUEFORGE_SCHEMA}+ WHERE nspname = ${schema}) AS exists`.execute(txn);if (result.rows[0]?.exists === true) {return;}- await sql`CREATE SCHEMA IF NOT EXISTS ${sql.id(TRUEFORGE_SCHEMA)}`.execute(txn);+ await sql`CREATE SCHEMA IF NOT EXISTS ${sql.id(schema)}`.execute(txn);if (!configuration.STANDALONE &&configuration.AUTOMATICALLY_MOVE_TRUEFORGE_TABLES_FROM_PUBLIC_TO_TRUEFORGE_SCHEMA) {for (const tableName of TABLES_TO_MOVE) {await sql`- ALTER TABLE IF EXISTS ${sql.id('public', tableName)} SET SCHEMA ${sql.id(TRUEFORGE_SCHEMA)}+ ALTER TABLE IF EXISTS ${sql.id('public', tableName)} SET SCHEMA ${sql.id(schema)}`.execute(txn);}}diff --git a/packages/trueforge/tests/db/postgres/client.test.ts b/packages/trueforge/tests/db/postgres/client.test.tsindex 006418dc8..7b0b42253 100644--- a/packages/trueforge/tests/db/postgres/client.test.ts+++ b/packages/trueforge/tests/db/postgres/client.test.ts@@ -1,7 +1,7 @@import { sql } from 'kysely';+import { DEFAULT_POSTGRES_SCHEMA } from '../../../src/config';import { createDb } from '../../../src/db/postgres/client';-import { TRUEFORGE_SCHEMA } from '../../../src/db/postgres/schema';const describePg = process.env['PG_STORE_TESTS_ENABLED'] === '1' ? describe : describe.skip;@@ -31,7 +31,7 @@ describePg('createDb postgres session timeouts', () => {const byName = new Map(rows.map(row => [row.name, row.setting]));expect(byName.get('statement_timeout')).toBe(String(statementTimeoutMs));expect(byName.get('idle_in_transaction_session_timeout')).toBe(String(idleInTransactionSessionTimeoutMs));- expect(byName.get('search_path')).toBe(TRUEFORGE_SCHEMA);+ expect(byName.get('search_path')).toBe(DEFAULT_POSTGRES_SCHEMA);} finally {await db.destroy();}