TinyDB

Warnings

• breaking Version 4.0 introduced significant API changes, including renaming table management methods (e.g., `purge_tables` to `drop_tables`, `Table.purge()` to `Table.truncate()`) and changes to how `TinyDB` is initialized. Python 2 support was also dropped.
  Fix: Consult the TinyDB v4.0 upgrade guide for a full list of changes and adapt code accordingly. Ensure Python 3.8+ is used.
• breaking Version 3.0 changed querying syntax. `where('...').contains('...')` became `where('...').search('...')`. `where('foo').has('bar')` was replaced by property access (`where('foo').bar` or `Query().foo.bar`) or dictionary access (`Query()['a.b.c']`). Explicit `exists()` is now required to check for key existence. External packages are needed for `SmartCacheTable` and serialization features.
  Fix: Update query methods to the new syntax. If using `SmartCacheTable` or advanced serialization, install `tinydb-smartcache` or `tinydb-serialization` respectively.
• gotcha When using property access for queries (e.g., `Query().field_name`), adding new query operations in later TinyDB versions might break code if your field name matches a new operation name (e.g., `Query().map` could break if a `map` operation is introduced).
  Fix: For document fields that might conflict with future query operation names, use dictionary-style access: `Query()['field_name']` instead of `Query().field_name`.
• gotcha TinyDB is not designed for concurrent access from multiple processes or threads without external tools. Direct concurrent writes can lead to data corruption.
  Fix: For multi-process/multi-thread scenarios, consider using `tinyrecord` (an external library) or ensuring proper locking mechanisms are implemented outside TinyDB to prevent race conditions.
• gotcha Writing individual records using `db.insert()` can be very slow due to file I/O overhead for each operation.
  Fix: For inserting multiple documents, use `db.insert_multiple()` with a list of documents to improve performance significantly.

Install

• pip install tinydb Install TinyDB

Imports

• TinyDB

  from tinydb import TinyDB

• Query

  from tinydb import Query

Quickstart

This quickstart demonstrates how to initialize a TinyDB database, insert, query, update, and delete documents using `TinyDB` and `Query` objects. It saves data to a local JSON file.

from tinydb import TinyDB, Query
import os

db_file = 'my_db.json'
# Clean up previous db file for fresh run
if os.path.exists(db_file):
    os.remove(db_file)

# Initialize database
db = TinyDB(db_file)

# Insert documents
db.insert({'name': 'Alice', 'age': 30, 'city': 'New York'})
db.insert({'name': 'Bob', 'age': 24, 'city': 'London'})
db.insert({'name': 'Charlie', 'age': 30, 'city': 'Paris'})

# Query documents
User = Query()
alice = db.search(User.name == 'Alice')
print(f"Alice: {alice}")

people_in_30s = db.search(User.age >= 30)
print(f"People aged 30 or more: {people_in_30s}")

# Update documents
db.update({'age': 31}, User.name == 'Alice')
alice_updated = db.search(User.name == 'Alice')
print(f"Alice after update: {alice_updated}")

# Delete documents
db.remove(User.name == 'Bob')
all_users = db.all()
print(f"All users after Bob's removal: {all_users}")

# Clean up after example
os.remove(db_file)