NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #2167 most downloaded on PyPI
TinyDB is a tiny, document oriented database optimized for your happiness :)
Last release 1 months ago
06 Aug 2026
Release timing varies
gaps range from 3 weeks to 1.8 years
Most releases are documented
notes for 52 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
13 years old
71 releases · first in 2013
Drop official support for Python 3.8 and 3.9 . Both versions have reached their official End of Life (Python 3.8 in October 2024, Python 3.9 in Octobe
Table.update(doc_ids=...) and Table.remove(doc_ids=...) behave consistently with Table.get(doc_id=...) when given document IDs that don't exist: missing IDs are now silently skipped and the returned list only contains IDs that were actually updated/removed. Previously both methods raised KeyError, and update could leave the table in a partially-updated state when a mix of existing and missing IDs was passed (see #591).TypeError when passing unhashable extra arguments (like lists or dicts) to Query.test() (see #517).FileNotFoundError when creating a database file in the current directory without an explicit path prefix (see #619).0 or None) stored in LRUCache (see #596).Table.get (see #602).Table.update and tinydb.operations to use MutableMapping, so transform functions that modify documents in place type-check correctly (see #598).Full Changelog: v4.8.2...v4.9.0
One column per quarter.
Fix: Correctly update query cache when search results have changed (see #560 ).
Full Changelog: v4.8.1...v4.8.2
Feature: Allow persisting empty tables (see #518 ).
doc_id type work properly (see #545).Full Changelog: v4.8.0...v4.8.1
Feature: Allow retrieve multiple documents by document ID using Table.get(doc_ids=[...]) (see #504 ).
Table.get(doc_ids=[...]) (see #504).Full Changelog: v4.7.1...v4.8.0
Improvement: Improve typing annotations (see pull request #477 ).
Full Changelog: v4.7.0...v4.7.1
Feature: Allow inserting Document instances using Table.insert_multiple (see #455 ).
Document instances using Table.insert_multiple (see #455).Table.count and Table.get operations and also for Table.search when only returning a few documents (see #460).Table tests JSONStorage in addition to MemoryStorage.Full Changelog: v4.6.1...v4.7.0
Fix: Make using callables as queries work again (see #454 )
Full Changelog: v4.6.0...v4.6.1
Feature: Add map() query operation to apply a transformation to a document or field when evaluating a query (see PR #445 ). Note : This may break code
map() query operation to apply a transformation to a document or field when evaluating a query (see PR #445).map using the Query APIs property access syntaxFull Changelog: v4.5.2...v4.6.0
Fix: Make Table.delete() 's argument priorities consistent with other table methods. This means that if you pass both cond as well as doc_ids to Table
Table.delete()'s argument priorities consistent with other table methods. This means that if you pass both cond as well as doc_ids to Table.delete(), the latter will be prefered (see #424)Full Changelog: v4.5.1...v4.5.2
Fix: Correctly install typing-extensions on Python 3.7 (see #413 )
typing-extensions on Python 3.7 (see #413)Full Changelog: v4.5.0...v4.5.1
Feature: Better type hinting/IntelliSense for PyCharm, VS Code and MyPy (see issue #372). PyCharm and VS Code should work out of the box, for MyPy see
Full Changelog: https://github.com/msiemens/tinydb/compare/v4.4.0...v4.5.0
- Feature: Add operation for searching for all documents that match a dict fragment (see issue 300 )
Feature: Add operation for searching for all documents that match a dict fragment (see issue 300 )
Fix: Correctly handle queries that use fields that are also Query methods, e.g. Query()['test'] for searching for documents with a test field (see issue 373 )
- Feature: Add operation for updating multiple documents: update_multiple (see issue 346 )
Feature: Add operation for updating multiple documents: update_multiple (see issue 346 )
Improvement: Expose type information for MyPy typechecking (PEP 561) (see pull request 352 )
- Feature: Add support for specifying document IDs during insertion (see issue 303 )
Feature: Add support for specifying document IDs during insertion (see issue 303 )
Internal change: Use OrderedDict.move_to_end() in the query cache (see issue 338 )
- Fix: Don’t install dev-dependencies when installing from PyPI (see issue 315 )
Fix: Don’t install dev-dependencies when installing from PyPI (see issue 315 )
- Feature: Add a no-op query Query().noop() (see issue 313 )
Feature: Add a no-op query Query().noop() (see issue 313 )
Feature: Add a access_mode flag to JSONStorage to allow opening files read-only (see issue 297 )
Fix: Don’t drop the first document that’s being inserted when inserting data on an existing database (see issue 314 )
Nothing published for this version
- The deprecated Element ID API has been removed (e.g. using the Element class or eids parameter) in favor the Document API, see pull request 158 for…
Upgrade Notes
Python 2 support has been removed, see issue 284 for background
API changes:
Removed classes: DataProxy , StorageProxy
Attributes removed from TinyDB in favor of customizing TinyDB ’s behavior by subclassing it and overloading init(...) and table(...) :
DEFAULT_TABLE
DEFAULT_TABLE_KWARGS
DEFAULT_STORAGE
Arguments removed from TinyDB(...) :
default_table : replace with TinyDB.default_table_name = 'name'
table_class : replace with TinyDB.table_class = Class
TinyDB.contains(...) ’s doc_ids parameter has been renamed to doc_id and now only takes a single document ID
TinyDB.purge_tables(...) has been renamed to TinyDB.drop_tables(...)
TinyDB.purge_table(...) has been renamed to TinyDB.drop_table(...)
TinyDB.write_back(...) has been removed
TinyDB.process_elements(...) has been removed
Table.purge() has been renamed to Table.truncate()
Evaluating an empty Query() without any test operators will now result in an exception, use Query().noop() (introduced in v4.1.0) instead
ujson support has been removed, see issue 263 and issue 306 for background
The deprecated Element ID API has been removed (e.g. using the Element class or eids parameter) in favor the Document API, see pull request 158 for details on the replacement
TinyDB’s internal architecture has been reworked to be more simple and streamlined in order to make it easier to customize TinyDB’s behavior
With the new architecture, TinyDB performance will improve for many applications
Don’t break the tests when ujson is installed (see issue 262 )
Fix performance when reading data (see issue 250 )
Fix inconsistent purge function names (see issue 103 )
Nothing published for this version
- Internal change: fix missing values handling for LRUCache
Internal change: fix missing values handling for LRUCache
- Feature: allow setting the parameters of TinyDB’s default table (see issue 278 )
Feature: allow setting the parameters of TinyDB’s default table (see issue 278 )
- Internal change: support correct iteration for LRUCache objects
Internal change: support correct iteration for LRUCache objects
- Internal change: fix Query class to permit subclass creation (see pull request 270 )
Internal change: fix Query class to permit subclass creation (see pull request 270 )
- Feature: direct access to a TinyDB instance’s storage (see issue 258 )
Feature: direct access to a TinyDB instance’s storage (see issue 258 )
- Internal change: convert documents to dicts during insertion (see pull request 256 )
Internal change: convert documents to dicts during insertion (see pull request 256 )
Internal change: use tuple literals instead of tuple class/constructor (see pull request 247 )
Infra: ensure YAML tests are run (see pull request 252 )
- Fix: Don’t break when searching the same query multiple times (see pull request 249 )
Fix: Don’t break when searching the same query multiple times (see pull request 249 )
Internal change: allow collections.abc.Mutable as valid document types (see pull request 245 )
- Feature: Add encoding option to JSONStorage (see pull request 238 )
Feature: Add encoding option to JSONStorage (see pull request 238 )
Internal change: allow collections.abc.Mutable as valid document types (see pull request 245 )
- Bugfix: Make path queries ( db.search(where('key)) ) work again (see issue 232 )
Bugfix: Make path queries ( db.search(where('key)) ) work again (see issue 232 )
Improvement: Add custom repr representations for main classes (see pull request 229 )
- Drop official support for Python 3.3 . Python 3.3 has reached its official End Of Life as of September 29, 2017. It will probably continue to work,
Drop official support for Python 3.3 . Python 3.3 has reached its official End Of Life as of September 29, 2017. It will probably continue to work, but will not be tested against ( issue 217 )
Feature: Allow extending TinyDB with a custom storage proxy class (see pull request 224 )
Bugfix: Return list of document IDs for upsert when creating a new document (see issue 223 )
- Feature: Add support for regex flags (see pull request 216 )
Feature: Add support for regex flags (see pull request 216 )
Nothing published for this version
- Feature: Allow setting a table class for single table only (see issue 197 )
Feature: Allow setting a table class for single table only (see issue 197 )
Internal change: call fsync after flushing JSONStorage (see issue 208 )
Nothing published for this version
- Bugfix: Don’t install tests as a package anymore (see pull request #195 )
Bugfix: Don’t install tests as a package anymore (see pull request #195 )
- Feature: Allow disabling the query cache with db.table(name, cache_size=0) (see pull request #187 )
Feature: Allow disabling the query cache with db.table(name, cache_size=0) (see pull request #187 )
Feature: Add db.write_back(docs) for replacing documents (see pull request #184 )
- Feature: one_of for checking if a value is contained in a list (see issue 164 )
Feature: one_of for checking if a value is contained in a list (see issue 164 )
Feature: Upsert (insert if document doesn’t exist, otherwise update; see https://forum.m-siemens.de/d/30-primary-key-well-sort-of )
Internal change: don’t read from storage twice during initialization (see https://forum.m-siemens.de/d/28-reads-the-whole-data-file-twice )
- Rename elements to documents. Document IDs now available with doc.doc_id , using doc.eid is now deprecated (see pull request #158 )
Allow updating all documents using db.update(fields) (see issue #157 ).
Rename elements to documents. Document IDs now available with doc.doc_id , using doc.eid is now deprecated (see pull request #158 )
- Expose the table name via table.name (see issue #147 ).
Expose the table name via table.name (see issue #147 ).
Allow better subclassing of the TinyDB class (see pull request #150 ).
- Expose TinyDB version via import tinyb; tinydb.__version__ (see issue #148 ).
Expose TinyDB version via import tinyb; tinydb.version (see issue #148 ).
- Add new update operations: add(key, value) , subtract(key, value) , and set(key, value) (see pull request #145 ).
Add new update operations: add(key, value) , subtract(key, value) , and set(key, value) (see pull request #145 ).
- Use relative imports to allow vendoring TinyDB in other packages (see pull request #142 ).
Use relative imports to allow vendoring TinyDB in other packages (see pull request #142 ).
- Allow iterating over a database or table yielding all documents (see pull request #139 ).
Allow iterating over a database or table yielding all documents (see pull request #139 ).
- Fix bug with accidental modifications to the query cache when modifying the list of search results (see issue #132 ).
Fix bug with accidental modifications to the query cache when modifying the list of search results (see issue #132 ).
- Fix the Query constructor to prevent wrong usage (see issue #117 ).
Fix the Query constructor to prevent wrong usage (see issue #117 ).
- Fix a bug with queries on documents that have a path key (see pull request #107 ).
Fix a bug with queries on documents that have a path key (see pull request #107 ).
Don’t write to the database file needlessly when opening the database (see pull request #104 ).
- Add a way to specify the default table name via default_table (see pull request #98 ).
Add a way to specify the default table name via default_table (see pull request #98 ).
Add db.purge_table(name) to remove a single table (see pull request #100 ).
Along the way: celebrating 100 issues and pull requests! Thanks everyone for every single contribution!
Extend API documentation (see issue #96 ).
- Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul ).
Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul ).
- Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul ).
Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul ).
- Inserting a dictionary with data that is not JSON serializable doesn’t lead to corrupt files anymore (see issue #89 ).
Inserting a dictionary with data that is not JSON serializable doesn’t lead to corrupt files anymore (see issue #89 ).
Fix a bug in the LRU cache that may lead to an invalid query cache (see issue #87 ).
- db.update(...) and db.remove(...) now return affected document IDs (see issue #83 ).
db.update(...) and db.remove(...) now return affected document IDs (see issue #83 ).
Inserting an invalid document (i.e. not a dict ) now raises an error instead of corrupting the database (see issue #74 ).
- where('...').contains('...') has been renamed to where('...').search('...') .
Overhauled Query model:
where('...').contains('...') has been renamed to where('...').search('...') .
Support for ORM-like usage: User = Query(); db.search(User.name == 'John') .
where('foo') is an alias for Query().foo .
where('foo').has('bar') is replaced by either where('foo').bar or Query().foo.bar .
In case the key is not a valid Python identifier, array notation can be used: where('a.b.c') is now Query()['a.b.c'] .
Checking for the existence of a key has to be done explicitly: where('foo').exists() .
Migrations from v1 to v2 have been removed.
SmartCacheTable has been moved to msiemens/tinydb-smartcache .
Serialization has been moved to msiemens/tinydb-serialization .
Empty storages are now expected to return None instead of raising ValueError . (see issue #67 .
Nothing published for this version
- Fix a forgotten debug output in the SerializationMiddleware (see issue #55 ).
Fix a forgotten debug output in the SerializationMiddleware (see issue #55 ).
Fix an “ignored exception” warning when using the CachingMiddleware (see pull request #54 )
Fix a problem with symlinks when checking out TinyDB on OSX Yosemite (see issue #52 ).
Nothing published for this version
Nothing published for this version
- Hopefully fix a problem with using TinyDB as a dependency in a setup.py script (see issue #51 ).
Hopefully fix a problem with using TinyDB as a dependency in a setup.py script (see issue #51 ).
- Added support for custom serialization. That way, you can teach TinyDB to store datetime objects in a JSON file :) (see issue #48 and pull request #
Added support for custom serialization. That way, you can teach TinyDB to store datetime objects in a JSON file :) (see issue #48 and pull request #50 )
Fixed a performance regression when searching became slower with every search (see issue #49 )
Internal code has been cleaned up
- Fixed a data loss when using CachingMiddleware together with JSONStorage (see issue #47 )
Fixed a data loss when using CachingMiddleware together with JSONStorage (see issue #47 )
- Fixed handling of IDs with the JSON backend that converted integers to strings (see issue #45 )
Fixed handling of IDs with the JSON backend that converted integers to strings (see issue #45 )
- Extended any and all queries to take lists as conditions (see pull request #38 )
Extended any and all queries to take lists as conditions (see pull request #38 )
Fixed an decode error when installing TinyDB in a non-UTF-8 environment (see pull request #37 )
Fixed some issues with CachingMiddleware in combination with JSONStorage (see pull request #39 )
Your coding agent can read these notes before it upgrades. Set up the MCP server →