Database Migration Procedures
Relevant source files
The following files were used as context for generating this wiki page:
Database Migration Procedures in flext-quality govern how the project manages schema changes and data persistence using a local Dolt database. This system integrates with the Beads (bd) issue tracker, where issues and project state live within a Dolt DB and sync via a git remote.
The migration workflow ensures that architectural state remains consistent across development environments by using a local database that supports version control operations like branching, merging, and pushing.
Sources: CLAUDE.md:10-23, AGENTS.md:144-156
Architectural Overview
The project utilizes Dolt as its underlying database engine for issue tracking and state management. Unlike traditional SQL databases, migrations and data syncs are handled through git-like commands via the bd (Beads) CLI.
The diagram shows the flow of data from the developer through the Beads CLI to the local Dolt database, which synchronizes with a specific git remote reference.
Sources: CLAUDE.md:20-23, AGENTS.md:154-156
Migration and Sync Workflow
Migrations in this context refer to the synchronization of the issue database and state between local and remote environments. Developers interact with the database using the bd utility.
Standard Operations
- Initialization: Run
bd primeto initialize the workflow context and ensure the local database is ready. - State Management: Use
bd ready,bd claim, andbd closeto modify the database state. - Synchronization: Push local changes to the remote to share state with other agents or team members.
Manual Synchronization Commands
When a manual sync is required, use the following commands:
bd dolt push: Pushes the current Dolt database state to the remoterefs/dolt/data.bd prime: Refreshes the local context from the remote state.
Sources: CLAUDE.md:10-23, AGENTS.md:144-162, AGENTS.md:188-195
Integration with Quality Gates
Database state and migrations are verified as part of the session completion protocol. Before a session is closed, the developer or agent must ensure the database is synchronized.
| Step | Action | Command |
|---|---|---|
| 1 | File remaining work | bd remember |
| 2 | Update issue status | bd close <id> |
| 3 | Sync Database | bd dolt push |
| 4 | Sync Git | git push |
Sources: CLAUDE.md:65-80, AGENTS.md:162-178
Maintenance and Backup Configuration
The MaintenanceConfig and related models define how maintenance tasks, including potential database cleanup or backups, are configured within the project.
This class diagram illustrates the configuration structure for scheduled maintenance and backup tasks as defined in the domain models.
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:112-149
Backup Fields and Descriptions
| Field | Type | Description |
|---|---|---|
backup_dir | str | Directory where backups created during maintenance are stored. |
reports_dir | str | Directory where maintenance reports are written. |
max_retries | int | Maximum retries for a failed maintenance task (Default: 3). |
retry_delay | int | Delay in seconds between retry attempts (Default: 60). |
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:73-89, src/flext_quality/_models/flextqualitymodels_part_02.py:112-124
Testing Database Integrations
The test suite includes specific categories for database and repository testing to ensure migration integrity. Integration tests verify the interaction with the persistence layer.
- Repository Testing: Located in
tests/integration/, these tests validate data persistence and retrieval. - Database Fixtures: Managed in
tests/conftest.py, these provide setup and teardown for the test database environment. - Oracle Database: Some tests (marked
@pytest.mark.oracle) require a shared Oracle database for external integrations.
Sources: tests/README.md:38-48, tests/README.md:154-158, pyproject.toml:500-510
Conclusion
Database Migration Procedures in flext-quality rely on the Beads/Dolt ecosystem to maintain a versioned, synchronizable state for project tracking. By following the bd workflow and ensuring proper synchronization with refs/dolt/data, developers maintain consistency between the local development environment and the remote repository.