sqlmodel 0.0.44__tar.gz → 0.0.45__tar.gz

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel
-Version: 0.0.44
+Version: 0.0.45
 Summary: SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.
 Author-Email: =?utf-8?q?Sebasti=C3=A1n_Ram=C3=ADrez?= <tiangolo@gmail.com>
 License-Expression: MIT

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial001_py310.py

@@ -0,0 +1,30 @@
+from datetime import datetime, timezone
+
+from sqlmodel import Field, Session, SQLModel, create_engine
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def main():
+    event = Event()
+    print("Event:", event)
+
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        session.add(event)
+        session.commit()
+        session.refresh(event)
+        print("Event from database:", event)
+
+
+if __name__ == "__main__":
+    main()

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial001_py311.py

@@ -0,0 +1,30 @@
+from datetime import UTC, datetime
+
+from sqlmodel import Field, Session, SQLModel, create_engine
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+sqlite_file_name = "database.db"
+sqlite_url = f"sqlite:///{sqlite_file_name}"
+
+engine = create_engine(sqlite_url, echo=True)
+
+
+def main():
+    event = Event()
+    print("Event:", event)
+
+    SQLModel.metadata.create_all(engine)
+    with Session(engine) as session:
+        session.add(event)
+        session.commit()
+        session.refresh(event)
+        print("Event from database:", event)
+
+
+if __name__ == "__main__":
+    main()

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial002_py310.py

@@ -0,0 +1,21 @@
+from pydantic import AwareDatetime, NaiveDatetime
+from sqlmodel import Field, SQLModel
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    starts_at: AwareDatetime
+    local_time: NaiveDatetime
+
+
+def main():
+    data = {
+        "starts_at": "2026-01-01T12:00:00Z",
+        "local_time": "2026-01-01T12:00:00",
+    }
+    event = Event.model_validate(data)
+    print("Event:", event)
+
+
+if __name__ == "__main__":
+    main()

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial003_py310.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+
+from sqlalchemy import DateTime
+from sqlmodel import Field, SQLModel
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    created_at: datetime = Field(sa_type=DateTime(timezone=False))
+
+
+def main():
+    event = Event(created_at=datetime(2026, 1, 1, 12))
+    print("Event:", event)
+
+
+if __name__ == "__main__":
+    main()

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial004_py310.py

@@ -0,0 +1,22 @@
+import sqlalchemy as sa
+from alembic import op
+
+
+def upgrade():
+    op.alter_column(
+        "event",
+        "created_at",
+        existing_type=sa.DateTime(timezone=False),
+        type_=sa.DateTime(timezone=True),
+        postgresql_using="created_at AT TIME ZONE 'UTC'",
+    )
+
+
+def downgrade():
+    op.alter_column(
+        "event",
+        "created_at",
+        existing_type=sa.DateTime(timezone=True),
+        type_=sa.DateTime(timezone=False),
+        postgresql_using="created_at AT TIME ZONE 'UTC'",
+    )

sqlmodel-0.0.45/docs_src/advanced/datetime/tutorial005_py310.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+
+from pydantic import NaiveDatetime
+from sqlmodel import Field, SQLModel
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    created_at: NaiveDatetime
+
+
+def main():
+    event = Event.model_validate({"created_at": datetime(2026, 1, 1, 12)})
+    print("Event:", event)
+
+
+if __name__ == "__main__":
+    main()

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/pyproject.toml

@@ -41,7 +41,7 @@ dependencies = [
     "pydantic>=2.11.0",
     "typing-extensions>=4.5.0",
 ]
-version = "0.0.44"
+version = "0.0.45"
 
 [project.urls]
 Homepage = "https://github.com/fastapi/sqlmodel"
