velocity-python 0.1.37__tar.gz → 0.1.38__tar.gz

{velocity_python-0.1.37/src/velocity_python.egg-info → velocity_python-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.37
+Version: 0.1.38
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.37 → velocity_python-0.1.38}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.37"
+version = "0.1.38"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.37 → velocity_python-0.1.38}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.37"
+__version__ = version = "0.1.38"
 
 import importlib as _importlib
 

{velocity_python-0.1.37 → velocity_python-0.1.38}/src/velocity/db/core/decorators.py

@@ -1,6 +1,7 @@
 import logging
 import time
 import random
+from collections.abc import Mapping, Sequence
 from functools import wraps
 from velocity.db import exceptions
 
@@ -148,6 +149,73 @@ def return_default(
     return decorator
 
 
+def _merge_schema_seed(target, value):
+    """Collect representative columns from dict payloads or lists of dict rows."""
+
+    if isinstance(value, Mapping):
+        for key, val in value.items():
+            if isinstance(key, str) and key not in target:
+                target[key] = val
+        return
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        for item in value:
+            if isinstance(item, Mapping):
+                _merge_schema_seed(target, item)
+
+
+def _collect_schema_seed(args, kwds):
+    data = {}
+
+    for key in ("pk", "data"):
+        _merge_schema_seed(data, kwds.get(key))
+
+    for arg in args:
+        _merge_schema_seed(data, arg)
+
+    return data
+
+
+def _normalize_conflict_columns(pk):
+    if pk is None:
+        return []
+    if isinstance(pk, str):
+        return [pk]
+    if isinstance(pk, Mapping):
+        return [str(key) for key in pk.keys()]
+    if isinstance(pk, Sequence) and not isinstance(pk, (str, bytes, bytearray)):
+        return [str(column) for column in pk]
+
+    try:
+        return [str(column) for column in pk]
+    except TypeError:
+        return [str(pk)]
+
+
+def _infer_conflict_columns(func, args, kwds):
+    """Infer explicit ON CONFLICT columns for upsert operations."""
+
+    if func.__name__ not in {"merge", "upsert_many"}:
+        return []
+
+    pk = kwds.get("pk")
+    if pk is None and len(args) >= 2:
+        pk = args[1]
+
+    columns = [column.lower() for column in _normalize_conflict_columns(pk) if column]
+    if len(columns) == 1 and columns[0] == "sys_id":
+        return []
+    return columns
+
+
+def _missing_conflict_constraint_error(exc):
+    message = str(exc or "").lower()
+    return (
+        "no unique or exclusion constraint matching the on conflict specification"
+        in message
+    )
+
+
 def create_missing(func):
     """
     If the function call fails with DbColumnMissingError or DbTableMissingError,
@@ -161,6 +229,8 @@ def create_missing(func):
 
     @wraps(func)
     def wrapper(self, *args, **kwds):
+        conflict_columns = _infer_conflict_columns(func, args, kwds)
+
         sp = self.tx.create_savepoint(cursor=self.cursor())
         try:
             result = func(self, *args, **kwds)
@@ -181,14 +251,7 @@ def create_missing(func):
                 ) from e
 
             # Existing logic for automatic creation
-            data = {}
-            if "pk" in kwds:
-                data.update(kwds["pk"])
-            if "data" in kwds:
-                data.update(kwds["data"])
-            for i, arg in enumerate(args):
-                if isinstance(arg, dict):
-                    data.update(arg)
+            data = _collect_schema_seed(args, kwds)
 
             # ALTER TABLE ADD COLUMN IF NOT EXISTS — acquire an advisory
             # lock to serialize DDL across concurrent Lambda containers,
@@ -220,15 +283,7 @@ def create_missing(func):
                 ) from e
 
             # Existing logic for automatic creation
-            data = {}
-            if "pk" in kwds:
-                data.update(kwds["pk"])
-            if "data" in kwds:
-                data.update(kwds["data"])
-            for i, arg in enumerate(args):
-                if isinstance(arg, dict):
-                    data.update(arg)
-
+            data = _collect_schema_seed(args, kwds)
             # CREATE TABLE IF NOT EXISTS — acquire advisory lock then
             # guard against concurrent creation with a savepoint.
             try:
@@ -242,6 +297,37 @@ def create_missing(func):
             except exceptions.DbObjectExistsError:
                 self.tx.rollback_savepoint(sp2, cursor=self.cursor())
 
+            if conflict_columns:
+                self.create_index(conflict_columns, unique=True)
+
+            return func(self, *args, **kwds)
+        except exceptions.DbException as e:
+            self.tx.rollback_savepoint(sp, cursor=self.cursor())
+
+            if not conflict_columns or not _missing_conflict_constraint_error(e):
+                raise
+
+            if self.tx.engine.schema_locked:
+                logger.warning(
+                    "@create_missing triggered on locked schema: table=%s error=%s",
+                    self.name, e,
+                    extra={
+                        "table_name": self.name,
+                        "operation": "create_missing_conflict_index",
+                        "schema_locked": True,
+                    },
+                )
+                raise exceptions.DbSchemaLockedError(
+                    "Cannot create missing unique index: schema is locked. "
+                    f"Original error: {e}"
+                ) from e
+
+            try:
+                self.tx.advisory_lock(f"velocity_ddl_{self.name}")
+            except Exception:
+                pass
+
+            self.create_index(conflict_columns, unique=True)
             return func(self, *args, **kwds)
 
     return wrapper

{velocity_python-0.1.37 → velocity_python-0.1.38}/src/velocity/db/core/table.py

@@ -2,7 +2,8 @@ import logging
 import re
 import warnings
 import sqlparse
-from collections.abc import Iterable, Mapping
+from collections import defaultdict
+from collections.abc import Iterable, Mapping, Sequence
 from velocity.db import exceptions
 from velocity.db.core.row import Row
 from velocity.db.core.result import Result
@@ -150,6 +151,198 @@ def _parse_column_spec(spec, default_nullable):
     }
 
 
+def _normalize_identifier(value):
+    return str(value or "").strip().strip('"').lower()
+
+
+def _split_sql_expressions(text):
+    expressions = []
+    current = []
+    depth = 0
+
+    for char in str(text or ""):
+        if char == "(":
+            depth += 1
+        elif char == ")" and depth > 0:
+            depth -= 1
+
+        if char == "," and depth == 0:
+            expression = "".join(current).strip()
+            if expression:
+                expressions.append(expression)
+            current = []
+            continue
+
+        current.append(char)
+
+    tail = "".join(current).strip()
+    if tail:
+        expressions.append(tail)
+
+    return expressions
+
+
+def _extract_parenthesized(text, start_index):
+    depth = 0
+    current = []
+
+    for index in range(start_index, len(text)):
+        char = text[index]
+        if char == "(":
+            if depth > 0:
+                current.append(char)
+            depth += 1
+            continue
+        if char == ")":
+            depth -= 1
+            if depth == 0:
+                return "".join(current), index
+            current.append(char)
+            continue
+        if depth > 0:
+            current.append(char)
+
+    raise ValueError(f"Unbalanced parentheses in SQL fragment: {text}")
+
+
+def _normalize_index_expression(expression):
+    normalized = str(expression or "").strip().replace('"', "")
+    normalized = re.sub(r"::[a-zA-Z0-9_\[\]\s\.]+", "", normalized)
+    normalized = re.sub(r"\s+", " ", normalized)
+    normalized = re.sub(r"\(\s+", "(", normalized)
+    normalized = re.sub(r"\s+\)", ")", normalized)
+    return normalized.strip().lower()
+
+
+def _parse_index_signature(index_sql):
+    normalized_sql = " ".join(str(index_sql or "").split())
+    upper_sql = normalized_sql.upper()
+
+    name_match = re.search(
+        r"CREATE(?:\s+UNIQUE)?\s+INDEX\s+([^\s]+)\s+ON\s+",
+        normalized_sql,
+        flags=re.IGNORECASE,
+    )
+    index_name = _normalize_identifier(name_match.group(1)) if name_match else None
+
+    on_pos = upper_sql.find(" ON ")
+    if on_pos == -1:
+        raise ValueError(f"Unable to parse index definition: {index_sql}")
+
+    open_paren = normalized_sql.find("(", on_pos)
+    if open_paren == -1:
+        raise ValueError(f"Unable to parse index columns: {index_sql}")
+
+    columns_text, closing_index = _extract_parenthesized(normalized_sql, open_paren)
+    where_clause = None
+    where_pos = upper_sql.find(" WHERE ", closing_index)
+    if where_pos != -1:
+        where_clause = _normalize_index_expression(normalized_sql[where_pos + 7 :])
+
+    return {
+        "name": index_name,
+        "unique": "CREATE UNIQUE INDEX" in upper_sql,
+        "columns": tuple(
+            _normalize_index_expression(expression)
+            for expression in _split_sql_expressions(columns_text)
+        ),
+        "where": where_clause,
+    }
+
+
+def _normalize_index_specs(indexes, *, unique_default=False):
+    if indexes is None:
+        return []
+
+    if isinstance(indexes, (str, bytes, Mapping)):
+        indexes = [indexes]
+
+    normalized = []
+    for definition in indexes:
+        if isinstance(definition, Mapping):
+            columns = definition.get("columns")
+            if not columns:
+                raise ValueError("Index definition requires non-empty columns")
+            unique = bool(definition.get("unique", unique_default))
+            direction = definition.get("direction")
+            where = definition.get("where")
+            lower = definition.get("lower")
+        else:
+            columns = definition
+            unique = unique_default
+            direction = None
+            where = None
+            lower = None
+
+        if isinstance(columns, str):
+            columns = [column.strip() for column in columns.split(",") if column.strip()]
+        elif isinstance(columns, Sequence):
+            columns = list(columns)
+        else:
+            columns = [columns]
+
+        normalized.append(
+            {
+                "columns": [_normalize_identifier(column) for column in columns],
+                "unique": unique,
+                "direction": direction,
+                "where": where,
+                "lower": lower,
+            }
+        )
+
+    return normalized
+
+
+def _normalize_foreign_key_specs(foreign_keys):
+    if foreign_keys is None:
+        return []
+
+    if isinstance(foreign_keys, Mapping):
+        foreign_keys = [foreign_keys]
+
+    normalized = []
+    for definition in foreign_keys:
+        if not isinstance(definition, Mapping):
+            raise TypeError("foreign_keys entries must be mappings")
+
+        columns = definition.get("columns") or definition.get("column")
+        if not columns:
+            raise ValueError("Foreign key definition requires columns")
+
+        ref_table = definition.get("ref_table") or definition.get("key_to_table")
+        if not ref_table:
+            raise ValueError("Foreign key definition requires ref_table")
+
+        ref_columns = definition.get("ref_columns") or definition.get("key_to_columns") or "sys_id"
+
+        if isinstance(columns, str):
+            columns = [column.strip() for column in columns.split(",") if column.strip()]
+        elif isinstance(columns, Sequence):
+            columns = list(columns)
+        else:
+            columns = [columns]
+
+        if isinstance(ref_columns, str):
+            ref_columns = [column.strip() for column in ref_columns.split(",") if column.strip()]
+        elif isinstance(ref_columns, Sequence):
+            ref_columns = list(ref_columns)
+        else:
+            ref_columns = [ref_columns]
+
+        normalized.append(
+            {
+                "columns": tuple(_normalize_identifier(column) for column in columns),
+                "ref_table": _normalize_identifier(ref_table),
+                "ref_columns": tuple(
+                    _normalize_identifier(column) for column in ref_columns
+                ),
+            }
+        )
+
+    return normalized
+
+
 class Table:
     SYSTEM_COLUMNS = SYSTEM_COLUMN_NAMES
 
@@ -343,6 +536,288 @@ class Table:
         _ddl_logger.warning("DDL CREATE TABLE %s columns=%s drop=%s", self.name, list(columns.keys()), drop)
         self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def _ensure_schema_unlocked(self, operation):
+        if self.tx.engine.schema_locked:
+            raise exceptions.DbSchemaLockedError(
+                f"Cannot {operation}: schema is locked for table '{self.name}'."
+            )
+
+    def _existing_index_signatures(self):
+        signatures = []
+        for name, _table_name, _schema_name, indexdef in self.indexes().as_tuple().all():
+            signature = _parse_index_signature(indexdef)
+            signature["name"] = _normalize_identifier(name)
+            signature["sql"] = indexdef
+            signatures.append(signature)
+        return signatures
+
+    def _desired_index_signature(self, spec):
+        sql, _vals = self.create_index(
+            spec["columns"],
+            unique=spec["unique"],
+            direction=spec["direction"],
+            where=spec["where"],
+            lower=spec["lower"],
+            sql_only=True,
+        )
+        return _parse_index_signature(sql)
+
+    def _existing_foreign_key_signatures(self):
+        sql, vals = self.sql.foreign_key_info(table=self.name, column=None)
+        rows = self.tx.execute(sql, vals, cursor=self.cursor()).as_dict().all()
+        grouped = defaultdict(list)
+        for row in rows:
+            grouped[_normalize_identifier(row["fk_constraint_name"])].append(row)
+
+        signatures = []
+        for constraint_name, constraint_rows in grouped.items():
+            ordered = sorted(
+                constraint_rows,
+                key=lambda item: item.get("fk_ordinal_position") or 0,
+            )
+            first = ordered[0]
+            ref_schema = _normalize_identifier(first.get("referenced_table_schema"))
+            ref_table = _normalize_identifier(first.get("referenced_table_name"))
+            full_ref_table = (
+                f"{ref_schema}.{ref_table}"
+                if ref_schema and ref_schema not in {"public", ""}
+                else ref_table
+            )
+            signatures.append(
+                {
+                    "constraint_name": constraint_name,
+                    "columns": tuple(
+                        _normalize_identifier(item["fk_column_name"]) for item in ordered
+                    ),
+                    "ref_table": full_ref_table,
+                    "ref_columns": tuple(
+                        _normalize_identifier(item["referenced_column_name"])
+                        for item in ordered
+                    ),
+                }
+            )
+        return signatures
+
+    def ensure_schema(
+        self,
+        columns=None,
+        unique_indexes=None,
+        indexes=None,
+        foreign_keys=None,
+        create_missing=True,
+        alter_missing_columns=True,
+        create_missing_indexes=True,
+        create_missing_foreign_keys=False,
+        ensure_system_columns=False,
+        on_existing_conflicts="raise",
+    ):
+        """Create or align safe schema objects for this table.
+
+        This is an idempotent helper intended for deploy-time or startup schema
+        sync. By default it will create missing tables, add missing columns, and
+        create declared indexes. It does not drop objects or rewrite existing
+        column types implicitly.
+        """
+
+        if on_existing_conflicts not in {"raise", "ignore"}:
+            raise ValueError(
+                "on_existing_conflicts must be either 'raise' or 'ignore'."
+            )
+
+        if columns is not None and not isinstance(columns, Mapping):
+            raise TypeError("columns must be a mapping when provided.")
+
+        normalized_columns = self.lower_keys(columns or {})
+        normalized_indexes = _normalize_index_specs(indexes)
+        normalized_unique_indexes = _normalize_index_specs(
+            unique_indexes, unique_default=True
+        )
+        normalized_foreign_keys = _normalize_foreign_key_specs(foreign_keys)
+
+        summary = {
+            "created_table": False,
+            "added_columns": [],
+            "created_indexes": [],
+            "skipped_indexes": [],
+            "created_foreign_keys": [],
+            "skipped_foreign_keys": [],
+            "ensured_system_columns": False,
+        }
+
+        table_exists = self.exists()
+        if not table_exists:
+            if not create_missing:
+                raise exceptions.DbTableMissingError(
+                    f"Table '{self.name}' does not exist and create_missing=False."
+                )
+            self._ensure_schema_unlocked("create missing table")
+            self.create(normalized_columns)
+            table_exists = True
+            summary["created_table"] = True
+
+        existing_columns = {column.lower() for column in self.sys_columns()}
+        if normalized_columns and alter_missing_columns:
+            missing_columns = {
+                key: value
+                for key, value in normalized_columns.items()
+                if key.lower() not in existing_columns
+            }
+            if missing_columns:
+                self._ensure_schema_unlocked("add missing columns")
+                self.alter(missing_columns, mode="add")
+                summary["added_columns"] = list(missing_columns.keys())
+                existing_columns.update(missing_columns.keys())
+
+        if ensure_system_columns:
+            required_system_columns = {name.lower() for name in self.SYSTEM_COLUMNS}
+            if not required_system_columns.issubset(existing_columns):
+                self._ensure_schema_unlocked("ensure system columns")
+            self.ensure_system_columns()
+            summary["ensured_system_columns"] = True
+
+        existing_indexes = self._existing_index_signatures()
+        index_specs = normalized_unique_indexes + normalized_indexes
+        for spec in index_specs:
+            desired_signature = self._desired_index_signature(spec)
+            exact_match = next(
+                (
+                    existing
+                    for existing in existing_indexes
+                    if existing["unique"] == desired_signature["unique"]
+                    and existing["columns"] == desired_signature["columns"]
+                    and existing["where"] == desired_signature["where"]
+                ),
+                None,
+            )
+            if exact_match:
+                continue
+
+            name_conflict = next(
+                (
+                    existing
+                    for existing in existing_indexes
+                    if existing["name"] == desired_signature["name"]
+                ),
+                None,
+            )
+            if name_conflict:
+                message = (
+                    f"Index '{desired_signature['name']}' on table '{self.name}' exists "
+                    "with a different definition."
+                )
+                if on_existing_conflicts == "raise":
+                    raise exceptions.DbSchemaConflictError(message)
+                summary["skipped_indexes"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "reason": message,
+                    }
+                )
+                continue
+
+            if not create_missing_indexes:
+                summary["skipped_indexes"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "reason": "create_missing_indexes is disabled",
+                    }
+                )
+                continue
+
+            self._ensure_schema_unlocked("create missing indexes")
+            try:
+                self.create_index(
+                    spec["columns"],
+                    unique=spec["unique"],
+                    direction=spec["direction"],
+                    where=spec["where"],
+                    lower=spec["lower"],
+                )
+                summary["created_indexes"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "unique": spec["unique"],
+                    }
+                )
+                existing_indexes = self._existing_index_signatures()
+            except exceptions.DbDuplicateKeyError as exc:
+                message = (
+                    f"Cannot create unique index on table '{self.name}' for columns "
+                    f"{spec['columns']}: existing rows violate uniqueness."
+                )
+                if on_existing_conflicts == "raise":
+                    raise exceptions.DbSchemaConflictError(message) from exc
+                summary["skipped_indexes"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "reason": message,
+                    }
+                )
+
+        existing_foreign_keys = self._existing_foreign_key_signatures()
+        for spec in normalized_foreign_keys:
+            exact_match = next(
+                (
+                    existing
+                    for existing in existing_foreign_keys
+                    if existing["columns"] == spec["columns"]
+                    and existing["ref_table"] == spec["ref_table"]
+                    and existing["ref_columns"] == spec["ref_columns"]
+                ),
+                None,
+            )
+            if exact_match:
+                continue
+
+            column_conflict = next(
+                (
+                    existing
+                    for existing in existing_foreign_keys
+                    if existing["columns"] == spec["columns"]
+                ),
+                None,
+            )
+            if column_conflict:
+                message = (
+                    f"Foreign key on table '{self.name}' for columns {spec['columns']} "
+                    "exists with a different target."
+                )
+                if on_existing_conflicts == "raise":
+                    raise exceptions.DbSchemaConflictError(message)
+                summary["skipped_foreign_keys"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "reason": message,
+                    }
+                )
+                continue
+
+            if not create_missing_foreign_keys:
+                summary["skipped_foreign_keys"].append(
+                    {
+                        "columns": list(spec["columns"]),
+                        "reason": "create_missing_foreign_keys is disabled",
+                    }
+                )
+                continue
+
+            self._ensure_schema_unlocked("create missing foreign keys")
+            self.create_foreign_key(
+                list(spec["columns"]),
+                spec["ref_table"],
+                list(spec["ref_columns"]),
+            )
+            summary["created_foreign_keys"].append(
+                {
+                    "columns": list(spec["columns"]),
+                    "ref_table": spec["ref_table"],
+                    "ref_columns": list(spec["ref_columns"]),
+                }
+            )
+            existing_foreign_keys = self._existing_foreign_key_signatures()
+
+        return summary
+
     def drop(self):
         """
         Drops this table if it exists.

{velocity_python-0.1.37 → velocity_python-0.1.38}/src/velocity/db/exceptions.py

@@ -99,6 +99,12 @@ class DbSchemaLockedError(DbApplicationError):
     pass
 
 
+class DbSchemaConflictError(DbApplicationError):
+    """Raised when declared schema cannot be reconciled safely."""
+
+    pass
+
+
 class DuplicateRowsFoundError(Exception):
     """Multiple rows found when expecting single result."""
 
@@ -132,5 +138,6 @@ __all__ = [
     "DbQueryError",
     "DbTransactionError",
     "DbSchemaLockedError",
+    "DbSchemaConflictError",
     "DuplicateRowsFoundError",
 ]