Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand All @@ -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`,
Expand Down
21 changes: 19 additions & 2 deletions docs/guide/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
6 changes: 3 additions & 3 deletions sqlalchemy_foundation_kit/base/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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__,
)

Expand Down
56 changes: 56 additions & 0 deletions tests/integration/test_datetime_columns_integration.py
Original file line number Diff line number Diff line change
@@ -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
6 changes: 3 additions & 3 deletions tests/unit/base/test_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand All @@ -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


Expand Down
Loading