Skip to content

Database {#architecture_database}

Database is the persistence and query layer above Core. It stores chess games in database formats, keeps searchable metadata resident in memory, resolves stored name identifiers, and materialises editable @ref scid::core::Game "scid::core::Game" values when callers need full game content.

@startuml database-overview skinparam backgroundColor #FFFFFF skinparam shadowing false skinparam linetype ortho skinparam defaultFontName Cantarel skinparam defaultFontSize 10 skinparam roundcorner 8 skinparam Nodesep 62 skinparam Ranksep 54 skinparam ArrowColor #4B5563 skinparam RectangleBorderColor #6B7280 skinparam RectangleBackgroundColor #EEF2FF

left to right direction

rectangle "Core game values" as CoreGame #EEF2FF

rectangle "Database session" as Session #FFF7ED

rectangle "Database metadata" as Metadata #EEF2FF

rectangle "Name registry" as Names #EEF2FF

rectangle "Filters and views" as Filters #EEF2FF

rectangle "Tree statistics" as Tree #EEF2FF

rectangle "Storage codecs" as Codec #EEF2FF

rectangle "Database files" as Files #EEF2FF

CoreGame -[hidden]right- Session Session -[hidden]right- Metadata Metadata -[hidden]right- Names Filters -[hidden]right- Tree Codec -[hidden]right- Files Session -[hidden]down- Filters Metadata -[hidden]down- Tree Names -[hidden]down- Files

CoreGame --> Session : exchanges Session --> Metadata : owns Session --> Names : resolves Session --> Filters : narrows Filters --> Tree : ply hints Metadata --> Tree : result / rating / year Session --> Codec : delegates Codec --> Files : persists @enduml

\htmlonly

\endhtmlonly - @subpage architecture_database_scidbase "scidBaseT" - @subpage architecture_database_metadata "Database Metadata" - @subpage architecture_database_name_registry "Name Registry" - @subpage architecture_database_filters_views "Filters and Views" - @subpage architecture_database_tree "Tree" - @subpage architecture_database_storage_codecs "Storage Codecs" - @subpage architecture_database_introduction "Introduction" - @subpage architecture_database_scid5_file_format "SCID5 File Format" \htmlonly

\endhtmlonly

@ref architecture_database_scidbase "scidBaseT" is the session facade. It owns the open database state, coordinates codecs, filters, sort caches and metadata, and is the usual public entry point for database work.

@ref architecture_database_metadata "Database metadata" is the resident catalog behind browsing, filtering, sorting and metadata-only updates. It lets callers answer many database questions without decoding a complete @ref scid::core::Game "Game".

@ref architecture_database_name_registry "Name registry" owns the canonical player, event, site and round strings. Metadata stores compact name IDs; callers resolve those IDs through the registry when they need display text or PGN roster tags.

@ref architecture_database_filters_views "Filters and views" define which games are visible to list, search, tree and bulk-update workflows. Filters are stored as per-game byte values rather than plain booleans, so a visible game can also carry a ply hint used by position and tree features.

@ref architecture_database_tree "Tree" turns a position-search filter into opening-style move statistics. It groups the next move played by each visible game and reports count, score, rating and year aggregates for each candidate.

@ref architecture_database_storage_codecs "Storage codecs" map the resident database session to concrete files or in-memory storage. They persist the index entries, name registry and encoded game records while the public session API continues to exchange Core game values and metadata snapshots.

Full game content is loaded on demand. Listing, sorting, filtering, flag updates, many metadata edits, and search prefilters can work from metadata alone. Loading or saving a complete game crosses into Core: the codec decodes stored bytes into @ref scid::core::Game "scid::core::Game", or encodes a @ref scid::core::Game "Game" back into the active database format.