@@ -78,6 +78,7 @@ github-actions = [
     "smokeshow >=0.5.0",
 ]
 tests = [
+    "alembic >=1.12.0",
     "black >=24.1.0",
     "coverage[toml] >=6.2",
     "dirty-equals >=0.11",

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/sqlmodel/.agents/skills/sqlmodel/SKILL.md

@@ -36,6 +36,33 @@ id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
 
 Use non-table `SQLModel` classes for create/update/public API schemas instead of mixing request/response-only fields into table models.
 
+## Datetimes
+
+In SQLModel `0.0.45` and newer, use `datetime` for timestamp fields. SQLModel automatically selects `UTCDateTime`, which normalizes aware values to UTC when writing and returns aware UTC datetimes when reading, including with SQLite and MySQL/MariaDB.
+
+Do not add `sa_type=DateTime(timezone=True)` or `sa_column=Column(DateTime(timezone=True))` just to enable timezone support. These overrides bypass SQLModel's UTC processing. If an explicit column type is needed, import `UTCDateTime` from `sqlmodel`.
+
+For generated timestamps on Python 3.11 and newer:
+
+```python
+from datetime import UTC, datetime
+
+from sqlmodel import Field, SQLModel
+
+
+class Event(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+```
+
+On Python 3.10, import `timezone` instead of `UTC` and use `lambda: datetime.now(timezone.utc)`.
+
+- Supply aware datetimes for writes, updates, and query filters. Avoid `datetime.now()` without a timezone and `datetime.utcnow()` for UTC timestamps. Naive database parameters are rejected when the statement executes.
+- Use Pydantic's `AwareDatetime` when input validation must reject naive values. It uses the same UTC storage. Validate table-model input with `Model.model_validate(data)`. Direct table-model construction currently skips Pydantic validation, and plain `datetime` validation accepts naive values.
+- Use Pydantic's `NaiveDatetime` for intentional naive storage. It selects `DateTime(timezone=False)` and requires naive values during Pydantic validation.
+
+When upgrading existing applications, follow the [datetime migration guide](https://sqlmodel.tiangolo.com/advanced/datetime/#upgrade-existing-applications). Changing the model does not alter existing columns or convert historical data.
+
 ## Sessions and Queries
 
 Open sessions directly with the engine:

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/sqlmodel/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.44"
+__version__ = "0.0.45"
 
 # Re-export from Pydantic
 from pydantic import Discriminator as Discriminator
@@ -145,3 +145,4 @@ from .sql.expression import tuple_ as tuple_
 from .sql.expression import type_coerce as type_coerce
 from .sql.expression import within_group as within_group
 from .sql.sqltypes import AutoString as AutoString
+from .sql.sqltypes import UTCDateTime as UTCDateTime

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/sqlmodel/_compat.py

@@ -12,13 +12,14 @@ from typing import (
     TypeAlias,
     TypeVar,
     Union,
+    cast,
     get_args,
     get_origin,
 )
 
 from annotated_types import MaxLen
 from pydantic import VERSION as P_VERSION
-from pydantic import BaseModel
+from pydantic import AwareDatetime, BaseModel, NaiveDatetime
 from pydantic import ConfigDict as ConfigDict
 from pydantic._internal._fields import PydanticMetadata
 from pydantic._internal._model_construction import ModelMetaclass as ModelMetaclass
@@ -179,7 +180,15 @@ def get_sa_type_from_type_annotation(annotation: Any) -> Any:
     if origin is None:
         return annotation
     elif origin is Annotated:
-        return get_sa_type_from_type_annotation(get_args(annotation)[0])
+        type_, *metadata = get_args(annotation)
+        type_ = get_sa_type_from_type_annotation(type_)
+        # Like Pydantic, apply the last timezone constraint in Annotated.
+        for meta in metadata:
+            if meta is AwareDatetime or isinstance(meta, cast(type, AwareDatetime)):
+                type_ = AwareDatetime
+            elif meta is NaiveDatetime or isinstance(meta, cast(type, NaiveDatetime)):
+                type_ = NaiveDatetime
+        return type_
     if _is_union_type(origin):
         bases = get_args(annotation)
         if len(bases) > 2:
@@ -194,7 +203,7 @@ def get_sa_type_from_type_annotation(annotation: Any) -> Any:
 
 
 def get_sa_type_from_field(field: Any) -> Any:
-    type_: Any = field.annotation
+    type_: Any = field.rebuild_annotation()
     return get_sa_type_from_type_annotation(type_)
 
 

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/sqlmodel/main.py

@@ -24,7 +24,7 @@ from typing import (
     overload,
 )
 
-from pydantic import BaseModel, Discriminator, EmailStr
+from pydantic import AwareDatetime, BaseModel, Discriminator, EmailStr, NaiveDatetime
 from pydantic.fields import FieldInfo as PydanticFieldInfo
 from sqlalchemy import (
     Boolean,
@@ -74,7 +74,7 @@ from ._compat import (
     sqlmodel_init,
     sqlmodel_validate,
 )
-from .sql.sqltypes import AutoString
+from .sql.sqltypes import AutoString, UTCDateTime
 
 if TYPE_CHECKING:
     from pydantic._internal._model_construction import ModelMetaclass as ModelMetaclass
@@ -754,8 +754,10 @@ def get_sqlalchemy_type(field: Any) -> Any:
         return Boolean
     if issubclass(type_, int):
         return Integer
-    if issubclass(type_, datetime):
-        return DateTime
+    if issubclass(type_, (datetime, AwareDatetime, NaiveDatetime)):
+        if issubclass(type_, cast(type, NaiveDatetime)):
+            return DateTime(timezone=False)
+        return UTCDateTime()
     if issubclass(type_, date):
         return Date
     if issubclass(type_, timedelta):

sqlmodel-0.0.45/sqlmodel/sql/sqltypes.py

@@ -0,0 +1,53 @@
+from datetime import datetime, timezone
+from typing import Any, cast
+
+from sqlalchemy import types
+from sqlalchemy.engine.interfaces import Dialect
+
+
+class UTCDateTime(types.TypeDecorator[datetime]):
+    """Store aware datetimes and return them in UTC."""
+
+    impl = types.DateTime
+    cache_ok = True
+
+    def __init__(self) -> None:
+        super().__init__(timezone=True)
+
+    def __repr__(self) -> str:
+        return "UTCDateTime()"
+
+    def process_bind_param(
+        self, value: datetime | None, dialect: Dialect
+    ) -> datetime | None:
+        if value is None:
+            return None
+        if value.utcoffset() is None:
+            raise ValueError(
+                "Datetime values must have timezone information. "
+                "Use datetime.now(timezone.utc), or annotate the field with "
+                "NaiveDatetime for naive storage."
+            )
+        return value.astimezone(timezone.utc)
+
+    def process_result_value(
+        self, value: datetime | None, dialect: Dialect
+    ) -> datetime | None:
+        if value is None:
+            return None
+        if value.utcoffset() is None:
+            # Databases without timezone support store UTC without an offset.
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+
+class AutoString(types.TypeDecorator):
+    impl = types.String
+    cache_ok = True
+    mysql_default_length = 255
+
+    def load_dialect_impl(self, dialect: Dialect) -> "types.TypeEngine[Any]":
+        impl = cast(types.String, self.impl)
+        if impl.length is None and dialect.name == "mysql":
+            return dialect.type_descriptor(types.String(self.mysql_default_length))
+        return super().load_dialect_impl(dialect)

{sqlmodel-0.0.44 → sqlmodel-0.0.45}/tests/conftest.py

@@ -1,5 +1,6 @@
 import shutil
 import subprocess
+import sys
 from collections.abc import Callable, Generator
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -83,3 +84,8 @@ def print_mock_fixture() -> Generator[PrintMock, None, None]:
     new_print = get_testing_print_function(print_mock.calls)
     with patch("builtins.print", new=new_print):
         yield print_mock
+
+
+needs_py311 = pytest.mark.skipif(
+    sys.version_info < (3, 11), reason="requires Python 3.11+"
+)

sqlmodel-0.0.45/tests/test_advanced/test_datetime/test_tutorial001.py

@@ -0,0 +1,40 @@
+import importlib
+from datetime import datetime, timezone
+from types import ModuleType
+
+import pytest
+from sqlmodel import SQLModel, create_engine
+
+from ...conftest import PrintMock, needs_py311
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial001_py310"),
+        pytest.param("tutorial001_py311", marks=needs_py311),
+    ],
+)
+def get_module(request: pytest.FixtureRequest) -> ModuleType:
+    mod = importlib.import_module(f"docs_src.advanced.datetime.{request.param}")
+    mod.sqlite_url = "sqlite://"
+    mod.engine = create_engine(mod.sqlite_url)
+    return mod
+
+
+def test_tutorial(print_mock: PrintMock, mod: ModuleType) -> None:
+    before = datetime.now(timezone.utc)
+    mod.main()
+    after = datetime.now(timezone.utc)
+
+    created_at = print_mock.calls[0][1]["created_at"]
+    assert created_at.tzinfo is timezone.utc
+    assert before <= created_at <= after
+    assert print_mock.calls == [
+        ["Event:", {"id": None, "created_at": created_at}],
+        ["Event from database:", {"id": 1, "created_at": created_at}],
+    ]
+    assert print_mock.calls[1][1]["created_at"].tzinfo is timezone.utc
+
+    table = SQLModel.metadata.tables["event"]
+    assert table.c.created_at.type.timezone is True

sqlmodel-0.0.45/tests/test_advanced/test_datetime/test_tutorial002.py

@@ -0,0 +1,50 @@
+import importlib
+from datetime import datetime, timezone
+from types import ModuleType
+
+import pytest
+from pydantic import ValidationError
+from sqlmodel import SQLModel
+
+from ...conftest import PrintMock
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial002_py310"),
+    ],
+)
+def get_module(request: pytest.FixtureRequest) -> ModuleType:
+    return importlib.import_module(f"docs_src.advanced.datetime.{request.param}")
+
+
+def test_tutorial(print_mock: PrintMock, mod: ModuleType) -> None:
+    mod.main()
+    assert print_mock.calls == [
+        [
+            "Event:",
+            {
+                "id": None,
+                "starts_at": datetime(2026, 1, 1, 12, tzinfo=timezone.utc),
+                "local_time": datetime(2026, 1, 1, 12),
+            },
+        ]
+    ]
+
+    with pytest.raises(ValidationError) as exc_info:
+        mod.Event.model_validate(
+            {
+                "starts_at": "2026-01-01T12:00:00",
+                "local_time": "2026-01-01T12:00:00Z",
+            }
+        )
+    errors = exc_info.value.errors()
+    assert [(error["loc"], error["type"]) for error in errors] == [
+        (("starts_at",), "timezone_aware"),
+        (("local_time",), "timezone_naive"),
+    ]
+
+    table = SQLModel.metadata.tables["event"]
+    assert table.c.starts_at.type.timezone is True
+    assert table.c.local_time.type.timezone is False

