@saasicat/spec 1.0.0-rc.2 → 1.0.0-rc.21

package/sql/1.0-a-settings-change-carries-its-order.postgres.sql

@@ -0,0 +1,73 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a settings change carries the order it was recorded in.
+-- =============================================================================
+--
+-- `settings_changes` gains `seq`, numbered by the database at the write that
+-- records each change, and the platform lists the changes by it. Until now the
+-- list was ordered by `noticedAt`, which is the recording start's own clock: a
+-- start delayed between reading its clock and writing — a pause, a slow
+-- connection — could land after a move made by another start and still be
+-- listed before it, and the list then showed an order the record never went
+-- through. The number is assigned inside the write, under the row lock the
+-- guarded write already takes, so it cannot.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-a-settings-change-carries-its-order.postgres.sql
+--
+-- An installation without `settings_changes` is left alone. Safe to run again:
+-- the block runs only while the column is missing. Rows
+-- recorded before it existed are numbered in the order they were listed until
+-- now — `noticedAt`, then `id` — so nothing an operator saw changes place, and
+-- the numbering continues after them. The unique index is created afterwards,
+-- because the renumbering passes through values the index would refuse. On a
+-- database created from `reference-schema.postgres.sql` the file does nothing
+-- at all.
+
+BEGIN;
+
+DO $$
+BEGIN
+    IF to_regclass('settings_changes') IS NULL THEN
+        RAISE NOTICE 'settings_changes is not present — nothing to migrate.';
+        RETURN;
+    END IF;
+
+    IF EXISTS (
+        SELECT 1
+        FROM information_schema.columns
+        WHERE table_schema = current_schema()
+          AND table_name = 'settings_changes'
+          AND column_name = 'seq'
+    ) THEN
+        RETURN;
+    END IF;
+
+    ALTER TABLE "settings_changes" ADD COLUMN "seq" SERIAL NOT NULL;
+
+    WITH ordered AS (
+        SELECT "id", row_number() OVER (ORDER BY "noticedAt", "id") AS n
+        FROM "settings_changes"
+    )
+    UPDATE "settings_changes" AS c
+    SET "seq" = ordered.n
+    FROM ordered
+    WHERE c."id" = ordered."id";
+
+    PERFORM setval(
+        pg_get_serial_sequence('settings_changes', 'seq'),
+        (SELECT COALESCE(MAX("seq"), 0) + 1 FROM "settings_changes"),
+        false
+    );
+END $$;
+
+DO $$
+BEGIN
+    IF to_regclass('settings_changes') IS NULL THEN
+        RETURN;  -- said once already, by the block above
+    END IF;
+    CREATE UNIQUE INDEX IF NOT EXISTS "settings_changes_seq_key" ON "settings_changes"("seq");
+END $$;
+
+COMMIT;

package/sql/1.0-line-items-record-their-money.postgres.sql

