blunderDB

blunderDB is a software for creating backgammon position databases. Its main strength is to provide a single place where a player can aggregate the positions he or she has encountered (online, in tournaments) and be able to review these positions by filtering them with various filters that can be arbitrarily combined. blunderDB can also be used to create catalogs of reference positions.

The present documentation is structured as follows:

• the download and installation section explains how to obtain and run blunderDB.

• the manual describes the general functioning of blunderDB and how it should be used.

• the user guide is a practical introduction for quickly using blunderDB.

• the list of commands as well as the list of keyboard shortcuts enables efficient use of blunderDB.

• the command line interface (CLI) section describes the available commands for bulk import, automation, and scripting.

• The FAQ provides answers to the most frequently asked questions.

Version history

Version	Date	Cause and/or nature of changes
0.1.0	December 31, 2024	Beta version
0.2.0	January 6, 2025	Various bug fixes. Addition of match/TP/GV tables. Added search filters (moves, cube decisions, date). Added metadata for positions. Import/export functionality between blunderDB instances. Added metadata functionality for databases. Introduction of version numbers (database and application).
0.3.0	January 27, 2025	Various bug fixes. Automatically saves the window size. Imports any comments from XG.
0.4.0	February 3, 2025	Various bug fixes. Adding an icon for blunderDB. Filter corrections. Adding macOS support.
0.5.0	February 4, 2025	Addition of new filters (mirror, non-contact, jan blot, outfield blot).
0.6.0	February 13, 2025	Add filter library. Displaying the database version in the metadata.
0.7.0	February 16, 2025	Support Japanese and German XG exports.
0.8.0	May 3, 2025	New button to hide pipcount. Button to load random position.
0.9.0	November 02, 2025	Fix filter library bug. Database import/export. Display arrows for selected moves. Keyboard shortcuts for import/export.
0.10.0	February 25, 2026	Match import from eXtreme Gammon (XG/XGP), GNUbg (SGF), Jellyfish (MAT/TXT) and BGBlitz (BGF/TXT). Match navigation: browse through moves of an imported match, with played move highlighting. Match panel: list, sort, inline editing, player swap, tournament assignment. Recursive folder import and drag & drop import. EPC (Effective Pip Count) calculator with built-in GNUbg bearoff database. Collections: custom position grouping. Tournaments: group matches by event. Save and restore session state (last search, current position). Automatic database schema migration. Multi-engine display in analysis. Player 1 error/blunder filter in searches. Database export with granular selection (matches, collections, tournaments, played moves). Match navigation button. Pipcount display in match navigation. Complete command-line interface (CLI). Automatic reopening of the last database. Improved toolbar and icons.
0.11.0	March 6, 2026	Filter to search within currently filtered positions. Add match and tournament filters. Automatic board clearing when opening the search panel.
0.12.0	March 19, 2026	Import eXtreme Gammon position files (XGP) with analysis.
0.13.0	March 28, 2026	Interface simplification: match and collection navigation is now done directly through panels. Command line integrated into the status bar. Console panel renamed to Log panel. Dedicated EPC panel in the bottom panel. Copy/paste position in the search panel. Drag and drop to reorder collections, positions within collections, and matches within tournaments. Tournament column in the match panel with inline editing. Automatic display of the analysis panel after a search.
0.14.0	March 30, 2026	Dedicated Anki panel for spaced repetition study (FSRS algorithm). Import comments from XG files.
0.15.0	March 31, 2026	Export position as PNG image to clipboard (board only via Ctrl+X, or board with analysis via Ctrl+X Ctrl+X).
0.16.0	April 18, 2026	Database schema v2.0.0: Zobrist-hashed position deduplication, denormalized filter columns, bitboard pattern pre-filter, WAL journaling. Batch import >=3x faster, filtered search <=100 ms on 10k+ positions. NOTE: DB files created with v0.16.0 cannot be opened by older versions; old DBs are auto-migrated in place (back up first).
0.17.0	April 20, 2026	Storage optimization: zlib compression of analysis data (~80% reduction), compact board encoding (~90% position state size reduction). Added 5 missing indexes for search performance. Fixed cube error search returning wrong results. Fixed EDIT mode after search returns no results. Restored search panel state when switching tabs. Removed 62 debug print statements from hot search/filter paths.
0.18.0	April 20, 2026	Major codebase refactoring: split db.go (10k lines) into 19 domain-focused files, extracted 7 service modules from App.svelte (4,888→469 lines), consolidated modal/panel stores. Full migration to Svelte 5 runes. Replaced 9 table modals with a generic DataTableModal component. Added ESLint + Prettier + vitest (125 frontend tests) with CI enforcement. WCAG 2.1 AA accessibility baseline (visible focus, ARIA roles, keyboard navigation). Upgraded Database mutex to RWMutex for better read concurrency. Complete CLI documentation (CLI_USAGE.md + Sphinx FR/EN). Rewrote README. Resolved all ESLint warnings (46→0) and Vite build warnings (6→0).
0.19.0	May 7, 2026	Added Stats panel: PR (Performance Rate), Snowie Error Rate and MWC cost (Match Winning Chance cost) indicators, filter bar (player, tournament, dates, decision type, match length), Dashboard tab with level cards / rolling PR / top blunders, Progression tab with per-tournament curve and per-match scatter plot, Errors tab with cube-action breakdown and error magnitude histogram. Interactive drill-down to positions / matches / tournaments from all indicators. Instant PR / MWC toggle. CLI command list –type stats. Alignment of PR / Snowie ER / MWC indicators with eXtremeGammon and gnuBG (0.16 equity threshold for close cubes). Fixed cube_error calculation for Double/Pass decisions. Statistics model documentation (Annex: Statistics model — XG / gnuBG / blunderDB alignment). See Stats Panel.
0.20.0	May 31, 2026	Added the Except exclusion structure to the search panel: excludes positions that contain any of the drawn checkers, with a « must be empty » marker (double-click) and no limit on the number of checkers per point (command x). Added a « first die only » option to the dice roll filter (D1 variant, –dice CLI option). Comments panel: the input field is focused automatically on open and the edit / delete buttons are always visible. Fixed the « Search Text » filter that failed to match all comment tags.
0.21.0	June 1, 2026	Interface internationalisation: the whole of blunderDB (toolbar, panels, messages, help) can now be displayed in English, French, German, Italian, Spanish, Finnish, Japanese, Greek or Russian, as you choose. Added a configuration window, accessible through a gear-shaped button in the toolbar, to select the language. The language choice is kept across sessions. See Configuration.
0.22.0	June 2, 2026	Added a headless (server) mode, advanced and optional, complementing the desktop application: a serve daemon exposing the engine over HTTP + JSON, a multi-user PostgreSQL backend with per-tenant isolation (and optional Row-Level Security), a migrate command to transfer a SQLite database to PostgreSQL, and a generic call dispatcher giving command-line access to every storage operation. Import of single positions from new formats (eXtreme Gammon .xgp, BGBlitz text, native .db library) with enrichment of duplicates across formats. Fixes: panels no longer raise an error when no database is open, and the Comments panel no longer loops on opening. See Headless mode (server).
0.23.0	June 5, 2026	Added guided tours of the interface (general tour, search, matches, tournaments), replayable from the toolbar or with the tour command, and a sample database loadable with the demo command to explore the tool without importing your own games. Customisation of the board colours (background, border, points, checkers, dice, doubling cube) from the configuration window. Command-line autocompletion (TAB key). Search panel: explicit control over the decision type (Checker / Cube), with a Double / No double or Take / Pass sub-type for cube decisions, synchronised with the board; the offered cube is shown in the centre of the board for take/pass decisions. Search for a position by its identifier (id filter). Fixed the attribution of the cube error to player 1. See Guided tours and sample database.
0.24.0	June 6, 2026	Added a container image (Docker) for headless mode: a dedicated serve entry point and a Dockerfile.serve producing a static binary with no graphical interface, to deploy the blunderDB engine as a service behind a reverse proxy. See Headless mode (server).
0.25.0	June 7, 2026	Server (headless) mode: two new methods to rebuild a position without storing it — positions.fromXGID decodes an XGID string into a position, and positions.fromXGP reads a single-position .xgp file. See Headless mode (server).
0.26.0	June 9, 2026	Interface display settings in the configuration window: a scale slider to enlarge or shrink the whole interface, and a panel position choice (bottom, side or automatic) to make better use of wide screens. Added an information bar above the board showing the players and the match context (event, location, round, date, length). When a database is opened, the matches panel is shown right away and the review starts on the first position. Keyboard shortcuts are now independent of the keyboard layout (AZERTY, QWERTY, QWERTZ…). Fixed XGID decoding (Jacoby/Beaver flags and cube value). See Configuration.
0.27.0	June 13, 2026	Anki panel: a new free-drill (cram) mode, available from the Cram button next to Study, which serves random positions from the deck without altering the spaced-repetition schedule — ideal for warming up before a tournament or intensively reviewing a deck without disturbing its ordering. Search: a new blunders command (alias bl) that loads your worst mistakes (equity/MWC) straight into the analysis view, with an optional number to choose how many (bl 50); a new player filter pl'name' that finds every position from a match involving a given player, on either side; and tooltips that, on hovering each search-panel filter, show the corresponding command token. Server (headless) mode: new matches.movesByMatch (all the moves of a match in a single call) and positions.epc (Effective Pip Count for both players) methods. See Anki Panel and List of commands.
0.28.0	July 15, 2026	Search panel: unified “Matches & Tournaments” filter replacing the free-text ID fields with a picker window (text-filterable checkbox lists, All/None buttons, checking a tournament checks its member matches) — faster on large databases, since the Matches tab and Tournaments view now only recompute PR/MWC badges for the matches actually displayed; cli list --type tournaments closes the matching parity gap. New “Individually Imported” filter (checkbox in the Other group, or the i command-line token, s i; also available in the CLI via --individual) to find a position that was saved or imported on its own rather than buried in a match import. Fixed a data-loss bug: deleting a match no longer deletes positions that were individually imported, added to a collection, or added to an Anki deck, even when the deleted match also contained them. Server mode (headless): six new methods for the Anki spaced-repetition scheduler — review log (anki.reviewLog), due-card forecast (anki.forecast), suspend / bury / remove a card (anki.suspendCard, anki.buryCard, anki.removeCard) and automatically nudging a deck’s target retention rate toward its observed pass rate (anki.optimizeParams); new tenant.purge method to permanently delete a tenant’s data on a multi-user PostgreSQL deployment; new matches.list (filter/sort/paginate) and stats.matchBadges (PR/MWC badges scoped to a list of matches) methods. Native Linux distribution: .deb/.rpm packages, which set the execute bit that was lost when downloading the raw binary. Import: after importing a match, the Matches tab now displays and the imported positions are immediately visible; after importing a standalone position (XGP file, BGBlitz position, position text file, pasted position, or a batch of positions), the Analysis tab now opens directly on the imported position instead of the Matches tab; fixed pasting a French or German eXtreme Gammon analysis from macOS, which came back empty (accents decomposed by the system clipboard). See Headless mode (server), List of commands and Download and Installation.

