plain.models 0.35.0__tar.gz → 0.37.0__tar.gz

{plain_models-0.35.0 → plain_models-0.37.0}/.gitignore

@@ -4,7 +4,6 @@
 *.py[co]
 __pycache__
 *.DS_Store
-.coverage
 
 # Test apps
 plain*/tests/.plain
@@ -17,4 +16,4 @@ plain*/tests/.plain
 # Plain temp dirs
 .plain
 
-coverage.xml
+.vscode

{plain_models-0.35.0 → plain_models-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.models
-Version: 0.35.0
+Version: 0.37.0
 Summary: Database models for Plain.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/CHANGELOG.md

@@ -1,5 +1,27 @@
 # plain-models changelog
 
+## [0.37.0](https://github.com/dropseed/plain/releases/plain-models@0.37.0) (2025-07-18)
+
+### What's changed
+
+- Added OpenTelemetry instrumentation for database operations - all SQL queries now automatically generate OpenTelemetry spans with standardized attributes following semantic conventions ([b0224d0](https://github.com/dropseed/plain/commit/b0224d0))
+- Database operations in tests are now wrapped with tracing suppression to avoid generating telemetry noise during test execution ([b0224d0](https://github.com/dropseed/plain/commit/b0224d0))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.36.0](https://github.com/dropseed/plain/releases/plain-models@0.36.0) (2025-07-18)
+
+### What's changed
+
+- Removed the `--merge` option from the `makemigrations` command ([d366663](https://github.com/dropseed/plain/commit/d366663))
+- Improved error handling in the `restore-backup` command using Click's error system ([88f06c5](https://github.com/dropseed/plain/commit/88f06c5))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.35.0](https://github.com/dropseed/plain/releases/plain-models@0.35.0) (2025-07-07)
 
 ### What's changed

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/backends/utils.py

@@ -7,6 +7,7 @@ from contextlib import contextmanager
 from hashlib import md5
 
 from plain.models.db import NotSupportedError
+from plain.models.otel import db_span
 from plain.utils.dateparse import parse_time
 
 logger = logging.getLogger("plain.models.backends")
@@ -80,18 +81,20 @@ class CursorWrapper:
         return executor(sql, params, many, context)
 
     def _execute(self, sql, params, *ignored_wrapper_args):
-        self.db.validate_no_broken_transaction()
-        with self.db.wrap_database_errors:
-            if params is None:
-                # params default might be backend specific.
-                return self.cursor.execute(sql)
-            else:
-                return self.cursor.execute(sql, params)
+        # Wrap in an OpenTelemetry span with standard attributes.
+        with db_span(self.db, sql, params=params):
+            self.db.validate_no_broken_transaction()
+            with self.db.wrap_database_errors:
+                if params is None:
+                    return self.cursor.execute(sql)
+                else:
+                    return self.cursor.execute(sql, params)
 
     def _executemany(self, sql, param_list, *ignored_wrapper_args):
-        self.db.validate_no_broken_transaction()
-        with self.db.wrap_database_errors:
-            return self.cursor.executemany(sql, param_list)
+        with db_span(self.db, sql, many=True, params=param_list):
+            self.db.validate_no_broken_transaction()
+            with self.db.wrap_database_errors:
+                return self.cursor.executemany(sql, param_list)
 
 
 class CursorDebugWrapper(CursorWrapper):

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/backups/cli.py

@@ -66,12 +66,10 @@ def restore_backup(backup_name, latest, pg_restore):
     backups_handler = DatabaseBackups()
 
     if backup_name and latest:
-        click.secho("Only one of --latest or backup_name is allowed", fg="red")
-        exit(1)
+        raise click.UsageError("Only one of --latest or backup_name is allowed")
 
     if not backup_name and not latest:
-        click.secho("Backup name or --latest is required", fg="red")
-        exit(1)
+        raise click.UsageError("Backup name or --latest is required")
 
     if not backup_name and latest:
         backup_name = backups_handler.find_backups()[0].name

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/cli.py

@@ -2,7 +2,6 @@ import os
 import subprocess
 import sys
 import time
-from itertools import takewhile
 
 import click
 
@@ -22,12 +21,10 @@ from .migrations.migration import Migration, SettingsTuple
 from .migrations.optimizer import MigrationOptimizer
 from .migrations.questioner import (
     InteractiveMigrationQuestioner,
-    MigrationQuestioner,
     NonInteractiveMigrationQuestioner,
 )
 from .migrations.recorder import MigrationRecorder
 from .migrations.state import ModelState, ProjectState
-from .migrations.utils import get_migration_name_timestamp
 from .migrations.writer import MigrationWriter
 from .registry import models_registry
 
@@ -92,7 +89,7 @@ def db_wait():
                 )
             time.sleep(1.5)
         else:
-            click.secho("Database ready", fg="green")
+            click.secho("✔ Database ready", fg="green")
             break
 
 
@@ -135,7 +132,6 @@ def list_models(package_labels, app_only):
     is_flag=True,
     help="Just show what migrations would be made; don't actually write them.",
 )
-@click.option("--merge", is_flag=True, help="Enable fixing of migration conflicts.")
 @click.option("--empty", is_flag=True, help="Create an empty migration.")
 @click.option(
     "--noinput",
@@ -157,9 +153,7 @@ def list_models(package_labels, app_only):
     default=1,
     help="Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output",
 )
-def makemigrations(
-    package_labels, dry_run, merge, empty, no_input, name, check, verbosity
-):
+def makemigrations(package_labels, dry_run, empty, no_input, name, check, verbosity):
     """Creates new migration(s) for packages."""
 
     written_files = []
@@ -226,103 +220,6 @@ def makemigrations(
                     )
                     log(writer.as_string(), level=3)
 
-    def handle_merge(loader, conflicts):
-        """Handle merging conflicting migrations."""
-        if interactive:
-            questioner = InteractiveMigrationQuestioner()
-        else:
-            questioner = MigrationQuestioner(defaults={"ask_merge": True})
-
-        for package_label, migration_names in conflicts.items():
-            log(click.style(f"Merging {package_label}", fg="cyan", bold=True), level=1)
-
-            merge_migrations = []
-            for migration_name in migration_names:
-                migration = loader.get_migration(package_label, migration_name)
-                migration.ancestry = [
-                    mig
-                    for mig in loader.graph.forwards_plan(
-                        (package_label, migration_name)
-                    )
-                    if mig[0] == migration.package_label
-                ]
-                merge_migrations.append(migration)
-
-            def all_items_equal(seq):
-                return all(item == seq[0] for item in seq[1:])
-
-            merge_migrations_generations = zip(*(m.ancestry for m in merge_migrations))
-            common_ancestor_count = sum(
-                1 for _ in takewhile(all_items_equal, merge_migrations_generations)
-            )
-            if not common_ancestor_count:
-                raise ValueError(f"Could not find common ancestor of {migration_names}")
-
-            for migration in merge_migrations:
-                migration.branch = migration.ancestry[common_ancestor_count:]
-                migrations_ops = (
-                    loader.get_migration(node_package, node_name).operations
-                    for node_package, node_name in migration.branch
-                )
-                migration.merged_operations = sum(migrations_ops, [])
-
-            for migration in merge_migrations:
-                log(click.style(f"  Branch {migration.name}", fg="yellow"), level=1)
-                for operation in migration.merged_operations:
-                    log(f"    - {operation.describe()}", level=1)
-
-            if questioner.ask_merge(package_label):
-                numbers = [
-                    MigrationAutodetector.parse_number(migration.name)
-                    for migration in merge_migrations
-                ]
-                biggest_number = (
-                    max(x for x in numbers if x is not None) if numbers else 0
-                )
-
-                subclass = type(
-                    "Migration",
-                    (Migration,),
-                    {
-                        "dependencies": [
-                            (package_label, migration.name)
-                            for migration in merge_migrations
-                        ],
-                    },
-                )
-
-                parts = [f"{biggest_number + 1:04d}"]
-                if migration_name:
-                    parts.append(migration_name)
-                else:
-                    parts.append("merge")
-                    leaf_names = "_".join(
-                        sorted(migration.name for migration in merge_migrations)
-                    )
-                    if len(leaf_names) > 47:
-                        parts.append(get_migration_name_timestamp())
-                    else:
-                        parts.append(leaf_names)
-
-                new_migration_name = "_".join(parts)
-                new_migration = subclass(new_migration_name, package_label)
-                writer = MigrationWriter(new_migration)
-
-                if not dry_run:
-                    with open(writer.path, "w", encoding="utf-8") as fh:
-                        fh.write(writer.as_string())
-                    log(f"\nCreated new merge migration {writer.path}", level=1)
-                elif verbosity == 3:
-                    log(
-                        click.style(
-                            f"Full merge migrations file '{writer.filename}':",
-                            fg="cyan",
-                            bold=True,
-                        ),
-                        level=3,
-                    )
-                    log(writer.as_string(), level=3)
-
     # Validate package labels
     package_labels = set(package_labels)
     has_bad_labels = False
@@ -351,21 +248,16 @@ def makemigrations(
             if package_label in package_labels
         }
 
-    if conflicts and not merge:
+    if conflicts:
         name_str = "; ".join(
             "{} in {}".format(", ".join(names), package)
             for package, names in conflicts.items()
         )
         raise click.ClickException(
             f"Conflicting migrations detected; multiple leaf nodes in the "
-            f"migration graph: ({name_str}).\nTo fix them run "
-            f"'python manage.py makemigrations --merge'"
+            f"migration graph: ({name_str})."
         )
 
-    # Handle merge if requested
-    if merge and conflicts:
-        return handle_merge(loader, conflicts)
-
     # Set up questioner
     if interactive:
         questioner = InteractiveMigrationQuestioner(
@@ -533,8 +425,7 @@ def migrate(
         )
         raise click.ClickException(
             "Conflicting migrations detected; multiple leaf nodes in the "
-            f"migration graph: ({name_str}).\nTo fix them run "
-            "'python manage.py makemigrations --merge'"
+            f"migration graph: ({name_str})."
         )
 
     # If they supplied command line arguments, work out what they mean.

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/migrations/questioner.py

@@ -74,10 +74,6 @@ class MigrationQuestioner:
         """Was this model really renamed?"""
         return self.defaults.get("ask_rename_model", False)
 
-    def ask_merge(self, package_label):
-        """Should these migrations really be merged?"""
-        return self.defaults.get("ask_merge", False)
-
     def ask_auto_now_add_addition(self, field_name, model_name):
         """Adding an auto_now_add field to a model."""
         # None means quit
@@ -227,16 +223,6 @@ class InteractiveMigrationQuestioner(MigrationQuestioner):
             default=False,
         )
 
-    def ask_merge(self, package_label):
-        return self._boolean_input(
-            (
-                "\nMerging will only work if the operations printed above do not conflict\n"
-                "with each other (working on different fields or models)\n"
-                "Should these migration branches be merged?"
-            ),
-            default=False,
-        )
-
     def ask_auto_now_add_addition(self, field_name, model_name):
         """Adding an auto_now_add field to a model."""
         if not self.dry_run:

plain_models-0.37.0/plain/models/otel.py

@@ -0,0 +1,175 @@
+import re
+from contextlib import contextmanager
+from typing import Any
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.semconv._incubating.attributes.db_attributes import (
+    DB_QUERY_PARAMETER_TEMPLATE,
+    DB_USER,
+)
+from opentelemetry.semconv.attributes.db_attributes import (
+    DB_COLLECTION_NAME,
+    DB_NAMESPACE,
+    DB_OPERATION_NAME,
+    DB_QUERY_SUMMARY,
+    DB_QUERY_TEXT,
+    DB_SYSTEM_NAME,
+)
+from opentelemetry.semconv.attributes.network_attributes import (
+    NETWORK_PEER_ADDRESS,
+    NETWORK_PEER_PORT,
+)
+from opentelemetry.semconv.trace import DbSystemValues
+from opentelemetry.trace import SpanKind
+
+from plain.runtime import settings
+
+_SUPPRESS_KEY = object()
+
+tracer = trace.get_tracer("plain.models")
+
+
+def db_system_for(vendor: str) -> str:  # noqa: D401 – simple helper
+    """Return the canonical ``db.system.name`` value for a backend vendor."""
+
+    return {
+        "postgresql": DbSystemValues.POSTGRESQL.value,
+        "mysql": DbSystemValues.MYSQL.value,
+        "mariadb": DbSystemValues.MARIADB.value,
+        "sqlite": DbSystemValues.SQLITE.value,
+    }.get(vendor, vendor)
+
+
+def extract_operation_and_target(sql: str) -> tuple[str, str | None, str | None]:
+    """Extract operation, table name, and collection from SQL.
+
+    Returns: (operation, summary, collection_name)
+    """
+    sql_upper = sql.upper().strip()
+    operation = sql_upper.split()[0] if sql_upper else "UNKNOWN"
+
+    # Pattern to match quoted and unquoted identifiers
+    # Matches: "quoted", `quoted`, [quoted], unquoted.name
+    identifier_pattern = r'("([^"]+)"|`([^`]+)`|\[([^\]]+)\]|([\w.]+))'
+
+    # Extract table/collection name based on operation
+    collection_name = None
+    summary = operation
+
+    if operation in ("SELECT", "DELETE"):
+        match = re.search(rf"FROM\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    elif operation in ("INSERT", "REPLACE"):
+        match = re.search(rf"INTO\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    elif operation == "UPDATE":
+        match = re.search(rf"UPDATE\s+{identifier_pattern}", sql, re.IGNORECASE)
+        if match:
+            collection_name = _clean_identifier(match.group(1))
+            summary = f"{operation} {collection_name}"
+
+    return operation, summary, collection_name
+
+
+def _clean_identifier(identifier: str) -> str:
+    """Remove quotes from SQL identifiers."""
+    # Remove different types of SQL quotes
+    if identifier.startswith('"') and identifier.endswith('"'):
+        return identifier[1:-1]
+    elif identifier.startswith("`") and identifier.endswith("`"):
+        return identifier[1:-1]
+    elif identifier.startswith("[") and identifier.endswith("]"):
+        return identifier[1:-1]
+    return identifier
+
+
+@contextmanager
+def db_span(db, sql: Any, *, many: bool = False, params=None):
+    """Open an OpenTelemetry CLIENT span for a database query.
+
+    All common attributes (`db.*`, `network.*`, etc.) are set automatically.
+    Follows OpenTelemetry semantic conventions for database instrumentation.
+    """
+
+    # Fast-exit if instrumentation suppression flag set in context.
+    if otel_context.get_value(_SUPPRESS_KEY):
+        yield None
+        return
+
+    sql = str(sql)  # Ensure SQL is a string for span attributes.
+
+    # Extract operation and target information
+    operation, summary, collection_name = extract_operation_and_target(sql)
+
+    if many:
+        summary = f"{summary} many"
+
+    # Span name follows semantic conventions: {target} or {db.operation.name} {target}
+    if summary:
+        span_name = summary[:255]
+    else:
+        span_name = operation
+
+    # Build attribute set following semantic conventions
+    attrs: dict[str, Any] = {
+        DB_SYSTEM_NAME: db_system_for(db.vendor),
+        DB_NAMESPACE: db.settings_dict.get("NAME"),
+        DB_QUERY_TEXT: sql,  # Already parameterized from Django/Plain
+        DB_QUERY_SUMMARY: summary,
+        DB_OPERATION_NAME: operation,
+    }
+
+    # Add collection name if detected
+    if collection_name:
+        attrs[DB_COLLECTION_NAME] = collection_name
+
+    # Add user attribute
+    if user := db.settings_dict.get("USER"):
+        attrs[DB_USER] = user
+
+    # Network attributes
+    if host := db.settings_dict.get("HOST"):
+        attrs[NETWORK_PEER_ADDRESS] = host
+
+    if port := db.settings_dict.get("PORT"):
+        try:
+            attrs[NETWORK_PEER_PORT] = int(port)
+        except (TypeError, ValueError):
+            pass
+
+    # Add query parameters as attributes when DEBUG is True
+    if settings.DEBUG and params is not None:
+        # Convert params to appropriate format based on type
+        if isinstance(params, dict):
+            # Dictionary params (e.g., for named placeholders)
+            for i, (key, value) in enumerate(params.items()):
+                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{key}"] = str(value)
+        elif isinstance(params, list | tuple):
+            # Sequential params (e.g., for %s or ? placeholders)
+            for i, value in enumerate(params):
+                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{i + 1}"] = str(value)
+        else:
+            # Single param (rare but possible)
+            attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.1"] = str(params)
+
+    with tracer.start_as_current_span(
+        span_name, kind=SpanKind.CLIENT, attributes=attrs
+    ) as span:
+        yield span
+        span.set_status(trace.StatusCode.OK)
+
+
+@contextmanager
+def suppress_db_tracing():
+    token = otel_context.attach(otel_context.set_value(_SUPPRESS_KEY, True))
+    try:
+        yield
+    finally:
+        otel_context.detach(token)

{plain_models-0.35.0 → plain_models-0.37.0}/plain/models/test/pytest.py

@@ -2,6 +2,7 @@ import re
 
 import pytest
 
+from plain.models.otel import suppress_db_tracing
 from plain.signals import request_finished, request_started
 
 from .. import transaction
@@ -60,29 +61,32 @@ def setup_db(request):
 def db(setup_db, request):
     if "isolated_db" in request.fixturenames:
         pytest.fail("The 'db' and 'isolated_db' fixtures cannot be used together")
+
     # Set .cursor() back to the original implementation to unblock it
     BaseDatabaseWrapper.cursor = BaseDatabaseWrapper._enabled_cursor
 
     if not db_connection.features.supports_transactions:
         pytest.fail("Database does not support transactions")
 
-    atomic = transaction.atomic()
-    atomic._from_testcase = True  # TODO remove this somehow?
-    atomic.__enter__()
+    with suppress_db_tracing():
+        atomic = transaction.atomic()
+        atomic._from_testcase = True  # TODO remove this somehow?
+        atomic.__enter__()
 
     yield
 
-    if (
-        db_connection.features.can_defer_constraint_checks
-        and not db_connection.needs_rollback
-        and db_connection.is_usable()
-    ):
-        db_connection.check_constraints()
+    with suppress_db_tracing():
+        if (
+            db_connection.features.can_defer_constraint_checks
+            and not db_connection.needs_rollback
+            and db_connection.is_usable()
+        ):
+            db_connection.check_constraints()
 
-    db_connection.set_rollback(True)
-    atomic.__exit__(None, None, None)
+        db_connection.set_rollback(True)
+        atomic.__exit__(None, None, None)
 
-    db_connection.close()
+        db_connection.close()
 
 
 @pytest.fixture

plain_models-0.37.0/plain/models/test/utils.py

@@ -0,0 +1,14 @@
+from plain.models import db_connection
+from plain.models.otel import suppress_db_tracing
+
+
+def setup_database(*, verbosity, prefix=""):
+    old_name = db_connection.settings_dict["NAME"]
+    with suppress_db_tracing():
+        db_connection.creation.create_test_db(verbosity=verbosity, prefix=prefix)
+    return old_name
+
+
+def teardown_database(old_name, verbosity):
+    with suppress_db_tracing():
+        db_connection.creation.destroy_test_db(old_name, verbosity)

{plain_models-0.35.0 → plain_models-0.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.models"
-version = "0.35.0"
+version = "0.37.0"
 description = "Database models for Plain."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain_models-0.35.0/plain/models/test/utils.py

@@ -1,11 +0,0 @@
-from plain.models import db_connection
-
-
-def setup_database(*, verbosity, prefix=""):
-    old_name = db_connection.settings_dict["NAME"]
-    db_connection.creation.create_test_db(verbosity=verbosity, prefix=prefix)
-    return old_name
-
-
-def teardown_database(old_name, verbosity):
-    db_connection.creation.destroy_test_db(old_name, verbosity)