by msiemens

msiemens / tinydb

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

3.8K Stars 349 Forks Last release: 27 days ago (v4.2.0) MIT License 587 Commits 52 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

.. image:: https://raw.githubusercontent.com/msiemens/tinydb/master/artwork/logo.png :scale: 100% :height: 150px

|Build Status| |Coverage| |Version|

Quick Links

  • Example Code
  • Supported Python Versions
  • Documentation 
  • Changelog 
  • Extensions 
  • Contributing


TinyDB is a lightweight document oriented database optimized for your happiness :) It's written in pure Python and has no external dependencies. The target are small apps that would be blown away by a SQL-DB or an external database server.

TinyDB is:

  • tiny: The current source code has 1800 lines of code (with about 40% documentation) and 1600 lines tests.

  • document oriented: Like MongoDB_, you can store any document (represented as

    ) in TinyDB.
  • optimized for your happiness: TinyDB is designed to be simple and fun to use by providing a simple and clean API.

  • written in pure Python: TinyDB neither needs an external server (as e.g.

    _) nor any dependencies from PyPI.
  • works on Python 3.5+ and PyPy: TinyDB works on all modern versions of Python and PyPy.

  • powerfully extensible: You can easily extend TinyDB by writing new storages or modify the behaviour of storages with Middlewares.

  • 100% test coverage: No explanation needed.

To dive straight into all the details, head over to the

TinyDB docs
. You can also discuss everything related to TinyDB like general development, extensions or showcase your TinyDB-based projects on the
discussion forum 

Supported Python Versions

TinyDB has been tested with Python 3.5 - 3.8 and PyPy.

Example Code

.. code-block:: python

>>> from tinydb import TinyDB, Query
>>> db = TinyDB('/path/to/db.json')
>>> db.insert({'int': 1, 'char': 'a'})
>>> db.insert({'int': 1, 'char': 'b'})

Query Language

.. code-block:: python

>>> User = Query()
>>> # Search for a field value
>>> db.search(User.name == 'John')
[{'name': 'John', 'age': 22}, {'name': 'John', 'age': 37}]

>>> # Combine two queries with logical and >>> db.search((User.name == 'John') & (User.age <= 30)) [{'name': 'John', 'age': 22}]

>>> # Combine two queries with logical or >>> db.search((User.name == 'John') | (User.name == 'Bob')) [{'name': 'John', 'age': 22}, {'name': 'John', 'age': 37}, {'name': 'Bob', 'age': 42}]

>>> # More possible comparisons: != < > <= >= >>> # More possible checks: where(...).matches(regex), where(...).test(your_test_func)


.. code-block:: python

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

Using Middlewares

.. code-block:: python

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


Whether reporting bugs, discussing improvements and new ideas or writing extensions: Contributions to TinyDB are welcome! Here's how to get started:

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug
  2. Fork
    the repository 
    _ on Github, create a new branch off the
    branch and start making your changes (known as
    GitHub Flow 
  3. Write a test which shows that the bug was fixed or that the feature works as expected
  4. Send a pull request and bug the maintainer until it gets merged and published ☺

.. |Build Status| image:: https://img.shields.io/azure-devops/build/msiemens/3e5baa75-12ec-43ac-9728-89823ee8c7e2/2.svg?style=flat-square :target: https://dev.azure.com/msiemens/github/_build?definitionId=2 .. |Coverage| image:: http://img.shields.io/coveralls/msiemens/tinydb.svg?style=flat-square :target: https://coveralls.io/r/msiemens/tinydb .. |Version| image:: http://img.shields.io/pypi/v/tinydb.svg?style=flat-square :target: https://pypi.python.org/pypi/tinydb/ .. _Buzhug: http://buzhug.sourceforge.net/ .. _CodernityDB: https://github.com/perchouli/codernitydb .. _MongoDB: http://mongodb.org/

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.