Table of contents

• 1. Download and Installation
  • 1.1. Installing on Linux
  • 1.2. Windows and Mac warnings
• 2. Manual
  • 2.1. Introduction
  • 2.2. Main Interactions
  • 2.3. Description of the interface
  • 2.4. Configuration
  • 2.5. Guided tours and sample database
  • 2.6. Browsing positions
  • 2.7. Editing positions
  • 2.8. The command line
  • 2.9. Analysis Panel
  • 2.10. Comments Panel
  • 2.11. Search Panel
  • 2.12. Collections Panel
  • 2.13. Matches Panel
  • 2.14. Tournaments Panel
  • 2.15. Stats Panel
  • 2.16. EPC Panel
  • 2.17. Anki Panel
  • 2.18. Metadata Panel
  • 2.19. Log Panel
• 3. User Guide
  • 3.1. Create a new database
  • 3.2. Open an existing database
  • 3.3. Import and merge a database
  • 3.4. Edit a position
  • 3.5. Add a position to the database
  • 3.6. Tag a position
  • 3.7. Delete a position
  • 3.8. Import a position from XG
  • 3.9. Import a match
  • 3.10. Import a folder of matches
  • 3.11. Drag and drop
  • 3.12. Navigate through a match
  • 3.13. Manage the match panel
  • 3.14. Manage collections
  • 3.15. Manage tournaments
  • 3.16. Display performance statistics
  • 3.17. Calculate the EPC
  • 3.18. Display the analysis of a position imported from XG
  • 3.19. Export a position to XG
  • 3.20. View the different positions
  • 3.21. Search for positions based on criteria