@@ -0,0 +1,134 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — a contract line item records the currency and the tax it was
+-- booked with.
+-- =============================================================================
+--
+-- `contract_line_items` gains three columns: "currency", "taxRate" and
+-- "taxAmount". They are NOT NULL in the shipped fragment, which a plain
+-- `prisma db push` cannot produce on a table that already holds rows — so this
+-- file adds them nullable, fills them, and only then tightens them. Run it
+-- BEFORE `db push`, the same way as the other file in this directory:
+--
+--   psql "$DATABASE_URL" -f 1.0-line-items-record-their-money.postgres.sql
+--
+-- Where the values come from. Every contract carries a `priceSnapshot` holding
+-- the currency and the VAT rate that were agreed for it, written in the same
+-- moment as its line items — so an existing line reads the fact one level up.
+-- "taxAmount" is the gap between the line's own net and gross, which is exact:
+-- both are already held to two places.
+--
+-- The rate is a percentage, as every tax rate in SaaSiCat is: 19 means 19 %.
+-- It is taken from the snapshot as it stands and checked, never read in some
+-- other unit or converted. A contract stops the migration, named, where its
+-- snapshot does not state a currency, does not state its vatRate as a number,
+-- or states a rate outside 0 to 100 or between 0 and 1 — the shape of a
+-- fraction such as 0.19. A line this file fills that already carries a rate of
+-- its own is held to the same rule; a line that already holds all three values
+-- is not touched. An installation that stored fractions converts them before it
+-- runs this file; a row labelled 0.19 % because a number was there is worse
+-- than a migration that did not run.
+--
+-- Safe to run again: the columns are added only where they are missing, a value
+-- already in a column is kept rather than rewritten, and tightening a column
+-- that is already NOT NULL is a no-op. On a database created from
+-- `reference-schema.postgres.sql` the whole file does nothing at all — the
+-- columns are already there, already tight, and there is nothing to fill.
+
+BEGIN;
+
+DO $$
+DECLARE
+    unfillable text[];
+BEGIN
+    IF to_regclass('contract_line_items') IS NULL THEN
+        RAISE NOTICE 'contract_line_items is not present — nothing to migrate.';
+        RETURN;  -- an installation that never adopted this fragment
+    END IF;
+
+    ALTER TABLE "contract_line_items" ADD COLUMN IF NOT EXISTS "currency" TEXT;
+    ALTER TABLE "contract_line_items" ADD COLUMN IF NOT EXISTS "taxRate" DECIMAL(5,2);
+    ALTER TABLE "contract_line_items" ADD COLUMN IF NOT EXISTS "taxAmount" DECIMAL(10,2);
+
+    -- What each row is to end up holding, worked out once.
+    --
+    -- Once, because the guard below and the backfill after it have to agree:
+    -- two copies of this expression is two chances to answer differently, and
+    -- the one that would go unnoticed is the guard passing a row the backfill
+    -- then cannot fill.
+    --
+    -- A value already in a column is kept. The columns are added only where
+    -- they are missing, so on a schema that already had a `currency` of its own
+    -- this migration reads it rather than overwriting it — and a row that needs
+    -- only one of the three is still found, which keying off `currency` alone
+    -- would have missed.
+    CREATE TEMP TABLE _saasicat_line_money ON COMMIT DROP AS
+    SELECT li."id" AS line_id,
+           coalesce(c."id", format('line %s', li."id")) AS witness,
+           coalesce(
+               li."currency",
+               CASE
+                   WHEN jsonb_typeof(c."priceSnapshot" -> 'currency') = 'string'
+                       THEN nullif(c."priceSnapshot" ->> 'currency', '')
+               END
+           ) AS currency,
+           -- The rate as it is stated, before it is rounded to the column's two
+           -- places: the rule is checked on what was written, as the guide's
+           -- query checks it, so 0.995 is a fraction here too.
+           coalesce(li."taxRate", snap.rate) AS stated_rate,
+           coalesce(li."taxRate", round(snap.rate, 2)) AS tax_rate,
+           coalesce(li."taxAmount", li."priceGross" - li."priceNet") AS tax_amount
+      FROM "contract_line_items" li
+      LEFT JOIN "subscription_contracts" c ON c."id" = li."contractId"
+      -- The rate is cast only once it is known to be a JSON number, so a
+      -- snapshot stating `"vatRate": "19"` reaches the refusal below with its
+      -- contract named rather than a cast error that names nothing.
+     CROSS JOIN LATERAL (
+         SELECT CASE WHEN jsonb_typeof(c."priceSnapshot" -> 'vatRate') = 'number'
+                    THEN (c."priceSnapshot" ->> 'vatRate')::numeric END AS rate
+     ) snap
+     WHERE li."currency" IS NULL
+        OR li."taxRate" IS NULL
+        OR li."taxAmount" IS NULL;
+
+    -- The contract names itself where there is one. A line whose contract is
+    -- missing names itself instead: the shipped fragment declares the foreign
+    -- key that makes that impossible, but a schema without it would otherwise
+    -- reach the message with nothing to say, and an installation this cannot
+    -- fill is exactly the one that needs telling which row to look at.
+    SELECT array_agg(DISTINCT witness)
+      INTO unfillable
+      FROM _saasicat_line_money
+     WHERE currency IS NULL
+        OR stated_rate IS NULL
+        OR stated_rate < 0
+        OR stated_rate > 100
+        -- The shape of a fraction: a percentage between 0 and 1 is refused
+        -- rather than recorded as a fraction of a per cent.
+        OR (stated_rate > 0 AND stated_rate < 1);
+
+    IF unfillable IS NOT NULL THEN
+        RAISE EXCEPTION
+            'Cannot record the money facts of % contract(s): their priceSnapshot does not state a '
+            'currency, or does not state its vatRate as a number, or states a tax rate — in the '
+            'snapshot, or on a line that already carries one — that is not a percentage from 0 '
+            'to 100, a value between 0 and 1 being refused as a fraction (%). The snapshot is '
+            'the only record of what was agreed, so this migration converts nothing. Repair those '
+            'rows and run it again. A line named on its own has no contract row at all.',
+            array_length(unfillable, 1),
+            array_to_string(unfillable[1:10], ', ')
+                || CASE WHEN array_length(unfillable, 1) > 10 THEN ', …' ELSE '' END;
+    END IF;
+
+    UPDATE "contract_line_items" li
+       SET "currency"  = m.currency,
+           "taxRate"   = m.tax_rate,
+           "taxAmount" = m.tax_amount
+      FROM _saasicat_line_money m
+     WHERE m.line_id = li."id";
+
+    ALTER TABLE "contract_line_items" ALTER COLUMN "currency" SET NOT NULL;
+    ALTER TABLE "contract_line_items" ALTER COLUMN "taxRate" SET NOT NULL;
+    ALTER TABLE "contract_line_items" ALTER COLUMN "taxAmount" SET NOT NULL;
+END $$;
+
+COMMIT;

