Skip to main content

sql3-lite-saver

CI License: MIT Python 3.9+

A Jedi-approved SQLite connection pool, strong in the WAL side of the Force.

We make your Bad Batch good.


Why You Need a Connection Pool

SQLite is fast and embedded, but it isn't built for many simultaneous writers.
Without pooling, each connection must reinitialize SQLite state, and you'll quickly see:

sqlite3.OperationalError: database is locked

sql3-lite-saver helps by:

  • Reusing a fixed number of open connections
  • Enabling WAL (Write-Ahead Logging) automatically
  • Retrying transparently with exponential backoff (optional Tenacity support)
  • Supporting multi-threaded and multi-process workloads safely

⚠️ IMPORTANT: WAL Checkpoint Maintenance

If you use WAL mode (enabled by default), you MUST run periodic checkpoints or your database files can bloat over time.

Without checkpoints:

  • WAL file can grow unbounded
  • Read performance can steadily degrade

See the WAL Checkpoint Management section below for details.


Installation

From PyPI

pip install sql3-lite-saver

With optional retry engine (Tenacity)

pip install sql3-lite-saver[retry]

For development (editable)

pip install -e .[dev,retry]

Extras explained

Extra Purpose What's Included
retry Adds Tenacity for advanced retry control tenacity>=8.0
dev Developer tools ruff, pytest (optional), twine, build

Example

from pathlib import Path
from sql3_lite_saver import ConnectionPool

pool = ConnectionPool(Path("app.db"), max_size=3)

with pool.acquire() as conn:
    conn.execute("CREATE TABLE IF NOT EXISTS demo (id, msg)")
    conn.execute("INSERT INTO demo VALUES (?, ?)", (1, "hello there"))

with pool.acquire() as conn:
    print([dict(r) for r in conn.execute("SELECT * FROM demo").fetchall()])

Advanced Retry with Tenacity

When you install Tenacity (pip install sql3-lite-saver[retry]), sql3-lite-saver can use it for retry logic.
You can fine-tune retry behavior with parameters:

pool = ConnectionPool(
    Path("app.db"),
    enable_retry=True,
    retry_attempts=8,
    base_delay=0.5,
    retry_jitter=0.25,
)

Without Tenacity installed, it falls back to built-in exponential backoff (1s, 2s, 4s, ... up to 60s).


WAL Checkpoint Management

Why Checkpoints Matter

When using WAL (Write-Ahead Logging), SQLite writes go to a separate file (app.db-wal) instead of the main database (app.db). Without regular checkpoints, the WAL file can grow indefinitely, causing:

  • Disk space bloat - WAL can balloon to gigabytes
  • Degraded read performance - SQLite may scan a larger WAL on reads
  • File system issues - Very large WAL files can cause problems

Checkpoints transfer WAL data from app.db-wal back to the main app.db file, resetting the WAL.

Additional database files created by WAL mode:

  • app.db-wal - Write-Ahead Log
  • app.db-shm - Shared memory for coordination

Checkpoint Modes

from pathlib import Path
from sql3_lite_saver import ConnectionPool

pool = ConnectionPool(Path("app.db"))

# PASSIVE (default) - Non-blocking, checkpoint what you can
result = pool.checkpoint("PASSIVE")

# FULL - Checkpoint all frames, may block briefly
result = pool.checkpoint("FULL")

# RESTART - Like FULL, then reset WAL for reuse
result = pool.checkpoint("RESTART")

# TRUNCATE - Like RESTART, then shrink WAL to zero bytes (reclaim disk space)
result = pool.checkpoint("TRUNCATE")

print(result)
# {'busy': 0, 'log': 1024, 'checkpointed': 1024}
# busy=0 means full success, >0 means some pages couldn't be checkpointed

When to Checkpoint

  • Periodic background task - Every hour with PASSIVE (or TRUNCATE if you want to reclaim space)
  • Before backups - Use TRUNCATE to minimize backup size
  • Low-traffic periods - TRUNCATE during maintenance windows
  • On application shutdown - Final TRUNCATE to clean up

References


Testing

If you use pytest:

pytest -q

Or with the standard library unittest:

python -m unittest discover -s tests -v

Developer Shortcuts

make install-dev   # editable install with dev + retry deps
make install-prod  # editable install (minimal)
make lint          # run Ruff
make test          # run tests
make release       # build + twine upload

License

MIT © 2025 @apresence

Metadata

Release files for sql3-lite-saver 0.99.1

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

Source distribution (sdist)

Source distribution for sql3-lite-saver 0.99.1
File Size Uploaded Provenance Actions
sql3_lite_saver-0.99.1.tar.gz 13.6 kB With provenance Details for sql3_lite_saver-0.99.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sql3-lite-saver 0.99.1
File Interpreter ABI Platform Actions
sql3_lite_saver-0.99.1-py3-none-any.whl Python 3 none any Details for sql3_lite_saver-0.99.1-py3-none-any.whl

Total release size: 22.7 kB

Release files / sql3_lite_saver-0.99.1.tar.gz

Download URL sql3_lite_saver-0.99.1.tar.gz
Size 13.6 kB
Tags Source
SHA-256 checksum
How to use checksums
2e16448ecd2dbafd614cddb6141f3c373f45f6c7f700b04b3a5d202a2fced5a7
BLAKE2b-256 checksum
How to use checksums
e631703f22b288a9292ee53913e2961993ce5647982213bfa82742b1e693f446
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 8, 2026.

Transparency log

Release files / sql3_lite_saver-0.99.1-py3-none-any.whl

Download URL sql3_lite_saver-0.99.1-py3-none-any.whl
Size 9.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d2c47604ba5817c3545d2ef041c1d0f9b0e7b12c2b7b5a193a0b95ce64d08839
BLAKE2b-256 checksum
How to use checksums
6ffe942afddd56822e71f09a67fe6d37b2da2a6d24056f4e3933f564f80c10d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 8, 2026.

Transparency log

Security for sql3-lite-saver 0.99.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sql3_lite_saver-0.99.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.99.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page