NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #678 most downloaded on PyPI
SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.
Last release 11 days ago
23 Sep 2026
Release timing varies
gaps range from 9 days to 7 months
Nearly every release is documented
notes for 47 of 47 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
50 releases · first in 2021
One column per quarter.
✨ Add direct support for PostgreSQL, MySQL, and MariaDB, include in CI tests. PR #2103 by @tiangolo .
🐛 Fix timedelta arithmetic with UTC datetime fields. PR #2101 by @tiangolo .
✨ Use UTC datetimes by default. PR #2099 by @tiangolo .
datetime fields now use UTCDateTime, a custom type based on DateTime(timezone=True). It requires aware datetime parameters, normalizes them to UTC, and returns aware UTC values from database reads, including on SQLite and MySQL/MariaDB. Pydantic's AwareDatetime uses the same type, while NaiveDatetime explicitly selects DateTime(timezone=False). Plain datetime validation still accepts both aware and naive values, but naive database parameters now raise an error.
Existing databases are not changed automatically. To retain naive storage, use NaiveDatetime or an explicit Field(sa_type=DateTime(timezone=False)). Explicit SQLAlchemy types retain their existing behavior. PostgreSQL needs a column migration that explicitly specifies the timezone of existing values. SQLite and MySQL/MariaDB keep their column definitions, but existing non-UTC values need a data migration before adopting the new type. Update datetime producers, query parameters, comparisons, and any database defaults to follow the new UTC convention.
Read Datetimes and Timezones: Upgrade Existing Applications before upgrading.
♻️ Replace the dataclass_transform shim with typing_extensions. PR #2097 by @tiangolo .
🐛 Fix SQLAlchemy type handling in Field . PR #2095 by @tiangolo .
🏷️ Allow Discriminator type for discriminator parameter in Field . PR #1729 by @YuriiMotov .
Discriminator type for discriminator parameter in Field. PR #1729 by @YuriiMotov.🗑️ Deprecate min_items and max_items parameters of Field . PR #1731 by @YuriiMotov .
min_items and max_items parameters of Field. PR #1731 by @YuriiMotov.✏️ Fix grammar and typos in docs. PR #2058 by @YuriiMotov .
Field() instead of condecimal(). PR #2035 by @anxkhn.0.26.1. PR #2078 by @YuriiMotov.setup-uv action to 10.0.1. PR #2077 by @YuriiMotov.✨ Add SQLModel Agent Library Skill, install with uvx library-skills . PR #2017 by @tiangolo .
guard-dependencies.yml. PR #1916 by @svlandeg.needs_py310 marker from tests. PR #1852 by @stickm4n.mypy with ty in precommit. PR #1806 by @svlandeg.🐛 Fix type annotation in SQLModel.__new__ , avoid explicitly returning Any . PR #1846 by @carljm .
SQLModel.__new__, avoid explicitly returning Any. PR #1846 by @carljm.tuple_ return type annotation. PR #1639 by @kakeruzoku.contributing.md. PR #1842 by @GopalGB.HeroPublicWithTeam model. PR #1678 by @berkaykrc.target=_blank and CSS automatically in JS and CSS. PR #1799 by @tiangolo..in_() method. PR #619 by @masylum.typing-extensions. PR #1815 by @musicinmybrain.griffelib instead of griffe. PR #1775 by @svlandeg.👷 Fix build CI to not attempt to build sqlmodel-slim . PR #1773 by @tiangolo .
➖ Drop support for sqlmodel-slim , no more versions will be released, use only sqmodel . PR #1772 by @tiangolo .
➖ Drop support for Python 3.9. PR #1766 by @tiangolo .
👷 Enable tests with lower and upper bound versions. PR #1735 by @tiangolo .
📝 Fix async example in session.execute() docstring & deprecation message. PR #1643 by @DanielLeviLucas .
expression.py. PR #1747 by @veeceey.session.execute() docstring & deprecation message. PR #1643 by @DanielLeviLucas.management-tasks.md to be in line with management-tasks.md in FastAPI repo. PR #1743 by @YuriiMotov.sqlmodel-slim. PR #1754 by @tiangolo.sqlmodel-slim, deprecate it, and make it only depend on sqlmodel. PR #1753 by @tiangolo.ValidationError schema in FastAPI-related tests to be compatible with FastAPI 0.128.1+. PR #1744 by @YuriiMotov.🐛 Fix support for Annotated fields with Pydantic 2.12+. PR #1607 by @vimota .
custom.js. PR #1711 by @alejsdev.read-relationships.md. PR #1705 by @stefmolin.uv.lock gets the internal label. PR #1719 by @svlandeg.>=0.103.2 in tests. PR #1709 by @YuriiMotov.deploy_docs_status.py. PR #1707 by @tiangolo.➖ Drop support for Pydantic v1. PR #1701 by @tiangolo .
prek version pin to >=0.2.24,<1.0.0. PR #1698 by @YuriiMotov.➖ Drop support for Python 3.8. PR #1696 by @tiangolo .
🐛 Fix alias support for Pydantic v2. PR #1577 by @ravishan16.
alias support for Pydantic v2. PR #1577 by @ravishan16.🐛 Fix RuntimeError: dictionary changed size during iteration in sqlmodel_update(). PR #997 by @BartSchuurmans.
RuntimeError: dictionary changed size during iteration in sqlmodel_update(). PR #997 by @BartSchuurmans.features.md. PR #1627 by @sparkiegeek.latest-changes GitHub Action and pin actions/checkout@v5. PR #1654 by @svlandeg.waiting label in issue-manager. PR #1609 by @YuriiMotov.⬆️ Add support for Python 3.14. PR #1578 by @svlandeg.
🐛 Fix attribute handling in model_dump for compatibility with the latest Pydantic versions. PR #1595 by @spazm.
model_dump for compatibility with the latest Pydantic versions. PR #1595 by @spazm.docs/tutorial/fastapi/simple-hero-api.md. PR #1583 by @kofi-kusi.✨ Add overload for exec method to support insert, update, delete statements. PR #1342 by @seriaati.
docs/tutorial/relationship-attributes/cascade-delete-relationships.md. PR #1543 by @YuriiMotov.docs/tutorial/insert.md. PR #1368 by @brettcannon.docs/tutorial/fastapi/relationships.md. PR #1365 by @Foxerine.docs/learn/index.md. PR #1363 by @brettcannon.Optional to use the new syntax in Python 3.10, e.g. int | None. PR #1351 by @tiangolo.model.sqlmodel_update() instead of old setattr(). PR #1117 by @jpizquierdo.docs/virtual-environments.md. PR #1321 by @sylvainHellin.tests/test_tutorial/test_code_structure/test_tutorial001.py, one test file for multiple variants. PR #1408 by @tiangolo.clear_sqlmodel. PR #1406 by @tiangolo.tests/test_select_gen.py, pass environment variables, needed for NixOS nixpkgs. PR #969 by @pbsds.⬆️ Add support for Python 3.13. PR #1289 by @svlandeg.
🐛 Fix type annotation in Field constructor. PR #1304 by @AlanBogarin.
Field constructor. PR #1304 by @AlanBogarin.main branch. PR #1291 by @svlandeg.list instead of List. PR #1147 by @bubbletroubles.databases.md. PR #1113 by @radi-dev.docs/tutorial/create-db-and-table.md. PR #1252 by @ArianHamdi.insert.md. PR #1256 by @Noushadaliam.docs/advanced/uuid.md. PR #1151 by @tiangolo.docs/tutorial/create-db-and-table.md. PR #1149 by @tiangolo.indexes.md . PR #1100 by @alejsdev.labeler.yml. PR #1128 by @tiangolo.issue-manager.yml. PR #1103 by @tiangolo.include-hidden-files to True when using the upload-artifact GH action. PR #1098 by @svlandeg.🐛 Fix support for types with Optional[Annoated[x, f()]], e.g. id: Optional[pydantic.UUID4]. PR #1093 by @tiangolo.
Optional[Annoated[x, f()]], e.g. id: Optional[pydantic.UUID4]. PR #1093 by @tiangolo.docs/virtual-environments.md. PR #1085 by @tiangolo.cascade_delete docs. PR #1030 by @tiangolo.latest-changes GitHub Action. PR #1087 by @tiangolo.pyproject.toml, show up in PyPI. PR #1074 by @tiangolo.✨ Add support for cascade delete relationships: cascade_delete, ondelete, and passive_deletes. Initial PR #983 by @estebanx64.
cascade_delete, ondelete, and passive_deletes. Initial PR #983 by @estebanx64.
✨ Add official UUID support, docs and tests, internally using new SQLAlchemy 2.0 types. Initial PR #992 by @estebanx64.
docs/tutorial/create-db-and-table.md. PR #911 by @tfpgh.create-db-and-table-with-db-browser.md. PR #976 by @alejsdev.docs/tutorial. PR #943 by @luco17.sqlmodel/_compat.py. PR #950 by @Highfire1.docs/tutorial/relationship-attributes/index.md. PR #880 by @UncleGoogle.🐛 Fix pydantic EmailStr support and max_length in several String subclasses. PR #966 by @estebanx64.
EmailStr support and max_length in several String subclasses. PR #966 by @estebanx64.max_length is set on Pydantic models using Pydantic v2. PR #963 by @estebanx64.TryCast used internally. PR #964 by @tiangolo.@dataclass_transform (now PEP 681) in docs/features.md. PR #753 by @soof-golan.✨ Add sqlmodel-slim setup. PR #916 by @tiangolo.
In the future SQLModel will include the standard default recommended packages, and sqlmodel-slim will come without those recommended standard packages and with a group of optional dependencies sqlmodel-slim[standard], equivalent to sqlmodel, for those that want to opt out of those packages.
Nothing published for this version
♻️ Refactor types to properly support Pydantic 2.7. PR #913 by @tiangolo.
Nothing published for this version
Nothing published for this version
✨ Add new method .sqlmodel_update() to update models in place, including an update parameter for extra data. And fix implementation for the (now docum
Features
.sqlmodel_update() to update models in place, including an update parameter for extra data. And fix implementation for the (now documented) update parameter for .model_validate(). PR #804 by @tiangolo.
🐛 Fix class initialization compatibility with Pydantic and SQLModel, fixing errors revealed by the latest Pydantic. PR #807 by @tiangolo.
✨ Add support for Pydantic v2 (while keeping support for v1 if v2 is not available). PR #722 by @tiangolo including initial work in PR #699 by @AntonD
🔇 Do not raise deprecation warnings for execute as it's automatically used internally. PR #716 by @tiangolo.
✨ Upgrade SQLAlchemy to 2.0. PR #700 by @tiangolo including initial work in PR #563 by @farahats9.
You might consider this a breaking change if you were using an incompatible combination of arguments, those arguments were not taking effect and now y…
Field() with sa_type. PR #505 by @maru0123-2004.
sa_column excludes sa_column_args, primary_key, nullable, etc. PR #681 by @tiangolo.# in annotations (from MkDocs Material). PR #677 by @Matthieu-LAURENT39.✨ Add support for all Field parameters from Pydantic 1.9.0 and above, make Pydantic 1.9.0 the minimum required version. PR #440 by @daniil-berg.
Field parameters from Pydantic 1.9.0 and above, make Pydantic 1.9.0 the minimum required version. PR #440 by @daniil-berg.🗑️ Deprecate Python 3.6 and upgrade Poetry and Poetry Version Plugin. PR #627 by @tiangolo.
AsyncSession type annotations for exec(). PR #58 by @Bobronium.ForeignKey directly, remove repeated column construction from SQLModelMetaclass.__init__ and upgrade minimum SQLAlchemy to >=1.4.36. PR #443 by @daniil-berg.get_sqlalchemy_type. PR #669 by @tiangolo.1.4.29 (related to #434). PR #439 by @daniil-berg.docs/tutorial/create-db-and-table.md. PR #601 by @SimonCW.docs/tutorial/fastapi/multiple-models.md. PR #674 by @tiangolo.offset in example with limit and where. PR #273 by @jbmchuck.le (lte is invalid, use le ). PR #207 by @jrycw.docs/db-to-code.md. PR #649 by @MatveyF.docs/tutorial/relationship-attributes/define-relationships-attributes.md. PR #474 by @jalvaradosegura.get_sqlachemy_type(). PR #496 by @cmarqu.docs/tutorial/create-db-and-table.md. PR #477 by @FluffyDietEngine.strict = true instead of manual configs. PR #428 by @michaeloliverx.CITATION.cff file for academic citations. PR #13 by @sugatoray.🐛 Fix auto detecting and setting nullable, allowing overrides in field. PR #423 by @JonasKs.
nullable, allowing overrides in field. PR #423 by @JonasKs.expresion.py, sync from Jinja2 template, implement inherit_cache to solve errors like: SAWarning: Class SelectOfScalar will not make use of SQL compilation caching. PR #422 by @tiangolo.docs/tutorial/create-db-and-table.md. PR #426 by @tiangolo.docs/tutorial/connect/remove-data-connections.md. PR #421 by @VerdantFox.✨ Allow setting unique in Field() for a column. PR #83 by @raphaelgibson.
unique in Field() for a column. PR #83 by @raphaelgibson.UUID.hex instead of an int. PR #26 by @andrewbolster.Session.get() parameter execution_options. PR #302 by @tiangolo.Model.parse_obj(), and Model.validate(). PR #321 by @phi-friday.Select and SelectOfScalar to inherit cache to avoid warning: SAWarning: Class SelectOfScalar will not make use of SQL compilation caching. PR #234 by @rabinadk1.None. PR #79 by @van51.id should not be updatable. PR #335 by @kurtportelli.hero_spider_boy.id => hero_spider_boy.team_id. PR #106 by @yoannmos.docs/databases.md and docs/tutorial/index.md. PR #35 by @prrao87.docs/tutorial/relationship-attributes/define-relationships-attributes.md. PR #239 by @jalvaradosegura.docs/tutorial/fastapi/simple-hero-api.md. PR #80 by @joemudryk.docs/tutorial/code-structure.md. PR #344 by @marciomazza.docs/db-to-code.md. PR #155 by @gr8jam.docs/contributing.md. PR #323 by @Fardad13.docs/tutorial/fastapi/tests.md. PR #265 by @johnhoman.docs/tutorial/where.md. PR #286 by @jalvaradosegura.docs/tutorial/fastapi/update.md. PR #268 by @cirrusj.docs/tutorial/fastapi/simple-hero-api.md. PR #247 by @hao-wang.docs/tutorial/automatic-id-none-refresh.md, docs/tutorial/fastapi/update.md, docs/tutorial/select.md. PR #185 by @rootux.docs/databases.md. PR #177 by @seandlg.docs/tutorial/fastapi/update.md. PR #162 by @wmcgee3.docs/tutorial/code-structure.md, docs/tutorial/fastapi/multiple-models.md, docs/tutorial/fastapi/simple-hero-api.md, docs/tutorial/many-to-many/index.md. PR #116 by @moonso.docs/tutorial/fastapi/teams.md. PR #154 by @chrisgoddard.back_populates, always use hero instead of owner. PR #120 by @onionj.docs/tutorial/fastapi/tests.md. PR #113 by @feanil.docs/tutorial/where.md. PR #72 by @ZettZet.docs/tutorial/code-structure.md. PR #91 by @dhiraj.docs/help.md. PR #84 by @mborus.docs/tutorial/many-to-many/create-models-with-link.md. PR #45 by @xginn8.docs/tutorial/index.md. PR #398 by @ryangrose.^0.68.0 to ^0.68.1. PR #48 by @alucarddelta.==1.2.0b1. PR #303 by @tiangolo.Here's the new documentation: Indexes - Optimize Queries. This is the same change described above in Breaking Changes. PR #205 by @tiangolo.
SQLModel no longer creates indexes by default for every column, indexes are now opt-in. You can read more about it in PR #205.
Before this change, if you had a model like this:
from typing import Optional
from sqlmodel import Field, SQLModel
class Hero(SQLModel, table=True):
id: Optional[int] = Field(default=None, primary_key=True)
name: str
secret_name: str
age: Optional[int] = None
...when creating the tables, SQLModel version 0.0.5 and below, would also create an index for name, one for secret_name, and one for age (id is the primary key, so it doesn't need an additional index).
If you depended on having an index for each one of those columns, now you can (and would have to) define them explicitly:
class Hero(SQLModel, table=True):
id: Optional[int] = Field(default=None, primary_key=True)
name: str = Field(index=True)
secret_name: str = Field(index=True)
age: Optional[int] = Field(default=None, index=True)
There's a high chance you don't need indexes for all the columns. For example, you might only need indexes for name and age, but not for secret_name. In that case, you could define the model as:
class Hero(SQLModel, table=True):
id: Optional[int] = Field(default=None, primary_key=True)
name: str = Field(index=True)
secret_name: str
age: Optional[int] = Field(default=None, index=True)
If you already created your database tables with SQLModel using versions 0.0.5 or below, it would have also created those indexes in the database. In that case, you might want to manually drop (remove) some of those indexes, if they are unnecessary, to avoid the extra cost in performance and space.
Depending on the database you are using, there will be a different way to find the available indexes.
For example, let's say you no longer need the index for secret_name. You could check the current indexes in the database and find the one for secret_name, it could be named ix_hero_secret_name. Then you can remove it with SQL:
DROP INDEX ix_hero_secret_name
or
DROP INDEX ix_hero_secret_name ON hero;
Here's the new, extensive documentation explaining indexes and how to use them: Indexes - Optimize Queries.
docs/tutorial/automatic-id-none-refresh.md. PR #14 by @leynier.docs/tutorial/index.md and docs/databases.md. PR #5 by @sebastianmarines.✨ Add support for Decimal fields from Pydantic and SQLAlchemy. Original PR #103 by @robcxyz. New docs: Advanced User Guide - Decimal Numbers.
expression.py and expression template, currently needed by CI. PR #187 by @tiangolo.🎨 Fix type detection of select results in PyCharm. PR #15 by @tiangolo.
⬆️ Update and relax specification range for sqlalchemy-stubs. PR #4 by @tiangolo.
This includes several small bug fixes detected during the first CI runs.
- First release. 🎉 Back to top
Your coding agent can read these notes before it upgrades. Set up the MCP server →