package/sql/1.0-remove-project-key.postgres.sql

@@ -0,0 +1,203 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — remove `projectKey` from the catalogue tables.
+-- =============================================================================
+--
+-- project-key-history: this file names the retired identifier because dropping
+-- it is what it does.
+--
+-- One installation serves one application, so a plan key, a bundle key, a
+-- feature key and a quota key are unique for the installation. The column that
+-- suggested otherwise never had a second value to hold: nothing in the platform
+-- could configure a second project, and `subscriptions.tenantId` is unique
+-- installation-wide, so two applications in one database was never a shape this
+-- model could carry.
+--
+-- Run this against an existing database, inside the transaction it opens. It is
+-- a one-way door — the values are dropped, not archived — but it is safe to run
+-- again: a table whose column has already gone is skipped, so a second run does
+-- nothing rather than failing.
+--
+--   psql "$DATABASE_URL" -f 1.0-remove-project-key.postgres.sql
+--
+-- The first statement is a guard. If the affected tables between them hold rows
+-- under more than one project, the migration STOPS and names the table each key
+-- came from, rather than merging rows nobody meant to merge — two `STANDARD`
+-- plans would otherwise collide on the new unique index, and which of them
+-- survives is not a decision a migration should take.
+--
+-- The question is asked across the tables and not once per table. A per-table
+-- count is one where `plans` holds only `alpha` and `bundles` only `beta`, and
+-- that is a two-project installation whose evidence this migration would drop.
+--
+-- Applies to a database created from `reference-schema.postgres.sql` at 0.27 or
+-- any release before 1.0.
+
+BEGIN;
+
+DO $$
+DECLARE
+    affected CONSTANT text[] := ARRAY[
+        'plans',
+        'bundles',
+        'capability_catalog_entries',
+        'feature_catalog_entries',
+        'quota_catalog_entries',
+        'marketing_projections',
+        'marketing_settings',
+        'promotions',
+        'checkout_offers',
+        'subscription_contracts'
+    ];
+    target text;
+    keys_here text[];
+    -- Every key seen anywhere, with the table it came from, so the message can
+    -- say where the disagreement is rather than only that there is one.
+    seen text[] := ARRAY[]::text[];
+    witnesses text[] := ARRAY[]::text[];
+BEGIN
+    FOREACH target IN ARRAY affected LOOP
+        IF to_regclass(format('%I', target)) IS NULL THEN
+            CONTINUE;  -- an installation that never adopted this fragment
+        END IF;
+        -- A table that has already been migrated says nothing, and asking it
+        -- would raise `column "projectKey" does not exist`. Everything below
+        -- this block is written with IF EXISTS / IF NOT EXISTS, so with this
+        -- check the whole file is a no-op on a second run rather than an error
+        -- — which is what a deploy that retries, or a container that restarts,
+        -- needs it to be.
+        IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = current_schema()
+              AND table_name = target
+              AND column_name = 'projectKey'
+        ) THEN
+            CONTINUE;
+        END IF;
+        EXECUTE format('SELECT array_agg(DISTINCT "projectKey") FROM %I', target)
+            INTO keys_here;
+        IF keys_here IS NULL THEN
+            CONTINUE;  -- an empty table says nothing about the installation
+        END IF;
+        seen := ARRAY(SELECT DISTINCT unnest(seen || keys_here) ORDER BY 1);
+        witnesses := witnesses || format('%s: %s', target, array_to_string(keys_here, ', '));
+    END LOOP;
+
+    IF array_length(seen, 1) > 1 THEN
+        RAISE EXCEPTION
+            'The catalogue holds rows under % different project keys (%). Removing the column '
+            'would merge them, and a duplicate key would then collide on the new unique index. '
+            'Per table: %. Decide which rows belong to this installation and delete the rest, '
+            'then run this migration again.',
+            array_length(seen, 1),
+            array_to_string(seen, ', '),
+            array_to_string(witnesses, ' | ');
+    END IF;
+END $$;
+
+-- ─── The indexes that carried the column ───
+
+DROP INDEX IF EXISTS "checkout_offers_projectKey_status_idx";
+DROP INDEX IF EXISTS "plans_projectKey_deletedAt_idx";
+DROP INDEX IF EXISTS "plans_projectKey_planKey_key";
+DROP INDEX IF EXISTS "bundles_projectKey_deletedAt_idx";
+DROP INDEX IF EXISTS "bundles_projectKey_bundleKey_key";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_codeStatus_idx";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_featureKey_idx";
+DROP INDEX IF EXISTS "capability_catalog_entries_projectKey_capabilityKey_key";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_discoveryStatus_idx";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_plannedOnly_idx";
+DROP INDEX IF EXISTS "feature_catalog_entries_projectKey_featureKey_key";
+DROP INDEX IF EXISTS "quota_catalog_entries_projectKey_discoveryStatus_idx";
+DROP INDEX IF EXISTS "quota_catalog_entries_projectKey_quotaKey_key";
+DROP INDEX IF EXISTS "marketing_projections_projectKey_targetType_locale_priority_idx";
+DROP INDEX IF EXISTS "marketing_settings_projectKey_key";
+DROP INDEX IF EXISTS "promotions_projectKey_targetType_validFrom_validTo_idx";
+DROP INDEX IF EXISTS "subscription_contracts_projectKey_status_idx";
+
+-- ─── The column, the tightened uniques, and the shrunken lookup indexes ───
+--
+-- Per table, and only where the table is there. The Prisma fragments are
+-- adopted à la carte — `saasicat schema check` reports what an app did not take
+-- — and an unconditional `ALTER TABLE "bundles"` raises `relation does not
+-- exist` on an app that never adopted bundles, which rolls back everything,
+-- including the tables it could have migrated. `IF EXISTS` on the column does
+-- not help when it is the relation that is missing.
+--
+-- One list, so a table and what happens to it cannot drift apart.
+
+DO $$
+DECLARE
+    step record;
+    statement text;
+BEGIN
+    FOR step IN
+        SELECT * FROM (VALUES
+            ('plans', ARRAY[
+                'ALTER TABLE "plans" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "plans_planKey_key" ON "plans"("planKey")',
+                'CREATE INDEX IF NOT EXISTS "plans_deletedAt_idx" ON "plans"("deletedAt")'
+            ]),
+            ('bundles', ARRAY[
+                'ALTER TABLE "bundles" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "bundles_bundleKey_key" ON "bundles"("bundleKey")',
+                'CREATE INDEX IF NOT EXISTS "bundles_deletedAt_idx" ON "bundles"("deletedAt")'
+            ]),
+            ('capability_catalog_entries', ARRAY[
+                'ALTER TABLE "capability_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "capability_catalog_entries_capabilityKey_key" ON "capability_catalog_entries"("capabilityKey")',
+                'CREATE INDEX IF NOT EXISTS "capability_catalog_entries_codeStatus_idx" ON "capability_catalog_entries"("codeStatus")',
+                'CREATE INDEX IF NOT EXISTS "capability_catalog_entries_featureKey_idx" ON "capability_catalog_entries"("featureKey")'
+            ]),
+            ('feature_catalog_entries', ARRAY[
+                'ALTER TABLE "feature_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "feature_catalog_entries_featureKey_key" ON "feature_catalog_entries"("featureKey")',
+                'CREATE INDEX IF NOT EXISTS "feature_catalog_entries_discoveryStatus_idx" ON "feature_catalog_entries"("discoveryStatus")',
+                'CREATE INDEX IF NOT EXISTS "feature_catalog_entries_plannedOnly_idx" ON "feature_catalog_entries"("plannedOnly")'
+            ]),
+            ('quota_catalog_entries', ARRAY[
+                'ALTER TABLE "quota_catalog_entries" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE UNIQUE INDEX IF NOT EXISTS "quota_catalog_entries_quotaKey_key" ON "quota_catalog_entries"("quotaKey")',
+                'CREATE INDEX IF NOT EXISTS "quota_catalog_entries_discoveryStatus_idx" ON "quota_catalog_entries"("discoveryStatus")'
+            ]),
+            ('marketing_projections', ARRAY[
+                'ALTER TABLE "marketing_projections" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "marketing_projections_targetType_locale_priority_idx" ON "marketing_projections"("targetType", "locale", "priority")'
+            ]),
+            ('promotions', ARRAY[
+                'ALTER TABLE "promotions" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "promotions_targetType_validFrom_validTo_idx" ON "promotions"("targetType", "validFrom", "validTo")'
+            ]),
+            ('checkout_offers', ARRAY[
+                'ALTER TABLE "checkout_offers" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "checkout_offers_status_idx" ON "checkout_offers"("status")'
+            ]),
+            ('subscription_contracts', ARRAY[
+                'ALTER TABLE "subscription_contracts" DROP COLUMN IF EXISTS "projectKey"',
+                'CREATE INDEX IF NOT EXISTS "subscription_contracts_status_idx" ON "subscription_contracts"("status")'
+            ]),
+            -- `marketing_settings` loses the column and gains the identity that
+            -- replaces it: one row, under a constant primary key. The CHECK is
+            -- what actually holds it. A default only applies where the caller
+            -- omits the id and a primary key accepts every distinct value, so
+            -- without it a consumer writing the row directly could make as many
+            -- as it liked — which is what the comment claiming otherwise was
+            -- worth.
+            ('marketing_settings', ARRAY[
+                'ALTER TABLE "marketing_settings" DROP COLUMN IF EXISTS "projectKey"',
+                'ALTER TABLE "marketing_settings" ALTER COLUMN "id" SET DEFAULT ''marketing-settings''',
+                'UPDATE "marketing_settings" SET "id" = ''marketing-settings''',
+                'ALTER TABLE "marketing_settings" DROP CONSTRAINT IF EXISTS "marketing_settings_is_a_singleton"',
+                'ALTER TABLE "marketing_settings" ADD CONSTRAINT "marketing_settings_is_a_singleton" CHECK ("id" = ''marketing-settings'')'
+            ])
+        ) AS t(relname, statements)
+    LOOP
+        IF to_regclass(format('%I', step.relname)) IS NULL THEN
+            CONTINUE;  -- a fragment this installation never adopted
+        END IF;
+        FOREACH statement IN ARRAY step.statements LOOP
+            EXECUTE statement;
+        END LOOP;
+    END LOOP;
+END $$;
+
+COMMIT;

