🏷️ Adjust type annotation for `Field.sa_type` to support instantiated SQLAlchemy types by diachkow · Pull Request #1345 · fastapi/sqlmodel · GitHub

Note

When I was writing description for this PR, I found another discussion started for just the same issue I was experiencing with mypy, so this changes are basically fixing the issue described here

Using sa_type and sa_column_kwargs instead of just sa_column can benefit when using inheritance for classes derived from SQLModel as it was suggested here.

If sa_column is not specified and sa_type is provided, it will be passed as a second, type argumnet to sqlalchemy.Column instance. If you would check sqlalchemy.Column construction definition, it looks as following:

    def __init__(
        self,
        __name_pos: Optional[
            Union[str, _TypeEngineArgument[_T], SchemaEventTarget]
        ] = None,
        __type_pos: Optional[
            Union[_TypeEngineArgument[_T], SchemaEventTarget]
        ] = None,
        *args: SchemaEventTarget,
        name: Optional[str] = None,
        type_: Optional[_TypeEngineArgument[_T]] = None,
        autoincrement: _AutoIncrementType = "auto",
        default: Optional[Any] = _NoArg.NO_ARG,
        insert_default: Optional[Any] = _NoArg.NO_ARG,
        doc: Optional[str] = None,
        key: Optional[str] = None,
        index: Optional[bool] = None,
        unique: Optional[bool] = None,
        info: Optional[_InfoType] = None,
        nullable: Optional[
            Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]
        ] = SchemaConst.NULL_UNSPECIFIED,
        onupdate: Optional[Any] = None,
        primary_key: bool = False,
        server_default: Optional[_ServerDefaultArgument] = None,
        server_onupdate: Optional[_ServerOnUpdateArgument] = None,
        quote: Optional[bool] = None,
        system: bool = False,
        comment: Optional[str] = None,
        insert_sentinel: bool = False,
        _omit_from_statements: bool = False,
        _proxies: Optional[Any] = None,
        **dialect_kwargs: Any,
    ):

Note the __type_pos argument with Union[_TypeEngineArgument[_T], SchemaEventTarget] where

_TypeEngineArgument = Union[Type["TypeEngine[_T]"], "TypeEngine[_T]"]

So, from technical perspective you can pass not only the subclass of TypeEngine, e.g. SQLAlchemy's sqltype such as String, Integer, DateTime, JSON etc, but also an instance of this type.

I was trying for JSONB(none_as_null=True) and String(50) and it worked just fine, alembic migrations were generated correctly, only mypy was arguing for type mismatch with call-overload issue.

To fix mypy error, we can update type annotation for sqlmodel.main.Field.sa_type to support also an instantiated SQLAlchemy's sqltype to match those of sqlalchemy.Column

Related discussions:

…QLAlchemy types

LGTM

Simple code example to check (in the details)

Details

from datetime import datetime

from sqlmodel import DateTime, Field, SQLModel, create_engine

class A(SQLModel):
    created_at: datetime = Field(sa_type=DateTime(timezone=False))

engine = create_engine("sqlite:///")
SQLModel.metadata.create_all(engine)

Running mypy gives

error: No overload variant of "Field" matches argument type "DateTime"  [call-overload]

on master and

Success: no issues found in 1 source file

after applying this fix

LGTM
See #1345 (review)

Thanks for approval! Who is responsible for merging this, what are the rules in this repo?

Thanks for approval! Who is responsible for merging this, what are the rules in this repo?

Only Sebastian can merge it. I already forwarded it to him. We should just wait

I have resolved conflicts here. I see you guys made some patch releases recently, hope this change can make it into one of them 🙃

was hitting this error when using sa_type, thanks for keeping it updated

It would be nice to get it merged though 😅

Hey @tiangolo, gently bumping this. It's been open about a year now, has an LGTM from @YuriiMotov, and @svlandeg mentioned back in September she'd forwarded it to you for merging.

To recap the issue:

Runtime is fine: sa_type already works correctly at runtime (SQLAlchemy accepts instantiated types like DateTime(timezone=False) just fine).
Typing is failing: The type annotation on Field.sa_type doesn't reflect that, so type checkers (basedpyright, zuban, mypy) flag valid code as an error.
Impact: It doesn't break anything at runtime, but it causes CI pipelines to fail.

Worth noting this is really a bug fix, not a feature. It's currently labeled as feature, but the code already does the right thing, this PR just corrects the type signature to match. Might be worth relabeling!

Totally understand if it's just buried under everything else, I didn't want it to get lost. Thanks for all the incredible work you do on FastAPI and SQLModel (and friends) :)

Thanks for the fix and for keeping this PR updated!

During final review, I found a subtle distinction: SQLAlchemy’s positional Column arguments also accept SchemaEventTarget for other schema objects, while sa_type should accept only SQLAlchemy type classes or instances.

