From 01a7f7095eab728a12c55522a3562f69c1be7601 Mon Sep 17 00:00:00 2001 From: Alexey Shalaev <75322386+AlexeyShalaev@users.noreply.github.com> Date: Fri, 13 Nov 2026 01:40:29 +0400 Subject: [PATCH] fix: default created_at and updated_at to now() so a non-UTC session does not shift them timezone('UTC', now()) is a timestamp without zone, and the cast into the timestamptz column reads it in the session TimeZone. In a Europe/Moscow session both columns ended up 3 hours in the past. Closes #88 --- docs/agents.md | 8 ++- docs/guide/quickstart.md | 21 ++++++- sqlalchemy_foundation_kit/base/models.py | 6 +- .../test_datetime_columns_integration.py | 56 +++++++++++++++++++ tests/unit/base/test_models.py | 6 +- 5 files changed, 86 insertions(+), 11 deletions(-) create mode 100644 tests/integration/test_datetime_columns_integration.py diff --git a/docs/agents.md b/docs/agents.md index df207e4..1722b7b 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -281,7 +281,7 @@ and the free function take `str | int`. |---|---| | `Base` | `DeclarativeBase` with `MetaData(naming_convention=DB_NAMING_CONVENTION)` and a `type_annotation_map` mapping `uuid.UUID` to `postgresql.UUID()` and `datetime.datetime` to `TIMESTAMP(timezone=True)` | | `BaseTable` | `Base`, `__abstract__`, plus a `__repr__` printing every column | -| `DatetimeColumnsMixin` | `created_at` / `updated_at`, both `server_default=timezone('UTC', now())`, `updated_at` also `onupdate`. Index them with the class variables `__created_at_index__` / `__updated_at_index__`, both `False` by default | +| `DatetimeColumnsMixin` | `created_at` / `updated_at`, both `server_default=now()`, `updated_at` also `onupdate=now()`, so both hold the instant of the write in any session time zone. Index them with the class variables `__created_at_index__` / `__updated_at_index__`, both `False` by default | | `DB_NAMING_CONVENTION` | `ix` `%(column_0_label)s_idx`, `uq` `%(table_name)s_%(column_0_name)s_key`, `ck` `%(table_name)s_%(constraint_name)s_check`, `fk` `%(table_name)s_%(column_0_name)s_fkey`, `pk` `%(table_name)s_pkey` | | `PydanticJSONB(model_type)` | `TypeDecorator` over `JSONB`. Validates on write and on read; `model_type` is required. A row that no longer validates is logged and returned raw, not raised | | `GenericJSONDict` | `dict[str, Any]`, for a JSONB column that needs no validation | @@ -477,8 +477,9 @@ decorator. ### Fixed since 0.2.0 Three published entry points raise before they reach the database on 0.2.0; on 0.2.1 the -PgBouncer-safe defaults cannot connect through PgBouncer; and up to 0.4.0 the pool metrics -do not say what their names say. All are right on current versions; the workaround column +PgBouncer-safe defaults cannot connect through PgBouncer; up to 0.4.0 the pool metrics +do not say what their names say; and up to 0.5.1 the `DatetimeColumnsMixin` timestamps are +shifted by the session time zone. All are right on current versions; the workaround column is what to do on the version the row names. | Call | What it does on that version | Workaround there | @@ -493,6 +494,7 @@ is what to do on the version the row names. | `uow.transaction()` with a failing flush (0.4.0 and earlier, `flush_before_commit=True`, the default) | logged `str(exc)` at WARNING as `extra={"error": ...}` before re-raising: the statement's parameters and PostgreSQL's `DETAIL: Key (...)=(...)` row values went to the logs, and `hide_parameters=True` removed only the parameters | `flush_before_commit=False`; the same exception still reaches the caller | | `uow.query()` (0.4.0 and earlier) | documented as read-only and transaction-free, but ran an ordinary autobegun transaction: a write followed by `qx.session.commit()` was persisted, and without the commit it was rolled back silently | do reads in `query()` and every write in `transaction()` | | `create_async_session_manager(BasePostgresConfig(...))` with `[settings]` only (0.4.0 and earlier) | `ImportError: orjson is required` before connecting: `use_orjson_serialization` defaulted to `True` while orjson ships only with `[orjson]` / `[all]` | `use_orjson_serialization=False`, or install `[orjson]` | +| `DatetimeColumnsMixin` with a session `TimeZone` other than UTC (0.5.1 and earlier) | `created_at` and `updated_at` were off by the zone's UTC offset, 3 hours in the past with `Europe/Moscow`. The default was `timezone('UTC', now())`, a `timestamp` without zone, which the session reads as local time when it is cast into the `timestamptz` column | set the session `TimeZone` to UTC (`extra_server_settings={"timezone": "UTC"}` or `ALTER ROLE ... SET timezone = 'UTC'`). After the upgrade `onupdate` is right at once, but a table created on these versions keeps its old column default until a migration sets it to `now()`, written by hand because autogenerate compares the two defaults on the server and a UTC session finds them equal (see the quick start). Rows written before stay shifted | | `postgres_db_connection_checkout_duration_seconds` (0.3.0 and earlier) | the only checkout histogram there was, and it measures the time between the `checkout` and `checkin` events — how long a connection was *held*, which is query duration seen from the pool. The time a caller waited for a connection, which is what the name suggests and what predicts a pool outage, was not exposed at all | none; the wait was not measurable from outside the pool | `IsolationLevel` itself was always fine — `READ_UNCOMMITTED`, `READ_COMMITTED`, diff --git a/docs/guide/quickstart.md b/docs/guide/quickstart.md index d54b824..f5fc06a 100644 --- a/docs/guide/quickstart.md +++ b/docs/guide/quickstart.md @@ -119,10 +119,27 @@ class UserDB(BaseTable, DatetimeColumnsMixin): is_active: Mapped[bool] = mapped_column(default=True) # DatetimeColumnsMixin provides: -# - created_at: Mapped[datetime] (with server default) -# - updated_at: Mapped[datetime] (auto-updated on changes) +# - created_at: Mapped[datetime] (server default now()) +# - updated_at: Mapped[datetime] (server default now(), set to now() on every ORM update) ``` +`now()` is the start of the transaction as a `timestamptz`, the same instant whatever the +session `TimeZone`. Up to 0.5.1 the default was `timezone('UTC', now())`, a `timestamp` +without zone that a session in another zone read as its local time, so `created_at` and +`updated_at` were off by the zone's UTC offset. The `onupdate` value comes from the model and +is right once you upgrade, but a table created on 0.5.1 or earlier keeps its column default +until a migration changes it: + +```python +def upgrade() -> None: + for column in ("created_at", "updated_at"): + op.alter_column("users", column, server_default=sa.text("now()")) +``` + +Write it by hand: autogenerate does not find it even with `compare_server_default=True`, +because Alembic compares the two defaults by evaluating them on the server, and in a UTC +session they are equal. Rows written earlier from a session that was not on UTC stay shifted. + ### 3. Create Session Manager `AsyncSessionManager` handles connection pooling, health checks, and graceful shutdown: diff --git a/sqlalchemy_foundation_kit/base/models.py b/sqlalchemy_foundation_kit/base/models.py index 8d0bb5a..c13b2eb 100644 --- a/sqlalchemy_foundation_kit/base/models.py +++ b/sqlalchemy_foundation_kit/base/models.py @@ -55,15 +55,15 @@ class DatetimeColumnsMixin: @declared_attr def created_at(self) -> Mapped[datetime.datetime]: return mapped_column( - server_default=func.timezone("UTC", func.now()), + server_default=func.now(), index=self.__created_at_index__, ) @declared_attr def updated_at(self) -> Mapped[datetime.datetime]: return mapped_column( - server_default=func.timezone("UTC", func.now()), - onupdate=func.timezone("UTC", func.now()), + server_default=func.now(), + onupdate=func.now(), index=self.__updated_at_index__, ) diff --git a/tests/integration/test_datetime_columns_integration.py b/tests/integration/test_datetime_columns_integration.py new file mode 100644 index 0000000..ed60a1e --- /dev/null +++ b/tests/integration/test_datetime_columns_integration.py @@ -0,0 +1,56 @@ +"""Integration tests for DatetimeColumnsMixin against a real PostgreSQL.""" + +from __future__ import annotations + +import pytest +from sqlalchemy import func, select, text +from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker + +from tests.integration.models import TestUser + +# Not UTC, and no daylight saving time since 2014, so the offset is the same all year. +SESSION_TIME_ZONE = "Europe/Moscow" + + +@pytest.mark.integration +@pytest.mark.asyncio +async def test__datetime_mixin__non_utc_session__defaults_are_insert_instant( + async_session_factory: async_sessionmaker[AsyncSession], +) -> None: + # Arrange + async with async_session_factory() as session, session.begin(): + await session.execute(text(f"SET LOCAL TIME ZONE '{SESSION_TIME_ZONE}'")) + user = TestUser(name="Ann", email="ann@example.com") + + # Act + session.add(user) + await session.flush() + await session.refresh(user) + transaction_start = (await session.execute(select(func.now()))).scalar_one() + + # Assert + assert user.created_at == transaction_start + assert user.updated_at == transaction_start + + +@pytest.mark.integration +@pytest.mark.asyncio +async def test__datetime_mixin__non_utc_session__updated_at_is_update_instant( + async_session_factory: async_sessionmaker[AsyncSession], +) -> None: + # Arrange + async with async_session_factory() as session: + async with session.begin(): + user = TestUser(name="Ann", email="ann@example.com") + session.add(user) + + # Act + async with session.begin(): + await session.execute(text(f"SET LOCAL TIME ZONE '{SESSION_TIME_ZONE}'")) + user.name = "Bob" + await session.flush() + await session.refresh(user) + transaction_start = (await session.execute(select(func.now()))).scalar_one() + + # Assert + assert user.updated_at == transaction_start diff --git a/tests/unit/base/test_models.py b/tests/unit/base/test_models.py index 70d3a8b..e8edc04 100644 --- a/tests/unit/base/test_models.py +++ b/tests/unit/base/test_models.py @@ -186,7 +186,7 @@ class ArticleWithCreatedAt(BaseTable, DatetimeColumnsMixin): # Assert assert created_at_col is not None - assert created_at_col.server_default is not None + assert str(created_at_col.server_default.arg) == "now()" assert created_at_col.index is False @@ -203,8 +203,8 @@ class ArticleWithUpdatedAt(BaseTable, DatetimeColumnsMixin): # Assert assert updated_at_col is not None - assert updated_at_col.server_default is not None - assert updated_at_col.onupdate is not None + assert str(updated_at_col.server_default.arg) == "now()" + assert str(updated_at_col.onupdate.arg) == "now()" assert updated_at_col.index is False