feat: implement metadata catalog database management

2026-08-27 22:43:54 +02:00
parent 705af3aeb2
commit 79c4c925b5
86 changed files with 12566 additions and 135 deletions
@@ -0,0 +1,27 @@
+# Hard-delete catalog tables during synchronization
+
+An explicit Table Synchronization makes the Catalog Table membership exactly match a successful
+observation of the Workspace Database: new tables are created, source metadata is refreshed, and
+absent tables plus their future column and relationship children are permanently deleted. Physical
+membership cannot be edited manually.
+
+The external scan runs without holding a catalog transaction. Its diff is applied atomically only
+while the Workspace Database version still matches the scanned binding. Failed scans change
+nothing, and a non-empty removal set must exactly match the names confirmed by the operator; a
+changed second scan therefore requires a new confirmation.
+
+## Considered Options
+
+- Soft deletion would preserve descriptions across accidental removals, but would add hidden state,
+  restore rules, and ambiguity about whether the catalog still represents the physical schema.
+- Rename detection based on similarity would preserve metadata in some cases, but could silently
+  attach curated semantics to the wrong physical table.
+- Append-only introspection, as in the legacy importer, would leave stale tables in the catalog and
+  make downstream schema linking unreliable.
+
+## Consequences
+
+A physical rename is delete plus create and loses curated metadata. The UI previews permanent
+deletions, and future Catalog Column and Relationship records must cascade with their table. The
+catalog remains an exact projection of the last accepted successful scan without tombstones or
+restore lifecycle.