[1c] Rename select_for_update() to for_update() and add lock-mode variants

[davegaeddert]

Postgres exposes four row-level lock strengths, but the ORM only offered FOR UPDATE (via select_for_update(), with a no_key= kwarg for the NO KEY variant). This adds all four as explicit QuerySet methods and drops the old name.

API

Model.query.for_update()         # FOR UPDATE
Model.query.for_no_key_update()  # FOR NO KEY UPDATE
Model.query.for_share()          # FOR SHARE
Model.query.for_key_share()      # FOR KEY SHARE

All four take the same nowait=, skip_locked=, and of= options. The old select_for_update() method and its no_key= kwarg are removed (no alias/shim — renames are handled by the upgrade agent). nowait + skip_locked together still raises ValueError; using any lock outside a transaction still raises TransactionManagementError. Chaining two lock modes keeps the last one.

Internals

The four booleans on Query (select_for_update, select_for_update_nowait, select_for_update_skip_locked, select_for_update_of, select_for_no_key_update) collapse into a single lock_mode: LockMode | None (a Literal["update", "no_key_update", "share", "key_share"]) plus lock_nowait, lock_skip_locked, lock_of. The compiler passes lock_mode straight through to dialect.lock_sql(mode, ...), which maps the token to its actual SQL keywords via LOCK_MODE_SQL — the queryset itself never carries raw SQL, only the mode token.

Callers updated

• plain-jobs worker claim query (.for_update(skip_locked=True))
• plain-oauthserver token exchange / refresh (.for_update())
• internal update_or_create and delete paths

Tests

New plain-postgres/tests/public/test_row_locking.py: each mode emits its clause, nowait/skip_locked/of render, nowait+skip_locked raises, last-mode-wins, lock-requires-transaction, and a behavioral check that a lock works inside atomic().

Docs

New "Row-level locking" section in the plain-postgres README under Transactions.

[pullapprove5]

PASS: 1 review scope passed

	Scope	Progress
✅	all	0/0

View in PullApprove

Next steps:

• @davegaeddert: Merge or close