QuoteForge/bible-local/03-database.md

03 - Database

SQLite

SQLite is the local runtime database.

Main tables:

Table	Purpose
local_components	synced component metadata
local_pricelists	local pricelist headers
local_pricelist_items	local pricelist rows, the only runtime price source
local_projects	user projects
local_configurations	user configurations
local_configuration_versions	immutable revision snapshots
local_partnumber_books	partnumber book headers
local_partnumber_book_items	PN -> LOT catalog payload
pending_changes	sync queue
connection_settings	encrypted MariaDB connection settings
app_settings	local app state
local_schema_migrations	applied local migration markers

Rules:

• cache tables may be rebuilt if local migration recovery requires it;
• user-authored tables must not be dropped as a recovery shortcut;
• local_pricelist_items is the only valid runtime source of prices;
• configuration items and vendor_spec are stored as JSON payloads inside configuration rows.

MariaDB

MariaDB is the central sync database.

Runtime read permissions:

• lot
• qt_lot_metadata
• qt_categories
• qt_pricelists
• qt_pricelist_items
• stock_log
• qt_partnumber_books
• qt_partnumber_book_items

Runtime read/write permissions:

• qt_projects
• qt_configurations
• qt_client_schema_state
• qt_pricelist_sync_status

Insert-only tracking:

• qt_vendor_partnumber_seen

Rules:

• QuoteForge runtime must not depend on any removed legacy BOM tables;
• stock enrichment happens during sync and is persisted into SQLite;
• normal UI requests must not query MariaDB tables directly.

Migrations

SQLite:

• schema creation and additive changes go through GORM AutoMigrate;
• data fixes, index repair, and one-off rewrites go through runLocalMigrations;
• local migration state is tracked in local_schema_migrations.

MariaDB:

• SQL files live in migrations/;
• they are applied by go run ./cmd/qfs -migrate.