• 4. List of commands
  • 4.1. Global operations
  • 4.2. Positions and navigation
  • 4.3. Editing and search
  • 4.4. Search Filters
  • 4.5. Various commands
• 5. Keyboard shortcuts
  • 5.1. Database
  • 5.2. Position
  • 5.3. Navigation
  • 5.4. Display
  • 5.5. Actions
  • 5.6. Tools
  • 5.7. Command Line
  • 5.8. Search History Panel
  • 5.9. Filter Library Panel
  • 5.10. Analysis Panel
  • 5.11. Match Panel
  • 5.12. Anki panel (spaced repetition)
• 6. Command Line Interface (CLI)
  • 6.1. Introduction
  • 6.2. General syntax
  • 6.3. Available commands
  • 6.4. create — Create a database
  • 6.5. import — Import data
  • 6.6. export — Export data
  • 6.7. search — Search positions
  • 6.8. list — List contents
  • 6.9. match — Display a match
  • 6.10. info — Database metadata
  • 6.11. edit — Edit metadata
  • 6.12. verify — Verify integrity
  • 6.13. delete — Delete data
  • 6.14. Workflow examples
  • 6.15. Exit codes
• 7. Frequently Asked Questions (FAQ)
  • 7.1. What is the purpose of blunderDB?
  • 7.2. What motivated the creation of blunderDB?
  • 7.3. How to save the state of the current database?
  • 7.4. Should I create different databases for different categories of positions?
  • 7.5. How to merge multiple databases?
  • 7.6. Which match file formats are supported?
  • 7.7. What is a collection?
  • 7.8. What is EPC?
  • 7.9. Does blunderDB have a command-line interface?
  • 7.10. Can I modify, copy, share blunderDB?
  • 7.11. What data format does blunderDB use?
  • 7.12. What were the design principles of blunderDB?
  • 7.13. What is the software architecture of blunderDB?
  • 7.14. On which platforms does blunderDB run?
  • 7.15. Where does the blunderDB icon come from?
