Skip to content
TinyDB is a lightweight document oriented database optimized for your happiness :)
Branch: master
Clone or download
msiemens refactor: use new architecture
See rationale and details in #284

Closes #250
Closes #103
Latest commit 50d0cd8 Nov 2, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update stale.yml Aug 25, 2018
artwork Larger PNG version of the logo Sep 4, 2014
docs style: clean up code formatting Nov 2, 2019
tests refactor: use new architecture Nov 2, 2019
tinydb refactor: use new architecture Nov 2, 2019
.coveragerc CI: Collect branch coverage Sep 13, 2017
.gitignore Feature: __repr__ methods for classes TinyDB, Table and Query (#229) Sep 13, 2018
CONTRIBUTING.rst Fix some spelling mistakes in the docs Jun 2, 2015
LICENSE Rename LICENCE to american spelling Oct 24, 2016
README.rst Docs: Use Azure Pipelines CI badge May 30, 2019
azure-pipelines.yml ci: run pytest using poetry Nov 2, 2019
pyproject.toml build: fix pytest-runner version specifier Nov 2, 2019
pytest.ini build: switch to Poetry for project configuration Nov 2, 2019


Build Status Coverage Version

Quick Links


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 1600 lines of code (with about 33% documentation) and 1800 lines of tests. For comparison: Buzhug has about 2500 lines of code (w/o tests), CodernityDB has about 7000 lines of code (w/o tests).
  • document oriented: Like MongoDB, you can store any document (represented as dict) 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. PyMongo) nor any dependencies from PyPI.
  • works on Python 2.7 and 3.3 – 3.7 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 2.7, 3.3 - 3.6 and PyPy.

Example Code

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

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

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

>>> # Combine two queries with logical or
>>> == 'John') | ( == '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)


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

Using Middlewares

>>> 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 master 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 ☺
You can’t perform that action at this time.