Version Numbering

TinyDB follows the SemVer versioning guidelines. For more information, see


  • Nothing yet

v3.12.1 (2018-11-09)

  • Fix: Don’t break when searching the same query multiple times (see pull request 249)
  • Internal change: allow as valid document types (see pull request 245)

v3.12.0 (2018-11-06)

  • Feature: Add encoding option to JSONStorage (see pull request 238)
  • Internal change: allow as valid document types (see pull request 245)

v3.11.1 (2018-09-13)

  • Bugfix: Make path queries ('key))) work again (see issue 232)
  • Improvement: Add custom repr representations for main classes (see pull request 229)

v3.11.0 (2018-08-20)

  • 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)

v3.10.0 (2018-07-21)

v3.9.0 (2018-04-24)

  • Feature: Allow setting a table class for single table only (see issue 197)
  • Internal change: call fsync after flushing JSONStorage (see issue 208)

v3.8.1 (2018-03-26)

v3.8.0 (2018-03-01)

  • 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)

v3.7.0 (2017-11-11)

v3.6.0 (2017-10-05)

  • 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)

v3.5.0 (2017-08-30)

v3.4.1 (2017-08-23)

  • Expose TinyDB version via import tinyb; tinydb.__version__ (see issue #148).

v3.4.0 (2017-08-08)

  • Add new update operations: add(key, value), substract(key, value), and set(key, value) (see pull request #145).

v3.3.1 (2017-06-27)

  • Use relative imports to allow vendoring TinyDB in other packages (see pull request #142).

v3.3.0 (2017-06-05)

  • Allow iterating over a database or table yielding all documents (see pull request #139).

v3.2.3 (2017-04-22)

  • Fix bug with accidental modifications to the query cache when modifying the list of search results (see issue #132).

v3.2.2 (2017-01-16)

  • Fix the Query constructor to prevent wrong usage (see issue #117).

v3.2.1 (2016-06-29)

  • 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).

v3.2.0 (2016-04-25)

  • 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).

v3.1.3 (2016-02-14)

  • Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul).

v3.1.2 (2016-01-30)

  • Fix a bug when using unhashable documents (lists, dicts) with Query.any or Query.all queries (see a forum post by karibul).

v3.1.1 (2016-01-23)

  • 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).

v3.1.0 (2015-12-31)

  • 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).

v3.0.0 (2015-11-13)

  • Overhauled Query model:
    • where('...').contains('...') has been renamed to where('...').search('...').
    • Support for ORM-like usage: User = Query(); == 'John').
    • where('foo') is an alias for Query().foo.
    • where('foo').has('bar') is replaced by either where('foo').bar or Query()
      • 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 explicitely: 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.

v2.4.0 (2015-08-14)

v2.3.2 (2015-05-20)

  • 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).

v2.3.1 (2015-04-30)

  • Hopefully fix a problem with using TinyDB as a dependency in a script (see issue #51).

v2.3.0 (2015-04-08)

  • 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

v2.2.2 (2015-02-12)

  • Fixed a data loss when using CachingMiddleware together with JSONStorage (see issue #47)

v2.2.1 (2015-01-09)

  • Fixed handling of IDs with the JSON backend that converted integers to strings (see issue #45)

v2.2.0 (2014-11-10)

  • 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)

v2.1.0 (2014-10-14)

  • Added where(...).contains(regex) (see issue #32)
  • Fixed a bug that corrupted data after reopening a database (see issue #34)

v2.0.1 (2014-09-22)

  • Fixed handling of Unicode data in Python 2 (see issue #28).

v2.0.0 (2014-09-05)

Upgrade Notes


TinyDB changed the way data is stored. You may need to migrate your databases to the new scheme. Check out the Upgrade Notes for details.

v1.4.0 (2014-07-22)

  • Added insert_multiple function (see issue #8).

v1.3.0 (2014-07-02)

  • Fixed bug #7: IDs not unique.
  • Extended the API: db.count(where(...)) and db.contains(where(...)).
  • The syntax query in db is now deprecated and replaced by db.contains.

v1.2.0 (2014-06-19)

v1.1.1 (2014-06-14)

  • Merged PR #5: Fix minor documentation typos and style issues.

v1.1.0 (2014-05-06)

  • Improved the docs and fixed some typos.
  • Refactored some internal code.
  • Fixed a bug with multiple TinyDB? instances.

v1.0.1 (2014-04-26)

  • Fixed a bug in JSONStorage that broke the database when removing entries.

v1.0.0 (2013-07-20)

  • First official release – consider TinyDB stable now.

« Contribution Guidelines | Upgrading to Newer Releases »