[3d] Add upsert() and remove update_or_create()

[davegaeddert]

Summary

Adds single-row QuerySet.upsert() and removes update_or_create() outright, migrating all internal callers. Stacked on bulk-upsert.

obj, created = Model.query.upsert(
    key="my-key",
    defaults={"value": data},              # both insert and conflict-update
    create_defaults={"source": "x"},       # insert-only
    conflict_defaults={"count": F("count") + 1},  # per-column SET override
    unique_fields=[Model.key],
)

One INSERT ... ON CONFLICT (unique_fields) DO UPDATE SET ... RETURNING <cols>, (xmax = 0) statement. Returns (obj, created) with obj hydrated from the post-write row (no second query); created comes from the (xmax = 0) flag (freshly-inserted tuples have xmax = 0).

How it works

• created flag: the compiler's SQLInsertCompiler.as_sql appends a raw (xmax = 0) column straight onto the RETURNING clause in its returning_created branch — returning_columns() stays a pure fields→SQL helper with no extra-column argument. Converters only run on the real field columns, and upsert() pops the trailing bool.
• conflict_defaults: the dialect's on_conflict_suffix_sql takes optional per-column SQL fragments; the insert compiler compiles each override value through the shared SQLCompiler._compile_assignment_value — the same helper UPDATE ... SET uses — so a value can be plain or an expression (F("count") + 1 resolves to the target row's existing column for an atomic counter). When every inserted column is a unique field there's nothing to SET, so a unique column is set to itself as a no-op — DO UPDATE (not DO NOTHING) is required for RETURNING to return the conflicting row.
• SET columns: every non-unique, non-PK column from kwargs/defaults → EXCLUDED.col; create_defaults are insert-only and never in the SET; conflict_defaults override per column.
• Validation: unique_fields take typed field references (Model.key, not "key") and must match the PK or a total UniqueConstraint; unique values must be non-null. Unknown keys in kwargs/defaults raise a clean FieldError (via _validate_model_field_names) before they fail later and more confusingly. No full_clean of the merged row (consistent with the bulk paths).

Caller migrations

• plain-flags, plain-sessions → upsert().
• FK reverse manager and M2M manager update_or_create → upsert; the M2M wrapper keeps its add-if-created behavior (adds the through-row only on insert).

Tests

New test_upsert.py (insert/conflict, defaults, create_defaults insert-only, F-counter, unique-only idempotency, validation errors including string/wrong-model unique fields, single-statement checks) plus M2M/FK manager add-if-created tests. Full suite green; type-check plain-postgres clean.