docs: align upsert_many scope notes with reverted single-row API

Post-revert (116b813), the docstring on
``OnConflictUpsert.supports_native_upsert`` was still the generic
"Check if the dialect supports native upsert operations." Replace it
with the precise scope: the flag is for the single-row
``create_upsert`` API on true ON-CONFLICT dialects; MERGE / INSERT
OR UPDATE go through ``Repository.upsert_many`` and aren't reported
here.

Also extend ``docs/usage/repositories/basics.rst`` with a "Server-managed
PK safety net" bullet documenting the resolver's transparent fallback
when MERGE / INSERT OR UPDATE rows are missing PK columns — the same
behavior the new ``BigIntPrimaryKey`` skip guards in the chunk-size
tests exist to side-step.

Author: cofin

advanced_alchemy/operations.py

@@ -409,13 +409,22 @@ class OnConflictUpsert:
 
     @staticmethod
     def supports_native_upsert(dialect_name: str) -> bool:
-        """Check if the dialect supports native upsert operations.
+        """Check if the dialect supports the single-row ``create_upsert`` API.
+
+        This flag is scoped to the per-row ``INSERT ... ON CONFLICT`` /
+        ``ON DUPLICATE KEY UPDATE`` dialects that
+        :meth:`OnConflictUpsert.create_upsert` can compile directly. The
+        bulk ``MERGE`` (mssql, oracle) and ``INSERT OR UPDATE`` (spanner)
+        primitives are dispatched separately by
+        :meth:`Repository.upsert_many` via :func:`resolve_upsert_strategy`
+        and are intentionally **not** reported here.
 
         Args:
             dialect_name: Name of the database dialect
 
         Returns:
-            True if native upsert is supported, False otherwise
+            ``True`` for postgresql / cockroachdb / sqlite / mysql /
+            mariadb / duckdb; ``False`` otherwise.
         """
         return dialect_name in {"postgresql", "cockroachdb", "sqlite", "mysql", "mariadb", "duckdb"}
 

docs/usage/repositories/basics.rst

@@ -184,6 +184,15 @@ Important behaviors:
 - **``chunk_size``** mirrors ``add_many``: each chunk compiles to exactly one
   native statement (plus a re-SELECT for hydration on dialects without
   RETURNING).
+- **Server-managed PK safety net.** ``MERGE`` (oracle / mssql) and
+  ``INSERT OR UPDATE`` (spanner) cannot transparently invoke server-side
+  ``Sequence`` / ``Identity`` defaults the way ``INSERT ... ON CONFLICT``
+  does on PostgreSQL. When any prepared row is missing a primary-key
+  column on those dialects, ``upsert_many`` transparently falls back to
+  the SELECT-then-partition path so the sequence/identity machinery
+  runs normally. Models with Python-callable PK defaults (UUIDv6 /
+  UUIDv7 / nano-id) keep the single-statement native path because
+  the row is populated before dispatch.
 - **No breaking changes.** ``Sequence[ModelT]`` return shape is preserved;
   Litestar session / store callers using the single-row ``OnConflictUpsert``
   API are unaffected.