sqlmodel-0.0.45/tests/test_advanced/test_datetime/test_tutorial003.py

@@ -0,0 +1,31 @@
+import importlib
+from datetime import datetime, timezone
+from types import ModuleType
+
+import pytest
+from sqlmodel import SQLModel
+
+from ...conftest import PrintMock
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial003_py310"),
+    ],
+)
+def get_module(request: pytest.FixtureRequest) -> ModuleType:
+    return importlib.import_module(f"docs_src.advanced.datetime.{request.param}")
+
+
+def test_tutorial(print_mock: PrintMock, mod: ModuleType) -> None:
+    mod.main()
+    assert print_mock.calls == [
+        ["Event:", {"id": None, "created_at": datetime(2026, 1, 1, 12)}]
+    ]
+
+    aware = datetime(2026, 1, 1, 12, tzinfo=timezone.utc)
+    assert mod.Event.model_validate({"created_at": aware}).created_at == aware
+
+    table = SQLModel.metadata.tables["event"]
+    assert table.c.created_at.type.timezone is False

sqlmodel-0.0.45/tests/test_advanced/test_datetime/test_tutorial004.py

@@ -0,0 +1,35 @@
+import importlib
+from io import StringIO
+from types import ModuleType
+
+import pytest
+from alembic.migration import MigrationContext
+from alembic.operations import Operations
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial004_py310"),
+    ],
+)
+def get_module(request: pytest.FixtureRequest) -> ModuleType:
+    return importlib.import_module(f"docs_src.advanced.datetime.{request.param}")
+
+
+def test_tutorial(mod: ModuleType) -> None:
+    output = StringIO()
+    context = MigrationContext.configure(
+        dialect_name="postgresql",
+        opts={"as_sql": True, "output_buffer": output},
+    )
+    with Operations.context(context):
+        mod.upgrade()
+        mod.downgrade()
+
+    assert output.getvalue() == (
+        "ALTER TABLE event ALTER COLUMN created_at TYPE TIMESTAMP WITH TIME ZONE "
+        "USING created_at AT TIME ZONE 'UTC';\n\n"
+        "ALTER TABLE event ALTER COLUMN created_at TYPE TIMESTAMP WITHOUT TIME ZONE "
+        "USING created_at AT TIME ZONE 'UTC';\n\n"
+    )

sqlmodel-0.0.45/tests/test_advanced/test_datetime/test_tutorial005.py

@@ -0,0 +1,38 @@
+import importlib
+from datetime import datetime, timezone
+from types import ModuleType
+
+import pytest
+from pydantic import ValidationError
+from sqlmodel import SQLModel
+
+from ...conftest import PrintMock
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial005_py310"),
+    ],
+)
+def get_module(request: pytest.FixtureRequest) -> ModuleType:
+    return importlib.import_module(f"docs_src.advanced.datetime.{request.param}")
+
+
+def test_tutorial(print_mock: PrintMock, mod: ModuleType) -> None:
+    mod.main()
+    assert print_mock.calls == [
+        ["Event:", {"id": None, "created_at": datetime(2026, 1, 1, 12)}]
+    ]
+
+    with pytest.raises(ValidationError) as exc_info:
+        mod.Event.model_validate(
+            {"created_at": datetime(2026, 1, 1, 12, tzinfo=timezone.utc)}
+        )
+    errors = exc_info.value.errors()
+    assert [(error["loc"], error["type"]) for error in errors] == [
+        (("created_at",), "timezone_naive"),
+    ]
+
+    table = SQLModel.metadata.tables["event"]
+    assert table.c.created_at.type.timezone is False