package/sql/1.0-the-applied-settings-are-recorded.postgres.sql

@@ -0,0 +1,67 @@
+-- =============================================================================
+-- SaaSiCat 1.0 — the platform records the configuration it applied.
+-- =============================================================================
+--
+-- Two tables, both additive: `applied_settings` holds the one row that says
+-- which settings the installation applied at its last start, with a fingerprint
+-- and the moment they took effect; `settings_changes` holds one row per start
+-- that found the fingerprint moved. The platform writes both at boot and reads
+-- them for the read-only settings screen — and for nothing else. The record is
+-- a mirror of `config/saas.yaml`, never a source.
+--
+-- Run it the same way as the other files in this directory, before `db push`
+-- where you use one:
+--
+--   psql "$DATABASE_URL" -f 1.0-the-applied-settings-are-recorded.postgres.sql
+--
+-- One row per installation. An installation serves one application and owns
+-- its database, so the row's identity is the installation's, and the CHECK is
+-- what holds it to one row — the constant default only lands a caller that
+-- omits the id on the right one.
+--
+-- A table this file creates has the shape the fragments declare now, the `seq`
+-- that orders the changes included: a fresh installation applies it after
+-- `1.0-a-settings-change-carries-its-order.postgres.sql`, which finds no table
+-- to add the column to, and `db push` refuses to add a unique column to a table
+-- it cannot see is empty.
+--
+-- Safe to run again: both tables and the indexes are created only where they are
+-- missing, and the constraint is dropped before it is added because
+-- `ADD CONSTRAINT` has no `IF NOT EXISTS`. On a database created from
+-- `reference-schema.postgres.sql` the whole file does nothing at all.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS "applied_settings" (
+    "id" TEXT NOT NULL DEFAULT 'installation',
+    "fingerprint" TEXT NOT NULL,
+    "settings" JSONB NOT NULL,
+    "source" TEXT NOT NULL,
+    "appliedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "applied_settings_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "applied_settings"
+    DROP CONSTRAINT IF EXISTS applied_settings_is_a_singleton;
+ALTER TABLE "applied_settings"
+    ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
+
+CREATE TABLE IF NOT EXISTS "settings_changes" (
+    "id" TEXT NOT NULL,
+    "seq" SERIAL NOT NULL,
+    "noticedAt" TIMESTAMP(3) NOT NULL,
+    "source" TEXT NOT NULL,
+    "previous" JSONB NOT NULL,
+    "current" JSONB NOT NULL,
+    "acknowledgedAt" TIMESTAMP(3),
+    "acknowledgedBy" TEXT,
+
+    CONSTRAINT "settings_changes_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "settings_changes_acknowledgedAt_noticedAt_idx"
+    ON "settings_changes"("acknowledgedAt", "noticedAt");
+CREATE UNIQUE INDEX IF NOT EXISTS "settings_changes_seq_key" ON "settings_changes"("seq");
+
+COMMIT;

package/sql/constraints.postgres.sql

@@ -17,3 +17,79 @@ CREATE UNIQUE INDEX IF NOT EXISTS plan_versions_draft_per_plan
 
 CREATE UNIQUE INDEX IF NOT EXISTS bundle_versions_draft_per_bundle
     ON bundle_versions ("bundleId") WHERE "publishedAt" IS NULL;
+
+-- `marketing_settings` holds at most ONE row.
+--
+-- The Prisma DSL cannot say this, and the constant default on `id` does not: a
+-- default applies only where the caller omits the value, and a primary key
+-- accepts every distinct one. A consumer writing the row directly could make as
+-- many as it liked, and the repository would then read one and ignore the rest.
+--
+-- `ADD CONSTRAINT` has no `IF NOT EXISTS`, and this file is applied again on
+-- every deployment — so it is dropped first. Two plain statements rather than a
+-- dollar-quoted `DO` block on purpose: every consumer of this file splits it at
+-- the statement separator, and a dollar-quoted body would need each of those
+-- splitters to become a SQL lexer. For the same reason no comment in this file
+-- may contain that separator — one here did, and three splitters cut the
+-- sentence in half.
+ALTER TABLE marketing_settings
+    DROP CONSTRAINT IF EXISTS marketing_settings_is_a_singleton;
+ALTER TABLE marketing_settings
+    ADD CONSTRAINT marketing_settings_is_a_singleton CHECK ("id" = 'marketing-settings');
+
+-- `applied_settings` holds at most ONE row: the installation's.
+--
+-- Same reasoning as above, and the same two plain statements. The row mirrors
+-- the settings the installation applied at its last start, and an installation
+-- serves one application, so there is exactly one configuration to record.
+ALTER TABLE applied_settings
+    DROP CONSTRAINT IF EXISTS applied_settings_is_a_singleton;
+ALTER TABLE applied_settings
+    ADD CONSTRAINT applied_settings_is_a_singleton CHECK ("id" = 'installation');
+
+-- A subscriber is live for at most ONE tenant, and a tenant has at most ONE
+-- live subscriber. A link that ended keeps its row with `unlinkedAt` set, so the
+-- tenants a subscriber had before stay in its history. Two partial unique
+-- indexes, because a link that is over must not count against the next one.
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_tenant
+    ON subscriber_tenants ("tenantId") WHERE "unlinkedAt" IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_tenants_live_per_subscriber
+    ON subscriber_tenants ("subscriberId") WHERE "unlinkedAt" IS NULL;
+
+-- A subscriber has at most ONE payment method in use. The one a newer payment
+-- method replaced keeps its row as `REPLACED`, so it does not count here.
+CREATE UNIQUE INDEX IF NOT EXISTS subscriber_payment_methods_active_per_subscriber
+    ON subscriber_payment_methods ("subscriberId") WHERE "status" = 'ACTIVE';
+
+-- A gateway session is confirmed ONCE.
+--
+-- A gateway delivers every event at least once, and it may report one session
+-- through more than one event — a completed form and the payment method behind
+-- it can arrive as two. `eventId` tells those apart, so both would be claimed,
+-- and both would record the session's payment method: for a sign-up that means
+-- a second tenant for one registration.
+--
+-- Both adapters claim with `ON CONFLICT DO NOTHING` and no conflict target, so
+-- this index turns the second confirmation into no row rather than an error,
+-- and the caller reads it as the duplicate it is. Partial on the kind, because
+-- a failed setup and an event SaaSiCat does not act on say nothing about the
+-- session being confirmed. A claim carrying no session does not collide:
+-- PostgreSQL counts nulls as distinct in a unique index.
+CREATE UNIQUE INDEX IF NOT EXISTS payment_event_log_confirmation_per_session
+    ON "PaymentEventLog" ("gatewayAccount", "sessionId")
+    WHERE "status" = 'payment-method-confirmed';
+
+-- Customer numbers count from 10001, so a number has five digits up to 99999
+-- and none reads as a count of subscribers. Two statements: the first makes
+-- 10001 where the sequence starts over, which a restart of its identity reads,
+-- and the second moves a sequence that has never handed out a number there. A
+-- second run finds the start already set and the sequence used, and an
+-- installation without the subscriber tables has no such sequence.
+ALTER SEQUENCE IF EXISTS "subscribers_customerSequence_seq" START WITH 10001;
+
+SELECT setval(format('%I.%I', schemaname, sequencename)::regclass, 10001, false)
+  FROM pg_sequences
+ WHERE schemaname = current_schema()
+   AND sequencename = 'subscribers_customerSequence_seq'
+   AND last_value IS NULL;