How to Use TinyDB

Basic Usage


By default, TinyDB stores data as JSON files, so you have to specify the file path:

>>> from tinydb import TinyDB, where
>>> db = TinyDB('/path/to/db.json')

You also can use in-memory JSON to store data:

>>> from tinydb.storages import MemoryStorage
>>> db = TinyDB(storage=MemoryStorage)


As a document-oriented database, TinyDB uses dicts to store data:

>>> db.insert({'int': 1, 'char': 'a'})
>>> db.insert({'int': 1, 'char': 'b'})
>>> db.insert({'int': 1, 'value': 5.0})

Getting Data


Throughout this section, the return values are stripped of the _id key for clarity reasons. So:

[{'int': 1, 'value': 5.0}]

would actually be some something like:

[{'int': 1, 'value': 5.0, '_id': 3}]

Getting all data stored:

>>> db.all()
[{'int': 1, 'char': 'a'}, {'int': 1, 'char': 'b'}, {'int': 1, 'value': 5.0}]

Getting the database size (number of elements stored):

>>> len(db)

Search for all elements that have the value key defined:

[{'int': 1, 'value': 5.0}]

Search for a specific value:

>>>'int') == 1)
[{'int': 1, 'char': 'a'}, {'int': 1, 'char': 'b'}, {'int': 1, 'value': 5.0}]

Count the number of elements matching a query:

>>> db.count(where('int') == 1)

Check whether a specific element is in the database:

>>> db.contains(where('int') == 1)
>>> db.contains(where('int') == 0)

Alternative syntax for db.contains:

>>> if where('value') == 0.5 in db: print 'Found!'


Deprecated since version 1.3.0: This syntax will propably be removed soon. Please use the db.contains(...) syntax instead.

Other comparison operators you can use:

  • where('int') != 1
  • where('int') < 2 and <=
  • where('int') > 0 and >=

Combine two queries with logical and:

>>>'int') == 1) & (where('char') == 'b'))
[{'int': 1, 'char': 'b'}]

Combine two queries with logical or:

>>>'char') == 'a') | (where('char') == 'b'))
[{'int': 1, 'char': 'a'}, {'int': 1, 'char': 'b'}]

When using & or |, make sure you wrap the conditions on both sides with parentheses or Python will mess up the comparison.

More advanced queries

Check against a regex:

[{'int': 1, 'char': 'a'}, {'int': 1, 'char': 'b'}]

Use a custom test function:

>>> test_func = lambda c: c == 'a'
[{'char': 'a', 'int': 1}]

Also, if you want to get only one element, you can use:

>>> db.get(where('value'))
{'int': 1, 'value': 5.0}


If multiple elements match the query, only one of them will be returned!


You can remove all elements matching a query:

>>> db.remove(where('int') == 1)
>>> len(db)

You also can purge all entries:

>>> db.purge()
>>> len(db)


You can update elements matching a query. Assuming you have these elements in the database:

>>> db.insert({'int': 1, 'char': 'a'})
>>> db.insert({'int': 1, 'char': 'b'})
>>> db.insert({'int': 1, 'value': 5.0})

Then you can update selected elements like this:

>>> db.update({'int': 2}, where('char') == 'a')
>>> db.all()
[{'int': 2, 'char': 'a'}, {'int': 1, 'char': 'b'}, {'int': 1, 'value': 5.0}]

Advanced Usage


You can use TinyDB with multiple tables. They behave exactly as described above:

>>> table = db.table('name')
>>> table.insert({'value': True})
>>> table.all()
[{'value': True}]

In addition, you can remove all tables by using:

>>> db.purge_tables()


When using the operations described above using db, TinyDB actually uses a table named _default.


Middlewares wrap around existing storages allowing you to customize their behaviour.

>>> from tinydb.storages import JSONStorage
>>> from tinydb.middlewares import CachingMiddleware
>>> db = TinyDB('/path/to/db.json', storage=CachingMiddleware(JSONStorage))

TinyDB ships with these middlewares:

  • CachingMiddleware: Improves speed by reducing disk I/O. It caches all read operations and writes data to disk every CachingMiddleware.WRITE_CACHE_SIZE write operations.
  • ConcurrencyMiddleware: Allows you to use TinyDB in multithreaded environments by using a lock on read and write operations, making them virtually atomic.


You can nest middlewares:

>>> from tinydb.middlewares import CachingMiddleware, ConcurrencyMiddleware
>>> db = TinyDB('/path/to/db.json', storage=ConcurrencyMiddleware(CachingMiddleware(JSONStorage)))

About TinyDB

TinyDB is a tiny, document oriented database optimized for your happiness :)

Useful Links

Table Of Contents