@akal/pg-conformance 0.0.0-stage → 0.0.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akal Software Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# pg-conformance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A PostgreSQL schema **fingerprint** and a **DDL conformance corpus**, shared by tools that need to agree on whether two schemas are the same.
+
+Data only. No runner, no database driver, no opinion about how you test.
+
+## Why this exists
+
+Two tools that compare PostgreSQL schemas each had their own answer to "are these the same?". They diverged, quietly, and one of them ended up reporting these pairs as identical:
+
+| | one side | the other |
+| --- | --- | --- |
+| view | `SELECT n FROM t WHERE n > 0` | `... WHERE n < 0` |
+| function | `RETURNS int AS $$ SELECT 1 $$` | `... SELECT 999 $$` |
+| trigger | `AFTER INSERT ON t` | `BEFORE UPDATE ON t` |
+| identity | `GENERATED ALWAYS AS IDENTITY (INCREMENT 10 START 100)` | `GENERATED ALWAYS AS IDENTITY` |
+
+None of those is exotic. Each was invisible because that fingerprint compared objects by *name* and read columns from `information_schema`, which cannot express identity options, generated columns, storage, compression or collation — and has nowhere to put a partition bound.
+
+The fix is not a better fingerprint in each tool. It is one fingerprint.
+
+## Install
+
+```bash
+npm install @akal/pg-conformance
+```
+
+**PHP consumers install the same npm package.** This is not published to
+Packagist, so `composer require` will not find it — the npm tarball ships
+`src/Conformance.php`, which is how DBDiff consumes it:
+
+```php
+require_once 'node_modules/@akal/pg-conformance/src/Conformance.php';
+```
+
+One package means one version number for both languages, which matters more
+here than idiomatic installation: a corpus whose whole job is to be the single
+shared answer to "are these schemas the same?" should not be publishable at two
+different versions at once. `composer.json` is kept for its autoload map and for
+requiring this from git if you need to.
+
+## Use
+
+```js
+import { fingerprintSql, loadCorpus } from '@akal/pg-conformance'
+
+const sql = fingerprintSql(['public'])
+const a = await query(sourceDb, sql)
+const b = await query(targetDb, sql)
+if (a !== b) { /* the schemas differ */ }
+
+for (const testCase of loadCorpus('hard-cases')) {
+  // testCase.sql builds the objects; testCase.minPgVersion gates it
+}
+```
+
+```php
+use Akal\PgConformance\Conformance;
+
+$sql = Conformance::fingerprintSql(['public']);
+$cases = Conformance::loadCorpus('hard-cases');
+```
+
+Schema names are quoted by the accessor, not by you — the query embeds them as SQL literals, so that is the one place an injection could enter. A name that is not a plain identifier is rejected rather than escaped.
+
+If you shell out to `psql`, use `fingerprintSqlPath` and substitute `__SCHEMAS__` yourself.
+
+## Schema state
+
+`fingerprintSql()` answers *are these the same?*. `stateSql()` answers *what is there?* — the same catalog knowledge shaped as a JSON document, so a consumer can compute its own diff instead of trusting someone else's idea of what changed.
+
+```js
+import { stateSql } from '@akal/pg-conformance'
+
+const before = JSON.parse(await query(db, stateSql(['public'])))
+// ... apply a migration ...
+const after  = JSON.parse(await query(db, stateSql(['public'])))
+```
+
+```json
+{
+  "meta": { "server_version_num": 170011, "schemas": ["public"] },
+  "tables": [{
+    "schema": "public", "name": "orders", "kind": "partitioned_table",
+    "unlogged": false, "partition_by": "RANGE (created_at)",
+    "options": ["fillfactor=70"], "rls_enabled": true,
+    "columns": [{
+      "name": "id", "type": "bigint", "not_null": true,
+      "identity": "always",
+      "identity_options": { "start": 100, "increment": 10, "cycle": false },
+      "storage": "plain", "compression": null, "collation": null
+    }],
+    "constraints": [...], "indexes": [...], "policies": [...], "triggers": [...]
+  }],
+  "views": [...], "sequences": [...], "routines": [...],
+  "types": [...], "extensions": [...]
+}
+```
+
+Two conventions, both learned from getting them wrong:
+
+**Values are semantic, not catalog shorthand.** `attstorage` `'x'` is reported as `"extended"`, `attcompression` `'l'` as `"lz4"`, `attidentity` `'a'` as `"always"`. A consumer should not have to memorise single letters.
+
+**Inherited defaults are `null`, not spelled out.** A column that merely uses the database collation reports `null` rather than `"default"` — otherwise every text column in an unchanged schema reads as different.
+
+The state document is verified to distinguish **every pair of corpus schemas the fingerprint distinguishes**, so adopting it loses nothing the fingerprint already caught. It is also byte-stable: identical schemas produce identical documents.
+
+Existing schema APIs are not a substitute. `information_schema` cannot express a partition bound, identity sequence options, storage, compression or collation, and `postgres-meta` reads `relkind`/`relrowsecurity` but not `relpartbound`, `relpersistence` or `reloptions`, no identity options, and does not model sequences at all.
+
+## What the fingerprint covers
+
+Relations (kind, persistence, partition bound, storage options, RLS) · columns (type, nullability, default, identity, generated, storage, compression, collation) · sequence options · constraints (definition, validated, deferrable) · indexes, per relation · views and materialised views, **by body** · routines, **by body** · triggers, **by definition** · policies (command, roles, `USING`, `WITH CHECK`) · enums, domains and composite types · inheritance · comments.
+
+Two principles decide the content:
+
+**Read the catalog, not `information_schema`.** The standard has no concept of most of what matters here.
+
+**Compare bodies, not names.** Where PostgreSQL can render an object canonically — `pg_get_viewdef`, `pg_get_constraintdef`, `pg_get_functiondef`, `pg_get_triggerdef` — that rendering is what gets compared, so both sides come from the same server code and formatting can never manufacture a difference.
+
+Definitions are flattened to one line, because entries are newline-joined and a multi-line body would otherwise arrive as several unattributed entries.
+
+## The corpora
+
+| corpus | what it is for |
+| --- | --- |
+| `objects` | creating each object kind from an empty schema |
+| `hard-cases` | DDL that is awkward to reproduce — identity options, generated columns, exclusion constraints, partitioning of all three strategies and multi-level, inheritance, collations, storage and TOAST parameters, compression, every index method, interval and range types, domains over domains, function overloads, `INSTEAD OF` and constraint triggers, restrictive policies |
+| `ordering` | dependency ordering, with names chosen to defeat text matching |
+| `migrations` | schema changes a migration tool must make in both directions — enum labels removed or reordered under views, policies and keys; identity, serial and storage changes; generated columns; types and functions created before, and dropped after, what uses them; cross-schema and multi-column foreign keys; objects in other schemas and in quoted ones; overloads, partitions, RLS, triggers, sequences and constraints |
+| `equivalences` | one schema written two ways — as a developer writes it and as PostgreSQL renders it — which a comparison must call identical |
+| `data` | rows a data migration must carry over both ways — text needing quoting, JSON, arrays, binary, numeric extremes, time zones, composite and missing keys, identity and generated columns, enums, domains and other types |
+
+`ordering` cases give statements in an order that does **not** apply, plus the precedences any correct order must satisfy — a property rather than one expected permutation, so a sorter's tie-breaking can change without invalidating the case.
+
+`migrations` cases give a `before` and an `after` schema. A tool migrating either into the other must leave it identical to a database built from the other directly, and its `preserve` queries must return the same rows on the migrated database as they did before it was migrated. They read only what a correct migration keeps — never a generated column whose expression changes, which it must recompute. These are the shapes found to produce SQL that is valid but cannot run, or that runs and loses something.
+
+`equivalences` exist because PostgreSQL does not render every expression the same way twice: `status IN ('draft', 'active')` on a `varchar` column renders as `ARRAY[...]::text[]`, and recreated from that, as `ARRAY[(...)::text, ...]`. A dump, a restore or a generated migration changes the text and not the schema. **The fingerprint does not yet call these pairs identical** — it compares renderings — so a consumer comparing a database with a copy of it has to re-render one side (the package's own test reports this as a to-do).
+
+`data` cases give one `schema` and two sets of rows. Migrating the `before` rows into the `after` rows, or back, must leave each `compare` query returning what it does on a database built from the other side directly. They are the values found to be quoted wrongly, or not handled at all, by a data diff.
+
+Cases carry `minPgVersion` where they need a particular server.
+
+## Requirements
+
+PostgreSQL 14 or newer. Tested against 14, 15, 16, 17 and 18 on every change.
+
+## Releases
+
+Every merge to `main` publishes a patch automatically, so consumers track it
+without ceremony. To ask for more than a patch, use any of these — the last one
+wins, and is the one to rely on:
+
+| How | Where |
+| --- | --- |
+| `[minor]` / `[major]` | anywhere in the commit message |
+| `[minor]` / `[major]` | in the pull request title |
+| `release:minor` / `release:major` | a label on the pull request |
+
+`[skip release]` opts out.
+
+This package is `0.x` while the fingerprint settles. **Depend on it with
+`~0.0.x`, not `^0.0.x`** — under semver a caret on a `0.0.z` version allows no
+updates at all, so `^0.0.6` is an exact pin and you would never receive a
+release:
+
+```jsonc
+"@akal/pg-conformance": "~0.0.6"   // tracks 0.0.7, 0.0.8, ...
+"@akal/pg-conformance": "^0.0.6"   // pinned to exactly 0.0.6
+```
+
+Once it reaches `0.1.0`, `^0.1.0` tracks the `0.1.x` line as you would expect.
+
+Consumers pin through their lockfile as usual; a bot bumps that lockfile, so `npm ci` stays reproducible and still moves.
+
+## Local development
+
+```bash
+npm link                                  # in this repo
+npm link @akal/pg-conformance             # in the consumer
+```
+
+Run the package's own tests against a real server:
+
+```bash
+PGURL=postgresql://user:pass@127.0.0.1:5432/postgres npm test
+```
+
+Without `PGURL` the database half skips and only the accessors are checked. The database half is the half that matters: it asserts the fingerprint *discriminates*, since one that returned a constant would pass every consumer's suite while proving nothing.
+
+## Licence
+
+MIT

package/corpus/data.json

@@ -0,0 +1,122 @@
+[
+  {
+    "id": "text_escaping",
+    "description": "Text a migration must quote rather than mangle: single and double quotes, backslashes, newlines and tabs, non-ASCII and emoji, and an empty string beside a NULL.",
+    "schema": "CREATE TABLE t (id int PRIMARY KEY, v text);",
+    "before": "INSERT INTO t VALUES (1, 'plain'), (2, 'to be deleted'), (3, NULL);",
+    "after": "INSERT INTO t VALUES (1, E'it''s a \"quote\" and a back\\\\slash'), (3, ''), (4, E'line1\\nline2\\ttab'), (5, 'ünïcödé 🎉'), (6, E'trailing backslash \\\\');",
+    "compare": [
+      "SELECT id, v, v IS NULL FROM t ORDER BY id"
+    ]
+  },
+  {
+    "id": "json_values",
+    "description": "json and jsonb holding quotes, backslashes, nesting, a bare string and a JSON null — distinct from an SQL NULL.",
+    "schema": "CREATE TABLE j (id int PRIMARY KEY, a json, b jsonb);",
+    "before": "INSERT INTO j VALUES (1, '{\"k\": 1}', '{\"k\": 1}'), (2, NULL, NULL);",
+    "after": "INSERT INTO j VALUES (1, '{\"q\": \"it''s \\\"quoted\\\"\", \"n\": [1, {\"x\": null}]}', '{\"q\": \"back\\\\slash\", \"z\": true}'), (2, '\"just a string\"', 'null'), (3, '[]', '{}');",
+    "compare": [
+      "SELECT id, a::text, b::text, a IS NULL, b IS NULL FROM j ORDER BY id"
+    ]
+  },
+  {
+    "id": "array_values",
+    "description": "Arrays whose elements need quoting — commas, braces, quotes, spaces — with NULL elements, an empty array and a two-dimensional one.",
+    "schema": "CREATE TABLE a (id int PRIMARY KEY, t text[], m int[]);",
+    "before": "INSERT INTO a VALUES (1, '{x}', '{1}');",
+    "after": "INSERT INTO a VALUES (1, ARRAY['a,b', '{c}', 'd\"e', 'f g', NULL, ''], '{{1,2},{3,4}}'), (2, '{}', NULL);",
+    "compare": [
+      "SELECT id, t::text, m::text FROM a ORDER BY id"
+    ]
+  },
+  {
+    "id": "binary_values",
+    "description": "bytea, including a zero byte, high bytes and an empty value. A driver may hand these back as a stream rather than a string.",
+    "schema": "CREATE TABLE b (id int PRIMARY KEY, v bytea);",
+    "before": "INSERT INTO b VALUES (1, '\\x00');",
+    "after": "INSERT INTO b VALUES (1, '\\x00ff10'), (2, '\\x'), (3, decode('68656c6c6f00776f726c64', 'hex'));",
+    "compare": [
+      "SELECT id, encode(v, 'hex') FROM b ORDER BY id"
+    ]
+  },
+  {
+    "id": "numeric_extremes",
+    "description": "Values that lose something if they pass through a float or an unquoted literal: high-precision numerics, NaN and infinities, the smallest double, and bigint at both ends.",
+    "schema": "CREATE TABLE n (id int PRIMARY KEY, d numeric, f float8, i bigint);",
+    "before": "INSERT INTO n VALUES (1, 1, 1, 1);",
+    "after": "INSERT INTO n VALUES (1, 123456789012345678901234567890.123456789, 'NaN', 9223372036854775807), (2, -0.000000001, '-Infinity', -9223372036854775808), (3, 'NaN', 1e-300, 0);",
+    "compare": [
+      "SELECT id, d::text, f::text, i::text FROM n ORDER BY id"
+    ]
+  },
+  {
+    "id": "time_values",
+    "description": "timestamptz written in other zones, infinite timestamps and dates, intervals with months and seconds, and a time with a zone.",
+    "schema": "CREATE TABLE tm (id int PRIMARY KEY, ts timestamptz, d date, iv interval, tz timetz);",
+    "before": "INSERT INTO tm VALUES (1, '2020-01-01 00:00+00', '2020-01-01', '1 day', '10:00+00');",
+    "after": "INSERT INTO tm VALUES (1, '2026-01-01 10:00+05:30', 'infinity', '1 year 2 months 3 days 04:05:06.789', '23:59:59.999+14'), (2, '-infinity', '0001-01-01', '-5 years', NULL);",
+    "compare": [
+      "SELECT id, ts AT TIME ZONE 'UTC', d::text, iv::text, tz::text FROM tm ORDER BY id"
+    ]
+  },
+  {
+    "id": "composite_key",
+    "description": "A two-column primary key: rows updated, inserted and deleted by both parts of the key, one of which shares a value with another row.",
+    "schema": "CREATE TABLE c (a int, b text, v text, PRIMARY KEY (a, b));",
+    "before": "INSERT INTO c VALUES (1, 'x', 'uno'), (3, 'z', 'three');",
+    "after": "INSERT INTO c VALUES (1, 'x', 'one'), (1, 'y', 'two'), (2, 'x', NULL);",
+    "compare": [
+      "SELECT a, b, v FROM c ORDER BY a, b"
+    ]
+  },
+  {
+    "id": "no_primary_key",
+    "description": "A table with no key at all, holding duplicate rows. Rows can only be told apart by their values, and a duplicate counts.",
+    "schema": "CREATE TABLE k (x int, y text);",
+    "before": "INSERT INTO k VALUES (1, 'a'), (3, 'c');",
+    "after": "INSERT INTO k VALUES (1, 'a'), (1, 'a'), (2, NULL);",
+    "compare": [
+      "SELECT x, y, count(*) FROM k GROUP BY x, y ORDER BY x, y"
+    ]
+  },
+  {
+    "id": "identity_always",
+    "description": "Rows in a table whose key is GENERATED ALWAYS AS IDENTITY: inserting them with their ids needs OVERRIDING SYSTEM VALUE.",
+    "schema": "CREATE TABLE ia (id int GENERATED ALWAYS AS IDENTITY PRIMARY KEY, v text);",
+    "before": "INSERT INTO ia (v) VALUES ('one');",
+    "after": "INSERT INTO ia (id, v) OVERRIDING SYSTEM VALUE VALUES (1, 'first'), (7, 'seventh');",
+    "compare": [
+      "SELECT id, v FROM ia ORDER BY id"
+    ]
+  },
+  {
+    "id": "generated_column",
+    "description": "A table with a stored generated column. Its values follow from the others: a migration writing them is refused by the server.",
+    "schema": "CREATE TABLE g (id int PRIMARY KEY, a int, twice int GENERATED ALWAYS AS (a * 2) STORED);",
+    "before": "INSERT INTO g (id, a) VALUES (1, 1);",
+    "after": "INSERT INTO g (id, a) VALUES (1, 5), (2, 7);",
+    "compare": [
+      "SELECT id, a, twice FROM g ORDER BY id"
+    ]
+  },
+  {
+    "id": "enum_and_domain_values",
+    "description": "Columns typed by an enum and by a domain over text.",
+    "schema": "CREATE TYPE mood AS ENUM ('sad', 'ok', 'happy'); CREATE DOMAIN code AS text CHECK (VALUE ~ '^[A-Z]+$'); CREATE TABLE ed (id int PRIMARY KEY, m mood, c code);",
+    "before": "INSERT INTO ed VALUES (1, 'sad', 'AB');",
+    "after": "INSERT INTO ed VALUES (1, 'happy', 'XYZ'), (2, NULL, 'Q');",
+    "compare": [
+      "SELECT id, m::text, c::text FROM ed ORDER BY id"
+    ]
+  },
+  {
+    "id": "assorted_types",
+    "description": "uuid, boolean, inet, macaddr, bit strings, money and a range.",
+    "schema": "CREATE TABLE at (id int PRIMARY KEY, u uuid, ok boolean, ip inet, mac macaddr, bits bit varying(8), price money, r int4range);",
+    "before": "INSERT INTO at VALUES (1, NULL, false, NULL, NULL, NULL, NULL, NULL);",
+    "after": "INSERT INTO at VALUES (1, 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11', true, '192.168.0.1/24', '08:00:2b:01:02:03', B'1011', 12.34, '[1,10)'), (2, NULL, NULL, '::1', NULL, B'', 0, 'empty');",
+    "compare": [
+      "SELECT id, u::text, ok::text, ip::text, mac::text, bits::text, price::numeric::text, r::text FROM at ORDER BY id"
+    ]
+  }
+]

package/corpus/equivalences.json

@@ -0,0 +1,44 @@
+[
+  {
+    "id": "in_list_on_varchar_check",
+    "kind": "check",
+    "description": "A CHECK constraint with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE TABLE t (status varchar(20), n int, CONSTRAINT c CHECK (status IN ('draft', 'active')));",
+    "rendered": "CREATE TABLE t (status varchar(20), n int, CONSTRAINT c CHECK (((status)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[]))));"
+  },
+  {
+    "id": "in_list_on_varchar_index",
+    "kind": "index",
+    "description": "A partial index with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE TABLE t (status varchar(20), n int); CREATE INDEX i ON t (n) WHERE status IN ('draft', 'active');",
+    "rendered": "CREATE TABLE t (status varchar(20), n int); CREATE INDEX i ON t (n) WHERE ((status)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[]));"
+  },
+  {
+    "id": "in_list_on_varchar_policy",
+    "kind": "policy",
+    "description": "A RLS policy with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE TABLE t (status varchar(20)); ALTER TABLE t ENABLE ROW LEVEL SECURITY; CREATE POLICY p ON t USING (status IN ('draft', 'active'));",
+    "rendered": "CREATE TABLE t (status varchar(20)); ALTER TABLE t ENABLE ROW LEVEL SECURITY; CREATE POLICY p ON t USING (((status)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[])));"
+  },
+  {
+    "id": "in_list_on_varchar_view",
+    "kind": "view",
+    "description": "A view with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE TABLE t (status varchar(20)); CREATE VIEW v AS SELECT * FROM t WHERE status IN ('draft', 'active');",
+    "rendered": "CREATE TABLE t (status varchar(20)); CREATE VIEW v AS SELECT t.status FROM t WHERE ((t.status)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[]));"
+  },
+  {
+    "id": "in_list_on_varchar_domain",
+    "kind": "domain",
+    "description": "A domain CHECK with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE DOMAIN d AS varchar(20) CHECK (VALUE IN ('draft', 'active')); CREATE TABLE t (status d);",
+    "rendered": "CREATE DOMAIN d AS varchar(20) CHECK (((VALUE)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[]))); CREATE TABLE t (status d);"
+  },
+  {
+    "id": "in_list_on_varchar_generated",
+    "kind": "generated",
+    "description": "A stored generated column with IN (...) on a varchar column, as written and as PostgreSQL renders it. Recreated from that rendering it renders differently again (ARRAY[...]::text[] becomes ARRAY[(...)::text, ...]), so a dump, restore or migration changes the text, not the schema.",
+    "written": "CREATE TABLE t (status varchar(20), ok boolean GENERATED ALWAYS AS (status IN ('draft', 'active')) STORED);",
+    "rendered": "CREATE TABLE t (status varchar(20), ok boolean GENERATED ALWAYS AS (((status)::text = ANY ((ARRAY['draft'::character varying, 'active'::character varying])::text[]))) STORED);"
+  }
+]