I’ve put together #2095 with that narrower annotation, explicit type_ passing, and regression tests. It addresses the issue you identified here, so I’m closing this PR in favor of that implementation.

Thank you again for your contribution, and sorry this took so long to resolve! ☕

🏷️ Adjust type annotation for Field.sa_type to support instantiated S…

af23ba8

…QLAlchemy types

This comment was marked as resolved.

Sign in to view

svlandeg added the feature New feature or request label Apr 22, 2025

This comment was marked as resolved.

Sign in to view

svlandeg and others added 2 commits April 28, 2025 10:56

Merge branch 'main' into main

cef7ec8

Merge branch 'main' into main

9893fb2

YuriiMotov approved these changes Aug 21, 2025

View reviewed changes

Comment thread sqlmodel/main.py Outdated

YuriiMotov changed the title 🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types 🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types Aug 21, 2025

diachkow and others added 4 commits September 1, 2025 08:41

Merge branch 'main' into main

f5b5781

feat: rename SaType to SaTypeOrInstance

e76daeb

🎨 [pre-commit.ci] Auto format from pre-commit.com hooks

96199fa

apply formatting

8b629d6

diachkow requested a review from YuriiMotov September 1, 2025 10:12

YuriiMotov approved these changes Sep 1, 2025

View reviewed changes

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Dec 26, 2025

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into main

20aa991

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Dec 27, 2025

Merge branch 'main' into main

d8741bf

This comment was marked as resolved.

Sign in to view

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Jan 13, 2026

Merge branch 'main' into main

07c11ba

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Jan 13, 2026

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Feb 20, 2026

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into main_diachkow

3ce918a

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Mar 3, 2026

pre-commit-ci-lite Bot and others added 2 commits March 3, 2026 20:14

🎨 Auto format

6c95e05

also fix the type in the dataclass

afbed47

YuriiMotov mentioned this pull request Mar 18, 2026

🐛 Fix pyright errors in type annotations and select() overloads #1820

Closed

estarfoo mentioned this pull request Mar 18, 2026

🐛 Declare __tablename__ on the metaclass (improve pyright compatibility) #1821

Open

github-actions Bot added the conflicts Automatically generated when a PR has a merge conflict label Apr 3, 2026

This comment was marked as resolved.

Sign in to view

Merge branch 'main' into main

98eabdf

github-actions Bot removed the conflicts Automatically generated when a PR has a merge conflict label Apr 3, 2026

ankane mentioned this pull request Sep 10, 2026

Fix the sample code of SQLModel pgvector/pgvector-python#157

Closed

tiangolo mentioned this pull request Sep 21, 2026

🐛 Fix SQLAlchemy type handling in Field #2095

Merged

tiangolo closed this Sep 21, 2026

🏷️ Adjust type annotation for `Field.sa_type` to support instantiated SQLAlchemy types by diachkow · Pull Request #1345 · fastapi/sqlmodel · GitHub

Repository navigation

🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types - #1345

🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types#1345
diachkow wants to merge 14 commits into
fastapi:mainfrom
diachkow:main

diachkow commented Apr 21, 2025 •
edited by YuriiMotov
Loading

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

YuriiMotov left a comment

Uh oh!

Uh oh!

YuriiMotov left a comment

Uh oh!

diachkow commented Sep 2, 2025

Uh oh!

YuriiMotov commented Sep 2, 2025

Uh oh!

This comment was marked as resolved.

diachkow commented Dec 27, 2025

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

AgamjotSB commented Jul 18, 2026

Uh oh!

diachkow commented Jul 18, 2026

Uh oh!

AgamjotSB commented Jul 20, 2026

Uh oh!

tiangolo commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

🏷️ Adjust type annotation for `Field.sa_type` to support instantiated SQLAlchemy types by diachkow · Pull Request #1345 · fastapi/sqlmodel · GitHub

Repository navigation

🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types - #1345

🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types#1345diachkow wants to merge 14 commits intofastapi:mainfastapi/sqlmodel:mainfrom diachkow:maindiachkow/sqlmodel:mainCopy head branch name to clipboard

Conversation

diachkow commented Apr 21, 2025 • edited by YuriiMotov Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

YuriiMotov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

YuriiMotov left a comment

Choose a reason for hiding this comment

Uh oh!

diachkow commented Sep 2, 2025

Uh oh!

YuriiMotov commented Sep 2, 2025

Uh oh!

This comment was marked as resolved.

diachkow commented Dec 27, 2025

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

AgamjotSB commented Jul 18, 2026

Uh oh!

diachkow commented Jul 18, 2026

Uh oh!

AgamjotSB commented Jul 20, 2026

Uh oh!

tiangolo commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

🏷️ Adjust type annotation for Field.sa_type to support instantiated SQLAlchemy types#1345
diachkow wants to merge 14 commits into
fastapi:mainfrom
diachkow:main

diachkow commented Apr 21, 2025 •
edited by YuriiMotov
Loading