https://github.com/endlesstrax/pgn-to-sqlite
Pull your Chess games from chess.com and lichess.org into a sqlite3 database.
https://github.com/endlesstrax/pgn-to-sqlite
chess database pgn python sqlite3
Last synced: 4 months ago
JSON representation
Pull your Chess games from chess.com and lichess.org into a sqlite3 database.
- Host: GitHub
- URL: https://github.com/endlesstrax/pgn-to-sqlite
- Owner: EndlessTrax
- License: mit
- Created: 2021-02-12T18:45:58.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-05-02T23:49:33.000Z (about 1 year ago)
- Last Synced: 2025-05-03T00:27:48.006Z (about 1 year ago)
- Topics: chess, database, pgn, python, sqlite3
- Language: Python
- Homepage: https://pypi.org/project/pgn_to_sqlite/
- Size: 312 KB
- Stars: 19
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PGN to SQLite
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](https://docs.astral.sh/uv/):
```bash
uv tool install pgn_to_sqlite
```
Alternatively, you can install it with [pipx](https://github.com/pypa/pipx):
```shell
pipx install pgn_to_sqlite
```
Or with `pip`:
```bash
pip install pgn_to_sqlite
```
## Usage
```shell
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](https://www.chess.com) and [Lichess.org](https://lichess.org) respectively.
**Example:**
```shell
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:**
```shell
pgn-to-sqlite -o games.db save ./chess/games/
```
## Development
This project uses [uv](https://docs.astral.sh/uv/) for dependency management and development workflows.
### Setting Up Your Development Environment
1. Install `uv` if you haven't already:
```bash
pip install uv
```
2. Clone the repository:
```bash
git clone https://github.com/EndlessTrax/pgn-to-sqlite.git
cd pgn-to-sqlite
```
3. Sync dependencies and set up the virtual environment:
```bash
uv sync
```
### Running Tests
Run the test suite with:
```bash
uv run pytest
```
For coverage reporting:
```bash
uv run pytest --cov
```
### Linting and Formatting
This project uses [Ruff](https://github.com/astral-sh/ruff) for linting and formatting:
```bash
# Check for issues
uv run ruff check .
# Format code
uv run ruff format .
```
### Building the Project
To build the package:
```bash
uv build
```
## Contributing
Contributions are welcome! Please follow these guidelines:
1. **File an issue first** - Before making a PR, please [file an issue](https://github.com/EndlessTrax/pgn-to-sqlite/issues) so the implementation can be discussed. This saves time and increases the chances of your PR being merged without significant changes.
2. **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.
3. **Include tests** - Please include tests for any code changes (unless current tests already cover your contribution).
4. **Update documentation** - If your changes affect usage, please update the README accordingly.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
If you find this project useful and would like to show your support, you can:
- [Sponsor on GitHub](https://github.com/sponsors/EndlessTrax)
- [Buy me a coffee](https://ko-fi.com/endlesstrax) ☕