feat(db): run TREK on PostgreSQL

TREK runs on PostgreSQL when TREK_DB_URL is set, and on SQLite as before
otherwise: an engine port under src/db/engine, the dialect helpers under
src/db/dialect, a Postgres baseline for the migrations up to the cut,
pg_dump/pg_restore backups, a probe of every repository method against a
real server and a Postgres test lane in CI.
This commit is contained in:
Isaias Tavares
2026-11-05 01:15:21 -03:00
committed by Maurice
parent 17b47b38b9
commit 2e3762afe1
176 changed files with 6728 additions and 777 deletions
+19 -4
View File
@@ -4,7 +4,8 @@
* The probe has no fixtures: it reads every repository class with the
* TypeScript checker and builds one sample argument list per public method
* from the declared parameter types (a number is 1, a string is "probe" or a
* date-shaped string when the name says so, an object gets every property
* date-shaped string when the name says so, a boolean false unless it is the
* `present` flag of a partial update's pair, an object gets every property
* it can sample, an array one element). The values only have to get the
* method to send its SQL; what the probe measures is whether Postgres
* accepts that SQL against an empty schema. A sample the column cannot take
@@ -24,6 +25,13 @@ export type MethodPlan =
| { className: string; file: string; method: string; unprobeable: string };
const MAX_DEPTH = 4;
/**
* The label of the flag in the repositories' `[present: boolean, value]`
* pairs (`presenceSet`): a patch whose pairs are all absent sends no SQL, so
* this one boolean is sampled true. Every other boolean stays false. The
* label is spelled in `presenceSet`'s signature, which a test pins.
*/
export const PRESENCE_LABEL = 'present';
const SAMPLE_DATE = '2026-01-01';
const SAMPLE_TIMESTAMP = '2026-01-01 00:00:00';
@@ -68,14 +76,14 @@ export function sampleFor(checker: ts.TypeChecker, type: ts.Type, name: string,
if (type.isUnion()) {
const members = type.types.filter((member) => !isNullish(member));
if (members.length === 0) return OK(null);
if (members.every((member) => member.flags & ts.TypeFlags.BooleanLiteral)) return OK(false);
if (members.every((member) => member.flags & ts.TypeFlags.BooleanLiteral)) return OK(name === PRESENCE_LABEL);
const numeric = members.find((member) => member.flags & ts.TypeFlags.NumberLike);
return sampleFor(checker, numeric ?? members[0]!, name, depth + 1);
}
if (type.isStringLiteral()) return OK(type.value);
if (type.isNumberLiteral()) return OK(type.value);
if (flags & ts.TypeFlags.BooleanLiteral) return OK(checker.typeToString(type) === 'true');
if (flags & ts.TypeFlags.BooleanLike) return OK(false);
if (flags & ts.TypeFlags.BooleanLike) return OK(name === PRESENCE_LABEL);
if (flags & ts.TypeFlags.BigIntLike) return OK(BigInt(1));
if (flags & ts.TypeFlags.NumberLike) return OK(1);
if (flags & (ts.TypeFlags.StringLike | ts.TypeFlags.TemplateLiteral)) return OK(sampleString(name));
@@ -88,8 +96,15 @@ export function sampleFor(checker: ts.TypeChecker, type: ts.Type, name: string,
function sampleObjectType(checker: ts.TypeChecker, type: ts.ObjectType, name: string, depth: number): Sample {
if (checker.isTupleType(type)) {
const values: unknown[] = [];
const labels = ((type as ts.TypeReference).target as ts.TupleType).labeledElementDeclarations;
for (const [i, element] of checker.getTypeArguments(type as ts.TypeReference).entries()) {
const sample = sampleFor(checker, element, `${name}[${i}]`, depth + 1);
const label = labels?.[i]?.name;
const sample = sampleFor(
checker,
element,
label && ts.isIdentifier(label) ? label.text : `${name}[${i}]`,
depth + 1,
);
if (!sample.ok) return sample;
values.push(sample.value);
}
+11 -7
View File
@@ -11,9 +11,9 @@
* `--update` lowers entries and drops the ones that reach zero or whose
* method is gone; it never raises or adds one.
*
* Only statements Postgres refuses as SQL count here (SQLSTATE classes 42
* and 0A, see `countsTowardRatchet`). A value the sample arguments got wrong
* (class 22, a sample string in a date column) says nothing about the
* Statements Postgres refuses as SQL or over a value's type count here
* (SQLSTATE classes 42, 0A and 22, see `countsTowardRatchet`). A constraint
* the sample values break (class 23) or a timeout says nothing about the
* dialect and is reported without being held.
*
* `uncovered` lists the methods whose SQL the probe did not see: the ones it
@@ -56,12 +56,16 @@ export interface BaselineVerdict {
/**
* Whether a refused statement counts toward the ratchet: SQLSTATE class 42
* (syntax error, unknown function, operator or column, datatype mismatch)
* and class 0A (feature not supported) are what a SQLite-only spelling gets.
* Anything else (a data exception such as 22P02 or 22007, a constraint, a
* timeout) comes from the sample values or the empty tables, not the SQL.
* and class 0A (feature not supported) are what a SQLite-only spelling gets,
* and class 22 (a data exception such as 22P02 or 22007) is a value of the
* wrong type reaching a column, which SQLite compares where Postgres refuses
* (a query-string id bound to an integer column). The sampler sends what
* each parameter declares, so a class 22 refusal is the code's, not the
* sample's. A constraint (class 23) or a timeout comes from the sample values
* or the empty tables, not the SQL.
*/
export function countsTowardRatchet(code: string): boolean {
return /^(42|0A)/.test(code);
return /^(42|0A|22)/.test(code);
}
const METHOD_KEY = /^[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*$/;
+4 -3
View File
@@ -5,6 +5,8 @@
* SQLite database the helper cases are compared on, and the loop that calls
* every repository method.
*/
import { applyPostgresColumnAdjustments, NOCASE_COLLATION_SQL } from '../../src/db/engine/postgres/schema-adjust';
import { splitStatements } from '../../src/db/engine/postgres/sql-split';
import { ALL_ENTITIES } from '../../src/db/entities';
import type { MethodPlan } from './arg-samples';
import {
@@ -18,8 +20,7 @@ import {
} from './helper-cases';
import { ProbePostgresDialect, type StatementRecorder } from './recorder';
import type { MethodResult } from './report';
import { adjustColumns, NOCASE_COLLATION_SQL, splitStatements, type ColumnMeta } from './schema';
import { RequestContext, type Configuration, type EntityManager, type EntityProperty } from '@mikro-orm/core';
import { RequestContext, type Configuration, type EntityManager } from '@mikro-orm/core';
import { MikroORM, PostgreSqlConnection, PostgreSqlDriver, type Options } from '@mikro-orm/postgresql';
import { SqlitePlatform } from '@mikro-orm/sql';
@@ -129,7 +130,7 @@ export async function prepareDatabase(
await run(NOCASE_COLLATION_SQL);
let adjusted = 0;
for (const meta of orm.getMetadata().getAll().values()) {
adjusted += adjustColumns(meta.props as EntityProperty[] as ColumnMeta[]).length;
adjusted += applyPostgresColumnAdjustments(meta.props).length;
}
const statements = splitStatements(await orm.schema.getCreateSchemaSQL({ wrap: false }));
for (const statement of statements) await run(statement);
+13
View File
@@ -44,6 +44,7 @@ import {
dateOf,
dayDistance,
foundAgainState,
ilike,
lower,
lowerParam,
lowerTrim,
@@ -269,6 +270,18 @@ export const HELPER_CASES: readonly HelperCase[] = [
raw: (p) => rawOf(dayDistance(p, 'a', '2026-09-24')),
expect: { equals: 3 },
},
{
name: 'ilike matches in other case',
row: { a: 'Probe Place' },
raw: (p) => ({ sql: ilike(p, ['a']), params: ['%PLACE%'] }),
expect: { equals: true },
},
{
name: 'ilike keeps the escaped wildcard literal',
row: { a: 'Probe Place' },
raw: (p) => ({ sql: ilike(p, ['a']), params: ['probe\\_place'] }),
expect: { equals: false },
},
{
name: 'collateNoCase',
row: { a: 'Probe' },
+8 -6
View File
@@ -22,7 +22,7 @@ export interface FailedStatement {
code: string;
message: string;
sql: string;
/** A dialect refusal (SQLSTATE class 42 or 0A) the ratchet holds; anything else is reported only. */
/** A refusal the ratchet holds (SQLSTATE class 42, 0A or 22); anything else is reported only. */
counted: boolean;
}
@@ -38,8 +38,9 @@ export interface ProbeSummary {
/** Every distinct statement Postgres refused, counted toward the ratchet or not. */
failedStatements: FailedStatement[];
/**
* `Class.method` → distinct statements Postgres refused as SQL (SQLSTATE
* class 42 or 0A); every called method appears, zeros included.
* `Class.method` → distinct statements Postgres refused as SQL or over a
* value's type (SQLSTATE class 42, 0A or 22); every called method appears,
* zeros included.
*/
failingByMethod: Map<string, number>;
/**
@@ -192,7 +193,8 @@ export function formatConsole(input: ReportInput): string {
const refusals = splitRefusals(summary);
lines.push(
`Statements: ${summary.statements} distinct, ${summary.failedStatements.length} refused by Postgres ` +
`(${refusals.counted.length} as SQL, held to the baseline; ${refusals.reported.length} over a sample value or the empty tables, reported only).`,
`(${refusals.counted.length} as SQL or over a value's type, held to the baseline; ` +
`${refusals.reported.length} over a constraint, a timeout or the empty tables, reported only).`,
);
for (const [code, count] of [...summary.failuresByCode.entries()].sort((a, b) => b[1] - a[1])) {
lines.push(` ${code}: ${count}${countsTowardRatchet(code) ? '' : ' (not held)'}`);
@@ -254,8 +256,8 @@ export function formatMarkdown(input: ReportInput): string {
);
out.push(`| Methods whose SQL the probe did not see | ${summary.uncovered.size} |`);
out.push(`| Distinct statements | ${summary.statements} |`);
out.push(`| Refused by Postgres as SQL (held) | ${refusals.counted.length} |`);
out.push(`| Refused over a sample value or the empty tables (reported only) | ${refusals.reported.length} |`);
out.push(`| Refused by Postgres as SQL or over a value's type (held) | ${refusals.counted.length} |`);
out.push(`| Refused over a constraint, a timeout or the empty tables (reported only) | ${refusals.reported.length} |`);
out.push('');
if (probedNothing(summary))
out.push('No repository method was called, so there is nothing to hold to the baseline.', '');
-106
View File
@@ -1,106 +0,0 @@
/**
* The Postgres schema the probe runs against, derived from the entities.
*
* The entities are generated from the migrated SQLite schema and a parity
* test pins them to it (`npm run check:entities`), so they are the one
* description of the tables both engines can read. MikroORM's schema
* generator turns them into Postgres DDL after three adjustments that keep
* the probe about the SQL the repositories send, not about the storage
* decisions a real Postgres port still has to make:
*
* - timestamps stay TEXT, the storage model the services and the dialect
* helpers are written for (server/CLAUDE.md, "Storage model");
* - a SQLite-only default (`datetime('now')`, `strftime('%s','now')`) gets
* its Postgres equivalent, and a column declared `COLLATE NOCASE` uses
* the `nocase` collation `collateNoCase()` names on Postgres;
* - no foreign keys, so a statement is never refused only because the
* sample row it writes points at nothing (every statement meets empty
* tables).
*
* Unique and partial unique indexes stay, because `ON CONFLICT` needs them.
*/
import { pgTimestampText, PG_UTC_NOW } from '../../src/db/dialect/platform';
/** SQLite's timestamp text on Postgres, for a column default. */
export const PG_NOW_TEXT_DEFAULT = pgTimestampText(PG_UTC_NOW);
/** The case-insensitive collation `collateNoCase()` names on Postgres. */
export const NOCASE_COLLATION_SQL =
"CREATE COLLATION IF NOT EXISTS nocase (provider = icu, locale = 'und-u-ks-level2', deterministic = false)";
/** The Postgres spelling of a column default the entities carry in SQLite's. */
export function portableDefault(raw: string): string {
const text = raw
.trim()
.replace(/^\((.*)\)$/s, '$1')
.trim();
if (/^current_timestamp$/i.test(text) || /^datetime\(\s*'now'\s*\)$/i.test(text)) return PG_NOW_TEXT_DEFAULT;
if (/^strftime\(\s*'%s'\s*,\s*'now'\s*\)$/i.test(text))
return 'CAST(EXTRACT(EPOCH FROM CURRENT_TIMESTAMP) AS bigint)';
return raw;
}
/**
* Splits generated DDL into single statements on `;` outside quotes, so one
* statement Postgres refuses does not take the rest of the schema with it.
*/
export function splitStatements(sql: string): string[] {
const statements: string[] = [];
let current = '';
let quote: '"' | "'" | null = null;
for (const char of sql) {
if (quote) {
if (char === quote) quote = null;
current += char;
} else if (char === "'" || char === '"') {
quote = char;
current += char;
} else if (char === ';') {
if (current.trim()) statements.push(current.trim());
current = '';
} else {
current += char;
}
}
if (current.trim()) statements.push(current.trim());
return statements.filter((statement) => !/^set\s/i.test(statement));
}
/** The subset of MikroORM's property metadata the schema adjustments touch. */
export interface ColumnMeta {
name: string;
defaultRaw?: string;
collation?: string;
columnTypes?: string[];
customType?: { constructor: { name: string } };
}
/**
* Applies the adjustments above to one entity's properties in place:
* timestamp columns become `text`, SQLite-only defaults and the NOCASE
* collation their Postgres spelling. Returns the names of the properties
* it changed, for the log.
*/
export function adjustColumns(properties: readonly ColumnMeta[]): string[] {
const changed: string[] = [];
for (const property of properties) {
let touched = false;
if (property.customType?.constructor.name === 'DbTimestampType' && property.columnTypes) {
property.columnTypes = property.columnTypes.map(() => 'text');
touched = true;
}
if (typeof property.defaultRaw === 'string') {
const next = portableDefault(property.defaultRaw);
if (next !== property.defaultRaw) {
property.defaultRaw = next;
touched = true;
}
}
if (property.collation?.toUpperCase() === 'NOCASE') {
property.collation = 'nocase';
touched = true;
}
if (touched) changed.push(property.name);
}
return changed;
}