What is TinyDB?
TinyDB is a lightweight NoSQL engine designed for Python applications that need simple, structured data storage. It supports storing data as JSON files on your hard disk or in memory for faster access times. Think of it as a free NoSQL alternative to SQLite that’s perfect for projects that don’t require a full-featured database engine.
Key advantages of TinyDB include:
- Zero configuration required
- Human-readable JSON storage format
- Built-in query system
- Thread-safe operations
- Pure Python implementation
Installing TinyDB
Before installing TinyDB, it’s recommended to set up a virtual environment for your Python project. This ensures clean dependency management and prevents conflicts with other projects.
# For Python 3
pip install tinydb
# Alternative for systems with both Python 2 and 3
pip3 install tinydb
If you don’t have pip installed or are unsure which Python version you’re using, check out our comprehensive Python Basics guide for setup instructions.
Getting Started with TinyDB
TinyDB operates entirely with JSON data structures using key/value pairs. For this tutorial, we’ll build a to-do list application that stores:
- Task description
- Due date
- Completion status
- Category classification
Basic Setup
# Import TinyDB and Query modules
from tinydb import TinyDB, Query
# Create database instance (creates todolist.json file)
db = TinyDB('todolist.json')
# Define sample records
item1 = {'Status':'New','DueDate': '5/12/18', 'Category': 'Work','Description':'Send that Email'}
item2 = {'Status':'New','DueDate': '5/11/18', 'Category': 'Home','Description':'Do the Laundry'}
item3 = {'Status':'New','DueDate': '5/11/18', 'Category': 'Home','Description':'Do the Dishes'}
Inserting Records
Adding data to TinyDB is straightforward using the insert() method. You can insert predefined variables or create records directly within the function call:
# Insert using predefined variables
db.insert(item1)
db.insert(item2)
db.insert(item3)
# Insert directly without variables
db.insert({'Status':'New','DueDate': '5/14/18', 'Category': 'Work','Description':'Request a Promotion'})
# Verify insertion by displaying all records
print(db.all())
Searching and Querying Records
TinyDB provides powerful search capabilities for filtering records based on specific criteria. Here are common search patterns:
# Create Query object
Todo = Query()
# Single criteria search
home_tasks = db.search(Todo.Category == 'Home')
# Multiple criteria with AND condition
work_urgent = db.search((Todo.Category == 'Work') & (Todo.DueDate == '5/14/18'))
# Multiple criteria with OR condition
urgent_or_home = db.search((Todo.Category == 'Home') | (Todo.DueDate == '5/14/18'))
# Store search results and iterate
results = db.search(Todo.Category == 'Home')
for result in results:
print(result)
Updating and Deleting Records
TinyDB makes it easy to update existing records or remove completed tasks from your database:
Updating Records
# Update all Home category tasks to Done status
db.update({'Status': 'Done'}, Todo.Category == 'Home')
Deleting Records
# Remove all completed tasks
db.remove(Todo.Status == 'Done')
# Clear entire database (useful for testing)
db.purge()
Complete Example Script
Here’s a comprehensive example that demonstrates all TinyDB operations in a single script:
# Complete TinyDB example script
from tinydb import TinyDB, Query
# Initialize database
db = TinyDB('todolist.json')
Todo = Query()
# Create sample data
item1 = {'Status':'New','DueDate': '5/12/18', 'Category': 'Work','Description':'Send that Email'}
item2 = {'Status':'New','DueDate': '5/11/18', 'Category': 'Home','Description':'Do the Laundry'}
item3 = {'Status':'New','DueDate': '5/11/18', 'Category': 'Home','Description':'Do the Dishes'}
# Insert records
db.insert(item1)
db.insert(item2)
db.insert(item3)
db.insert({'Status':'New','DueDate': '5/14/18', 'Category': 'Work','Description':'Request a Promotion'})
# Display all records
print("All records:")
print(db.all())
# Update Home category tasks to Done
db.update({'Status': 'Done'}, Todo.Category == 'Home')
# Search and display Home category tasks
print("\nHome category tasks:")
results = db.search(Todo.Category == 'Home')
for result in results:
print(result)
# Remove completed tasks
db.remove(Todo.Status == 'Done')
# Show remaining records
print("\nRemaining records:")
print(db.all())
Best Practices and Tips
💡 Pro Tips for TinyDB Success
- Use descriptive field names for better code readability
- Implement data validation before inserting records
- Consider using TinyDB’s memory storage for temporary data
- Back up your JSON files regularly in production environments
- Use the purge() function during testing to reset your database