Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(db): refuse to boot on a main database from another release
Yudhi Armyndharis686aaf339068
diff --git a/.env.example b/.env.exampleindex 88063f42d..230ee0067 100644--- a/.env.example+++ b/.env.example@@ -333,8 +333,11 @@ DATABASE_SYNCHRONIZE=false # WARNING: Set false in production! (data DB# MAIN_DATABASE_NAME=./data/main.sqlite# Auth/audit (main) DB schema management. By default the bundled main-owned migrations create# and upgrade api_keys/audit_logs at boot (an existing synchronize-built file is adopted in place).-# "true" switches to TypeORM synchronize instead: for development only, and warned about under+# Boot stops on a file a newer release migrated, or one an older release rebuilt after its ledger+# recorded the lost column; a file without that ledger row is not detected (see docs/05 section 5.6).+# "true" also runs TypeORM synchronize after them: for development only, and warned about under# NODE_ENV=production.+# A new api_keys/audit_logs column still needs a migrations-main migration; synchronize does not add it.# MAIN_DATABASE_SYNCHRONIZE=false# DATABASE_SSL=false # Set true for managed Postgres (Supabase, Heroku, Render, Railway)# DATABASE_SSL_REJECT_UNAUTHORIZED=true # Set false to allow self-signed certs (only when DATABASE_SSL=true)diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex aa3dae35c..3aced1639 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -818,7 +818,7 @@ OpenWA runs **two separate TypeORM connections**, each with its own migrations dMigrations are hand-authored and idempotent (`IF NOT EXISTS`) so they are safe to adopt on a database originally created by `synchronize`. The two connections differ in how schema is managed:- **data** — `synchronize` defaults **off**, so this connection is migration-managed by default. On PostgreSQL `migrationsRun` is hardcoded on, and `DATABASE_SYNCHRONIZE=true` is rejected outright at boot validation (it would drop the migration-created `body_ts` tsvector column that `/search` depends on). On SQLite there is no such rejection and `migrationsRun` is the inverse of `synchronize` — so an opted-in `DATABASE_SYNCHRONIZE=true` switches the data connection to entity-synchronized schema and turns its migrations **off**.-- **main**: migration-managed by default, like data: `migrations-main/` creates and upgrades `api_keys` / `audit_logs` at boot. The chain is idempotent, so a `main.sqlite` an earlier release built with synchronize is adopted in place on the first boot (rows kept, missing columns added, the ledger written). `MAIN_DATABASE_SYNCHRONIZE=true` opts into synchronize instead, for development; boot logs a warning when it is set under `NODE_ENV=production`. `migrationsRun` on this connection is the inverse of `synchronize`.+- **main**: migration-managed by default, like data: `migrations-main/` creates and upgrades `api_keys` / `audit_logs` at boot. The chain is idempotent, so a `main.sqlite` an earlier release built with synchronize is adopted in place on the first boot (rows kept, missing columns added, the ledger written). `MAIN_DATABASE_SYNCHRONIZE=true` additionally synchronizes after the chain, for development; it cannot add an entity column that has no migration yet, because the missing-column check below refuses the boot first, so write the migration in `migrations-main/`. Boot logs a warning when it is set under `NODE_ENV=production`. Before any provider reads the file, boot refuses to start (in both modes) when the ledger records a migration this release does not ship (a newer release upgraded the file) or when an entity column is still missing after the chain ran (an older release rebuilt the table, so its values are gone, or the column has no migration yet); the error names the migration or column. For a newer ledger or a rebuilt table, the remedy is restoring `main.sqlite` from the backup taken before the downgrade or upgrade; for a column with no migration yet, it is adding one in `migrations-main/`. For a table rebuilt without `api_keys.allowedChats` and no backup, stop the instance, delete that migration's ledger row from the file the error names (the `MAIN_DATABASE_NAME` path, `data/main.sqlite` by default) and start it. On a source install that is `sqlite3 data/main.sqlite "DELETE FROM migrations WHERE name = 'AddApiKeyAllowedChats1786600000000'"`. On the compose deployment the file lives in the `openwa-data` volume, not on the host, and a stopped container cannot be exec'd into, so run the CLI in a one-off container of the service: `docker compose stop openwa-api && docker compose run --rm --no-deps openwa-api sqlite3 /app/data/main.sqlite "DELETE FROM migrations WHERE name = 'AddApiKeyAllowedChats1786600000000'"` (with `MAIN_DATABASE_NAME` set, use that path under `/app`). Then the chain re-creates `api_keys.allowedChats` empty, which means every chat, so re-apply each key's `allowedChats` before exposing the API. A file whose ledger does not record the lost column's migration (0.23.6 and 0.23.7 wrote the ledger only with `MAIN_DATABASE_SYNCHRONIZE=false`) is not detected: the column comes back empty, which means every chat, so each key's `allowedChats` must be re-applied. Never delete or rename a `migrations-main/` file: its ledger row would read as a newer release's.### Migration Filesdiff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex 0e4370ac5..a330c10ba 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -726,12 +726,12 @@ Upgrades are cumulative: migrations apply in order from wherever the schema currstraight to the current release is supported. There is no required intermediate stop — but read everyintervening `CHANGELOG.md` entry, because behavior changes are not replayed by migrations.-Schema migrations run automatically at boot on the **data** connection only — always on PostgreSQL,-and on SQLite unless `DATABASE_SYNCHRONIZE=true` puts the data store in synchronize mode. The Main-(auth/audit) connection defaults to synchronize instead, and under that default runs no migrations at-boot. Setting `MAIN_DATABASE_SYNCHRONIZE=false` switches it to its own migration chain, which then-also runs at boot (`migrationsRun` is the inverse of `synchronize` on both connections); run that-chain by hand with `npm run migration:run:main`.+Schema migrations run automatically at boot on both connections. The **data** connection always runs+them on PostgreSQL, and on SQLite unless `DATABASE_SYNCHRONIZE=true` puts the data store in synchronize+mode. The Main (auth/audit) connection runs its own `migrations-main/` chain at every boot. The chain is+idempotent, so a `main.sqlite` that an earlier release built with synchronize is adopted in place (rows+kept, missing columns added, the ledger written). `MAIN_DATABASE_SYNCHRONIZE=true` only adds a+synchronize pass after the chain. Run the main chain by hand with `npm run migration:run:main`.### Upgrade Stepsdiff --git a/src/app.module.ts b/src/app.module.tsindex f625c6251..8086b4c97 100644--- a/src/app.module.ts+++ b/src/app.module.ts@@ -10,7 +10,7 @@ import { createThrottlerRedisClient } from './common/throttler/throttler-redis.cimport configuration from './config/configuration';import { validateEnv } from './config/env.validation';import { createBootDataSource } from './database/pg-boot-migrations';-import { mainConnectionOptions } from './database/main-connection';+import { createMainDataSource, mainConnectionOptions } from './database/main-connection';import { SessionModule } from './modules/session/session.module';import { MessageModule } from './modules/message/message.module';import { TemplateModule } from './modules/template/template.module';@@ -130,8 +130,10 @@ if (dashboardServingEnabled && dashboardBuildPresent) {name: 'main',imports: [ConfigModule],inject: [ConfigService],- // Migrations by default, synchronize only on MAIN_DATABASE_SYNCHRONIZE=true (see the helper).+ // Migrations always, then synchronize on MAIN_DATABASE_SYNCHRONIZE=true; the factory refuses a+ // file whose schema does not match this release (see main-connection.ts).useFactory: (configService: ConfigService) => mainConnectionOptions(configService),+ dataSourceFactory: createMainDataSource,}),// Data Storage Database (pluggable - user data)diff --git a/src/config/bootstrap-security.ts b/src/config/bootstrap-security.tsindex 582c3f98b..e3827b935 100644--- a/src/config/bootstrap-security.ts+++ b/src/config/bootstrap-security.ts@@ -136,10 +136,9 @@ export function isApiKeyPepperMissingInProduction(nodeEnv?: string, apiKeyPepper}/**- * Whether to warn that the main (auth/audit) DB schema is managed by synchronize in production.- * Synchronize rebuilds api_keys/audit_logs from whatever release is running, so a rollback to an- * older image reshapes them (dropping columns it does not know) and the migration chain no longer- * applies. Advisory only: the explicit opt-in keeps working.+ * Whether to warn that the main (auth/audit) DB schema is also managed by synchronize in production.+ * After the migrations-main chain, synchronize alters api_keys/audit_logs to this release's entities+ * without recording those changes in the migration ledger. Advisory only: the explicit opt-in keeps working.*/export function isMainDbSynchronizeInProduction(nodeEnv?: string, mainDbSynchronize?: string): boolean {return nodeEnv === 'production' && mainDbSynchronize === 'true';diff --git a/src/config/configuration.ts b/src/config/configuration.tsindex 781dac810..8deee3205 100644--- a/src/config/configuration.ts+++ b/src/config/configuration.ts@@ -163,8 +163,8 @@ export default () => ({// Schema management for the auth/audit DB. By default the main-owned migrations run at boot// (they also adopt a file an earlier release built with synchronize); run them by hand with// `npm run migration:run:main` (or `migration:run:main:prod` for the compiled image), since the- // plain `migration:run` only manages the data connection. MAIN_DATABASE_SYNCHRONIZE=true opts- // into synchronize instead, which main.ts warns about in production.+ // plain `migration:run` only manages the data connection. MAIN_DATABASE_SYNCHRONIZE=true also+ // synchronizes after the chain, which main.ts warns about in production.synchronize: process.env.MAIN_DATABASE_SYNCHRONIZE === 'true',logging: process.env.DATABASE_LOGGING === 'true',},diff --git a/src/database/data-source-main.ts b/src/database/data-source-main.tsindex 03cb513df..2387346e5 100644--- a/src/database/data-source-main.ts+++ b/src/database/data-source-main.ts@@ -20,7 +20,7 @@ if (sqlitePathCollision) {* The app runs the main connection as a separate, ALWAYS-SQLite connection (app.module.ts), distinct* from the pluggable data connection. The default data-source.ts CLI only manages the data* connection's migrations, so without this the CLI could not run/generate the main-owned migrations- * (migrations-main), which also run at boot by default (MAIN_DATABASE_SYNCHRONIZE unset or false).+ * (migrations-main), which also run at every boot.** Mirrors the runtime main connection exactly: SQLite at ./data/main.sqlite, auth/audit entities,* migrations-main. synchronize is always false here — the CLI manages schema via migrations.diff --git a/src/database/main-connection.spec.ts b/src/database/main-connection.spec.tsnew file mode 100644index 000000000..02c32cf4a--- /dev/null+++ b/src/database/main-connection.spec.ts@@ -0,0 +1,339 @@+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'fs';+import { tmpdir } from 'os';+import { join } from 'path';+import type { ConfigService } from '@nestjs/config';+import { load } from 'js-yaml';+import { DataSource } from 'typeorm';+import { ApiKey } from '../modules/auth/entities/api-key.entity';+import { AuditLog } from '../modules/audit/entities/audit-log.entity';+import { CreateAuthAuditTables1779900000000 } from './migrations-main/1779900000000-CreateAuthAuditTables';+import { AddApiKeyAllowedChats1786600000000 } from './migrations-main/1786600000000-AddApiKeyAllowedChats';+import {+ createMainDataSource,+ MainSchemaMismatchError,+ mainConnectionOptions,+ retryMainConnection,+} from './main-connection';++/**+ * The main connection runs its migration chain by default. Existing installs have a main.sqlite+ * built by synchronize and no migrations ledger, so the first boot must adopt that file in place:+ * keep every row, add the columns an older release lacked, record the chain, and leave one index+ * per indexed column. A file whose schema does not match the release must stop the boot.+ */+describe('main connection', () => {+ let dir: string;+ let file: string;++ beforeEach(() => {+ dir = mkdtempSync(join(tmpdir(), 'openwa-main-'));+ file = join(dir, 'main.sqlite');+ });+ afterEach(() => rmSync(dir, { recursive: true, force: true }));++ const SHIPPED = readdirSync(join(__dirname, 'migrations-main'))+ .filter(name => name.endsWith('.ts'))+ .map(name => name.replace(/^(\d+)-(\w+)\.ts$/, '$2$1'))+ .sort();++ const config = (values: Record<string, unknown> = {}): ConfigService =>+ ({+ get: (key: string, fallback?: unknown) => (key in values ? values[key] : fallback),+ }) as unknown as ConfigService;++ /** Boot the file the way the app does (default configuration unless synchronize is asked for). */+ const boot = (synchronize = false): Promise<DataSource> =>+ createMainDataSource(+ mainConnectionOptions(+ config({ 'database.database': file, ...(synchronize && { 'database.synchronize': true }) }),+ ),+ );++ /** Open the file with no schema management at all, to arrange or inspect it. */+ const raw = (): Promise<DataSource> =>+ new DataSource({ type: 'better-sqlite3', database: file, entities: [ApiKey, AuditLog] }).initialize();++ const columns = async (ds: DataSource, table: string): Promise<string[]> =>+ (await ds.query<Array<{ name: string }>>(`PRAGMA table_info("${table}")`)).map(c => c.name);++ /** A main.sqlite as an earlier release left it: built by synchronize, with a scoped key and an audit row. */+ const seedSynchronizeBuilt = async (withAllowedChats: boolean): Promise<void> => {+ const ds = await new DataSource({+ type: 'better-sqlite3',+ database: file,+ entities: [ApiKey, AuditLog],+ synchronize: true,+ }).initialize();+ await ds.query(+ `INSERT INTO api_keys (id, name, keyHash, keyPrefix, allowedSessions, allowedChats) ` ++ `VALUES ('k1', 'scoped', 'h1', 'owa_k1', 's1', '[email protected]')`,+ );+ await ds.query(`INSERT INTO audit_logs (id, action) VALUES ('a1', 'api_key_created')`);+ if (!withAllowedChats) await ds.query(`ALTER TABLE api_keys DROP COLUMN allowedChats`);+ await ds.destroy();+ };++ const ledger = async (ds: DataSource): Promise<string[]> =>+ (await ds.query<Array<{ name: string }>>(`SELECT name FROM migrations`)).map(r => r.name).sort();++ /** Indexed columns per table, one entry per index: a duplicate index shows up as a repeated entry. */+ const indexedColumns = async (ds: DataSource, table: string): Promise<string[]> => {+ const indexes = await ds.query<Array<{ name: string; origin: string }>>(`PRAGMA index_list("${table}")`);+ const columns: string[] = [];+ for (const index of indexes.filter(i => i.origin === 'c')) {+ const info = await ds.query<Array<{ name: string }>>(`PRAGMA index_info("${index.name}")`);+ columns.push(info.map(c => c.name).join(','));+ }+ return columns.sort();+ };++ const expectOneIndexPerColumn = async (ds: DataSource): Promise<void> => {+ expect(await indexedColumns(ds, 'api_keys')).toEqual(['keyHash']);+ expect(await indexedColumns(ds, 'audit_logs')).toEqual(['action', 'apiKeyId', 'createdAt', 'sessionId']);+ };++ it('defaults to the migration chain on a fresh file', async () => {+ const ds = await boot();+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ await ds+ .getRepository(ApiKey)+ .save({ id: 'k1', name: 'n', keyHash: 'h', keyPrefix: 'p', allowedChats: ['[email protected]'] });+ expect((await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' })).allowedChats).toEqual(['[email protected]']);+ await expectOneIndexPerColumn(ds);+ } finally {+ await ds.destroy();+ }+ });++ it('adopts a synchronize-built file from the previous release without losing a row or a scope', async () => {+ await seedSynchronizeBuilt(true);++ const ds = await boot();+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ const key = await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' });+ expect(key.allowedSessions).toEqual(['s1']);+ expect(key.allowedChats).toEqual(['[email protected]']);+ expect(await ds.getRepository(AuditLog).count()).toBe(1);+ await expectOneIndexPerColumn(ds);+ } finally {+ await ds.destroy();+ }++ // A second boot has nothing left to run.+ const again = await boot();+ try {+ expect(await again.showMigrations()).toBe(false);+ } finally {+ await again.destroy();+ }+ });++ it('keeps an index on every column when an earlier release had synchronize replace the migrated ones', async () => {+ // An earlier release migrated the file, then a synchronize boot swapped the migration-named+ // indexes for generated ones while the ledger kept CreateAuthAuditTables recorded.+ const migrated = await new DataSource({+ type: 'better-sqlite3',+ database: file,+ entities: [ApiKey, AuditLog],+ migrations: [CreateAuthAuditTables1779900000000, AddApiKeyAllowedChats1786600000000],+ migrationsRun: true,+ }).initialize();+ await migrated.destroy();+ const synchronized = await new DataSource({+ type: 'better-sqlite3',+ database: file,+ entities: [ApiKey, AuditLog],+ synchronize: true,+ }).initialize();+ await synchronized.destroy();++ const ds = await boot();+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ await expectOneIndexPerColumn(ds);+ } finally {+ await ds.destroy();+ }+ });++ it('adds the chat-scope column to a file from a release that predates it', async () => {+ await seedSynchronizeBuilt(false);++ const ds = await boot();+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ const key = await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' });+ expect(key.allowedSessions).toEqual(['s1']);+ expect(key.allowedChats).toBeNull();+ await expectOneIndexPerColumn(ds);+ } finally {+ await ds.destroy();+ }+ });++ it('reads MAIN_DATABASE_SYNCHRONIZE=true as synchronize after the chain', async () => {+ expect(mainConnectionOptions(config()).synchronize).toBe(false);+ expect(mainConnectionOptions(config({ 'database.synchronize': true })).synchronize).toBe(true);++ const ds = await boot(true);+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ expect(await ds.driver.createSchemaBuilder().log()).toEqual(expect.objectContaining({ upQueries: [] }));+ } finally {+ await ds.destroy();+ }+ const again = await boot(true);+ try {+ expect((await again.driver.createSchemaBuilder().log()).upQueries).toEqual([]);+ } finally {+ await again.destroy();+ }+ });++ it('keeps the connection name Nest resolves the main DataSource by at shutdown', () => {+ expect(mainConnectionOptions(config()).name).toBe('main');+ });++ describe('schema mismatch', () => {+ /** A file this release migrated, then rebuilt by a release older than the chat-scope column. */+ const rebuiltByOlderRelease = async (): Promise<void> => {+ await (await boot()).destroy();+ const ds = await raw();+ await ds.query(+ `INSERT INTO api_keys (id, name, keyHash, keyPrefix, allowedChats) VALUES ('k1', 'n', 'h1', 'p', '[email protected]')`,+ );+ await ds.query(`ALTER TABLE api_keys DROP COLUMN allowedChats`);+ await ds.destroy();+ };++ it.each([false, true])(+ 'refuses a file that lost a recorded column instead of re-adding it empty (synchronize=%s)',+ async synchronize => {+ await rebuiltByOlderRelease();++ const failure = boot(synchronize);+ await expect(failure).rejects.toBeInstanceOf(MainSchemaMismatchError);+ await expect(failure).rejects.toThrow(/api_keys\.allowedChats/);+ // Names both causes: a rollback that dropped the values, and a new entity column no migration creates.+ await expect(failure).rejects.toThrow(/restore the file from the backup/);+ await expect(failure).rejects.toThrow(/no migrations-main migration creates yet/);+ // An operator without that backup is pointed at the documented way to re-create the column empty.+ await expect(failure).rejects.toThrow(/without a backup, docs\/05-database-design\.md section 5\.6/);++ const ds = await raw();+ try {+ expect(await columns(ds, 'api_keys')).not.toContain('allowedChats');+ } finally {+ await ds.destroy();+ }+ },+ );++ it.each([false, true])('refuses a file a newer release migrated (synchronize=%s)', async synchronize => {+ await (await boot()).destroy();+ let ds = await raw();+ await ds.query(`INSERT INTO migrations (timestamp, name) VALUES (1799999999999, 'Future1799999999999')`);+ await ds.query(`ALTER TABLE api_keys ADD COLUMN "futureColumn" varchar`);+ await ds.destroy();++ const failure = boot(synchronize);+ await expect(failure).rejects.toBeInstanceOf(MainSchemaMismatchError);+ await expect(failure).rejects.toThrow(/Future1799999999999/);++ ds = await raw();+ try {+ expect(await columns(ds, 'api_keys')).toContain('futureColumn');+ } finally {+ await ds.destroy();+ }+ });++ it.each([false, true])(+ 'upgrades a migrated file from before the chat-scope column (synchronize=%s)',+ async synchronize => {+ await (await boot()).destroy();+ let ds = await raw();+ await ds.query(`DELETE FROM migrations WHERE name <> 'CreateAuthAuditTables1779900000000'`);+ await ds.query(`ALTER TABLE api_keys DROP COLUMN allowedChats`);+ await ds.destroy();++ ds = await boot(synchronize);+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ expect(await columns(ds, 'api_keys')).toContain('allowedChats');+ } finally {+ await ds.destroy();+ }+ },+ );++ const forgetLostColumn = `DELETE FROM migrations WHERE name = 'AddApiKeyAllowedChats1786600000000'`;++ it('boots again once the lost column is removed from the ledger, re-creating it empty', async () => {+ await rebuiltByOlderRelease();+ let ds = await raw();+ await ds.query(forgetLostColumn);+ await ds.destroy();++ ds = await boot();+ try {+ expect(await ledger(ds)).toEqual(SHIPPED);+ expect((await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' })).allowedChats).toBeNull();+ } finally {+ await ds.destroy();+ }+ });++ it('documents that remedy for a source install and for the compose deployment', () => {+ const root = join(__dirname, '..', '..');+ const doc = readFileSync(join(root, 'docs', '05-database-design.md'), 'utf8');+ const remedy = doc.split('\n').find(line => line.includes(forgetLostColumn)) ?? '';+ // The refusal names the configured path, which the remedy must send the operator to.+ expect(remedy).toContain('MAIN_DATABASE_NAME');+ expect(remedy).toContain(`sqlite3 data/main.sqlite "${forgetLostColumn}"`);++ // On compose the file lives in a named volume, so a host path cannot reach it and the+ // stopped (or crash-looping) container cannot be exec'd into: a one-off run of the service can.+ const compose = load(readFileSync(join(root, 'docker-compose.yml'), 'utf8')) as {+ services: Record<string, { volumes?: string[] }>;+ };+ const [service, mount] = Object.entries(compose.services)+ .flatMap(([name, svc]) =>+ (svc.volumes ?? []).filter(v => v.startsWith('openwa-data:')).map(v => [name, v.split(':')[1]]),+ )+ .at(0) ?? ['', ''];+ expect(service).not.toBe('');+ expect(remedy).toContain(`docker compose stop ${service}`);+ expect(remedy).toContain(+ `docker compose run --rm --no-deps ${service} sqlite3 ${mount}/main.sqlite "${forgetLostColumn}"`,+ );+ });++ it('is described in the upgrade guide as running the main chain at every boot', () => {+ const guide = readFileSync(join(__dirname, '..', '..', 'docs', '14-migration-guide.md'), 'utf8').replace(+ /\s+/g,+ ' ',+ );+ expect(guide).toContain('The Main (auth/audit) connection runs its own `migrations-main/` chain at every boot.');+ expect(guide).not.toMatch(/Main \(auth\/audit\) connection defaults to synchronize/);+ });++ it('closes the connection it opened when it refuses', async () => {+ await rebuiltByOlderRelease();+ const destroy = jest.spyOn(DataSource.prototype, 'destroy');+ try {+ await expect(boot()).rejects.toBeInstanceOf(MainSchemaMismatchError);+ expect(destroy).toHaveBeenCalledTimes(1);+ } finally {+ destroy.mockRestore();+ }+ });++ it('fails the boot at once on a mismatch but retries anything else', () => {+ expect(retryMainConnection(new MainSchemaMismatchError('x'))).toBe(false);+ expect(retryMainConnection(new Error('SQLITE_BUSY'))).toBe(true);+ });+ });+});diff --git a/src/database/main-connection.ts b/src/database/main-connection.tsindex 46900bb5f..3955c2277 100644--- a/src/database/main-connection.ts+++ b/src/database/main-connection.ts@@ -1,6 +1,23 @@import { join } from 'path';import type { ConfigService } from '@nestjs/config';-import type { DataSourceOptions } from 'typeorm';+import { DataSource, MigrationExecutor, type DataSourceOptions } from 'typeorm';++/**+ * Raised when main.sqlite does not match this release: its migrations ledger records a migration this+ * release does not ship (a newer release has upgraded it), or a column the entities need is missing+ * after every shipped migration ran (an older release has rebuilt the table, or an entity column has no+ * migrations-main migration yet). Booting on+ * would either misread the newer schema or read the missing column as NULL, so boot stops instead.+ */+export class MainSchemaMismatchError extends Error {+ constructor(message: string) {+ super(message);+ this.name = 'MainSchemaMismatchError';+ }+}++/** Retrying cannot fix a schema mismatch, so it fails the boot at once instead of nine times. */+export const retryMainConnection = (err: unknown): boolean => !(err instanceof MainSchemaMismatchError);/*** TypeORM options for the main (auth/audit) connection, which is always a node-local SQLite file.@@ -8,11 +25,12 @@ import type { DataSourceOptions } from 'typeorm';* Schema management defaults to the main-owned migration chain (migrations-main), like the data* connection. The chain is idempotent, so a file an earlier release built with synchronize is* adopted in place on the first boot: existing tables are kept, missing columns are added, and the- * migrations ledger is written. MAIN_DATABASE_SYNCHRONIZE=true opts back into synchronize, which- * then runs instead of the migrations.+ * migrations ledger is written. MAIN_DATABASE_SYNCHRONIZE=true additionally synchronizes after the+ * chain. createMainDataSource runs both, with the schema checks, before any provider reads the file.*/-export function mainConnectionOptions(configService: ConfigService): DataSourceOptions & { name: string } {- const synchronize = configService.get<boolean>('database.synchronize', false);+export function mainConnectionOptions(+ configService: ConfigService,+): DataSourceOptions & { name: string; toRetry: (err: unknown) => boolean } {return {// Nest's TypeOrmCoreModule resolves the DataSource to close at shutdown from these options.name: 'main',@@ -25,8 +43,67 @@ export function mainConnectionOptions(configService: ConfigService): DataSourceO// Dedicated migrations dir for the main connection only (must NOT run the data-connection// migrations, which target session/webhook/message tables).migrations: [join(__dirname, 'migrations-main/*{.ts,.js}')],- synchronize,- migrationsRun: !synchronize,+ // Read by createMainDataSource, which owns the schema steps (initialize() never runs them).+ synchronize: configService.get<boolean>('database.synchronize', false),logging: configService.get<boolean>('database.logging', false),+ toRetry: retryMainConnection,};}++/**+ * dataSourceFactory for the main connection. Order: refuse a ledger from a newer release, run the+ * migration chain (in both modes, so every file carries a ledger), refuse a missing entity column,+ * then synchronize if MAIN_DATABASE_SYNCHRONIZE=true. The missing-column check is what stops a key+ * scope column an older release dropped from coming back as NULL; it runs before synchronize, so a+ * new entity column needs its migrations-main migration even in synchronize mode. A file that was+ * rolled back and upgraded again before any release with this check first booted it has no ledger+ * row for the lost column, and is not detected. Never delete or rename a migrations-main file: a ledger row this+ * release no longer ships reads as a newer release's.+ */+export async function createMainDataSource(options?: DataSourceOptions): Promise<DataSource> {+ // useFactory always resolves a full options object; the optional parameter is the library's typing.+ const opts = options as DataSourceOptions;+ const ds = new DataSource({ ...opts, synchronize: false, migrationsRun: false });+ await ds.initialize();+ try {+ const shipped = new Set(ds.migrations.map(m => m.name));+ const unknown = (await new MigrationExecutor(ds).getExecutedMigrations())+ .map(m => m.name)+ .filter(name => !shipped.has(name));+ if (unknown.length) {+ throw new MainSchemaMismatchError(+ `${String(opts.database)} records migration(s) this release does not ship (${unknown.join(', ')}): a ` ++ 'newer OpenWA release has upgraded it. Run that release, or restore the file from the backup taken ' ++ 'before the upgrade (docs/14-migration-guide.md, section 14.6).',+ );+ }++ await ds.runMigrations({ transaction: 'all' });++ const missing: string[] = [];+ for (const metadata of ds.entityMetadatas) {+ const rows = await ds.query<Array<{ name: string }>>(`PRAGMA table_info("${metadata.tableName}")`);+ const present = new Set(rows.map(r => r.name));+ for (const column of metadata.columns) {+ if (!present.has(column.databaseName)) missing.push(`${metadata.tableName}.${column.databaseName}`);+ }+ }+ if (missing.length) {+ throw new MainSchemaMismatchError(+ `${String(opts.database)} lacks ${missing.join(', ')} after every shipped migrations-main migration ` ++ 'ran. Either an older OpenWA release has rebuilt the table and the values it held are gone (restore ' ++ 'the file from the backup taken before the downgrade, docs/14-migration-guide.md, section 14.6; ' ++ 'without a backup, docs/05-database-design.md section 5.6 re-creates the column empty, and each ' ++ "key's chat scope must then be re-applied), or " ++ 'an entity declares a column that no migrations-main migration creates yet (add one: ' ++ 'MAIN_DATABASE_SYNCHRONIZE=true does not add columns the chain lacks).',+ );+ }++ if (opts.synchronize) await ds.synchronize();+ return ds;+ } catch (err) {+ await ds.destroy().catch(() => undefined);+ throw err;+ }+}diff --git a/src/database/migrations-main/1779900000000-CreateAuthAuditTables.ts b/src/database/migrations-main/1779900000000-CreateAuthAuditTables.tsindex 7ba30cf46..78ec57b0d 100644--- a/src/database/migrations-main/1779900000000-CreateAuthAuditTables.ts+++ b/src/database/migrations-main/1779900000000-CreateAuthAuditTables.ts@@ -6,9 +6,10 @@ import { MigrationInterface, QueryRunner } from 'typeorm';* `synchronize: true`, with no migrations — so turning synchronize off would leave a* fresh install with no `api_keys` table and total auth failure at boot.*- * The `main` connection runs this chain at boot by default (`migrationsRun: !synchronize`; only- * `MAIN_DATABASE_SYNCHRONIZE=true` opts out). The main DB is always SQLite (boot config). `IF NOT- * EXISTS` makes it idempotent, so it adopts a DB an earlier release created by synchronize.+ * The `main` connection runs this chain at every boot (createMainDataSource, main-connection.ts;+ * `MAIN_DATABASE_SYNCHRONIZE=true` only adds a synchronize after it). The main DB is always SQLite+ * (boot config). `IF NOT EXISTS` makes it idempotent, so it adopts a DB an earlier release created+ * by synchronize.*/export class CreateAuthAuditTables1779900000000 implements MigrationInterface {name = 'CreateAuthAuditTables1779900000000';diff --git a/src/database/migrations-main/__tests__/adopt-existing-main-db.spec.ts b/src/database/migrations-main/__tests__/adopt-existing-main-db.spec.tsdeleted file mode 100644index 87338bdb1..000000000--- a/src/database/migrations-main/__tests__/adopt-existing-main-db.spec.ts+++ /dev/null@@ -1,141 +0,0 @@-import { mkdtempSync, readdirSync, rmSync } from 'fs';-import { tmpdir } from 'os';-import { join } from 'path';-import type { ConfigService } from '@nestjs/config';-import { DataSource } from 'typeorm';-import { ApiKey } from '../../../modules/auth/entities/api-key.entity';-import { AuditLog } from '../../../modules/audit/entities/audit-log.entity';-import { mainConnectionOptions } from '../../main-connection';--/**- * The main connection runs its migration chain by default. Existing installs have a main.sqlite- * built by synchronize and no migrations ledger, so the first boot must adopt that file in place:- * keep every row, add the columns an older release lacked, record the chain, and leave one index- * per indexed column.- */-describe('main connection adopts an existing main.sqlite', () => {- let dir: string;- let file: string;-- beforeEach(() => {- dir = mkdtempSync(join(tmpdir(), 'openwa-main-'));- file = join(dir, 'main.sqlite');- });- afterEach(() => rmSync(dir, { recursive: true, force: true }));-- const SHIPPED = readdirSync(join(__dirname, '..'))- .filter(name => name.endsWith('.ts'))- .map(name => name.replace(/^(\d+)-(\w+)\.ts$/, '$2$1'))- .sort();-- const config = (values: Record<string, unknown> = {}): ConfigService =>- ({- get: (key: string, fallback?: unknown) => (key in values ? values[key] : fallback),- }) as unknown as ConfigService;-- /** Boot the file the way the app does (the current default configuration). */- const boot = async (): Promise<DataSource> => {- const ds = new DataSource(mainConnectionOptions(config({ 'database.database': file })));- return ds.initialize();- };-- /** A main.sqlite as an earlier release left it: built by synchronize, with a scoped key and an audit row. */- const seedSynchronizeBuilt = async (withAllowedChats: boolean): Promise<void> => {- const ds = await new DataSource({- type: 'better-sqlite3',- database: file,- entities: [ApiKey, AuditLog],- synchronize: true,- }).initialize();- await ds.query(- `INSERT INTO api_keys (id, name, keyHash, keyPrefix, allowedSessions, allowedChats) ` +- `VALUES ('k1', 'scoped', 'h1', 'owa_k1', 's1', '[email protected]')`,- );- await ds.query(`INSERT INTO audit_logs (id, action) VALUES ('a1', 'api_key_created')`);- if (!withAllowedChats) await ds.query(`ALTER TABLE api_keys DROP COLUMN allowedChats`);- await ds.destroy();- };-- const ledger = async (ds: DataSource): Promise<string[]> =>- (await ds.query<Array<{ name: string }>>(`SELECT name FROM migrations`)).map(r => r.name).sort();-- /** Indexed columns per table, one entry per index: a duplicate index shows up as a repeated entry. */- const indexedColumns = async (ds: DataSource, table: string): Promise<string[]> => {- const indexes = await ds.query<Array<{ name: string; origin: string }>>(`PRAGMA index_list("${table}")`);- const columns: string[] = [];- for (const index of indexes.filter(i => i.origin === 'c')) {- const info = await ds.query<Array<{ name: string }>>(`PRAGMA index_info("${index.name}")`);- columns.push(info.map(c => c.name).join(','));- }- return columns.sort();- };-- const expectOneIndexPerColumn = async (ds: DataSource): Promise<void> => {- expect(await indexedColumns(ds, 'api_keys')).toEqual(['keyHash']);- expect(await indexedColumns(ds, 'audit_logs')).toEqual(['action', 'apiKeyId', 'createdAt', 'sessionId']);- };-- it('defaults to the migration chain on a fresh file', async () => {- const ds = await boot();- try {- expect(ds.options.synchronize).toBe(false);- expect(await ledger(ds)).toEqual(SHIPPED);- await ds- .getRepository(ApiKey)- .save({ id: 'k1', name: 'n', keyHash: 'h', keyPrefix: 'p', allowedChats: ['[email protected]'] });- expect((await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' })).allowedChats).toEqual(['[email protected]']);- await expectOneIndexPerColumn(ds);- } finally {- await ds.destroy();- }- });-- it('adopts a synchronize-built file from the previous release without losing a row or a scope', async () => {- await seedSynchronizeBuilt(true);-- const ds = await boot();- try {- expect(await ledger(ds)).toEqual(SHIPPED);- const key = await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' });- expect(key.allowedSessions).toEqual(['s1']);- expect(key.allowedChats).toEqual(['[email protected]']);- expect(await ds.getRepository(AuditLog).count()).toBe(1);- await expectOneIndexPerColumn(ds);- } finally {- await ds.destroy();- }-- // A second boot has nothing left to run.- const again = await boot();- try {- expect(await again.showMigrations()).toBe(false);- } finally {- await again.destroy();- }- });-- it('adds the chat-scope column to a file from a release that predates it', async () => {- await seedSynchronizeBuilt(false);-- const ds = await boot();- try {- expect(await ledger(ds)).toEqual(SHIPPED);- const key = await ds.getRepository(ApiKey).findOneByOrFail({ id: 'k1' });- expect(key.allowedSessions).toEqual(['s1']);- expect(key.allowedChats).toBeNull();- await expectOneIndexPerColumn(ds);- } finally {- await ds.destroy();- }- });-- it('still synchronizes, without migrations, when MAIN_DATABASE_SYNCHRONIZE=true', () => {- const options = mainConnectionOptions(config({ 'database.synchronize': true }));- expect(options.synchronize).toBe(true);- expect(options.migrationsRun).toBe(false);- });-- it('keeps the connection name Nest resolves the main DataSource by at shutdown', () => {- expect(mainConnectionOptions(config()).name).toBe('main');- });-});diff --git a/src/main.ts b/src/main.tsindex d4e0fb8cd..671cd3cb3 100644--- a/src/main.ts+++ b/src/main.ts@@ -104,9 +104,9 @@ async function bootstrap() {// Advisory (not enforced): the main DB normally runs its migration chain; synchronize is an opt-in.if (isMainDbSynchronizeInProduction(process.env.NODE_ENV, process.env.MAIN_DATABASE_SYNCHRONIZE)) {bootstrapLogger.warn(- 'MAIN_DATABASE_SYNCHRONIZE=true in production: the auth/audit database schema is rebuilt from the ' +- "running release's entities instead of its migrations, so running an older release against it " +- 'reshapes api_keys and audit_logs. Unset it to use the main migrations.',+ 'MAIN_DATABASE_SYNCHRONIZE=true in production: after its migrations the auth/audit schema is also ' ++ "synchronized to this release's entities, and those changes are not recorded in the migration ledger. " ++ 'Unset it to use the main migrations alone.',);}