• 8. Headless mode (server)
  • 8.1. Overview
  • 8.2. The serve daemon
  • 8.3. PostgreSQL backend and multi-user
  • 8.4. Migrating a SQLite database to PostgreSQL
  • 8.5. The generic call dispatcher
• 9. Annex: Advanced Filter Usage
  • 9.1. Command-line search for positions
  • 9.2. Search in Current Results
  • 9.3. Filter Library
  • 9.4. Examples
• 10. Windows Annex: False Detection of blunderDB as Malware
  • 10.1. Windows SmartScreen Warning
  • 10.2. Windows Defender Blocking
  • 10.3. Verify the download integrity (SHA256)
• 11. Mac Annex: Possible Blocking of blunderDB
  • 11.1. Installation of blunderDB
  • 11.2. Authorization to Run blunderDB
• 12. Annex: Database Schema
  • 12.1. Versioning and migrations
  • 12.2. Main tables
  • 12.3. Design principles
• 13. Annex: Statistics model — XG / gnuBG / blunderDB alignment
  • 13.1. Formal definitions
  • 13.2. Decisions counted in the PR denominator
  • 13.3. blunderDB ↔ XG ↔ gnuBG correspondence
  • 13.4. Validating your own figures
  • 13.5. gnuBG reference

Contact

Author: Kévin Unger <blunderdb@proton.me>. You can also find me on Heroes under the username postmanpat.

I initially developed blunderDB for my personal use to help detect patterns in my mistakes. However, it’s very rewarding to receive feedback, especially after spending a lot of time on design, coding, and debugging. So feel free to reach out to share your experiences. All (constructive) feedback is welcome.

Here are several ways to discuss:

• Join the Discord server of blunderDB: https://discord.gg/DA5PpzM9En

• Email me at blunderdb@proton.me.

• Discuss with me if we meet in a tournament.

• On GitHub.

  • Open an issue: https://github.com/kevung/blunderDB/issues

  • For bug fixes or improvement suggestions, create a pull request.

Donate

If you appreciate blunderDB and want to support its past and future developments, you can

• buy me a drink if we have the pleasure of meeting!

• make a small donation via PayPal to the address blunderdb@proton.me

Acknowledgments

I dedicate this little software to my wife Anne-Claire and our dear daughter Perrine. I would especially like to thank a few friends:

• Tristan Remille, for introducing me to backgammon with joy and kindness; for showing the way in understanding this wonderful game; and for continuing to support me despite my poor attempts to improve my play.

• Nicolas Harmand, a cheerful companion for over a decade in great adventures, and a fantastic sparring partner since he has caught the backgammon bug.