SQLModel with Protocol Buffers & gRPC support

A fork of SQLModel adding seamless protobuf/gRPC integration

---

🚀 What is this?

This is a fork of SQLModel that extends the original library with Protocol Buffers (protobuf) and gRPC integration. SQLModel is a library for interacting with SQL databases from Python code, with Python objects.

Original SQLModel: https://sqlmodel.tiangolo.com | GitHub

---

SQLModel is a library for interacting with SQL databases from Python code, with Python objects. It is designed to be intuitive, easy to use, highly compatible, and robust.

SQLModel is based on Python type annotations, and powered by Pydantic and SQLAlchemy.

The key features are:

• Intuitive to write: Great editor support. Completion everywhere. Less time debugging. Designed to be easy to use and learn. Less time reading docs.
• Easy to use: It has sensible defaults and does a lot of work underneath to simplify the code you write.
• Compatible: It is designed to be compatible with FastAPI, Pydantic, and SQLAlchemy.
• Extensible: You have all the power of SQLAlchemy and Pydantic underneath.
• Short: Minimize code duplication. A single type annotation does a lot of work. No need to duplicate models in SQLAlchemy and Pydantic.
• 🆕 Protocol Buffers Integration: SQLModel classes now implement the protobuf Message interface, enabling direct serialization/deserialization and gRPC compatibility.
• 🆕 Automatic Descriptor Generation: Protobuf descriptors are automatically synthesized from your SQLModel classes with intelligent type inference.
• 🆕 gRPC Ready: Use your SQLModel models directly in gRPC services without additional conversion code.

SQL Databases in FastAPI

SQLModel is designed to simplify interacting with SQL databases in FastAPI applications, it was created by the same author. 😁

It combines SQLAlchemy and Pydantic and tries to simplify the code you write as much as possible, allowing you to reduce the code duplication to a minimum, but while getting the best developer experience possible.

SQLModel is, in fact, a thin layer on top of Pydantic and SQLAlchemy, carefully designed to be compatible with both.

New Features: Protocol Buffers & gRPC Integration

This fork extends SQLModel with seamless Protocol Buffers (protobuf) and gRPC support:

✨ Key Additions

1. Protobuf Message Interface: All SQLModel classes now inherit from google.protobuf.message.Message, making them fully compatible with protobuf serialization and gRPC.

2. Automatic Descriptor Generation: Protobuf descriptors are automatically synthesized from your SQLModel class definitions, with intelligent type inference from Python type annotations.

3. Full Protobuf API: All standard protobuf methods are implemented:

   • SerializeToString() / serialize_to_string() - Serialize to binary
   • ParseFromString() / parse_from_string() - Deserialize from binary
   • MergeFrom() / merge_from() - Merge from another message
   • Clear() / clear() - Reset to defaults
   • HasField() / has_field() - Check field presence
   • And more...

4. Type Inference: Automatically maps Python types to protobuf field types:

   • int → TYPE_INT64
   • float → TYPE_DOUBLE
   • bool → TYPE_BOOL
   • str → TYPE_STRING
   • bytes → TYPE_BYTES
   • Lists/tuples → LABEL_REPEATED

5. Custom Field Descriptors: Optionally provide custom protobuf field descriptors via Field(grpc_descriptor=...) for fine-grained control.

Example: Using SQLModel with gRPC

from sqlmodel import Field, SQLModel

class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    age: int | None = None

# Create a hero instance
hero = Hero(name="Deadpond", age=30)

# Serialize to protobuf binary format
serialized = hero.SerializeToString()

# Deserialize back
hero2 = Hero()
hero2.ParseFromString(serialized)

# Use directly in gRPC services!
# Your SQLModel classes work seamlessly with gRPC

Requirements

A recent and currently supported version of Python.

As SQLModel is based on Pydantic and SQLAlchemy, it requires them. They will be automatically installed when you install SQLModel.

Additional requirement for this fork: protobuf>=5.29.5 (automatically installed).

Installation

Make sure you create a virtual environment, activate it, and then install this fork:

# Install from source (this fork)
$ uv pip install -e .

# Or install directly from git
$ uv pip install git+https://github.com/YOUR_USERNAME/grpcmodel.git

Note: For the original SQLModel without protobuf support, install from PyPI:

$ uv pip install sqlmodel

Example

For an introduction to databases, SQL, and everything else, see the SQLModel documentation.

Here's a quick example. ✨

A SQL Table

Imagine you have a SQL table called hero with:

• id
• name
• secret_name
• age

And you want it to have this data:

id	name	secret_name	age
1	Deadpond	Dive Wilson	null
2	Spider-Boy	Pedro Parqueador	null
3	Rusty-Man	Tommy Sharp	48

Create a SQLModel Model

Then you could create a SQLModel model like this:

from sqlmodel import Field, SQLModel


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None

That class Hero is a SQLModel model, the equivalent of a SQL table in Python code.

And each of those class attributes is equivalent to each table column.

Create Rows

Then you could create each row of the table as an instance of the model:

hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)

This way, you can use conventional Python code with classes and instances that represent tables and rows, and that way communicate with the SQL database.

Editor Support

Everything is designed for you to get the best developer experience possible, with the best editor support.

Including autocompletion:

And inline errors:

Write to the Database

You can learn a lot more about SQLModel by quickly following the tutorial, but if you need a taste right now of how to put all that together and save to the database, you can do this:

from sqlmodel import Field, Session, SQLModel, create_engine


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None


hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)


engine = create_engine("sqlite:///database.db")


SQLModel.metadata.create_all(engine)

with Session(engine) as session:
    session.add(hero_1)
    session.add(hero_2)
    session.add(hero_3)
    session.commit()

That will save a SQLite database with the 3 heroes.

Select from the Database

Then you could write queries to select from that same database, for example with:

from sqlmodel import Field, Session, SQLModel, create_engine, select


class Hero(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: int | None = None


engine = create_engine("sqlite:///database.db")

with Session(engine) as session:
    statement = select(Hero).where(Hero.name == "Spider-Boy")
    hero = session.exec(statement).first()
    print(hero)

Editor Support Everywhere

SQLModel was carefully designed to give you the best developer experience and editor support, even after selecting data from the database:

SQLAlchemy, Pydantic, and Protocol Buffers

That class Hero is a SQLModel model.

But at the same time, ✨ it is a SQLAlchemy model ✨. So, you can combine it and use it with other SQLAlchemy models, or you could easily migrate applications with SQLAlchemy to SQLModel.

And at the same time, ✨ it is also a Pydantic model ✨. You can use inheritance with it to define all your data models while avoiding code duplication. That makes it very easy to use with FastAPI.

And now, ✨ it is also a protobuf Message ✨. You can serialize it to binary format, use it directly in gRPC services, and interact with any protobuf-based system without additional conversion layers.

Differences from Original SQLModel

This fork maintains 100% compatibility with the original SQLModel while adding:

• ✅ All original SQLModel features work exactly as before
• ✅ New protobuf/gRPC capabilities seamlessly integrated
• ✅ Automatic descriptor generation (no extra code needed)
• ✅ Backward compatible - existing code continues to work

Contributing

This is a fork of the original SQLModel. For issues and contributions related to:

• Core SQLModel features: Please refer to the original SQLModel repository
• Protobuf/gRPC features: Please open issues in this repository

License

This project is licensed under the terms of the MIT license, same as the original SQLModel.