TinyDB is a lightweight, document-oriented database written in pure Python that stores records as dictionaries in a local JSON file, aimed at small applications that would be overwhelmed by a SQL database or an external database server.

What it is

TinyDB lives in the Python ecosystem as an embedded database in the literal sense: the database is a library inside the application process, not a service running somewhere else. Documents are ordinary Python dict objects, storage defaults to a JSON file on disk, and the implementation is pure Python with no dependencies from PyPI. The specific thing it replaces is the setup in which a small application has to install, configure, secure, and keep running a database daemon, or reach a remote one through a driver such as PyMongo.

The problem it solves is the mismatch between small applications and server-grade databases. A script, a desktop tool, a prototype, or a test harness that needs to store a few thousand documents does not need a network protocol, a connection pool, or an operations story. TinyDB offers query, tables, and persistence in 1800 lines of source code, about 40 percent of it documentation, backed by 1600 lines of tests and 100 percent coverage. It is tested on Python 3.8 through 3.13 and PyPy3, and released under the MIT licence.

Key capabilities

• Single-call document storage: db = TinyDB('/path/to/db.json') opens the file, and db.insert({'int': 1, 'char': 'a'}) writes a document into it.
• A query language built on Query(): field comparisons, logical combination with & and |, negation with ~, and field transformation through User.age.map(lambda x: x + x).
• Predicate checks through where(...).matches(regex) for regular expressions and where(...).test(your_test_func) for custom Python callables.
• Multiple tables inside one database, created with db.table('name') and read back through table.all().
• Pluggable storages and middlewares: JSONStorage is the default, and passing storage=CachingMiddleware(JSONStorage) to the TinyDB constructor changes how storage behaves.
• Pure Python with no external server and no PyPI dependencies, documented at tinydb.readthedocs.org alongside a changelog and an extensions list.

Who uses it and how

• Small applications and scripts that need persistence but cannot justify provisioning a database server or a client/server driver.
• Prototypes and internal tools where the store is a plain db.json file that can be inspected, copied, or handled like any other file.
• Test and development setups that create an isolated database per run without a container, daemon, or network dependency.
• Environments pinned to Python 3.8 through 3.13 or PyPy3, or projects that need to change storage behaviour through custom storages and middlewares.

Getting started

TinyDB ships as the pure-Python tinydb package, with no external dependencies and no server to run. The documented entry point is from tinydb import TinyDB, Query followed by db = TinyDB('/path/to/db.json'), and full installation and API guidance lives at tinydb.readthedocs.org.

How it compares

Where MongoDB requires a server and PyMongo requires a driver to reach it, TinyDB runs inside the Python process with neither and pulls nothing from PyPI. Licencing is MIT with no paid tier, self-hosting means installing a package rather than operating a service, and data ownership is immediate because the documents are a file the application already owns.

When to use it — and when not to

Self-hosters operate nothing beyond their own Python environment: no database server, no external dependency, no container. The honest limitation is project status, as TinyDB is in maintenance mode, mature and stable but with no significant new features or architectural changes planned and releases limited mainly to bugfixes and community contributions. Teams that need an active feature roadmap, a client/server architecture, or a database built for heavy multi-process write contention should look elsewhere.

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

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

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

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