38 lines
1.1 KiB
Markdown
38 lines
1.1 KiB
Markdown
|
# SQLAlchemy Metadata Isolation
|
||
|
|
|
||
|
|
**Updated:** 2026-07-09
|
||
|
|
**Workplan:** `HUB-WP-0003-T03`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Rule
|
||
|
|
|
||
|
|
`hub_core.models.base.Base` owns metadata for **shared primitive tables only**
|
||
|
|
(domains, managed_repos, agent_messages, progress_events, capability_*, tpsc_*).
|
||
|
|
|
||
|
|
Each host runtime keeps its own declarative base for host-specific tables:
|
||
|
|
|
||
|
|
| Host | Base module | Session style |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| `state-hub` | `api.models.base.Base` | Sync |
|
||
|
|
| `core-hub` | `core_hub.db.Base` | Async |
|
||
|
|
|
||
|
|
Router factories never import host models from hub-core. Hosts inject models at
|
||
|
|
mount time:
|
||
|
|
|
||
|
|
```python
|
||
|
|
from hub_core.routers.domains import create_domains_router
|
||
|
|
|
||
|
|
app.include_router(create_domains_router(get_session, domain_model=Domain, ...))
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Why separate metadata
|
||
|
|
|
||
|
|
- Migration ownership stays with the host that runs the database.
|
||
|
|
- core-hub framework tables (`hubs`, `widgets`, …) must not appear in hub-core.
|
||
|
|
- state-hub dev-hub tables (workplans, tasks, …) must not appear in hub-core.
|
||
|
|
- Async and sync engines can coexist without forcing one base class.
|
||
|
|
|
||
|
|
See `the-custodian/docs/hub-ecosystem-architecture.md` for the full stack model.
|