sqlmodel README

The project's README from github.com/fastapi/sqlmodel. As one markdown file: README.md.

SQLModel

SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.

Test Coverage Package version

Documentation: https://sqlmodel.tiangolo.com

Source Code: https://github.com/fastapi/sqlmodel

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:

Sponsors

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.

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.

Installation

First, install uv, and then add SQLModel to your project:

$ uv add sqlmodel
---> 100%

If you prefer to use pip, install sqlmodel inside a virtual environment. See the installation guide for the alternative steps.

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:

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 and Pydantic

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.

License

This project is licensed under the terms of the MIT license.

sqlmodel (fastapi/sqlmodel)

Searching Database…

18.4K ·GitHub
Sqlmodel
Что это такое?SQLModel — это библиотека для Python, которая позволяет работать с SQL-базами данных через объекты Python вместо чистого SQL. Она построена на Pydantic и SQLAlchemy и задумана как простая, совместимая и надёжная.
То есть это библиотека, а не фреймворк? И как она связана с SQLAlchemy и Pydantic?Это библиотека: тонкая прослойка над Pydantic и SQLAlchemy. Классы, которые вы объявляете, одновременно являются моделями SQLModel, SQLAlchemy и Pydantic, поэтому вся мощь обеих библиотек остаётся вам доступна.
Как добавить её в проект?Установите uv и добавьте SQLModel в свой проект, либо просто выполните pip install sqlmodel внутри виртуального окружения. Pydantic и SQLAlchemy установятся вместе с ней автоматически.
Что должно быть установлено заранее?Только актуальная поддерживаемая версия Python. SQLModel требует Pydantic и SQLAlchemy, но обе библиотеки ставятся автоматически вместе с SQLModel.
Есть ли подвох — придётся ли всё равно изучать сам SQLAlchemy?Библиотека делает код коротким за счёт разумных настроек по умолчанию, поэтому для повседневной работы глубокое знание SQLAlchemy не нужно. А поскольку это тонкая прослойка, вся мощь SQLAlchemy и Pydantic остаётся доступной для сложных случаев.
Это имеет смысл только если я делаю приложение на FastAPI?Нет. Её создал автор FastAPI, чтобы упростить работу с SQL в приложениях FastAPI, но это обычная библиотека для Python, которую можно использовать в любом проекте, работающем с SQL-базой данных.
Можно ли бесплатно использовать её в своих проектах?Да. SQLModel — проект с открытым исходным кодом под лицензией MIT, её можно свободно использовать, в том числе в коммерческих целях.
Как выглядит объявление таблицы в коде?Вы пишете обычный класс на Python: класс соответствует таблице в SQL, а каждый его атрибут — столбцу. Строки таблицы — это просто экземпляры этого класса, так что данные создаются и запрашиваются обычным кодом на Python.
Чем она лучше связки обычных SQLAlchemy и Pydantic?Обычно данные приходится объявлять дважды: один раз для SQLAlchemy и один раз для Pydantic. SQLModel достаточно одного описания типов, чтобы решить обе задачи, — это сокращает дублирование кода, оставаясь полностью совместимым с каждой из библиотек.
Можно ли перевести на неё существующее приложение на SQLAlchemy?Да. Модель SQLModel — это одновременно и модель SQLAlchemy, поэтому её можно сочетать с вашими существующими моделями SQLAlchemy, что делает перенос приложения несложным.
В какой базе данных она хранит данные?В любых SQL-базах данных. Быстрый пример из README сохраняет данные в файл SQLite, а поскольку под капотом работает SQLAlchemy, доступны и другие поддерживаемые ею SQL-базы.
What are similar projects?sqlalchemy, pydantic, fastapi, peewee, mongoose, ajv, auth, react-jsonschema-form
Which topics is it in?validations, pydantic, annotations, json-schema, autocomplete, schema, validation, orm, fastapi, sql, json, beginner-friendly
Creator
fastapi
Size
8.5 MB
Stars
18.4K
Updated
CommitOct 15Release0.0.48Oct 06
Age
5y
Commits · 90 Days