Skip to content

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.md
new file mode 100644
index 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.example
index 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.json
index 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.ts
index 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; defaul
throw 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 = standalone
raw: 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.ts
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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 1
FROM 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.ts
index 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();
}