Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(config): reject a mixed-case or padded POSTGRES_SCHEMA

Yudhi Armyndharis7db588c4e07f
diff --git a/.env.example b/.env.example
index dd409f25c..f5191b272 100644
--- a/.env.example
+++ b/.env.example
@@ -309,6 +309,7 @@ OPENWA_PIDS_LIMIT=2048
# Postgres where you get a project schema, or to share one DB across apps). The schema must
# already exist — the built-in container creates it; for external/managed Postgres create it
# once (CREATE SCHEMA openwa;). A missing schema fails fast at migration time.
+# Lower case only (letters, digits, underscores): boot rejects upper case.
# POSTGRES_SCHEMA=public
# DATABASE_USERNAME=openwa
# MUST set a strong, unique value before using Postgres — no default is shipped.
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index aba3202a2..d17f05632 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -90,9 +90,9 @@ The container can still be coming up when the `data` connection first dials it,
When using PostgreSQL, OpenWA can place its tables and migration ledger in a dedicated schema via the `POSTGRES_SCHEMA` environment variable:
-| Setting | Default | Description |
-| ----------------- | -------- | ---------------------------------------------------------------- |
-| `POSTGRES_SCHEMA` | `public` | PostgreSQL schema for OpenWA tables and TypeORM migration ledger |
+| Setting | Default | Description |
+| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `POSTGRES_SCHEMA` | `public` | PostgreSQL schema for OpenWA tables and TypeORM migration ledger (lower-case letters, digits and underscores) |
**Use Cases:**
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 5960130df..91565e858 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5444,7 +5444,7 @@ Merge-save infrastructure config to `data/.env.generated` (a `0600` secret file)
| `database.type` | `'sqlite' \| 'postgres'` | If `database` is present | enum | `sqlite` drops stale postgres keys; `postgres` writes connection keys |
| `database.builtIn` | boolean | No | — | When `true`+postgres, forces the bundled `postgres` container creds + pushes `postgres` Docker profile |
| `database.host` / `.port` / `.username` / `.database` | string | No | `port` is a string | External postgres connection (defaults `localhost`/`5432`/`postgres`/`openwa`) |
-| `database.schema` | string | No | — | Postgres schema, saved as `POSTGRES_SCHEMA`; an empty value writes `public` (also forced to `public` when switching to the built-in DB) |
+| `database.schema` | string | No | lower-case, no `pg_` prefix (else 400) | Postgres schema, saved as `POSTGRES_SCHEMA`; an empty value writes `public` (also forced to `public` when switching to the built-in DB) |
| `database.password` | string | No | secret | Empty/omitted keeps the existing stored secret |
| `database.poolSize` | number | No | — | Default 10 |
| `database.sslEnabled` | boolean | No | — | Default false |
diff --git a/scripts/postgres-init-schema.sh b/scripts/postgres-init-schema.sh
index c957bb828..c8779ec05 100755
--- a/scripts/postgres-init-schema.sh
+++ b/scripts/postgres-init-schema.sh
@@ -25,14 +25,15 @@ fi
# The value is interpolated into the CREATE SCHEMA / SET search_path statements below, so apply
# the same boot-time validation the app does (src/config/env.validation.ts): a plain, non-reserved
-# Postgres identifier or nothing. Fail fast here rather than let a typo reach the SQL.
-identifier_re='^[A-Za-z_][A-Za-z0-9_]{0,62}$'
+# Postgres identifier or nothing. Fail fast here rather than let a typo reach the SQL. Lower case
+# only: the app sets an unquoted search_path, which Postgres folds to lower case.
+identifier_re='^[a-z_][a-z0-9_]{0,62}$'
if ! [[ "$schema" =~ $identifier_re ]]; then
- echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must be a valid Postgres identifier (a letter or underscore, then letters/digits/underscores, max 63 chars; got '${schema}')." >&2
+ echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must be a valid lower-case Postgres identifier (a lower-case letter or underscore, then lower-case letters/digits/underscores, max 63 chars; got '${schema}')." >&2
exit 1
fi
case "$schema" in
- [pP][gG]_*)
+ pg_*)
echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must not use the reserved \"pg_\" prefix (got '${schema}')." >&2
exit 1
;;
diff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.ts
index 2570db83c..298fb5f5a 100644
--- a/src/config/env.validation.spec.ts
+++ b/src/config/env.validation.spec.ts
@@ -31,9 +31,16 @@ describe('validateEnv', () => {
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: '1bad' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'has space' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'a.b' })).toThrow(/POSTGRES_SCHEMA/);
- // reserved pg_ prefix rejected (case-insensitive)
+ // upper case rejected: the unquoted search_path folds it, TypeORM's quoted schema does not
+ expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'OpenWA' })).toThrow(/lower-case/);
+ // reserved pg_ prefix rejected
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'pg_catalog' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'Pg_temp' })).toThrow(/POSTGRES_SCHEMA/);
+ // surrounding whitespace rejected, not trimmed: the app and the migration CLI use the raw value
+ expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: ' openwa' })).toThrow(/POSTGRES_SCHEMA/);
+ expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'openwa ' })).toThrow(/POSTGRES_SCHEMA/);
+ expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: ' ' })).toThrow(/POSTGRES_SCHEMA/);
+ expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: '' })).not.toThrow();
// ignored for sqlite: a bogus value must NOT trip when not on postgres
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', POSTGRES_SCHEMA: '1bad' })).not.toThrow();
});
diff --git a/src/config/env.validation.ts b/src/config/env.validation.ts
index c2a2705b2..3c4758300 100644
--- a/src/config/env.validation.ts
+++ b/src/config/env.validation.ts
@@ -41,6 +41,20 @@ export function sqliteDataMainPathCollision(config: EnvConfig): string | null {
return null;
}
+/**
+ * POSTGRES_SCHEMA rule shared by boot validation and the Infrastructure save path: a legal,
+ * non-reserved, lower-case Postgres identifier. Returns the error message, or null when valid.
+ */
+export function postgresSchemaError(schema: string): string | null {
+ if (!/^[a-z_][a-z0-9_]{0,62}$/.test(schema)) {
+ return `POSTGRES_SCHEMA must be a valid lower-case Postgres identifier (a lower-case letter or underscore, then lower-case letters/digits/underscores, max 63 chars; got ${JSON.stringify(schema)})`;
+ }
+ if (schema.startsWith('pg_')) {
+ return `POSTGRES_SCHEMA must not use the reserved "pg_" prefix (got ${JSON.stringify(schema)})`;
+ }
+ return null;
+}
+
/**
* Fail-fast environment validation. Wired as ConfigModule's `validate`
* callback so a misconfigured deployment is rejected at BOOT instead of silently
@@ -115,15 +129,14 @@ export function validateEnv(config: EnvConfig): EnvConfig {
// POSTGRES_SCHEMA is optional (defaults to 'public' in configuration.ts). When set, validate it
// is a legal, non-reserved Postgres identifier so a typo / injection-ish value fails fast at boot
// rather than reaching CREATE TABLE "<schema>"."..." (or a search_path SET) at migration time.
- const pgSchema = str('POSTGRES_SCHEMA');
- if (pgSchema !== undefined) {
- if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(pgSchema)) {
- errors.push(
- `POSTGRES_SCHEMA must be a valid Postgres identifier (a letter or underscore, then letters/digits/underscores, max 63 chars; got ${JSON.stringify(pgSchema)})`,
- );
- } else if (pgSchema.toLowerCase().startsWith('pg_')) {
- errors.push(`POSTGRES_SCHEMA must not use the reserved "pg_" prefix (got ${JSON.stringify(pgSchema)})`);
- }
+ // Lower case only: the search_path startup option is unquoted, so Postgres folds it to lower
+ // case, while TypeORM quotes the schema. A mixed-case name would split DDL and queries across
+ // two schemas. The raw value is checked, untrimmed: the app and the migration CLI both use it
+ // as set, so a padded (or whitespace-only) value must fail here as it fails in the CLI.
+ const pgSchema = config.POSTGRES_SCHEMA;
+ const pgSchemaError = typeof pgSchema === 'string' && pgSchema !== '' ? postgresSchemaError(pgSchema) : null;
+ if (pgSchemaError) {
+ errors.push(pgSchemaError);
}
} else {
// SQLite (explicit or default): DATABASE_NAME is a file path for the 'data' connection. It must
diff --git a/src/database/data-source.spec.ts b/src/database/data-source.spec.ts
index 6f579a8f7..dbebfc049 100644
--- a/src/database/data-source.spec.ts
+++ b/src/database/data-source.spec.ts
@@ -55,6 +55,28 @@ describe('data CLI DataSource', () => {
jest.resetModules();
}
});
+
+ it('refuses to load a postgres CLI connection with a mixed-case POSTGRES_SCHEMA', () => {
+ // search_path is unquoted (folded to lower case) while TypeORM quotes the schema, so migration DDL
+ // and the ledger would land in two different schemas.
+ const prevType = process.env.DATABASE_TYPE;
+ const prevSchema = process.env.POSTGRES_SCHEMA;
+ process.env.DATABASE_TYPE = 'postgres';
+ process.env.POSTGRES_SCHEMA = 'OpenWA';
+ jest.resetModules();
+ try {
+ expect(() => {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ require('./data-source');
+ }).toThrow(/POSTGRES_SCHEMA/);
+ } finally {
+ if (prevType !== undefined) process.env.DATABASE_TYPE = prevType;
+ else delete process.env.DATABASE_TYPE;
+ if (prevSchema !== undefined) process.env.POSTGRES_SCHEMA = prevSchema;
+ else delete process.env.POSTGRES_SCHEMA;
+ jest.resetModules();
+ }
+ });
});
// The migration CLI connection runs DDL (CREATE INDEX, unique backfills) that can legitimately take
diff --git a/src/database/data-source.ts b/src/database/data-source.ts
index 5b6070814..3bd173b22 100644
--- a/src/database/data-source.ts
+++ b/src/database/data-source.ts
@@ -2,7 +2,7 @@ import { DataSource, DataSourceOptions } from 'typeorm';
import * as path from 'path';
import { loadCliEnv } from './load-cli-env';
import { postgresUtcExtra } from './postgres-utc';
-import { sqliteDataMainPathCollision } from '../config/env.validation';
+import { postgresSchemaError, sqliteDataMainPathCollision } from '../config/env.validation';
// Load env with the same precedence as the app (process.env > .env > data/.env.generated), so the
// migration CLI targets the SAME database the dashboard configured — not the default SQLite DB.
@@ -20,6 +20,15 @@ if (sqlitePathCollision) {
const dbType = process.env.DATABASE_TYPE || 'sqlite';
+// Same POSTGRES_SCHEMA rule as boot: a mixed-case name is quoted by TypeORM (ledger) but folded to
+// lower case in the unquoted search_path (raw migration DDL), splitting one migration run across two
+// schemas.
+const pgSchemaError =
+ dbType === 'postgres' && process.env.POSTGRES_SCHEMA ? postgresSchemaError(process.env.POSTGRES_SCHEMA) : null;
+if (pgSchemaError) {
+ throw new Error(pgSchemaError);
+}
+
const sourceGlob = (...segments: string[]): string => path.join(__dirname, ...segments).replace(/\\/g, '/');
// Scoped to the DATA-owned modules only (session/webhook/message/template/engine/integration/status-store), mirroring
diff --git a/src/modules/infra/config-sections.ts b/src/modules/infra/config-sections.ts
index 6e7005067..3f7b9559f 100644
--- a/src/modules/infra/config-sections.ts
+++ b/src/modules/infra/config-sections.ts
@@ -1,4 +1,5 @@
import { BadRequestException } from '@nestjs/common';
+import { postgresSchemaError } from '../../config/env.validation';
import type { EngineFactory } from '../../engine/engine.factory';
import { DatabaseConfigDto, EngineConfigDto, RedisConfigDto, StorageConfigDto } from './dto/save-config.dto';
@@ -66,7 +67,12 @@ export function applyDatabaseSection(
if (database.username !== undefined) updates.DATABASE_USERNAME = database.username || 'postgres';
setSecret(updates, 'DATABASE_PASSWORD', database.password);
if (database.database !== undefined) updates.DATABASE_NAME = database.database || 'openwa';
- if (database.schema !== undefined) updates.POSTGRES_SCHEMA = database.schema || 'public';
+ if (database.schema !== undefined) {
+ // Refuse a schema the next boot would reject, or the saved file crash-loops the instance.
+ const schemaError = database.schema ? postgresSchemaError(database.schema) : null;
+ if (schemaError) throw new BadRequestException(schemaError);
+ updates.POSTGRES_SCHEMA = database.schema || 'public';
+ }
}
if (database.poolSize !== undefined) {
updates.DATABASE_POOL_SIZE = String(database.poolSize || 10);
diff --git a/src/modules/infra/infra-config.controller.spec.ts b/src/modules/infra/infra-config.controller.spec.ts
index 339e16b93..9744de16d 100644
--- a/src/modules/infra/infra-config.controller.spec.ts
+++ b/src/modules/infra/infra-config.controller.spec.ts
@@ -92,6 +92,25 @@ describe('InfraConfigController PostgreSQL schema (POSTGRES_SCHEMA)', () => {
expect(preserved).toContain('POSTGRES_SCHEMA=openwa');
});
+ it('refuses a schema the next boot would reject instead of writing it', () => {
+ (fs.writeFileSync as jest.Mock).mockClear();
+ for (const schema of ['OpenWA', 'pg_data', 'bad-name']) {
+ expect(() =>
+ newController().saveConfig({
+ database: { type: 'postgres', builtIn: false, host: 'db', schema, password: 'unit-test-pw' },
+ } as never),
+ ).toThrow(BadRequestException);
+ }
+ expect(fs.writeFileSync).not.toHaveBeenCalled();
+ });
+
+ it('still writes the public default for an empty schema', () => {
+ const env = written({
+ database: { type: 'postgres', builtIn: false, host: 'db', schema: '', password: 'unit-test-pw' },
+ });
+ expect(env).toContain('POSTGRES_SCHEMA=public');
+ });
+
it('pins POSTGRES_SCHEMA=public for the built-in Postgres container', () => {
const env = written({ database: { type: 'postgres', builtIn: true } });
expect(env).toContain('POSTGRES_SCHEMA=public');