SqliteDict

Warnings

• breaking Version 2.0.0 and above dropped support for Python 2.x and requires Python 3.7 or newer. If you need support for older Python versions, you must use `sqlitedict` version 1.7.0 or earlier.
  Fix: Upgrade your Python environment to 3.7+ or pin `sqlitedict` to version `1.7.0` for older Python versions.
• gotcha By default, `autocommit` is `False` for performance reasons. Forgetting to call `db.commit()` after modifications will result in unsaved data. Always ensure you commit changes or initialize with `autocommit=True`.
  Fix: Explicitly call `db.commit()` after a series of modifications, or initialize `SqliteDict` with `autocommit=True`. Using a `with` statement also ensures the database is closed, but doesn't implicitly commit if `autocommit` is `False`.
• gotcha While `sqlitedict` is marketed as 'multithread-safe', this primarily refers to a workaround for Python's `sqlite3` module's threading limitations, serializing requests internally. SQLite itself operates on a single-writer model. True concurrent *writes* from multiple processes or threads will still be serialized and can lead to performance bottlenecks or locking issues if not carefully managed (e.g., with WAL mode and proper error handling).
  Fix: For high write concurrency, consider alternative databases or ensure proper transaction management, retry mechanisms, and potentially enable SQLite's Write-Ahead Logging (WAL) mode. `sqlitedict` is not designed for concurrent high-volume writes across many distinct processes.
• gotcha Improperly closing an `SqliteDict` instance (e.g., not calling `db.close()` or not using a `with` statement) can lead to data not being saved (if `autocommit` is `False`) or resource leaks. Earlier versions also had reported `AttributeError` or `TypeError` upon closing.
  Fix: Always use the `with` statement when opening an `SqliteDict` instance: `with SqliteDict('path/to/db') as db: ...`. This ensures the database connection is properly closed.
• gotcha By default, keys are expected to be strings. If using non-string keys (e.g., integers, tuples) or complex objects as keys, `sqlitedict` will serialize them. If deterministic serialization is critical for unordered containers or custom key types, you might need to provide custom `encode_key` and `decode_key` functions to `SqliteDict`.
  Fix: For non-string or complex keys, test thoroughly. If unexpected behavior occurs or custom serialization is desired, provide `encode_key` and `decode_key` functions as parameters to the `SqliteDict` constructor to handle key serialization/deserialization explicitly.

Install

• pip install sqlitedict Install with pip

Imports

• SqliteDict

  from sqlitedict import SqliteDict

Quickstart

This quickstart demonstrates how to create and interact with an SqliteDict, covering both `autocommit=True` and manual `commit()` usage, as well as the recommended `with` statement for proper database closing. It stores dictionary objects that are automatically pickled.

from sqlitedict import SqliteDict
import os

db_path = 'my_data.sqlite'

# Clean up previous run if exists
if os.path.exists(db_path):
    os.remove(db_path)

# Open a new SqliteDict with autocommit enabled (recommended for many small writes)
with SqliteDict(db_path, autocommit=True) as db:
    db['user:1'] = {'name': 'Alice', 'age': 30}
    db['user:2'] = {'name': 'Bob', 'age': 25}
    db['settings:theme'] = 'dark'
    print(f"Added 3 items. Current length: {len(db)}")

# Re-open the database (autocommit defaults to False if not specified)
with SqliteDict(db_path) as db_read_only:
    print(f"Retrieved user:1: {db_read_only['user:1']}")
    print(f"All keys: {list(db_read_only.keys())}")

    # Manual commit is needed if autocommit is False
    db_read_only['new_item'] = 'This will NOT be saved without commit()'
    # db_read_only.commit() # Uncomment to save

print("Demonstrating explicit commit")
# Open without autocommit, requiring explicit commit
with SqliteDict(db_path, autocommit=False) as db_manual:
    db_manual['product:101'] = {'name': 'Widget', 'price': 19.99}
    db_manual.commit() # Explicitly commit changes
    print(f"Added product:101. Current length: {len(db_manual)}")

# Verify the manually committed item
with SqliteDict(db_path) as db_verify:
    print(f"Retrieved product:101: {db_verify['product:101']}")

# Clean up the database file
if os.path.exists(db_path):
    os.remove(db_path)