mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: unify installation model catalog

Browse Source
This commit is contained in:
Codex
2026-09-02 18:45:33 +02:00
parent ae053961a3
commit 7b7927bfe5
169 changed files with 3696 additions and 4572 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations/database-management.md
+52 -3
View File
@@ -70,14 +70,63 @@ capability, malformed snapshot, or connector error applies no catalog changes. S
## Synchronize authoritative schema metadata
Start a synchronization from a database or a selected table set. The available scopes are tables,
columns, relationships, and all. One database can have only one active catalog operation at a
time; cleanup shares this exclusion.
Schema synchronization reads the external database and reconciles the installation-local catalog.
It never changes the source database. The available synchronization scopes are **tables**,
**columns**, **relationships**, and **all**, but the UI exposes them at different levels:
| Location | Action | Effective scope |
| --- | --- | --- |
| Database view | **Synchronize tables** | All tables in the selected database |
| Database view | **Synchronize relationships** | All physical foreign-key relationships in the selected database |
| Database view | **Synchronize all** | Tables, columns, and physical relationships in the selected database |
| Tables view | **Synchronize database tables** | All tables in the selected database. Selecting a table enables the action, but does not narrow its scope. |
| Tables view | **Synchronize columns for selected tables** | Columns belonging to the selected tables |
| Columns view | **Synchronize columns for this table** | All columns belonging to the table currently open. Selecting at least one column enables the action, but does not narrow its scope to that column. |
There is no database-level column action and no synchronization action for an individual column.
The selection requirement in the tables and columns views controls whether the action selector can
be used; it is not always the same as the synchronization target. The **Sync all** button in the
tables view is the direct shortcut for the full-database scope.
Before starting any synchronization, run **Test connection**. Synchronization is rejected when
the binding is unreachable or its tested version is older than the current binding configuration.
Only one catalog operation can be active for a database at a time; explicit cleanup shares this
exclusion.
### What a synchronization does
Every run first creates a durable queued operation and reads a schema snapshot. The scan reports
these phases:
1. Connect to the database.
2. Read tables.
3. Read columns and primary-key positions.
4. Read foreign-key relationships.
5. Calculate the planned catalog difference.
6. Apply only the requested scope.
The scan currently reads the complete physical snapshot, including foreign keys, even when the
requested scope is only tables or columns. This is required by the introspection contract and is
why the log can mention foreign-key reading during a table synchronization. Reading those keys
does not by itself create or update catalog relationships:
- **Synchronize tables** writes table membership and source comments. If a table disappears, its
catalog columns and physical relationships are removed through the table cascade.
- **Synchronize columns** writes column membership and structural attributes for all tables or for
the selected table subset. It does not write physical relationships.
- **Synchronize relationships** writes the physical relationships derived from the source foreign
keys. It does not create generated or manual logical relationships.
- **Synchronize all** applies all three scopes and marks the database schema version as fully
synchronized.
The run scans first and publishes a durable operation. If it detects a destructive difference, it
requires confirmation and re-scans before applying. You can cancel before apply; completed and
failed runs remain in history. The live log is delivered over SSE with a polling fallback.
The synchronization history records the requested scope, progress phases, planned changes,
confirmation, result counts, and errors. Closing the history drawer does not cancel a running
operation; it can be reopened from the database synchronization history control.
Explicit cleanup is different from source synchronization: administrators can clear selected
table/relationship or column/relationship catalog metadata without changing the external source,
the connection binding, or secrets. Deleting a table cascades to its columns and relationships.
docs/operations/workspaces.md
+10 -3
View File
@@ -16,13 +16,20 @@ The root catalog has `schema_version: 1` and an ordered list of workspace identi
<!-- non-workspace-migration:end -->
<!-- workspace-descriptor-contract:start -->
Schema v3 is the only accepted workspace descriptor. Schema v1 and v2 workspace descriptors are
rejected before activation. Each catalog entry must have a matching descriptor at
Schema v4 is the only accepted workspace descriptor. Schema v1, v2, and v3 workspace descriptors
are rejected before activation. Each catalog entry must have a matching descriptor at
`<id>/workspace.yaml` in the same Git commit. The application validates a complete candidate
revision and activates it atomically; invalid content leaves the preceding active revision in
place.
<!-- workspace-descriptor-contract:end -->
<!-- non-workspace-migration:start -->
To convert a v3 descriptor before committing it, set `workspace.schema_version` to `4`, remove
`llm_policy`, and remove `semantic_index`. Database, Evidence, diagnostics, and binding data remain
unchanged. Validate the resulting v4 repository revision before activation; ThothII never rewrites
the curator-owned repository during pull.
<!-- non-workspace-migration:end -->
## Operator sequence
1. Curate and push a complete repository revision. Do not put DWH passwords, API keys, private
@@ -58,7 +65,7 @@ tht --installation "$INSTALLATION" workspace preprocess run \
The contract gives exact validation, exit code, and JSON rules in
[Workspace preprocessing CLI](../contracts/workspace-preprocessing-cli.md). For Evidence source
forms and the schema-v3 descriptor contract, see
forms and the schema-v4 descriptor contract, see
[Workspace Evidence v3](../contracts/workspace-evidence-v3.md).
## Transport and revision rules