altcodepro-polydb-python 2.5.20__py3-none-any.whl → 2.5.22__py3-none-any.whl

{altcodepro_polydb_python-2.5.20.dist-info → altcodepro_polydb_python-2.5.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.5.20
+Version: 2.5.22
 Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
 Author: AltCodePro
 Project-URL: Homepage, https://github.com/altcodepro/polydb-python

{altcodepro_polydb_python-2.5.20.dist-info → altcodepro_polydb_python-2.5.22.dist-info}/RECORD

@@ -1,12 +1,12 @@
-altcodepro_polydb_python-2.5.20.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
+altcodepro_polydb_python-2.5.22.dist-info/licenses/LICENSE,sha256=9X8GLocsBwy-5aR5JGOt2SAMDDPs9Qv-YnqmHBHOXrw,1067
 polydb/PolyDB.py,sha256=Lp0QtG7D89Z6P6nt9fVoT8rVHAy8xlE2kFRSS70r-mk,23672
-polydb/__init__.py,sha256=fNrKwNBgwMJKrBhs_eaRu4XpQ3olREipIOiwBmv38b8,1876
+polydb/__init__.py,sha256=5nO3ONrpIkzQDi4oka8UgcO4jAWVyAvt9gAmj7mPNdQ,1876
 polydb/advanced_query.py,sha256=M9sKmdF2PsLZWSc-zKpXRcwaDumbYYTsibmL_IAjKP4,6931
 polydb/aio.py,sha256=0EQ6hXrf6N4If6pcht6L9B7qz0PU2yGahyGzEss2eQg,8340
 polydb/batch.py,sha256=ulvSdtVeofsOiVNVAQwrE9tXIIaP8fjiW1Sbpz3dcv0,4093
 polydb/cache.py,sha256=ArI0zRbuhAYd6kn4TPVMBHBptdRmuZyy05_hwIATUsQ,11784
 polydb/cloudDatabaseFactory.py,sha256=eJiNKycdaC9nO2BKWPjkig3GaNGkNjoJci6yVJC7A_c,25301
-polydb/databaseFactory.py,sha256=0gjc5wk0zkOsCqOY7ET8klaNG8wZMPJhKOvzmdYTwr0,59610
+polydb/databaseFactory.py,sha256=_faf37970W9T5z26q5IRuRUiXpnvABBkRX0H_5aV-jo,59746
 polydb/errors.py,sha256=AtXCLdzkHE2ncUaE1P0wH5HmIyW3NXx9KHL-fCejjA4,1832
 polydb/json_safe.py,sha256=jj3ZA6gImGwgTO0dCZVcckjeUHtewa2HP6OA1-u6VZ0,137
 polydb/models.py,sha256=Pq_63FXu1IiTxl-RshZ2vmoe-5m5k6qft-tXpHLn-70,12600
@@ -19,15 +19,15 @@ polydb/registry.py,sha256=RD_elvFXcmhTdCyZDm2f3ej0elxqhArnSJ2aO9k5VCU,2352
 polydb/retry.py,sha256=0rILN3-auuzomOXPveIAvgnhBbtXXGNKvxg6qcRgN4g,4926
 polydb/schema.py,sha256=v3lnD9jUoBippMj2eLNwvmykPygO0nFx806X7cmeb8Q,9840
 polydb/security.py,sha256=IF8Oh6Y6YU9xSjz_pi6lotfJuhIUJgP7cCmpGc8bz6w,20158
-polydb/types.py,sha256=Kx_d9_XJP9UnIbABaVCOcWiBEem_cfUrDwiPc3uaxCY,2825
+polydb/types.py,sha256=UbO5tQ2oPfviszWAvZvhuYv6PMp_WhgPFgUa5tTVgKI,3026
 polydb/utils.py,sha256=YS-BhBpQfQsOf-z_i1zw_kvMYwJ05Zn1S2Xt6K4_2ak,3171
 polydb/validation.py,sha256=DK9-AFndTr0cLodpc3KX0wnABDpw2vPB4H6hp67BJKE,4570
 polydb/adapters/AWSSecretsManagerAdapter.py,sha256=W4B3xhQFcBAlNlwQ4uTgcDmRrOmZr6v-suC4qihTpJw,2747
 polydb/adapters/AzureBlobStorageAdapter.py,sha256=ZTovSC_CVduGnIoIQUUeNxDQlf-IbFDBRzjGDk8U9Io,7084
 polydb/adapters/AzureFileStorageAdapter.py,sha256=VZNprqlBXCuWUgtqClNT-NrQmRf-XFYEiRA2BLbf-Sc,7046
-polydb/adapters/AzureKeyVaultAdapter.py,sha256=7Nizs9qGh6cytbZNgV78f-odOO4Z6sUlwm_HQYqt-pc,2339
+polydb/adapters/AzureKeyVaultAdapter.py,sha256=EtsrxI3X75nORnO0KbvKTVXJfliHd-gt3y9Mo8Npugs,3365
 polydb/adapters/AzureQueueAdapter.py,sha256=1e2HiFvkH1BI_JKS9fgays2J41kOfH6pUPbZDe1wmWA,13658
-polydb/adapters/AzureTableStorageAdapter.py,sha256=u2DsUIMOjYnBX_2G4abaLCjRaVOCORQQnwC4e0XrJ0Q,35567
+polydb/adapters/AzureTableStorageAdapter.py,sha256=W0MU4Q2v9ArlI_wz-8stqGehstPJnPkQr8jz6zNTnV4,39218
 polydb/adapters/BlockchainBlobAdapter.py,sha256=85H3PxiL9rGDtK-sTsW26jOuUQ_SGipLSPu3s-juZRA,3298
 polydb/adapters/BlockchainFileAdapter.py,sha256=lZbRyC18LghZcVh5QyIRP7tCftNF_Ep1FKG0KRkvMmk,8335
 polydb/adapters/BlockchainKVAdapter.py,sha256=pvpiPshDE5Z_IRcSBvBwgAXT--86lgEyIsEUeqcmoE8,5422
@@ -57,18 +57,19 @@ polydb/audit/__init__.py,sha256=VANh47kW5V9gi7anUCZ7LklQ6ofaFRmBKrPVitRxdw0,245
 polydb/audit/context.py,sha256=jbw58vDoslY2mEcS0qUBlEhYg54EoMk4Xcfuq1L3FuY,1945
 polydb/audit/manager.py,sha256=DgBkDcZlf_EotUm-RlKA1CWAoVi3DIUlRCsN4wzsfgc,1237
 polydb/audit/models.py,sha256=XHT-te2XpmdywfakKm1cVH09yi3C9Fa4FaBTZaJ5vqY,7044
-polydb/base/NoSQLKVAdapter.py,sha256=9nG--KZ1Q0-KTc6n_i1nBIGDlSgOVEei0-QhBmqC_tI,17175
+polydb/base/NoSQLKVAdapter.py,sha256=0-yu9yO4DNT1Ya608Lh3J6v3PZ8sCWi5hEuzUUNVUK4,18533
 polydb/base/ObjectStorageAdapter.py,sha256=mr6UMGmAFOBKlJeoyubaUJ7x7BDZMlylqnuggIatEv0,2289
 polydb/base/QueueAdapter.py,sha256=PzTlEuc37TXEnYNdsrrmxzFworbieWBxljDXJ-qq4XQ,8206
 polydb/base/SecretsAdapter.py,sha256=RaWejh21oQji0TdEBa7P5JgD9y6N06M1aCBbLvzTQU0,990
 polydb/base/SharedFilesAdapter.py,sha256=YHoPMZ5T9Bm5S1oStDvIEzGEgxx7TeXqqr74Yt4KRiE,852
 polydb/base/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polydb/base/constraints.py,sha256=meIH7dnqYl1zX5PgAmeggNKWxQbsvz00BtWMi6wrH_8,13269
 polydb/observability/__init__.py,sha256=ZIMx5ODCBZI_FnROJFb11Q9E5kRq0ZcCp6_RmlwG53k,122
 polydb/observability/logging.py,sha256=FWYky-Mg1IhLpwuaKuLIsTROBZc9bI_-AO-y53nvES0,3911
 polydb/services/__init__.py,sha256=Zs3PZbHutgPdPjJatygvtYvKPZMBt1qKSqESbFRPHJs,241
 polydb/services/compliance_service.py,sha256=UMjCbQ4z13-w6pT4RLQpMi_u1zbShEpiz8kawA2WsSU,5075
 polydb/services/security_service.py,sha256=gGo_j9Ca_rgvxS7s6C5JUktugQBj1PV1DXpMnOYAGbI,4992
-altcodepro_polydb_python-2.5.20.dist-info/METADATA,sha256=1UKkHliLCxQix8uakLf4qjXErKRQHzbJnlBZmqYZy3w,15599
-altcodepro_polydb_python-2.5.20.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-altcodepro_polydb_python-2.5.20.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
-altcodepro_polydb_python-2.5.20.dist-info/RECORD,,
+altcodepro_polydb_python-2.5.22.dist-info/METADATA,sha256=26GBAk1iot-WHk6DimfIK7Lzshb77-_xsPPOKg0lWIQ,15599
+altcodepro_polydb_python-2.5.22.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+altcodepro_polydb_python-2.5.22.dist-info/top_level.txt,sha256=WgLFWJoYjUhwvyPxJFl6jYLrVFuBJDX3OABf4ocwk_E,7
+altcodepro_polydb_python-2.5.22.dist-info/RECORD,,

polydb/__init__.py

@@ -4,7 +4,7 @@ PolyDB - Enterprise Cloud-Independent Database Abstraction
 Full LINQ support, field-level audit, cache, soft delete, overflow storage
 """
 
-__version__ = "2.5.20"
+__version__ = "2.5.22"
 
 from .aio import AsyncDatabaseFactory, AsyncPolyDB
 from .audit.context import AuditContext

polydb/adapters/AzureKeyVaultAdapter.py

@@ -19,10 +19,24 @@ class AzureKeyVaultAdapter(SecretsAdapter):
         self._initialize_client()
 
     def _initialize_client(self) -> None:
-        from azure.identity import DefaultAzureCredential
         from azure.keyvault.secrets import SecretClient
 
-        self._client = SecretClient(vault_url=self.vault_url, credential=DefaultAzureCredential())
+        self._client = SecretClient(vault_url=self.vault_url, credential=self._build_credential())
+
+    @staticmethod
+    def _build_credential():
+        """Inside Azure Container Apps / App Service / Functions a managed identity is available
+        (IDENTITY_ENDPOINT / MSI_ENDPOINT). DefaultAzureCredential tries EnvironmentCredential FIRST, and a deployment that
+        also exports AZURE_CLIENT_ID + AZURE_CLIENT_SECRET (for some other purpose) then fails with AADSTS7000232
+        "MSI identity should not use ClientSecretCredential". So when a managed identity exists it goes first
+        (AZURE_CLIENT_ID, if set, names a user-assigned identity); the normal chain stays as the fallback, so local
+        development (az login, environment variables) behaves as before."""
+        from azure.identity import ChainedTokenCredential, DefaultAzureCredential, ManagedIdentityCredential
+
+        if os.getenv("IDENTITY_ENDPOINT") or os.getenv("MSI_ENDPOINT"):
+            client_id = os.getenv("AZURE_CLIENT_ID") or None
+            return ChainedTokenCredential(ManagedIdentityCredential(client_id=client_id), DefaultAzureCredential())
+        return DefaultAzureCredential()
 
     # Key Vault secret names may only contain alphanumerics and dashes --
     # our secret keys (e.g. "tenant-42/stripe/api_key") use slashes, so

polydb/adapters/AzureTableStorageAdapter.py

@@ -40,6 +40,10 @@ _BASE64_RE = re.compile(r"^[A-Za-z0-9+/]*={0,2}$")
 # ensures model isolation across the same table
 _MODEL_FIELD = "__polydb_model__"
 
+
+class _AlreadyExists(Exception):
+    """create_entity found the (PartitionKey, RowKey) taken. Deliberately NOT a NoSQLError so `@retry` does not retry it."""
+
 _CONNECT_TIMEOUT = float(os.getenv("AZURE_TABLE_CONNECT_TIMEOUT", "10"))
 _READ_TIMEOUT = float(os.getenv("AZURE_TABLE_READ_TIMEOUT", "30"))
 _RETRY_TOTAL = int(os.getenv("AZURE_TABLE_RETRY_TOTAL", "3"))
@@ -47,6 +51,59 @@ _RETRY_TOTAL = int(os.getenv("AZURE_TABLE_RETRY_TOTAL", "3"))
 logging.getLogger("azure").setLevel(logging.ERROR)
 
 
+
+def _is_table_missing(exc: BaseException) -> bool:
+    text = f"{type(exc).__name__} {exc}"
+    return "TableNotFound" in text or "The table specified does not exist" in text
+
+
+class _SelfHealingTableClient:
+    """Wraps an Azure TableClient so a table that disappears while the process is running (deleted by hand, a data
+    reset, a restore) is created again and the operation retried once, instead of failing with TableNotFound until
+    the process restarts. Lazy iterators (query_entities / list_entities) are healed only if the failure happens
+    before the first row was produced."""
+
+    _LAZY = ("query_entities", "list_entities")
+
+    def __init__(self, adapter: "AzureTableStorageAdapter", table_name: str, client: Any):
+        self._adapter = adapter
+        self._table_name = table_name
+        self._client = client
+
+    def _heal(self) -> None:
+        self._adapter._ensured_tables.discard(self._table_name)
+        self._adapter._client.create_table_if_not_exists(self._table_name)
+        self._adapter._ensured_tables.add(self._table_name)
+        logger.warning(f"Azure Table {self._table_name} was missing; created it again")
+
+    def __getattr__(self, name: str):
+        target = getattr(self._client, name)
+        if not callable(target):
+            return target
+        if name in self._LAZY:
+            def lazy(*args, **kwargs):
+                produced = False
+                try:
+                    for item in target(*args, **kwargs):
+                        produced = True
+                        yield item
+                except Exception as exc:  # noqa: BLE001
+                    if produced or not _is_table_missing(exc):
+                        raise
+                    self._heal()
+                    yield from getattr(self._client, name)(*args, **kwargs)
+            return lazy
+
+        def call(*args, **kwargs):
+            try:
+                return target(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001
+                if not _is_table_missing(exc):
+                    raise
+                self._heal()
+                return getattr(self._client, name)(*args, **kwargs)
+        return call
+
 class AzureTableStorageAdapter(NoSQLKVAdapter):
     """
     Azure Table Storage adapter with:
@@ -441,17 +498,21 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                 try:
                     self._client.create_table_if_not_exists(table_name)
                     logger.info(f"✅ Azure Table ensured/created: {table_name}")
+                    self._ensured_tables.add(table_name)
                 except Exception as e:
                     msg = str(e)
-                    if "TableAlreadyExists" not in msg and "already exists" not in msg.lower():
-                        logger.warning(f"Could not create table {table_name}: {e}")
-                self._ensured_tables.add(table_name)
+                    if "TableAlreadyExists" in msg or "already exists" in msg.lower():
+                        self._ensured_tables.add(table_name)
+                    else:
+                        # Do NOT remember a failed creation as "ensured": the next call tries again instead of
+                        # failing with TableNotFound for the rest of the process's life.
+                        logger.error(f"Could not create table {table_name}: {e}")
 
             if cached is None:
                 cached = self._client.get_table_client(table_name=table_name)
                 self._table_clients_cache[table_name] = cached
 
-            return cached
+            return _SelfHealingTableClient(self, table_name, cached)
 
     def _restore_overflow_properties(self, entity_dict: JsonDict) -> JsonDict:
         restored = {}
@@ -500,7 +561,9 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
         return restored
 
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
-    def _put_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> JsonDict:
+    def _put_raw(
+        self, model: type, pk: str, rk: str, data: JsonDict, *, _insert_only: bool = False
+    ) -> JsonDict:
         try:
             table_client = self._get_table_client(model)
             safe_pk = self._sanitize_pk_rk(pk)
@@ -575,7 +638,10 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                 else:
                     reference_entity[k] = v
 
-            table_client.upsert_entity(reference_entity)
+            if _insert_only:
+                table_client.create_entity(reference_entity)  # 409 when the key is taken: atomic claim
+            else:
+                table_client.upsert_entity(reference_entity)
 
             restored = self._unpack_entity(model, entity)
             # Mirror the write-side condition above (line ~521): only
@@ -602,11 +668,27 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             return restored
 
         except Exception as e:
+            if _insert_only and (
+                type(e).__name__ == "ResourceExistsError" or "EntityAlreadyExists" in str(e)
+            ):
+                raise _AlreadyExists() from e
             if "PropertyValueTooLarge" in str(e):
                 raise NoSQLError("Azure Table limit exceeded → must use blob overflow") from e
 
             raise NoSQLError(f"Azure Table put failed: {str(e)}")
 
+    def _put_new_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> bool:
+        """Atomic insert-if-absent via Table Storage's `create_entity` (HTTP 409 when the key exists)."""
+        try:
+            self._put_raw(model, pk, rk, data, _insert_only=True)
+            return True
+        except _AlreadyExists:
+            return False
+
+    def _query_partition_raw(self, model: type, partition: str, limit: Optional[int]) -> List[JsonDict]:
+        """One partition -- a PartitionKey filter, not a table scan."""
+        return self._query_raw(model, {"partition_key": partition}, limit)
+
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
     def _get_raw(self, model: type, pk: str, rk: str) -> Optional[JsonDict]:
         try:

polydb/base/NoSQLKVAdapter.py

@@ -12,6 +12,7 @@ from ..json_safe import json_safe
 from ..query import Operator, QueryBuilder
 from ..retry import retry
 from ..types import JsonDict, Lookup
+from .constraints import NoSQLConstraintsMixin, UniqueConstraintError  # noqa: F401  (re-exported)
 
 if TYPE_CHECKING:
     from ..models import PartitionConfig
@@ -46,7 +47,7 @@ def select_columns(
     return None
 
 
-class NoSQLKVAdapter:
+class NoSQLKVAdapter(NoSQLConstraintsMixin):
     """Base with auto-overflow and LINQ support"""
 
     # An adapter sets this True when its `_query_raw` accepts `select=[property names]` and really sends it to the store (Azure
@@ -266,8 +267,16 @@ class NoSQLKVAdapter:
     # Protocol implementation
     def put(self, model: type, data: JsonDict) -> JsonDict:
         pk, rk = self._get_pk_rk(model, data)
-        store_data, _ = self._check_overflow(data)
-        return self._put_raw(model, pk, rk, store_data)
+
+        def _write() -> JsonDict:
+            store_data, _ = self._check_overflow(data)
+            return self._put_raw(model, pk, rk, store_data)
+
+        uq, ix = self._constraint_fields(model)
+        if not (uq or ix):
+            return _write()
+        previous = self._get_raw(model, pk, rk)
+        return self._constrained_write(model, pk, rk, previous, {**(previous or {}), **data}, _write)
 
     def query(
         self,
@@ -279,6 +288,9 @@ class NoSQLKVAdapter:
         fields: Optional[List[str]] = None,
         omit: Optional[List[str]] = None,
     ) -> List[JsonDict]:
+        indexed = self._indexed_query(model, query or {}, limit)
+        if indexed is not None:
+            return project_rows([self._retrieve_overflow(r) for r in indexed], fields, omit)
         select = select_columns(fields, omit, getattr(model, "__polydb__", {}).get("columns"))
         if select is not None and self.SUPPORTS_SELECT_PUSHDOWN:
             results = self._query_raw(model, query or {}, limit, select=select)
@@ -318,15 +330,25 @@ class NoSQLKVAdapter:
         else:
             pk, rk = self._get_pk_rk(model, {"id": entity_id, **data})
 
-        if not replace:
+        uq, ix = self._constraint_fields(model)
+        constrained = bool(uq or ix) and pk is not None
+        previous: Optional[JsonDict] = None
+        if not replace or constrained:
             existing = self._get_raw(model, pk, rk)  # type: ignore
             if existing:
                 existing = self._retrieve_overflow(existing)
-                existing.update(data)
-                data = existing
+                previous = dict(existing)
+                if not replace:
+                    existing.update(data)
+                    data = existing
+
+        def _write() -> JsonDict:
+            store_data, _ = self._check_overflow(data)
+            return self._put_raw(model, pk, rk, store_data)  # type: ignore
 
-        store_data, _ = self._check_overflow(data)
-        return self._put_raw(model, pk, rk, store_data)  # type: ignore
+        if not constrained:
+            return _write()
+        return self._constrained_write(model, pk, rk, previous, data, _write)  # type: ignore[arg-type]
 
     def upsert(self, model: type, data: JsonDict, *, replace: bool = False) -> JsonDict:
         return self.put(model, data)
@@ -340,7 +362,13 @@ class NoSQLKVAdapter:
         else:
             pk, rk = self._get_pk_rk(model, {"id": entity_id})
 
-        return self._delete_raw(model, pk, rk, etag)  # type: ignore
+        uq, ix = self._constraint_fields(model)
+        if not (uq or ix) or pk is None:
+            return self._delete_raw(model, pk, rk, etag)  # type: ignore
+        existing = self._get_raw(model, pk, rk)  # type: ignore
+        result = self._delete_raw(model, pk, rk, etag)  # type: ignore
+        self._release_all(model, pk, rk, existing)
+        return result
 
     def query_linq_rows(self, model: type, builder: QueryBuilder) -> List[JsonDict]:
         """

polydb/base/constraints.py

@@ -0,0 +1,260 @@
+# src/polydb/base/constraints.py
+"""
+Unique constraints and equality lookup indexes for key/value NoSQL stores.
+
+Table Storage (and every other KV backend here) enforces uniqueness only for the (PartitionKey, RowKey) pair and can only be
+queried efficiently by those two keys. A model that declares `unique_fields` / `index_fields` in `__polydb__` gets both from this
+mixin, on every NoSQL adapter, with no per-provider code beyond one primitive (`_put_new_raw`, insert-if-absent).
+
+How it works -- two hidden side tables per model (`<table>uq`, `<table>ix`):
+
+* UNIQUE   one "claim" row per (field, value): PartitionKey = u<2 hex of the hash>, RowKey = sha256(field, value). The claim is
+           written with an INSERT-IF-ABSENT before the entity, so two writers racing for one value cannot both succeed. A
+           duplicate raises UniqueConstraintError. The claim names its owner entity; a claim whose owner no longer exists, or
+           whose owner moved to another value (a crash between the claim and the entity write), is taken over.
+* INDEX    one row per (field, value, entity): PartitionKey = i<hash of (field, value)>, RowKey = hash of the entity key. An
+           equality query on an indexed field reads that one partition, then point-reads each owner and re-checks every filter,
+           so a stale index row can never produce a wrong result (it is skipped).
+
+Ordering: claims and index rows are written BEFORE the entity and removed AFTER a delete / value change, so a visible entity
+always has its rows. The residue of a crash is a stale row, which is harmless (verified on read, taken over on the next claim).
+
+Not covered: rows written before a field was declared have no claim/index row -- run `rebuild_constraints()` once. Backends
+without a native conditional insert fall back to a non-atomic get-then-put (documented on `_put_new_raw`).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..errors import NoSQLError
+from ..types import JsonDict
+
+_UNSAFE_KEY = re.compile(r"[\\/#\?\x00-\x1f\x7f:+ ]")
+_UQ, _IX = "uq", "ix"
+
+
+class UniqueConstraintError(NoSQLError):
+    """A write would create a second row with a value a `unique_fields` field already holds."""
+
+    def __init__(self, field: str, value: Any):
+        super().__init__(f"unique constraint violated on {field!r}")
+        self.field = field
+        self.value = value
+
+
+def normalize_value(value: Any) -> Optional[str]:
+    """The string two values are compared as. None/empty/containers carry no constraint."""
+    if value is None or isinstance(value, (dict, list, tuple, set)):
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    text = str(value)
+    return text if text != "" else None
+
+
+def _digest(*parts: str) -> str:
+    return hashlib.sha256("\x1f".join(parts).encode("utf-8")).hexdigest()
+
+
+class NoSQLConstraintsMixin:
+    """Mixed into NoSQLKVAdapter. Needs `_get_raw`, `_put_raw`, `_delete_raw`, `_query_raw`, `_get_pk_rk`."""
+
+    # -- metadata ---------------------------------------------------------------------------------------------------------
+
+    @staticmethod
+    def _constraint_fields(model: type) -> Tuple[Tuple[str, ...], Tuple[str, ...]]:
+        meta = getattr(model, "__polydb__", None) or {}
+        return tuple(meta.get("unique_fields") or ()), tuple(meta.get("index_fields") or ())
+
+    def _side_model(self, model: type, suffix: str) -> type:
+        cache = self.__dict__.setdefault("_side_models", {})
+        meta = getattr(model, "__polydb__", None) or {}
+        base = meta.get("collection") or meta.get("collection_name") or meta.get("table") or getattr(model, "__name__", "model")
+        base = re.sub(r"[^A-Za-z0-9]", "", str(base)).lower()[:58] or "model"
+        key = (base, suffix)
+        if key not in cache:
+            name = f"{base}{suffix}"
+            cache[key] = type(name, (), {"__polydb__": {"storage": "nosql", "table": name, "pk_field": "bucket", "rk_field": "id"}})
+        return cache[key]
+
+    # -- insert-if-absent primitive ----------------------------------------------------------------------------------------
+
+    def _put_new_raw(self, model: type, pk: str, rk: str, data: JsonDict) -> bool:
+        """Insert only when (pk, rk) is absent. True = inserted, False = already there. This default is get-then-put and is NOT
+        atomic; an adapter with a native conditional create (Azure `create_entity`, Dynamo `attribute_not_exists`, ...) overrides."""
+        if self._get_raw(model, pk, rk) is not None:  # type: ignore[attr-defined]
+            return False
+        self._put_raw(model, pk, rk, data)  # type: ignore[attr-defined]
+        return True
+
+    def _query_partition_raw(self, model: type, partition: str, limit: Optional[int]) -> List[JsonDict]:
+        """Every row of one partition. Portable default: a property equality on the mirrored `ix_bucket` field."""
+        return self._query_raw(model, {"ix_bucket": partition}, limit)  # type: ignore[attr-defined]
+
+    # -- side-row helpers --------------------------------------------------------------------------------------------------
+
+    def _safe_delete(self, model: type, pk: str, rk: str) -> None:
+        try:
+            self._delete_raw(model, pk, rk, None)  # type: ignore[attr-defined]
+        except Exception:  # already gone, or the row was never written
+            pass
+
+    def _claim(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _UQ)
+        h = _digest(field, value)
+        spk = f"u{h[:2]}"
+        row = {"bucket": spk, "ix_bucket": spk, "id": h, "field": field, "owner_pk": pk, "owner_rk": rk}
+        for _ in range(4):
+            if self._put_new_raw(side, spk, h, row):
+                return
+            cur = self._get_raw(side, spk, h)  # type: ignore[attr-defined]
+            if cur is None:  # released between our insert and our read
+                continue
+            if (cur.get("owner_pk"), cur.get("owner_rk")) == (pk, rk):
+                return  # our own claim (an idempotent retry)
+            owner = self._get_raw(model, cur.get("owner_pk"), cur.get("owner_rk"))  # type: ignore[attr-defined]
+            if owner is not None and normalize_value(owner.get(field)) == value:
+                raise UniqueConstraintError(field, value)
+            self._safe_delete(side, spk, h)  # orphaned or moved-on claim: take it over
+        raise UniqueConstraintError(field, value)
+
+    def _release(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _UQ)
+        h = _digest(field, value)
+        spk = f"u{h[:2]}"
+        cur = self._get_raw(side, spk, h)  # type: ignore[attr-defined]
+        if cur is not None and (cur.get("owner_pk"), cur.get("owner_rk")) == (pk, rk):
+            self._safe_delete(side, spk, h)
+
+    def _index_key(self, field: str, value: str, pk: str, rk: str) -> Tuple[str, str]:
+        return f"i{_digest(field, value)}", _digest(str(pk), str(rk))
+
+    def _index_put(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        side = self._side_model(model, _IX)
+        spk, srk = self._index_key(field, value, pk, rk)
+        row = {"bucket": spk, "ix_bucket": spk, "id": srk, "field": field, "owner_pk": pk, "owner_rk": rk}
+        self._put_raw(side, spk, srk, row)  # type: ignore[attr-defined]
+
+    def _index_del(self, model: type, pk: str, rk: str, field: str, value: str) -> None:
+        spk, srk = self._index_key(field, value, pk, rk)
+        self._safe_delete(self._side_model(model, _IX), spk, srk)
+
+    # -- write path --------------------------------------------------------------------------------------------------------
+
+    def _constrained_write(self, model: type, pk: str, rk: str, previous: Optional[JsonDict], new: JsonDict, write):
+        """Claim -> index -> entity write -> release/remove the old rows. `new` is the row as it will exist afterwards."""
+        uq, ix = self._constraint_fields(model)
+        prev = previous or {}
+        claimed: List[Tuple[str, str]] = []
+        try:
+            for f in uq:
+                nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+                if nv is not None and nv != ov:
+                    self._claim(model, pk, rk, f, nv)
+                    claimed.append((f, nv))
+            for f in ix:
+                nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+                if nv is not None and nv != ov:
+                    self._index_put(model, pk, rk, f, nv)
+            result = write()
+        except Exception:
+            for f, v in claimed:
+                self._release(model, pk, rk, f, v)
+            raise
+        for f in uq:
+            nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+            if ov is not None and ov != nv:
+                self._release(model, pk, rk, f, ov)
+        for f in ix:
+            nv, ov = normalize_value(new.get(f)), normalize_value(prev.get(f))
+            if ov is not None and ov != nv:
+                self._index_del(model, pk, rk, f, ov)
+        return result
+
+    def _release_all(self, model: type, pk: str, rk: str, row: Optional[JsonDict]) -> None:
+        if not row:
+            return
+        uq, ix = self._constraint_fields(model)
+        for f in uq:
+            v = normalize_value(row.get(f))
+            if v is not None:
+                self._release(model, pk, rk, f, v)
+        for f in ix:
+            v = normalize_value(row.get(f))
+            if v is not None:
+                self._index_del(model, pk, rk, f, v)
+
+    # -- read path ---------------------------------------------------------------------------------------------------------
+
+    def _lookup_owners(self, model: type, field: str, value: str, limit: Optional[int]) -> List[Tuple[str, str]]:
+        uq, _ = self._constraint_fields(model)
+        h = _digest(field, value)
+        if field in uq:
+            cur = self._get_raw(self._side_model(model, _UQ), f"u{h[:2]}", h)  # type: ignore[attr-defined]
+            return [(cur["owner_pk"], cur["owner_rk"])] if cur else []
+        rows = self._query_partition_raw(self._side_model(model, _IX), f"i{h}", limit)
+        return [(r["owner_pk"], r["owner_rk"]) for r in rows if r.get("owner_pk") is not None]
+
+    @staticmethod
+    def _filter_matches(row: JsonDict, query: Dict[str, Any], pk: str, rk: str) -> bool:
+        for k, want in query.items():
+            if k in ("partition_key", "PartitionKey"):
+                if _UNSAFE_KEY.sub("_", str(pk)) != str(want):
+                    return False
+            elif k in ("row_key", "RowKey"):
+                if _UNSAFE_KEY.sub("_", str(rk)) != str(want):
+                    return False
+            elif want is None:
+                if row.get(k) is not None:
+                    return False
+            elif normalize_value(row.get(k)) != normalize_value(want):
+                return False
+        return True
+
+    def _indexed_query(self, model: type, query: Dict[str, Any], limit: Optional[int]) -> Optional[List[JsonDict]]:
+        """Rows for a query that has an equality on a unique/indexed field, or None when the index cannot serve it."""
+        uq, ix = self._constraint_fields(model)
+        if not query or not (uq or ix):
+            return None
+        if any(isinstance(v, (dict, list, tuple, set)) for v in query.values()):
+            return None
+        for f in (*uq, *ix):
+            nv = normalize_value(query.get(f)) if f in query else None
+            if nv is None:
+                continue
+            out: List[JsonDict] = []
+            for opk, ork in self._lookup_owners(model, f, nv, None):
+                row = self._get_raw(model, opk, ork)  # type: ignore[attr-defined]
+                if row is not None and self._filter_matches(row, query, opk, ork):
+                    out.append(row)
+                    if limit and len(out) >= limit:
+                        break
+            return out
+        return None
+
+    def rebuild_constraints(self, model: type) -> Dict[str, int]:
+        """One-off backfill for rows written before a field was declared unique/indexed. Claims every existing value (the
+        first holder keeps it; a duplicate is reported, not overwritten) and writes every index row."""
+        uq, ix = self._constraint_fields(model)
+        done = {"rows": 0, "claims": 0, "indexed": 0, "duplicates": 0}
+        for row in self._query_raw(model, {}, None):  # type: ignore[attr-defined]
+            pk, rk = self._get_pk_rk(model, row)  # type: ignore[attr-defined]
+            done["rows"] += 1
+            for f in uq:
+                v = normalize_value(row.get(f))
+                if v is None:
+                    continue
+                try:
+                    self._claim(model, pk, rk, f, v)
+                    done["claims"] += 1
+                except UniqueConstraintError:
+                    done["duplicates"] += 1
+            for f in ix:
+                v = normalize_value(row.get(f))
+                if v is not None:
+                    self._index_put(model, pk, rk, f, v)
+                    done["indexed"] += 1
+        return done

polydb/databaseFactory.py

@@ -167,6 +167,8 @@ def _extract_meta(model: Union[type, str]) -> ModelMeta:
                 cache=raw.get("cache", False),
                 cache_ttl=raw.get("cache_ttl"),
                 encrypted_fields=tuple(raw.get("encrypted_fields") or ()),
+                unique_fields=tuple(raw.get("unique_fields") or ()),
+                index_fields=tuple(raw.get("index_fields") or ()),
             )
     return ModelMeta(storage="nosql", table=None, collection=None)
 

polydb/types.py

@@ -26,6 +26,9 @@ class ModelMeta:
     cache_ttl: Optional[int] = None
     # Fields stored encrypted when the factory has encryption enabled (a tuple: the dataclass is frozen/hashable).
     encrypted_fields: Tuple[str, ...] = ()
+    # NoSQL: fields that must stay unique across the model / that get an equality lookup index (see base/constraints.py).
+    unique_fields: Tuple[str, ...] = ()
+    index_fields: Tuple[str, ...] = ()
 
 
 @runtime_checkable