compat

func (Change) Validate ¶

func (change Change) Validate() error

func (*ConflictError) Error ¶

func (err *ConflictError) Error() string

func (Contract) Validate ¶

func (c Contract) Validate() error

func (Schema) Validate ¶

func (s Schema) Validate() error

func (*Store) ApplyChanges ¶

func (store *Store) ApplyChanges(ctx context.Context, schema Schema, changes []Change) error

ApplyChanges applies one ordered source stream atomically. Reapplying the same stream is safe: committed source sequences are recorded in the target transaction and skipped on subsequent attempts.

func (*Store) ApplyChangesTolerant ¶

func (store *Store) ApplyChangesTolerant(ctx context.Context, schema Schema, changes []Change) error

ApplyChangesTolerant applies one ordered source stream atomically with an opt-in, catch-up conflict policy. It exists for zero-window migrations whose capture-install → snapshot → catch-up sequence inherently overlaps: a change journaled after capture was installed may already have traveled inside the snapshot, so re-applying it would trip a spurious ConflictError even though the destination already reflects the change's final state.

The only difference from ApplyChanges is conflict resolution. A change is treated as already applied — and recorded in __compat_applied_changes as if it had just been applied — when the destination's CURRENT state already equals the change's FINAL state:

• insert: the row already exists and rowsEqual(after, actual);
• update: the row exists and rowsEqual(after, actual) even though Before no longer matches (the snapshot already carried the after state);
• delete: the row no longer exists.

Any other divergence remains a strict ConflictError: the tolerant mode is a catch-up convenience, not a bypass. ApplyChanges is unchanged.

func (*Store) ApplySchema ¶

func (store *Store) ApplySchema(ctx context.Context, schema Schema) error

func (*Store) CallRoutine ¶

func (store *Store) CallRoutine(ctx context.Context, schema Schema, name string, arguments map[string]Value) error

CallRoutine executes a canonical routine inside one transaction. The routine is stored in the canonical schema and therefore has the same implementation on SQLite and PostgreSQL instead of relying on engine-specific languages.

func (*Store) Close ¶

func (store *Store) Close() error

func (*Store) DropTable ¶ added in v0.2.0

func (store *Store) DropTable(ctx context.Context, table string) error

DropTable compiles (CompileDropTable) and executes the drop against this store's database. Engine errors — a missing table, or a foreign key from another table pointing at this one — are wrapped with the operation name and propagated; nothing is retried with CASCADE.

Note on the change-capture triggers installed by InstallChangeCapture: both engines drop the triggers attached to the table together with the table itself. On PostgreSQL the trigger FUNCTIONS (`__compat_capture_<table>_<kind>_fn`) are separate catalog objects and survive the drop, orphaned but harmless; re-running InstallChangeCapture recreates them with CREATE OR REPLACE. The rows already written to `__compat_change_journal` for the dropped table are also kept on both engines — the journal is an append-only history and this package never deletes data implicitly.

func (*Store) DropTableIfExists ¶ added in v0.2.0

func (store *Store) DropTableIfExists(ctx context.Context, table string) error

DropTableIfExists is DropTable with the idempotent statement; see CompileDropTableIfExists for why the choice is explicit in the name.

func (*Store) ExportSnapshot ¶

func (store *Store) ExportSnapshot(ctx context.Context, schema Schema) (Snapshot, error)

func (*Store) ImportSnapshot ¶

func (store *Store) ImportSnapshot(ctx context.Context, snapshot Snapshot) error

ImportSnapshot creates the canonical schema and inserts every canonical row. It is intentionally append-only; replacement and synchronization policies are handled by higher layers so data is never deleted implicitly.

func (*Store) InspectSchema ¶

func (store *Store) InspectSchema(ctx context.Context) (Inspection, error)

InspectSchema reconstructs the exact canonical schema when the database was managed by this compatibility layer. For external databases it falls back to catalog inspection and explicitly reports objects not yet translated.

func (*Store) InstallChangeCapture ¶

func (store *Store) InstallChangeCapture(ctx context.Context, schema Schema) error

InstallChangeCapture installs engine-native triggers which journal every committed row mutation in canonical, ordered form.

func (*Store) IsForeignKeyViolation ¶ added in v0.5.0

