{"id":2810,"library":"tinydb","title":"TinyDB","description":"TinyDB is a lightweight, document-oriented NoSQL database for Python, optimized for simplicity and happiness. It stores data in human-readable JSON files and is designed for small applications that don't require a full-featured database server. Currently in maintenance mode (v4.8.2), it focuses on bugfixes and community-contributed features, with new releases for minor updates and patches.","status":"maintenance","version":"4.8.2","language":"en","source_language":"en","source_url":"https://github.com/msiemens/tinydb","tags":["database","NoSQL","document-oriented","json","embedded"],"install":[{"cmd":"pip install tinydb","lang":"bash","label":"Install TinyDB"}],"dependencies":[],"imports":[{"symbol":"TinyDB","correct":"from tinydb import TinyDB"},{"symbol":"Query","correct":"from tinydb import Query"}],"quickstart":{"code":"from tinydb import TinyDB, Query\nimport os\n\ndb_file = 'my_db.json'\n# Clean up previous db file for fresh run\nif os.path.exists(db_file):\n    os.remove(db_file)\n\n# Initialize database\ndb = TinyDB(db_file)\n\n# Insert documents\ndb.insert({'name': 'Alice', 'age': 30, 'city': 'New York'})\ndb.insert({'name': 'Bob', 'age': 24, 'city': 'London'})\ndb.insert({'name': 'Charlie', 'age': 30, 'city': 'Paris'})\n\n# Query documents\nUser = Query()\nalice = db.search(User.name == 'Alice')\nprint(f\"Alice: {alice}\")\n\npeople_in_30s = db.search(User.age >= 30)\nprint(f\"People aged 30 or more: {people_in_30s}\")\n\n# Update documents\ndb.update({'age': 31}, User.name == 'Alice')\nalice_updated = db.search(User.name == 'Alice')\nprint(f\"Alice after update: {alice_updated}\")\n\n# Delete documents\ndb.remove(User.name == 'Bob')\nall_users = db.all()\nprint(f\"All users after Bob's removal: {all_users}\")\n\n# Clean up after example\nos.remove(db_file)\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult the TinyDB v4.0 upgrade guide for a full list of changes and adapt code accordingly. Ensure Python 3.8+ is used.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update query methods to the new syntax. If using `SmartCacheTable` or advanced serialization, install `tinydb-smartcache` or `tinydb-serialization` respectively.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For document fields that might conflict with future query operation names, use dictionary-style access: `Query()['field_name']` instead of `Query().field_name`.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"TinyDB is not designed for concurrent access from multiple processes or threads without external tools. Direct concurrent writes can lead to data corruption.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For inserting multiple documents, use `db.insert_multiple()` with a list of documents to improve performance significantly.","message":"Writing individual records using `db.insert()` can be very slow due to file I/O overhead for each operation.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}