PGN to SQLite

PyPI version GitHub Python Version

A CLI application for pulling PGN files from Chess.com and Lichess.org and saving your games into a SQLite database.

It can also be used to save PGN files from a local folder to a SQLite database.

Requirements

Python 3.10 or higher is required.

Installation

It is recommended that you install this package in a virtual or isolated environment. The easiest way to do this is with uv:

uv tool install pgn_to_sqlite

Alternatively, you can install it with pipx:

pipx install pgn_to_sqlite

Or with pip:

pip install pgn_to_sqlite

Usage

Usage: pgn-to-sqlite [OPTIONS] COMMAND [ARGS]...

  Save your chess games to a SQLite database.

  You can `fetch` your games from chess.com or lichess.org. You can also
  `save` local PGN files to the database.

Options:
  -u, --user TEXT    Your username for the chess site.
  -o, --output FILE  Where you would like your database saved.  [required]
  --help             Show this message and exit.

Commands:
  fetch  Fetch all games from the requested site.
  save   Save all PGN files from the given folder.

Fetching Games from Chess.com or Lichess.org

To download, parse, and save your games, both --user and --output are required. The fetch command accepts either chess or lichess as an argument for Chess.com and Lichess.org respectively.

Example:

pgn-to-sqlite -u endlesstrax -o games.db fetch lichess

Note: If you've played a lot of games, be patient—it could take a minute or two to download and process them all.

Saving Games from a Local Folder

To save games from local PGN files to your database, only --output is required. The save command expects a folder path as an argument.

Example:

pgn-to-sqlite -o games.db save ./chess/games/

Development

This project uses uv for dependency management and development workflows.

Setting Up Your Development Environment

Install uv if you haven't already:
```
pip install uv
```

Clone the repository:

git clone https://github.com/EndlessTrax/pgn-to-sqlite.git
cd pgn-to-sqlite

Sync dependencies and set up the virtual environment:
```
uv sync
```

Running Tests

Run the test suite with:

uv run pytest

For coverage reporting:

uv run pytest --cov

Linting and Formatting

This project uses Ruff for linting and formatting:

# Check for issues
uv run ruff check .

# Format code
uv run ruff format .

Building the Project

To build the package:

uv build

Contributing

Contributions are welcome! Please follow these guidelines:

File an issue first - Before making a PR, please file an issue so the implementation can be discussed. This saves time and increases the chances of your PR being merged without significant changes.
Lint and format your code - Use uv run ruff check . and uv run ruff format . to ensure your code follows the project's style guidelines.
Include tests - Please include tests for any code changes (unless current tests already cover your contribution).
Update documentation - If your changes affect usage, please update the README accordingly.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you find this project useful and would like to show your support, you can:

Sponsor on GitHub
Buy me a coffee ☕

Metadata

Release files for pgn-to-sqlite 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pgn-to-sqlite 2.4.0
File	Size	Uploaded
pgn_to_sqlite-2.4.0.tar.gz	6.8 kB	Mar 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pgn-to-sqlite 2.4.0
File	Interpreter	ABI	Platform	Reset
pgn_to_sqlite-2.4.0-py3-none-any.whl 7.8 kB Mar 7, 2026	Python 3	none	any	Details

Total release size: 14.6 kB

Release files / pgn_to_sqlite-2.4.0.tar.gz

Download URL	pgn_to_sqlite-2.4.0.tar.gz
Size	6.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`8df8a5c432c422b16ce5163b1f1e7a89f1c5ade1b12b4331922e94b699d6225e`
BLAKE2b-256 checksum How to use checksums	`7d195ad3bb289fce0c4f1d1210d1fced2b85ce71b28d2a38adf0bcb1a37c5af1`
Upload date	Mar 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / pgn_to_sqlite-2.4.0-py3-none-any.whl

Download URL	pgn_to_sqlite-2.4.0-py3-none-any.whl
Size	7.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`72fce0d307af1b9cfa74ccb1672b4f9a99f0b67a5b59e97ddfe36262372acc88`
BLAKE2b-256 checksum How to use checksums	`aa6e6d35bce80cf0ac026b670fc3b001f1802bb19611dfe7504c8c1db894ea17`
Upload date	Mar 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`