Skip to main content
Databases in Obsidian Chess Studio are SQLite files that store chess games, player information, tournaments, and metadata for fast searching and analysis.

​
Creating a Database

1

Navigate to Databases

Click on Databases in the main navigation menu.
2

Click Add New

Click the Add New button in the top-right corner.
3

Choose Creation Method

Select how to create your database:
Create a blank database:
  • Enter a name for your database
  • Choose a location to save the .db3 file
  • Click Create
4

Database Created

Your new database appears in the database list and is ready to use.
Databases are stored as .db3 files (SQLite format) in your app’s database folder. Profile databases are automatically created when you create a profile.

​
Database Types

​
Local Game Databases

Standard databases you create:
  • Full read/write access
  • Can add, edit, and delete games
  • Can be exported, merged, or deleted
  • Indexed for fast searching

​
Profile Databases

Automatically created for each profile:
  • Stored as profile_{id}.db3
  • Contains all games from linked accounts
  • Used for personal statistics and tracking
  • Not shown in the main databases list (accessed via Profiles)

​
Online Tournament Databases

Created from online tournament imports:
  • Read-only (linked to online source)
  • Marked with “online” source tag
  • Can be merged into local databases
  • Automatically named after the tournament

​
Importing Large PGN Files

For master game collections or large archives:
1

Prepare PGN File

Ensure your PGN file is:
  • Valid PGN format
  • UTF-8 encoded
  • Not corrupted (test with a PGN viewer first)
2

Create Database from PGN

Use the Add New > From PGN option.
3

Monitor Progress

The import shows:
  • Games processed per second
  • Total games imported
  • Elapsed time
  • Current batch
4

Wait for Optimization

After import, the database is optimized:
  • Indexes are created for players, events, dates
  • This ensures fast searching later
  • May take a few minutes for very large databases (100k+ games)
Large Database Import Times:
  • 10,000 games: ~30 seconds
  • 50,000 games: ~2-3 minutes
  • 100,000 games: ~5-10 minutes
  • 1,000,000+ games: ~30-60 minutes
Times vary based on CPU speed and disk performance.

​
Database Operations

​
Viewing Database Contents

1

Open Database

Double-click any database in the list to open the database view.
2

Explore Tabs

The database view has three main tabs:
Browse all games with filtering and sorting:
  • Filter by player, date range, result, rating
  • Sort by date, ply count, rating
  • Search by player names
  • Click any game to view it on the analysis board

​
Filtering Games

Use the filter panel to narrow down games:
  • Search for player names (White or Black)
  • Filter by specific player side
  • Supports partial name matching
  • Date range selector
  • From date, to date
  • Filter by year, month, or specific dates
  • White wins (1-0)
  • Black wins (0-1)
  • Draws (1/2-1/2)
  • Unknown/ongoing (*)
  • Minimum/maximum Elo range
  • Filter by White or Black rating
  • Find games within specific rating bands
  • Search by ECO code
  • Filter by opening name
  • Find games in your repertoire

​
Sorting Games

Sort game lists by:
  • Date: Newest or oldest first
  • Plies: Shortest or longest games
  • Rating: Highest or lowest rated games
  • White/Black: Alphabetically by player name

​
Exporting Databases

1

Select Database

Click on the database you want to export.
2

Export to PGN

Click the Export button and choose a location.
3

PGN Generated

All games are exported to a single PGN file with:
  • Full game headers (players, event, date, etc.)
  • All moves with variations and annotations
  • Evaluation comments (if analyzed)
Exporting large databases may take a few minutes. The PGN file can be imported into other chess software or shared with others.

​
Reference Databases

Set a database as a reference database for position searches:
1

Select Database

Click on a database in the list.
2

Set as Reference

Click the star icon or “Set as Reference” button.
3

Use in Position Search

When you search for a position on the analysis board, the reference database is queried to find matching games.
Only one database can be the reference database at a time. This is useful for searching your personal games or a master game collection.

​
Merging Databases

Combine multiple databases into one:
1

Open Target Database

Open the database you want to merge others into.
2

Go to Merge Tab

If available, navigate to the Merge tab (shown for online tournament databases).
3

Select Source Databases

Choose which databases to merge from.
4

Merge

Click Merge to combine all games into the target database.
  • Duplicates are automatically detected and skipped
  • All games retain their original metadata

​
Database Maintenance

​
Optimizing Databases

Over time, databases can become fragmented:
  1. Automatic Optimization: Runs after large imports
  2. Manual Optimization: Available in database settings
What Optimization Does:
  • Rebuilds indexes for faster searches
  • Reclaims unused space
  • Improves query performance

​
Deleting Databases

Deleting a database is permanent and cannot be undone. Export to PGN first if you want a backup.
1

Select Database

Click the database you want to delete.
2

Click Delete

Click the Delete (trash icon) button.
3

Confirm Deletion

Confirm that you want to permanently delete the database.
4

Database Removed

The .db3 file is deleted from disk.

​
Database Statistics

Each database shows:
  • Game Count: Total number of games
  • Player Count: Unique players in the database
  • Event Count: Number of tournaments/events
  • Storage Size: Disk space used by the database file
  • Date Range: Earliest and latest game dates

​
Advanced Database Features

​
Database Schema

Obsidian Chess Studio uses a normalized SQLite schema: 
Tables:
- games (id, white_id, black_id, event_id, date, result, pgn, ...)
- players (id, name, rating, ...)
- events (id, name, site, date, ...)
- positions (fen, game_id, ply, ...)
Indexes on:
  • Player names
  • Event names
  • Dates
  • Positions (FEN)
This structure enables fast queries even on databases with millions of games.

​
Custom SQL Queries

For advanced users, you can access the database directly:
  1. Locate the .db3 file in your database folder
  2. Open with any SQLite client (DB Browser for SQLite, etc.)
  3. Run custom queries for advanced statistics
Direct database access is for advanced users only. Always back up before making changes.

​
Best Practices

Organize by Theme

Create separate databases for different purposes:
  • Personal games (use profiles instead)
  • Master games by era
  • Opening-specific collections
  • Tournament archives

Regular Exports

Periodically export important databases to PGN as backups.

Use Reference Wisely

Set your most frequently searched database (e.g., master games) as the reference database.

Clean Duplicates

When merging databases, let the app handle deduplication automatically.

​
Troubleshooting

​
Database Won’t Open

  1. Check if the file is corrupted
  2. Verify file permissions (read/write access)
  3. Try opening in a SQLite browser to verify integrity
  4. Restore from PGN backup if available

​
Slow Search Performance

  1. Optimize the database (Settings > Optimize)
  2. Ensure indexes are built (automatic after import)
  3. For very large databases, consider splitting by year or event

​
Import Errors

  • PGN Parse Errors: Fix the PGN file format
  • Duplicate Games: Normal - duplicates are skipped
  • Memory Issues: Close other applications or split PGN into smaller files

​
Missing Games After Import

  1. Check the import summary for errors
  2. Verify the PGN file contains valid games
  3. Search by different filters (some games may have missing metadata)
  4. Check if games were deduplicated (already existed)

Build docs developers (and LLMs) love

Get started for freeTalk to us