Database Format

Pawn au Chocolat stores chess databases in SQLite format. This document describes the technical details of how data is stored and encoded.

Storage Format

Databases are stored in a single file using SQLite, a widely-used general-purpose database format. This choice enables compatibility with existing SQLite tools such as DB Browser for SQLite, allowing you to inspect and query your databases externally if needed.

Move Encoding

Rather than storing moves as human-readable text (which would consume significant storage space), the system employs binary encoding. Each move is encoded as a single byte, representing the index of the move in the list of legal moves at that position.

The move list generation uses Shakmaty, a chess library that provides consistent move ordering. The encoded byte value corresponds directly to the move's position within the generated list.

Database Schema

The database contains several tables for storing games, players, tournaments, and other metadata. Key tables include:

games

Stores game information including players, result, date, event, and the encoded move list.

players

Contains player names and their associated ELO ratings.

events

Stores tournament and event information for games.

positions

An optional index table that maps position hashes to games, enabling fast position search functionality.

Position Indexing

For fast position search, databases can be indexed. The indexing process:

  1. Iterates through all games in the database
  2. Computes a hash for each position reached during the game
  3. Stores the hash-to-game mapping in the positions table
  4. Enables O(1) lookup of games containing any specific position

Note: Indexing increases database size but significantly improves position search performance.

Puzzle Database Format

Puzzle databases follow a similar SQLite format with additional fields:

  • FEN position string for the starting position
  • Solution move sequence (UCI notation)
  • Difficulty rating
  • Theme tags (e.g., "fork", "pin", "discovered attack")
  • Source game reference (if generated from a game)