func (store *Store) IsForeignKeyViolation(err error) bool

IsForeignKeyViolation reports whether err is the engine's way of saying "a foreign key rejected this write". Like IsUniqueViolation it is a classifier over the driver error, not a new error type: nothing is wrapped, replaced or re-raised, and it is deliberately its sibling in shape.

It exists for the same reason: the portable-looking way to detect it is to match the text `FOREIGN KEY constraint failed`, which is SQLite's wording. PostgreSQL says `insert or update on table "..." violates foreign key constraint "..."` and reports SQLSTATE 23503, so a consumer that migrates keeps compiling and silently stops detecting the referential rejection: a clean 400 turns into a 500. The alternative the consumer is forced into without this predicate — checking that the referenced row exists BEFORE the write — is worse than merely verbose: it leaves a race window, because the referenced row can disappear between the check and the write, and the honest rejection then arrives as a 500.

Classification is by **structured code**, never by message text:

• SQLite (modernc.org/sqlite): `*sqlite.Error` with the extended result code SQLITE_CONSTRAINT_FOREIGNKEY (787) **or** SQLITE_CONSTRAINT_TRIGGER (1811). The sibling constraint codes SQLITE_CONSTRAINT_UNIQUE (2067) and SQLITE_CONSTRAINT_PRIMARYKEY (1555) are different rejections and are not folded in; 1555 belongs to IsUniqueViolation because a primary key IS a unique constraint.
• PostgreSQL (github.com/jackc/pgx/v5): `*pgconn.PgError` with SQLSTATE 23503 (foreign_key_violation).

**Why 1811 is in the SQLite list — measured, not assumed.** SQLite implements a foreign key declared `ON DELETE RESTRICT` / `ON UPDATE RESTRICT` with its internal trigger machinery, so the rejection on the PARENT side carries SQLITE_CONSTRAINT_TRIGGER instead of SQLITE_CONSTRAINT_FOREIGNKEY. With DDL identical except for the referential action (SQLite 3, modernc driver):

NO ACTION  INSERT child with a missing parent -> FOREIGN KEY constraint failed   787
NO ACTION  DELETE the referenced parent       -> FOREIGN KEY constraint failed   787
NO ACTION  UPDATE the referenced parent key   -> FOREIGN KEY constraint failed   787
RESTRICT   INSERT child with a missing parent -> FOREIGN KEY constraint failed   787
RESTRICT   DELETE the referenced parent       -> FOREIGN KEY constraint failed   1811
RESTRICT   UPDATE the referenced parent key   -> FOREIGN KEY constraint failed   1811

The **message text is byte-identical in all six**, so it could not separate them even if this predicate were willing to read it (it is not). PostgreSQL answers 23503 to every one of those writes. Leaving 1811 out therefore made the two engines classify the SAME canonical schema and the SAME operation differently — the silent divergence this package exists to prevent — and it was found by a real consumer that declares RESTRICT. `no_action` (declared or omitted) stays at 787; `cascade` and `set_null` do not reject at all on the parent side (they propagate), so they never reach this predicate — except that a `set_null` into a NOT NULL column fails with SQLITE_CONSTRAINT_NOTNULL (1299), which is correctly NOT classified here.

**The residue this buys, stated rather than hidden.** 1811 has a second producer: a trigger that aborts with RAISE(ABORT|FAIL|ROLLBACK). It is unreachable from the canonical grammar — a trigger action is one of exactly three kinds (INSERT/UPDATE/DELETE) and the expression grammar is a closed allowlist by node kind with no RAISE, so a schema this package compiles cannot emit one (pinned by TestCanonicalTriggerGrammarCannotRaiseAbort). A consumer CAN still create its own trigger with raw SQL against store.DB, and if that trigger aborts, this predicate will call it a foreign-key violation. That is an accepted, bounded consequence — raw consumer SQL is already outside the package's guarantees — and it is fixed by a test (TestConsumerRawTriggerAbortClassifiesAsForeignKeyViolation) so it stays measured and visible instead of becoming a future surprise. The alternative, separating the two by message text, is exactly what this classifier refuses to do, and would not work anyway: the RESTRICT text is the ordinary `FOREIGN KEY constraint failed` and the RAISE text is whatever the consumer wrote.

