Welcome to pydantic-sqlite!

pydantic-sqlite makes it easy to store Pydantic models directly in a SQLite database and retrieve fully-typed objects -> no manual serialization.

pydantic-sqlite bridges the gap between Pydantic models and SQLite persistence. Instead of manually mapping your models to database columns or writing SQL, you work directly with your Pydantic BaseModel instances. The library automatically handles serialization and deserialization. You can store BaseModel instancea directly in the database, and when querying, you always get back fully reconstructed, ready-to-use Pydantic objects—just like your originals.

Key Features

  • Seamless Model Storage - Store Pydantic BaseModel directly in SQLite
  • Nested Model Support - Automatically handle foreign key relationships between models
  • Flexible Primary Keys - Use any field as primary key (defaults to uuid)
  • Complex Type Handling - Support for lists, unions, and custom type conversions
  • Type Safety - Retrieved objects are fully reconstructed as their original Pydantic models
  • Simple Query API - Intuitive interface for adding and querying data
  • Error Recovery - Optional FailSafeDataBase context manager for automatic snapshots on exceptions

Quick Example

from pydantic import BaseModel
from pydantic_sqlite import DataBase

class Person(BaseModel):
    uuid: str
    name: str
    age: int

# Create database and add model
db = DataBase()
person = Person(uuid="1", name="Alice", age=30)
db.add("Persons", person)

# Query and retrieve
for person in db("Persons"):
    print(f"{person.name} is {person.age} years old")

Getting Started

Follow the Basic Usage guide for installation and your first database.

For more examples and use cases, check out Advanced Usage and Examples.

Installation

Using pip: 

pip install pydantic-sqlite

Using uv: 

uv add pydantic-sqlite

Using poetry: 

poetry add pydantic-sqlite

Documentation

  • Basic Usage - Installation, core features and common patterns
  • Advanced Usage - Nested models, custom configurations, and complex scenarios
  • Examples - Complete, runnable code examples

Support

License

MIT – See LICENSE for details.