{"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":"python","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,"search_vec":"'applic':32 'bugfix':51 'communiti':54 'community-contribut':53 'contribut':55 'current':43 'data':20 'databas':10,41,65 'design':29 'document':7,68 'document-ori':6,67 'embed':71 'featur':40,56 'file':26 'focus':49 'full':39 'full-featur':38 'happi':17 'human':23 'human-read':22 'json':25,70 'lightweight':5 'mainten':45 'minor':61 'mode':46 'new':58 'nosql':9,66 'optim':13 'orient':8,69 'patch':64 'python':12 'readabl':24 'releas':59 'requir':36 'server':42 'simplic':15 'small':31 'store':19 'tinydb':1,2 'updat':62 'v4.8.2':47","created_at":"2026-04-11T01:43:44.706075+00:00","updated_at":"2026-04-16T22:58:39.166975+00:00","problems":[{"fix":"pip install tinydb","cause":"The `tinydb` package has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'tinydb'"},{"fix":"from tinydb import TinyDB, Query","cause":"The `Query` class, which is essential for defining search criteria in TinyDB, has not been imported.","error":"NameError: name 'Query' is not defined"},{"fix":"db.get(Query().name == 'Alice')","cause":"Filtering methods like `get()`, `search()`, `update()`, or `remove()` require a `Query` object for specifying conditions, not a plain string.","error":"TypeError: cond must be a Query instance, got <class 'str'>"},{"fix":"db.update({'age': 31}, Query().name == 'Alice')","cause":"The `update` method requires a condition (`cond`) defined with `Query` to specify which documents should be modified.","error":"TypeError: update() missing 1 required positional argument: 'cond'"},{"fix":"db.insert_multiple([{'name': 'Alice'}, {'name': 'Bob'}])","cause":"The `db.insert()` method expects a single dictionary as a document, not a list of documents.","error":"TypeError: Document must be a dictionary, got <class 'list'>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/msiemens/tinydb","docs":"https://tinydb.readthedocs.org/","changelog":"https://tinydb.readthedocs.io/en/latest/changelog.html","pypi":"https://pypi.org/project/tinydb/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}