TinyDB: Lightweight NoSQL Database for Python

Complete Guide to TinyDB: A Lightweight NoSQL Database for Python

Introduction

Modern applications don't always need powerful, complex database systems. When your project doesn't require scalability or high-speed processing of large datasets, a lightweight embedded database is often enough. TinyDB – a NoSQL database written entirely in Python – offers a convenient and simple solution for storing structured data without SQL.

TinyDB saves data in JSON format and requires no server setup. This makes it ideal for scripts, small CLI tools, desktop applications, prototypes, and educational projects. The library is only a few kilobytes in size with minimal dependencies, making it an excellent choice for lightweight solutions.

Installation and Basic Setup

Installing TinyDB

Install TinyDB with a single pip command:

pip install tinydb

Optional extensions for additional features:

pip install tinydb[compression]  # For data compression
pip install tinydb[yaml]         # For YAML support

Creating a Database

Create a database saved to a file:

from tinydb import TinyDB
db = TinyDB('db.json')  # File is created automatically

Create an in-memory database:

from tinydb.storages import MemoryStorage
db = TinyDB(storage=MemoryStorage)

Configuring Encoding and Options

from tinydb import TinyDB
from tinydb.storages import JSONStorage

# Configure encoding
db = TinyDB('db.json', encoding='utf-8')

# Configure JSON indentation for readability
db = TinyDB('db.json', indent=4, separators=(',', ': '))

TinyDB Data Structure Basics

TinyDB uses a document-oriented data model:

• Data is stored as a list of documents (Python dictionaries)
• Each document has a unique doc_id, auto-generated
• Supported types: strings, numbers, lists, dictionaries, booleans, and null
• Documents can have different structures within the same table
• Supports nested data of any depth

Basic Data Operations

Inserting Data

Insert a single document:

from tinydb import TinyDB
db = TinyDB('db.json')

# Simple insert
db.insert({'name': 'John', 'age': 30, 'city': 'New York'})

# Insert and get the document ID
doc_id = db.insert({'name': 'Anna', 'age': 25})
print(f"Document added with ID: {doc_id}")

Insert multiple documents:

users = [
    {'name': 'Anna', 'age': 25, 'profession': 'Designer'},
    {'name': 'Peter', 'age': 40, 'profession': 'Developer'},
    {'name': 'Maria', 'age': 28, 'profession': 'Manager'}
]

doc_ids = db.insert_multiple(users)
print(f"Documents inserted: {len(doc_ids)}")

Reading Data

Get all documents:

all_users = db.all()
print(f"Total users: {len(all_users)}")

Get a document by ID:

user = db.get(doc_id=1)
if user:
    print(f"Found user: {user['name']}")

Searching and Filtering

Basic search with Query:

from tinydb import Query
User = Query()

# Exact match search
users = db.search(User.name == 'John')

# Conditional search
adults = db.search(User.age >= 30)

# Get first match
user = db.get(User.name == 'Anna')

Advanced search conditions:

# Logical AND
young_designers = db.se