sqlitedict Documentation

Because of Python semantics, sqlitedict cannot detect when a mutable object retrieved from the database has been modified in memory. To save changes to a mutable object, you must explicitly assign the modified object back to the SqliteDict and call .commit().

from sqlitedict import SqliteDict

db = SqliteDict("example.sqlite")
db["colors"] = {"red": (255, 0, 0)}
db.commit()

# Retrieve the object
colors = db["colors"]

# Modify the object in RAM
colors["blue"] = (0, 0, 255) 

# IMPORTANT: Re-assign and commit to save changes
db["colors"] = colors
db.commit()

db.close()

Install or upgrade sqlitedict using pip. The module has no dependencies beyond Python itself and requires Python 3.7 or higher.

pip install -U sqlitedict

Use SqliteDict as a persistent, dictionary-like interface.

Important: Committing changes By default, autocommit is False for performance. You must call .commit() to save changes to the database. If you want every write to be saved immediately, initialize with autocommit=True.

Closing the database You should call .close() when finished, or use a context manager to ensure the connection is closed properly.

Using SqliteDict in a with statement ensures the database is automatically closed when leaving the block.

Warning: Uncommitted objects are not saved on close. You must still call .commit() within the block to persist changes.

By default, sqlitedict extracts and outputs the outer exception stack to error logs, which favors verbosity. For better performance/efficiency, initialize the database with outer_stack=False.

from sqlitedict import SqliteDict
# outer_stack=False improves efficiency
db = SqliteDict("example.sqlite", outer_stack=False)

By default, sqlitedict uses pickle to serialize values. You can provide custom encode and decode functions to use other formats like JSON or to apply compression (e.g., zlib).

Example: Using JSON

import json
with SqliteDict("example.sqlite", encode=json.dumps, decode=json.loads) as mydict:
    pass

Example: Using zlib compression

import zlib, pickle, sqlite3

def my_encode(obj):
    return sqlite3.Binary(zlib.compress(pickle.dumps(obj, pickle.HIGHEST_PROTOCOL)))

def my_decode(obj):
    return pickle.loads(zlib.decompress(bytes(obj)))

with SqliteDict("example.sqlite", encode=my_encode, decode=my_decode) as mydict:
    pass

By default, keys in sqlitedict must be strings. To use non-string keys, provide custom encode_key and decode_key functions.

from sqlitedict import encode_key, decode_key

# Use custom key encoding/decoding
with SqliteDict("example.sqlite", encode_key=encode_key, decode_key=decode_key) as mydict:
    pass

A single SQLite database file can host multiple independent dictionaries (tables). Use the tablename argument during initialization to specify which table to use.

Use get_tablenames(filename) to retrieve a list of all table names in a database file.