Both lookups go through errors.As, so an error the consumer has wrapped — `fmt.Errorf("save entry: %w", err)`, which is how it will actually arrive after crossing a repository layer — is still classified. A nil error is false.

It dispatches on this store's engine rather than trying both drivers, for the same reason IsUniqueViolation does: the answer must be the one the engine actually connected to would give, and a PostgreSQL error reaching a SQLite store is a caller bug that should not be papered over by a lucky match.

**Documented limitation — it cannot tell you WHICH DIRECTION of the violation happened.** Both engines report the very same code for the two opposite cases:

• writing a row whose foreign key points at a parent that does not exist (the caller sent a bad reference — usually a 400), and
• deleting or updating a parent row that a child still references (the caller's target is in use — usually a 409).

PostgreSQL raises 23503 for both, differing only in the message text and in which table it names. SQLite raises 787 for both when the key is NO ACTION, and 787 (child side) versus 1811 (parent side) when it is RESTRICT — a difference that is an artifact of the referential action, NOT a usable direction signal: it does not exist on PostgreSQL and it does not exist on SQLite for a NO ACTION key, so a caller keying off it would be writing code that means different things per engine and per DDL. Telling the directions apart would therefore require reading the message or the constraint name — exactly the thing this predicate exists to avoid — so it is documented rather than resolved, in the same spirit as IsUniqueViolation documenting that it cannot say WHICH unique constraint was violated. A caller that must answer 400 vs 409 has to know it from the operation it issued (an INSERT of a child cannot be a "still referenced" failure; a DELETE of a parent cannot be a "missing parent" one), not from this boolean.

**Reachability note for SQLite.** SQLite only enforces foreign keys when the connection has `PRAGMA foreign_keys` on, and it is OFF by default, so with it off there would be no violation to classify at all. It is not off here: OpenSQLite pins `_pragma=foreign_keys(1)` in the DSN and caps the pool at a single connection (the pragma is connection-scoped), which is the same guarantee DropTable already relies on. A `Store` built by hand around a `*sql.DB` opened without that pragma is outside the package's contract; there the write simply succeeds and this predicate is never consulted.

func (*Store) IsUniqueViolation ¶ added in v0.4.0

func (store *Store) IsUniqueViolation(err error) bool

IsUniqueViolation reports whether err is the engine's way of saying "a unique constraint rejected this write". It is a classifier over the driver error, not a new error type: nothing is wrapped, replaced or re-raised.

It exists because the portable-looking way to detect a duplicate is to match the text `UNIQUE constraint failed`, which is SQLite's wording. PostgreSQL says `duplicate key value violates unique constraint "..."` and reports SQLSTATE 23505, so a consumer that migrates keeps compiling and silently stops detecting duplicates: a clean 400 turns into a 500, and nobody finds out until a user duplicates a value in production. That regression has no compiler signal, which is what makes it worth a primitive.

Classification is by **structured code**, never by message text:

• SQLite (modernc.org/sqlite): `*sqlite.Error` with the extended result code SQLITE_CONSTRAINT_UNIQUE (2067) or SQLITE_CONSTRAINT_PRIMARYKEY (1555). Both are included on purpose — a primary key IS a unique constraint, and PostgreSQL reports a duplicate primary key with the very same 23505 it uses for a UNIQUE index. Leaving 1555 out would make the two engines disagree on the identical write.
• PostgreSQL (github.com/jackc/pgx/v5): `*pgconn.PgError` with SQLSTATE 23505 (unique_violation), which covers both UNIQUE and PRIMARY KEY.

Both lookups go through errors.As, so an error the consumer has wrapped — `fmt.Errorf("save entry: %w", err)`, which is how it will actually arrive after crossing a repository layer — is still classified. A nil error is false.

It dispatches on this store's engine rather than trying both drivers: the answer must be the one the engine actually connected to would give, and a PostgreSQL error reaching a SQLite store is a bug in the caller that should not be papered over by a lucky match.

**Documented limitation — it returns a boolean, and cannot tell you WHICH constraint was violated.** That is a deliberate stop, not an oversight: the engines report different granularities. SQLite names the `table.column` list in the message; PostgreSQL names the CONSTRAINT, which it also auto-generates when the declaration does not fix one (`zzt_email_key`, `zzt_pkey`). Exposing "which constraint" would mean mapping engine-chosen names back onto the canonical schema — a larger API with its own ambiguities. The consequence the caller must know: **with two unique constraints on the same table you cannot tell which one was violated**, on either engine. If a caller needs to distinguish them (to report a different field to the user), the portable way is to check the candidate values before the write, not to parse this error.

func (*Store) QueryRoutine ¶ added in v0.3.0

func (store *Store) QueryRoutine(ctx context.Context, schema Schema, name string, arguments map[string]Value) ([]Row, error)

QueryRoutine executes a canonical READ routine and returns canonical rows. It is the read counterpart of CallRoutine, which stays write-only and unchanged: CallRoutine returns only error and has production consumers, so reading is new, additive surface rather than a signature change.

The routine must contain exactly one action, of kind "select" (enforced by Schema.Validate too). The statement is composed from pieces that already exist: compileRoutineWhere for the filter — which emits the right placeholder per engine and binds every caller value instead of inlining it, and already maps LIKE to ILIKE on PostgreSQL — and the exportTable pattern for reading, which canonicalizes every scanned value by type family. Here the family comes from the action's DECLARED output columns, because a view has no output types.

Every identifier (relation, output columns, order keys) goes through quoteIdentifier; every caller value, including LIMIT and OFFSET, is bound as a placeholder. Nothing supplied by the caller is ever concatenated into the SQL.

func (*Store) ReadCapturedChanges ¶

func (store *Store) ReadCapturedChanges(ctx context.Context, schema Schema, after uint64, limit int) ([]Change, error)

ReadCapturedChanges reads an ordered source stream after the supplied cursor.

func (*Store) SearchText ¶

func (store *Store) SearchText(ctx context.Context, table, idColumn string, textColumns []string, query string) ([]SearchResult, error)

SearchText implements deterministic Unicode token matching in the common Go runtime. It does not delegate tokenization or ranking to either database.

func (*Store) TableExists ¶ added in v0.4.0

func (store *Store) TableExists(ctx context.Context, table string) (bool, error)

TableExists reports whether the table physically exists in the engine's own catalog: `sqlite_master` on SQLite, `pg_class` on PostgreSQL (that relation does not exist there, and `sqlite_master` has no PostgreSQL equivalent, which is exactly why the consumer cannot write this once).

It does NOT consult `__compat_schema`, and that is the whole point of the method rather than an implementation detail. InspectSchema prefers the stored canonical metadata over the physical catalog, which is right for the canonical path and wrong in precisely the situations where this question gets asked: a hand-written migration, or a half-finished table rebuild, where the metadata is the thing about to be rewritten and therefore cannot be the oracle. That cache has already caused four incidents across this family of projects. This method is the honest way out — it asks the engine, not the cache — and callers should read a disagreement between TableExists and InspectSchema as a real signal, not as a bug.

Engine notes, verified against real engines rather than assumed:

• PostgreSQL: the lookup is restricted to `current_schema()`, which is the first existing schema of the session `search_path` and therefore the exact place an unqualified `CREATE TABLE` from ApplySchema lands. Asking any other schema of the database — or asking without a schema filter — would answer a different question than "did ApplySchema create it here?".
• A VIEW with the searched name answers false on both engines: SQLite filters `type = 'table'` and PostgreSQL filters `relkind IN ('r','p')` (ordinary and partitioned tables). `information_schema.tables` is deliberately not used on PostgreSQL because it also lists views.
• The name is matched as a value through a bound placeholder, never spliced into the SQL, so it needs no quoting and a name containing a quote or a semicolon is simply a name. It is matched **byte for byte** on both engines: this package quotes every identifier it emits, so `CREATE TABLE "Foo"` stores `Foo` in both catalogs and neither engine folds the case. `TableExists(ctx, "foo")` is therefore false for a table declared as `Foo`, identically on SQLite and PostgreSQL — pass the name exactly as it was declared in the canonical schema.

The four reserved internal tables are NOT rejected here (unlike DropTable): the question is physical, and `__compat_schema` really does exist once this package has written it.

func (Target) Validate ¶

func (t Target) Validate() error

func (Version) String ¶

func (v Version) String() string

func (Version) Valid ¶

func (v Version) Valid() bool