sqlmodel-object-helpers 0.0.9__tar.gz → 0.0.11__tar.gz

{sqlmodel_object_helpers-0.0.9 → sqlmodel_object_helpers-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-object-helpers
-Version: 0.0.9
+Version: 0.0.11
 Summary: Generic async query helpers for SQLModel: filtering, eager loading, pagination
 Project-URL: Homepage, https://github.com/itstandart/sqlmodel-object-helpers
 Project-URL: Repository, https://github.com/itstandart/sqlmodel-object-helpers
@@ -43,6 +43,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Pagination** - Page/per\_page with total count and configurable max\_per\_page limit
 - **Projections** - Select specific columns across joins with dot-notation and SQL aliases
 - **CRUD Mutations** - `add_object`, `update_object`, `delete_object` plus bulk `update_objects`, `delete_objects` with flush-only semantics for composable transactions
+- **Idempotent Bulk Insert** - `insert_objects_ignore_conflicts`: `INSERT ... ON CONFLICT DO NOTHING` as executemany of one single-row statement (PostgreSQL, SQLite), safe to replay
+- **Bulk Upsert** - `upsert_objects`: `INSERT ... ON CONFLICT DO UPDATE` as executemany of one single-row statement (PostgreSQL, SQLite); update expressions run on every call
 - **Count & Exists** - `count_objects` (single `SELECT count(*)`) and `exists_object` (`SELECT EXISTS(...)`) without loading data
 - **Row Locking** - `for_update` parameter on `get_object` for `SELECT ... FOR UPDATE`
 - **Time Filtering** - `TimeFilter` for `created_at`/`updated_at` range filtering with half-open interval semantics
@@ -392,6 +394,14 @@ user = await soh.add_object(session, User(name="Alice"))
 users = await soh.add_objects(session, [User(name="Alice"), User(name="Bob")])
 ```
 
+Choose the insert helper by its contract:
+
+| Need | Helper | Result |
+|---|---|---|
+| Persist ORM objects and populate generated fields; duplicates are errors | `add_objects` | ORM objects |
+| Insert rows and skip duplicates by a unique key | [`insert_objects_ignore_conflicts`](#insert_objects_ignore_conflicts) | Inserted count |
+| Insert rows and update existing ones by a unique key | [`upsert_objects`](#upsert_objects) | Inserted + updated count |
+
 ### update_object
 
 ```python
@@ -440,6 +450,56 @@ count = await soh.delete_objects(
 
 Filters are **required** for safety -- empty filters are rejected. Dot-notation (relationship) filters are not supported in bulk operations.
 
+### insert_objects_ignore_conflicts
+
+Idempotent bulk insert -- `INSERT ... ON CONFLICT (...) DO NOTHING`, no objects loaded or refreshed:
+
+```python
+import sqlmodel_object_helpers as soh
+
+inserted = await soh.insert_objects_ignore_conflicts(
+    session, PaymentLog,
+    rows=[{"source_id": "run1:1", "base": "a-cso"}, {"source_id": "run1:2", "base": "a-cso"}],
+    conflict_columns=["source_id"],
+)
+# inserted -> rows actually written; duplicates by source_id are skipped and not counted
+```
+
+Replaying the same batch (or two concurrent identical batches) is safe, unlike `add_objects`, where one duplicate fails the whole batch. All rows must have the same keys. Rows go to the database as given (no Pydantic validation or coercion -- pass already-typed values); omitted columns get their column defaults: `Field(default=...)` / `default_factory` of a plain field and `server_default` (SQLModel does not copy `Field(default)` into an explicit `sa_column`). Rows go as executemany of one single-row statement: SQLAlchemy [insertmanyvalues](https://docs.sqlalchemy.org/en/20/core/connections.html#engine-insertmanyvalues) renders up to `insertmanyvalues_page_size` rows (1000 by default) per INSERT and keeps each statement within the dialect parameter limit, omitted Python defaults included. A row with an SQL expression value (`func.now()`, `literal(...)`) cannot be an executemany parameter set, so it is inserted by its own statement, in input order. An engine created with `use_insertmanyvalues=False` cannot return rows from an executemany, so there every row runs as its own statement. A Core INSERT does not autoflush, so pending session changes are flushed first. PostgreSQL and SQLite only (`MutationError` on other dialects).
+
+The caller owns the transaction. If a later batch fails, roll back the transaction to discard earlier batches too. The helper does not commit or perform its own rollback. Standalone wrappers manage commit/rollback automatically.
+
+### upsert_objects
+
+Bulk upsert -- `INSERT ... ON CONFLICT (...) DO UPDATE SET ...`: new rows are inserted, rows hitting the unique key are updated:
+
+```python
+import sqlmodel_object_helpers as soh
+from sqlalchemy import func
+
+written = await soh.upsert_objects(
+    session, Ast,
+    rows=[{"code": "a", "width": 10, "ordinal": 1}, {"code": "b", "width": 20, "ordinal": 2}],
+    conflict_columns=["code"],
+    update_columns=["width", "ordinal"],        # default: every row field except conflict_columns
+    set_extra={"updated_at": func.now()},       # applied only on update
+)
+# written -> distinct table rows inserted or updated, counted by primary key from RETURNING
+```
+
+If a key repeats inside `rows`, the last row wins and the row is counted once, with the result of row-by-row execution. PostgreSQL rejects a statement that hits one key twice, so on PostgreSQL:
+
+- a key value equal in Python to an earlier one starts the next statement, in input order (rows of other keys may depend on earlier rows through another unique constraint): one INSERT per page plus one per repeat. `ARRAY` and `JSONB` values are compared by content;
+- each page of up to `insertmanyvalues_page_size` rows of a multi-row call runs in a SAVEPOINT, also when its rows go one by one (a row with an SQL expression, an expanding `IN` in `set_extra`, `use_insertmanyvalues=False`), since only the database decides what is a repeat: the column type (`NUMERIC` rounding, `citext`, the `VARCHAR(n)` cut), the collation of the column or of the unique index, a `BEFORE INSERT` trigger that changes the key, `NULLS NOT DISTINCT`. A page the database rejects for a repeated key is rolled back to the SAVEPOINT and re-run row by row in a new SAVEPOINT, so an error during the retry also rolls back that entire page; distinct values such as two instants of a DST fold stay distinct. Each SAVEPOINT costs two round trips: one per page, plus one when a page is retried; a single-row call goes without it. A released SAVEPOINT keeps its subtransaction until commit: more than 64 pages in one transaction (over 64000 rows at the default page size) overflow the backend subtransaction cache, and until commit other sessions check this transaction's rows through `pg_subtrans`, which is slower under load. Split such a load into several transactions.
+
+The distinct primary-key count preserves JSON types: `true` and `1` (also `false` and `0`) are different keys, including inside objects and arrays. Numerically equal JSON numbers such as `1` and `1.0` remain one key, and object field order does not affect equality. Repeated keys across pages are counted once.
+
+SQLite applies repeated keys in order within one statement. Every `conflict_columns` field must be present in each row. `update_columns` must be a subset of the row fields outside `conflict_columns`; `set_extra` takes model fields (value or SQL expression) that are in neither; a `None` value becomes SQL `NULL`. An expanding `IN` or `literal_execute` parameter in `set_extra` cannot be used with executemany, so each row then runs as its own statement. When nothing is left to update, use `insert_objects_ignore_conflicts` instead (`MutationError`). `Column.onupdate` does not fire on conflict -- pass it in `set_extra`. Objects already loaded in the session are not refreshed. A conditional update (`WHERE`) or `RETURNING` is not covered -- build the statement with SQLAlchemy for that. Other rules as in `insert_objects_ignore_conflicts`: same keys in all rows, no Pydantic validation, executemany batching, caller-managed transaction, PostgreSQL and SQLite only.
+
+Repeating an upsert does not create duplicate keys, but it repeats the update: expressions such as `hits + 1` and `func.now()` run again. NULL conflict-key values follow the index: an ordinary UNIQUE keeps them distinct, `NULLS NOT DISTINCT` treats them as one key.
+
+Other database errors are not retried. On PostgreSQL an error in a multi-row upsert is rolled back to the SAVEPOINT of its page; an error in `insert_objects_ignore_conflicts`, in a single-row upsert or on SQLite aborts the transaction, as with a hand-written INSERT. Earlier pages stay written either way: roll back after `MutationError` / `DatabaseError`, or wrap the call in `session.begin_nested()` to keep the earlier work.
+
 ### check_for_related_records
 
 Pre-deletion check that inspects all ONETOMANY relationships:
@@ -772,6 +832,8 @@ Endpoints can be migrated one at a time. Three strategies per endpoint:
 - `soh.update_objects(session, model, data, filters)` -- Bulk update via single `UPDATE ... WHERE`
 - `soh.delete_object(session, model, *, instance, pk)` -- Delete by reference or PK
 - `soh.delete_objects(session, model, filters)` -- Bulk delete via single `DELETE ... WHERE`
+- `soh.insert_objects_ignore_conflicts(session, model, rows, *, conflict_columns)` -- Bulk insert via `INSERT ... ON CONFLICT DO NOTHING`, returns inserted count
+- `soh.upsert_objects(session, model, rows, *, conflict_columns, update_columns=None, set_extra=None)` -- Bulk insert via `INSERT ... ON CONFLICT DO UPDATE`, returns inserted + updated count
 - `soh.check_for_related_records(session, model, pk)` -- Pre-deletion dependency check
 
 ### Dynamic Meta
@@ -850,6 +912,14 @@ uv sync
 uv run pytest tests/
 ```
 
+PostgreSQL integration tests use the optional `postgres` dependency group (asyncpg). Each test creates a randomly named schema and removes that schema afterwards; it does not recreate application tables. Without `SOH_TEST_POSTGRES_URL`, these tests are skipped.
+
+```bash
+uv sync --group postgres
+SOH_TEST_POSTGRES_URL=postgresql+asyncpg://user:password@localhost/test_db \
+  uv run --group postgres pytest -q tests/test_conflict_mutations_postgres.py
+```
+
 ### Syncing with Remote
 
 ```bash
@@ -891,6 +961,25 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
+### 0.0.11 — unreleased
+
+- **Performance** — `insert_objects_ignore_conflicts` and `upsert_objects` execute one single-row statement as executemany instead of compiling a multi-row `VALUES` statement per chunk; SQLAlchemy insertmanyvalues renders the rows into multi-row pages. No statement cache is involved: SQLAlchemy does not cache PostgreSQL `INSERT ... ON CONFLICT`. On PostgreSQL 18 with asyncpg, inserting 1000 rows of an 18-column table takes about 27 ms instead of 610 ms (20000 rows: 0.56 s instead of 13 s), on par with a hand-written bulk insert; upserting 1000 rows of a 6-column table takes about 12 ms instead of 165 ms (10000 rows: 0.11 s instead of 1.65 s), SAVEPOINTs included. Server-side execution time is unchanged.
+- `upsert_objects` on PostgreSQL: a key repeated in Python terms starts the next statement, in input order, instead of re-running the batch row by row. Each page of a multi-row call keeps the 0.0.10 SAVEPOINT, also when its rows go one by one: a repeat only the database sees (column type, collation of the column or of the unique index, a `BEFORE INSERT` trigger) is retried row by row in a new SAVEPOINT. Another error, including during that retry, rolls back the page without aborting the caller's transaction. A single-row call goes without a SAVEPOINT.
+- A `JSONB` primary key works in both operations: `insert_objects_ignore_conflicts` counts the returned rows, and the upsert count compares `JSONB` / `ARRAY` primary keys by content (the 0.0.10 upsert failed with `DatabaseError`). JSON booleans are distinct from numbers, both as scalar keys and inside objects or arrays; numerically equal JSON numbers remain one key.
+- An engine with `use_insertmanyvalues=False` runs every row as its own statement: an executemany cannot return rows there.
+- A row with SQL expression values is inserted by its own statement in input order; a `None` in `set_extra` is sent as `NULL`, which keeps the upsert batched; an expanding `IN` in `set_extra` makes the upsert run row by row.
+- Pending session changes are flushed before the insert on every dialect: a Core INSERT does not autoflush.
+- A single row no longer fails with `MutationError` for exceeding a parameter budget: SQLAlchemy keeps every statement within the dialect limit.
+- Tested on PostgreSQL 13.23, 14.24, 15.19, 16.15, 17.7, 18.1 and 18.4 (on 13 and 14 without the `NULLS NOT DISTINCT` test, a PostgreSQL 15 feature) and with SQLAlchemy 2.0.46, 2.0.52 and 2.1.6.
+
+### 0.0.10 — 2026-10-26
+
+- `insert_objects_ignore_conflicts` and `upsert_objects`: bulk insert with explicit unique-key conflict handling, inserted/updated counts, and standalone wrappers.
+- Chunk sizes account for actual SQL parameters, including omitted Python defaults, repeated positional parameters, expanding `IN` expressions, and update expressions. Tested with SQLAlchemy 2.0.46, 2.0.52 and 2.1.6.
+- Upsert reports a missing conflict-key field as `MutationError`. Repeated update expressions are explicitly documented as non-idempotent.
+- Upsert leaves repeated keys to the database instead of Python equality: no silent loss of distinct keys (DST fold), no `DatabaseError` for keys equal only after column type coercion (`NUMERIC(10,2)`), no `TypeError` for unhashable keys (`ARRAY`). The count is distinct rows by primary key.
+- PostgreSQL tests run through the optional `postgres` dependency group; tested on PostgreSQL 18.4 and 18.1, the versions of the SRO Agent and ExamCRM dev databases.
+
 ### 0.0.9 — 2026-10-09
 
 - Dependency lower bound is now `sqlmodel>=0.0.27`. SQLModel 0.0.22–0.0.26 cannot create models on Python 3.14 (`Field 'id' requires a type annotation`), so the previous `>=0.0.22` bound was never satisfiable. Test suite passes on every SQLModel from 0.0.27 to 0.0.48.

{sqlmodel_object_helpers-0.0.9 → sqlmodel_object_helpers-0.0.11}/README.md

@@ -15,6 +15,8 @@ Generic async query helpers for [SQLModel](https://sqlmodel.tiangolo.com/): filt
 - **Pagination** - Page/per\_page with total count and configurable max\_per\_page limit
 - **Projections** - Select specific columns across joins with dot-notation and SQL aliases
 - **CRUD Mutations** - `add_object`, `update_object`, `delete_object` plus bulk `update_objects`, `delete_objects` with flush-only semantics for composable transactions
+- **Idempotent Bulk Insert** - `insert_objects_ignore_conflicts`: `INSERT ... ON CONFLICT DO NOTHING` as executemany of one single-row statement (PostgreSQL, SQLite), safe to replay
+- **Bulk Upsert** - `upsert_objects`: `INSERT ... ON CONFLICT DO UPDATE` as executemany of one single-row statement (PostgreSQL, SQLite); update expressions run on every call
 - **Count & Exists** - `count_objects` (single `SELECT count(*)`) and `exists_object` (`SELECT EXISTS(...)`) without loading data
 - **Row Locking** - `for_update` parameter on `get_object` for `SELECT ... FOR UPDATE`
 - **Time Filtering** - `TimeFilter` for `created_at`/`updated_at` range filtering with half-open interval semantics
@@ -364,6 +366,14 @@ user = await soh.add_object(session, User(name="Alice"))
 users = await soh.add_objects(session, [User(name="Alice"), User(name="Bob")])
 ```
 
+Choose the insert helper by its contract:
+
+| Need | Helper | Result |
+|---|---|---|
+| Persist ORM objects and populate generated fields; duplicates are errors | `add_objects` | ORM objects |
+| Insert rows and skip duplicates by a unique key | [`insert_objects_ignore_conflicts`](#insert_objects_ignore_conflicts) | Inserted count |
+| Insert rows and update existing ones by a unique key | [`upsert_objects`](#upsert_objects) | Inserted + updated count |
+
 ### update_object
 
 ```python
@@ -412,6 +422,56 @@ count = await soh.delete_objects(
 
 Filters are **required** for safety -- empty filters are rejected. Dot-notation (relationship) filters are not supported in bulk operations.
 
+### insert_objects_ignore_conflicts
+
+Idempotent bulk insert -- `INSERT ... ON CONFLICT (...) DO NOTHING`, no objects loaded or refreshed:
+
+```python
+import sqlmodel_object_helpers as soh
+
+inserted = await soh.insert_objects_ignore_conflicts(
+    session, PaymentLog,
+    rows=[{"source_id": "run1:1", "base": "a-cso"}, {"source_id": "run1:2", "base": "a-cso"}],
+    conflict_columns=["source_id"],
+)
+# inserted -> rows actually written; duplicates by source_id are skipped and not counted
+```
+
+Replaying the same batch (or two concurrent identical batches) is safe, unlike `add_objects`, where one duplicate fails the whole batch. All rows must have the same keys. Rows go to the database as given (no Pydantic validation or coercion -- pass already-typed values); omitted columns get their column defaults: `Field(default=...)` / `default_factory` of a plain field and `server_default` (SQLModel does not copy `Field(default)` into an explicit `sa_column`). Rows go as executemany of one single-row statement: SQLAlchemy [insertmanyvalues](https://docs.sqlalchemy.org/en/20/core/connections.html#engine-insertmanyvalues) renders up to `insertmanyvalues_page_size` rows (1000 by default) per INSERT and keeps each statement within the dialect parameter limit, omitted Python defaults included. A row with an SQL expression value (`func.now()`, `literal(...)`) cannot be an executemany parameter set, so it is inserted by its own statement, in input order. An engine created with `use_insertmanyvalues=False` cannot return rows from an executemany, so there every row runs as its own statement. A Core INSERT does not autoflush, so pending session changes are flushed first. PostgreSQL and SQLite only (`MutationError` on other dialects).
+
+The caller owns the transaction. If a later batch fails, roll back the transaction to discard earlier batches too. The helper does not commit or perform its own rollback. Standalone wrappers manage commit/rollback automatically.
+
+### upsert_objects
+
+Bulk upsert -- `INSERT ... ON CONFLICT (...) DO UPDATE SET ...`: new rows are inserted, rows hitting the unique key are updated:
+
+```python
+import sqlmodel_object_helpers as soh
+from sqlalchemy import func
+
+written = await soh.upsert_objects(
+    session, Ast,
+    rows=[{"code": "a", "width": 10, "ordinal": 1}, {"code": "b", "width": 20, "ordinal": 2}],
+    conflict_columns=["code"],
+    update_columns=["width", "ordinal"],        # default: every row field except conflict_columns
+    set_extra={"updated_at": func.now()},       # applied only on update
+)
+# written -> distinct table rows inserted or updated, counted by primary key from RETURNING
+```
+
+If a key repeats inside `rows`, the last row wins and the row is counted once, with the result of row-by-row execution. PostgreSQL rejects a statement that hits one key twice, so on PostgreSQL:
+
+- a key value equal in Python to an earlier one starts the next statement, in input order (rows of other keys may depend on earlier rows through another unique constraint): one INSERT per page plus one per repeat. `ARRAY` and `JSONB` values are compared by content;
+- each page of up to `insertmanyvalues_page_size` rows of a multi-row call runs in a SAVEPOINT, also when its rows go one by one (a row with an SQL expression, an expanding `IN` in `set_extra`, `use_insertmanyvalues=False`), since only the database decides what is a repeat: the column type (`NUMERIC` rounding, `citext`, the `VARCHAR(n)` cut), the collation of the column or of the unique index, a `BEFORE INSERT` trigger that changes the key, `NULLS NOT DISTINCT`. A page the database rejects for a repeated key is rolled back to the SAVEPOINT and re-run row by row in a new SAVEPOINT, so an error during the retry also rolls back that entire page; distinct values such as two instants of a DST fold stay distinct. Each SAVEPOINT costs two round trips: one per page, plus one when a page is retried; a single-row call goes without it. A released SAVEPOINT keeps its subtransaction until commit: more than 64 pages in one transaction (over 64000 rows at the default page size) overflow the backend subtransaction cache, and until commit other sessions check this transaction's rows through `pg_subtrans`, which is slower under load. Split such a load into several transactions.
+
+The distinct primary-key count preserves JSON types: `true` and `1` (also `false` and `0`) are different keys, including inside objects and arrays. Numerically equal JSON numbers such as `1` and `1.0` remain one key, and object field order does not affect equality. Repeated keys across pages are counted once.
+
+SQLite applies repeated keys in order within one statement. Every `conflict_columns` field must be present in each row. `update_columns` must be a subset of the row fields outside `conflict_columns`; `set_extra` takes model fields (value or SQL expression) that are in neither; a `None` value becomes SQL `NULL`. An expanding `IN` or `literal_execute` parameter in `set_extra` cannot be used with executemany, so each row then runs as its own statement. When nothing is left to update, use `insert_objects_ignore_conflicts` instead (`MutationError`). `Column.onupdate` does not fire on conflict -- pass it in `set_extra`. Objects already loaded in the session are not refreshed. A conditional update (`WHERE`) or `RETURNING` is not covered -- build the statement with SQLAlchemy for that. Other rules as in `insert_objects_ignore_conflicts`: same keys in all rows, no Pydantic validation, executemany batching, caller-managed transaction, PostgreSQL and SQLite only.
+
+Repeating an upsert does not create duplicate keys, but it repeats the update: expressions such as `hits + 1` and `func.now()` run again. NULL conflict-key values follow the index: an ordinary UNIQUE keeps them distinct, `NULLS NOT DISTINCT` treats them as one key.
+
+Other database errors are not retried. On PostgreSQL an error in a multi-row upsert is rolled back to the SAVEPOINT of its page; an error in `insert_objects_ignore_conflicts`, in a single-row upsert or on SQLite aborts the transaction, as with a hand-written INSERT. Earlier pages stay written either way: roll back after `MutationError` / `DatabaseError`, or wrap the call in `session.begin_nested()` to keep the earlier work.
+
 ### check_for_related_records
 
 Pre-deletion check that inspects all ONETOMANY relationships:
@@ -744,6 +804,8 @@ Endpoints can be migrated one at a time. Three strategies per endpoint:
 - `soh.update_objects(session, model, data, filters)` -- Bulk update via single `UPDATE ... WHERE`
 - `soh.delete_object(session, model, *, instance, pk)` -- Delete by reference or PK
 - `soh.delete_objects(session, model, filters)` -- Bulk delete via single `DELETE ... WHERE`
+- `soh.insert_objects_ignore_conflicts(session, model, rows, *, conflict_columns)` -- Bulk insert via `INSERT ... ON CONFLICT DO NOTHING`, returns inserted count
+- `soh.upsert_objects(session, model, rows, *, conflict_columns, update_columns=None, set_extra=None)` -- Bulk insert via `INSERT ... ON CONFLICT DO UPDATE`, returns inserted + updated count
 - `soh.check_for_related_records(session, model, pk)` -- Pre-deletion dependency check
 
 ### Dynamic Meta
@@ -822,6 +884,14 @@ uv sync
 uv run pytest tests/
 ```
 
+PostgreSQL integration tests use the optional `postgres` dependency group (asyncpg). Each test creates a randomly named schema and removes that schema afterwards; it does not recreate application tables. Without `SOH_TEST_POSTGRES_URL`, these tests are skipped.
+
+```bash
+uv sync --group postgres
+SOH_TEST_POSTGRES_URL=postgresql+asyncpg://user:password@localhost/test_db \
+  uv run --group postgres pytest -q tests/test_conflict_mutations_postgres.py
+```
+
 ### Syncing with Remote
 
 ```bash
@@ -863,6 +933,25 @@ This project follows [Semantic Versioning](https://semver.org/) (MAJOR.MINOR.PAT
 
 ## Changelog
 
+### 0.0.11 — unreleased
+
+- **Performance** — `insert_objects_ignore_conflicts` and `upsert_objects` execute one single-row statement as executemany instead of compiling a multi-row `VALUES` statement per chunk; SQLAlchemy insertmanyvalues renders the rows into multi-row pages. No statement cache is involved: SQLAlchemy does not cache PostgreSQL `INSERT ... ON CONFLICT`. On PostgreSQL 18 with asyncpg, inserting 1000 rows of an 18-column table takes about 27 ms instead of 610 ms (20000 rows: 0.56 s instead of 13 s), on par with a hand-written bulk insert; upserting 1000 rows of a 6-column table takes about 12 ms instead of 165 ms (10000 rows: 0.11 s instead of 1.65 s), SAVEPOINTs included. Server-side execution time is unchanged.
+- `upsert_objects` on PostgreSQL: a key repeated in Python terms starts the next statement, in input order, instead of re-running the batch row by row. Each page of a multi-row call keeps the 0.0.10 SAVEPOINT, also when its rows go one by one: a repeat only the database sees (column type, collation of the column or of the unique index, a `BEFORE INSERT` trigger) is retried row by row in a new SAVEPOINT. Another error, including during that retry, rolls back the page without aborting the caller's transaction. A single-row call goes without a SAVEPOINT.
+- A `JSONB` primary key works in both operations: `insert_objects_ignore_conflicts` counts the returned rows, and the upsert count compares `JSONB` / `ARRAY` primary keys by content (the 0.0.10 upsert failed with `DatabaseError`). JSON booleans are distinct from numbers, both as scalar keys and inside objects or arrays; numerically equal JSON numbers remain one key.
+- An engine with `use_insertmanyvalues=False` runs every row as its own statement: an executemany cannot return rows there.
+- A row with SQL expression values is inserted by its own statement in input order; a `None` in `set_extra` is sent as `NULL`, which keeps the upsert batched; an expanding `IN` in `set_extra` makes the upsert run row by row.
+- Pending session changes are flushed before the insert on every dialect: a Core INSERT does not autoflush.
+- A single row no longer fails with `MutationError` for exceeding a parameter budget: SQLAlchemy keeps every statement within the dialect limit.
+- Tested on PostgreSQL 13.23, 14.24, 15.19, 16.15, 17.7, 18.1 and 18.4 (on 13 and 14 without the `NULLS NOT DISTINCT` test, a PostgreSQL 15 feature) and with SQLAlchemy 2.0.46, 2.0.52 and 2.1.6.
+
+### 0.0.10 — 2026-10-26
+
+- `insert_objects_ignore_conflicts` and `upsert_objects`: bulk insert with explicit unique-key conflict handling, inserted/updated counts, and standalone wrappers.
+- Chunk sizes account for actual SQL parameters, including omitted Python defaults, repeated positional parameters, expanding `IN` expressions, and update expressions. Tested with SQLAlchemy 2.0.46, 2.0.52 and 2.1.6.
+- Upsert reports a missing conflict-key field as `MutationError`. Repeated update expressions are explicitly documented as non-idempotent.
+- Upsert leaves repeated keys to the database instead of Python equality: no silent loss of distinct keys (DST fold), no `DatabaseError` for keys equal only after column type coercion (`NUMERIC(10,2)`), no `TypeError` for unhashable keys (`ARRAY`). The count is distinct rows by primary key.
+- PostgreSQL tests run through the optional `postgres` dependency group; tested on PostgreSQL 18.4 and 18.1, the versions of the SRO Agent and ExamCRM dev databases.
+
 ### 0.0.9 — 2026-10-09
 
 - Dependency lower bound is now `sqlmodel>=0.0.27`. SQLModel 0.0.22–0.0.26 cannot create models on Python 3.14 (`Field 'id' requires a type annotation`), so the previous `>=0.0.22` bound was never satisfiable. Test suite passes on every SQLModel from 0.0.27 to 0.0.48.

{sqlmodel_object_helpers-0.0.9 → sqlmodel_object_helpers-0.0.11}/pyproject.toml

@@ -45,10 +45,13 @@ packages = ["src/sqlmodel_object_helpers"]
 
 [dependency-groups]
 dev = [
-    "ruff==0.16.10",
+    "ruff==0.17.2",
     "pyright==1.1.414",
     "tzdata==2026.5",
     "pytest==9.1.1",
     "pytest-asyncio==1.4.0",
     "aiosqlite==0.22.1",
 ]
+postgres = [
+    "asyncpg==0.32.0",
+]

{sqlmodel_object_helpers-0.0.9 → sqlmodel_object_helpers-0.0.11}/src/sqlmodel_object_helpers/__init__.py

@@ -1,6 +1,6 @@
 """sqlmodel-object-helpers — reusable query helpers for SQLModel projects."""
 
-__version__ = "0.0.9"
+__version__ = "0.0.11"
 
 from .constants import QueryHelperSettings, settings
 from .dynamic_meta import (
@@ -26,8 +26,10 @@ from .mutations import (
     check_for_related_records,
     delete_object,
     delete_objects,
+    insert_objects_ignore_conflicts,
     update_object,
     update_objects,
+    upsert_objects,
 )
 from .operators import SPECIAL_OPERATORS, SUPPORTED_OPERATORS, LogicalOperator, Operator
 from .query import count_objects, exists_object, get_object, get_objects, get_projection
@@ -119,9 +121,11 @@ __all__ = [
     "get_object",
     "get_objects",
     "get_projection",
+    "insert_objects_ignore_conflicts",
     "invalidate_meta_cache",
     "load_pg_comments",
     "settings",
     "update_object",
     "update_objects",
+    "upsert_objects",
 ]