TinyDB: document database in pure Python with no dependencies

TinyDB stores dictionaries as JSON documents to a local file

TinyDB is a document database that lives in a single Python file with no external dependencies. Unlike SQLite or PostgreSQL, TinyDB has no server component and no separate daemon to configure; you import it in your Python code and point it at a file path where you want to store data. Documents are Python dictionaries, stored to disk as JSON. The README explains that TinyDB targets small applications that would be overwhelmed by a SQL database or external server.

The architecture is simple: each table is a JSON file on disk. When you insert a document, TinyDB writes it to the JSON file immediately. When you query, TinyDB reads the entire file into memory, searches through the documents, and returns matches. This means TinyDB performs well when your dataset is small enough to fit in RAM, but slows down noticeably as the corpus grows. The README emphasizes that the codebase is tiny: 1800 lines of code (with 40% documentation) plus 1600 lines of tests.

Installing TinyDB and creating your first database

Install TinyDB from PyPI with pip. According to pyproject.toml, TinyDB requires Python 3.10 or later and PyPy3. The package is compatible with CPython 3.10, 3.11, 3.12, 3.13, and 3.14, as well as the PyPy3 implementation.

pip install tinydb

After installation, create a Python script that imports TinyDB and opens a database. The README's example code shows instantiating a TinyDB object with a file path, then inserting documents:

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

Each insert call writes a document to the database file. TinyDB automatically assigns each document an ID. The path can be any location your Python process has write access to. The database file is a plain JSON file, so you can inspect and edit it directly if needed. TinyDB has no setup wizard or initialization step; simply importing the library and calling TinyDB() with a path is sufficient to begin storing data.

Querying documents with Python expressions

TinyDB's query syntax uses Python object notation to express conditions. Create a Query object, then use Python operators to build filter expressions. According to the README, comparisons include ==, !=, <, >, <=, and >= for equality and ordering checks. Logical operators combine conditions: & for AND, | for OR, and ~ for NOT.

The README demonstrates searching for a single field value:

from tinydb import Query
User = Query()
db.search(User.name == 'John')

This returns all documents where the name field equals 'John'. Combine conditions with logical operators:

db.search((User.name == 'John') & (User.age <= 30))

This finds documents matching both conditions, with & requiring both to be true. You can also use | for OR logic:

db.search((User.name == 'John') | (User.name == 'Bob'))

This returns all documents where the name is either 'John' or 'Bob'. The ~ operator negates a query:

db.search(~(User.name == 'John'))

TinyDB also supports regex matching with `.matches()`, custom test functions with `.test()`, and field transformations with `.map()`. The README notes that `.map()` applies a function to a field value before comparison:

db.search((User.age.map(lambda x: x + x) == 44))

This finds documents where doubling the age field equals 44. These operators enable complex queries without SQL syntax, leveraging Python's native object model instead.

Storing separate tables and adding caching middleware

TinyDB supports multiple tables within a single database instance. Call the `.table()` method with a table name to access a separate collection:

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

Each table stores data in a separate JSON file. This is useful for organizing data by type, such as users in one table and products in another. Calling `.all()` returns every document in the table, making it useful for iterating over the full dataset without filtering.

For read-heavy workloads, add a caching middleware to avoid re-reading the JSON file on every query. The README shows using CachingMiddleware:

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

With caching enabled, TinyDB holds the entire table in memory until the cache is explicitly cleared or the program exits. This trades memory usage for query speed. The CachingMiddleware wraps JSONStorage, which is TinyDB's default storage backend, to cache the JSON document in RAM. This is particularly useful for applications with frequent queries but infrequent writes.

TinyDB only works in-process and with small datasets

TinyDB is not a network database. It runs only within your Python process; other processes and machines cannot access the same TinyDB instance. If you need multiple processes to share data, run a database server like PostgreSQL or SQLite instead.

Dataset size matters. TinyDB reads and parses the entire JSON file into memory for each query by default (even with caching, the cache is still in-process). A 100 MB JSON file of documents will require 100 MB of RAM per query. For applications with millions of records or datasets larger than available RAM, TinyDB becomes impractical. Use PostgreSQL, MongoDB or another server-based database for larger corpora.

The README states the project is in maintenance mode: it has reached a mature, stable state where significant new features or architectural changes are not planned. Bug fixes and community contributions are still accepted. This means TinyDB will not gain features like replication, sharding or distributed queries.

Where SQLite and MongoDB differ from TinyDB

SQLite is a relational database engine embedded in many applications. It supports SQL queries, transactions, indexes, and handles much larger datasets than TinyDB. SQLite also has a C implementation optimized for performance. Choose SQLite over TinyDB if you need relational joins, transactions, or datasets larger than a few hundred thousand records.

MongoDB is a document database like TinyDB, but runs as a server. Multiple processes and remote clients can connect to MongoDB simultaneously. MongoDB handles replication, sharding, and scales horizontally. MongoDB requires more setup and infrastructure. Choose MongoDB if you need multi-process access, network clients, or data replication.

TinyDB occupies a middle ground: simpler than SQLite for small projects, sufficient when you do not need SQL or multiple processes, but limited to in-process use and small datasets.

Maintenance status and extensibility

The project is in maintenance mode. The last push was on 2026-09-18, and the most recent release v4.9.0 was published on 2026-08-06. No major feature development is planned, but the maintainer releases updates for bugs and contributions from the community. The stable status means the API is unlikely to change in breaking ways, making TinyDB reliable for long-term use in small projects.

TinyDB is extensible. According to the README, you can write custom storage backends to replace JSONStorage, such as storage that persists to a database, cloud storage, or custom binary format. Middlewares allow you to modify storage behavior; CachingMiddleware is one example. The documentation links to an extensions page listing community-maintained storage and middleware implementations. This extensibility allows you to adapt TinyDB to custom persistence layers without forking the project.

TinyDB is licensed under the MIT license, making it suitable for commercial use. The project includes 100% test coverage according to the README, and development is open to contributions via pull requests. The codebase has 1800 lines of production code and 1600 lines of tests, allowing contributors to understand and modify the entire implementation quickly.

Editorial conclusion

Use TinyDB for small Python applications that need persistent storage of structured data without running a database server. Skip it if you have more than a few hundred thousand records, need transactions or complex joins, or run on Python 3.9 or earlier. Start by installing from pip, creating a TinyDB instance pointing to a JSON file, and experimenting with insert and search operations.

Frequently asked questions

Official sources

1. License: MIT
2. msiemens/tinydb on GitHub
3. Project website
4. README
5. Releases