README

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

|Build Status| |Coverage| |Version|

Quick Links


- Example Code_
- Supported Python Versions_
- Documentation _
- Changelog _
- Extensions _
- Contributing_

Introduction


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 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 3.8+ and PyPy3: 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.8 - 3.13 and PyPy3.

Project Status


This project is in maintenance mode. It has reached a mature, stable state
where significant new features or architectural changes are not planned. That
said, there will still be releases for bugfixes or features contributed by
the community. Read more about what this means in particular
here _.

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

      Negate a query with logical not
     db.search(~(User.name == 'John'))
    [{'name': 'Megan', 'age': 27}, {'name': 'Bob', 'age': 42}]

      Apply transformation to field with map
     db.search((User.age.map(lambda x: x + x) == 44))
     [{'name': 'John', 'age': 22}]

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

Tables
======

.. code-bl