claude22

Author: bdowning

CLAUDE.md

@@ -176,7 +176,7 @@ tags: Annotated[list, ColumnInfo(type="JSONB", serialize=json.dumps, deserialize
 
 ### Bulk Insert Modes
 - `unnest` (default): Most efficient for PostgreSQL using UNNEST
-- `array_safe`: Uses VALUES syntax with chunking for large datasets  
+- `array_safe`: Uses VALUES syntax; required when model has array columns (PostgreSQL doesn't support arrays-of-arrays)
 - `executemany`: Uses asyncpg's executemany (slowest but most compatible)
 
 ## Version Info

sql_athame/dataclasses.py

@@ -954,8 +954,9 @@ def insert_multiple_sql(cls: type[T], rows: Iterable[T]) -> Fragment:
     def insert_multiple_array_safe_sql(cls: type[T], rows: Iterable[T]) -> Fragment:
         """Generate bulk INSERT SQL using VALUES syntax.
         
-        This method is safer for very large datasets as it doesn't create
-        large arrays that might exceed PostgreSQL limits.
+        This method is required when your model contains array columns, because
+        PostgreSQL doesn't support arrays-of-arrays (which UNNEST would require).
+        Use this instead of the UNNEST method when you have array-typed fields.
         
         Args:
             rows: Model instances to insert
@@ -1043,7 +1044,9 @@ async def insert_multiple_array_safe(
     ) -> str:
         """Insert multiple records using VALUES syntax with chunking.
         
-        This method chunks large datasets to avoid PostgreSQL array size limits.
+        This method is required when your model contains array columns, because
+        PostgreSQL doesn't support arrays-of-arrays (which UNNEST would require).
+        Data is processed in chunks to manage memory usage.
         
         Args:
             connection_or_pool: Database connection or pool
@@ -1075,7 +1078,7 @@ async def insert_multiple(
         Note:
             The actual method used depends on the insert_multiple_mode setting:
             - 'unnest': Most efficient, uses UNNEST (default)
-            - 'array_safe': Uses VALUES with chunking for large datasets
+            - 'array_safe': Uses VALUES syntax; required when model has array columns
             - 'executemany': Uses asyncpg's executemany, slowest but most compatible
         """
         if cls.insert_multiple_mode == "executemany":
@@ -1137,6 +1140,9 @@ async def upsert_multiple_array_safe(
     ) -> str:
         """Bulk upsert using VALUES syntax with chunking.
         
+        This method is required when your model contains array columns, because
+        PostgreSQL doesn't support arrays-of-arrays (which UNNEST would require).
+        
         Args:
             connection_or_pool: Database connection or pool
             rows: Model instances to upsert