feat(migrations): introduce model-aware operations, flat discovery, and colored CLI output

ryx-common/Cargo.toml

@@ -10,3 +10,4 @@ sqlx = { workspace = true }
 tokio = { workspace = true }
 thiserror = { workspace = true }
 serde = { workspace = true }
+tracing = { workspace = true }

ryx-python/ryx/__init__.py

@@ -2,8 +2,26 @@
 
 # Import the compiled Rust extension directly to avoid circular import
 import ryx.ryx_core as _core
+import logging as _logging
 import os
 
+# Configure Ryx logging from RYX_LOG_LEVEL env var
+_ryx_logger = _logging.getLogger("ryx")
+_ryx_log_level = os.environ.get("RYX_LOG_LEVEL", "").strip().upper()
+if _ryx_log_level in ("NO_LOG", "OFF", "SILENT"):
+    _ryx_logger.disabled = True
+    _ryx_logger.propagate = False
+    _ryx_logger.addHandler(_logging.NullHandler())
+elif _ryx_log_level:
+    _ryx_log_level_num = getattr(_logging, _ryx_log_level, _logging.INFO)
+    _ryx_log_handler = _logging.StreamHandler()
+    _ryx_log_handler.setFormatter(
+        _logging.Formatter("[ryx] %(levelname)s %(name)s: %(message)s")
+    )
+    _ryx_logger.addHandler(_ryx_log_handler)
+    _ryx_logger.setLevel(_ryx_log_level_num)
+    _ryx_logger.propagate = False
+
 
 # ORM core
 from ryx.models import Constraint, Index, Model
@@ -123,8 +141,12 @@ async def setup(
 
     # For old versions wrap the url with a dict
     if isinstance(urls, str):
-        urls = {'default': urls} 
+        urls = {'default': urls}
 
+    _ryx_logger.info(
+        "Initializing pools: %s (max_conn=%d, min_conn=%d)",
+        list(urls.keys()), max_connections, min_connections,
+    )
     await _core.setup(
         urls,
         max_connections = max_connections,
@@ -133,10 +155,12 @@ async def setup(
         idle_timeout = idle_timeout,
         max_lifetime = max_lifetime,
     )
+    _ryx_logger.info("Pools initialized: %s", list(urls.keys()))
 
 
 def register_lookup(name: str, sql_template: str) -> None:
     """Register a custom lookup operator (process-global)."""
+    _ryx_logger.debug("Register custom lookup: %s = %s", name, sql_template)
     _core.register_lookup(name, sql_template)
 
 
@@ -345,7 +369,10 @@ def _discover_config_file():
 
 def _auto_setup():
     global _AUTO_INIT_DONE
-    if _AUTO_INIT_DONE or not _should_auto_init():
+    if _AUTO_INIT_DONE:
+        return
+    if not _should_auto_init():
+        _ryx_logger.debug("Auto-init disabled via RYX_AUTO_INITIALIZE")
         return
 
     urls = _discover_urls_from_env()
@@ -356,8 +383,11 @@ def _auto_setup():
         pool_cfg = cfg.get("pool", {}) or {}
 
     if not urls:
+        _ryx_logger.debug("No URLs found — auto-init skipped")
         return
 
+    _ryx_logger.info("Auto-initializing with URLs: %s", list(urls.keys()))
+
     try:
         import asyncio
 

ryx-python/ryx/bulk.py

@@ -25,6 +25,7 @@
 
 from __future__ import annotations
 
+import logging
 from typing import List, Sequence, Type, TYPE_CHECKING, Optional
 
 if TYPE_CHECKING:
@@ -33,6 +34,8 @@
 from ryx import ryx_core as _core
 from ryx.router import get_router
 
+logger = logging.getLogger("ryx.bulk")
+
 
 def _resolve_alias(model: "Model") -> Optional[str]:
     """Resolve DB alias using Router → Meta.database → default(None)."""
@@ -96,6 +99,11 @@ async def bulk_create(
     """
     from ryx.models import _apply_auto_timestamps
 
+    logger.info(
+        "bulk_create %s: %d rows (batch_size=%d, validate=%s, ignore_conflicts=%s)",
+        model.__name__, len(instances), batch_size, validate, ignore_conflicts,
+    )
+
     if not instances:
         return list(instances)
 
@@ -271,6 +279,11 @@ async def bulk_update(
     Signals:
         Does NOT fire pre_save / post_save signals (for performance).
     """
+    logger.info(
+        "bulk_update %s: %d rows, fields=%s (batch_size=%d)",
+        model.__name__, len(instances), fields, batch_size,
+    )
+
     if not instances or not fields:
         return 0
 
@@ -352,6 +365,11 @@ async def bulk_delete(
     Signals:
         Does NOT fire pre_delete / post_delete signals.
     """
+    logger.info(
+        "bulk_delete %s: %d rows (batch_size=%d)",
+        model.__name__, len(instances), batch_size,
+    )
+
     pk_field = model._meta.pk_field
     if not pk_field:
         raise ValueError(f"{model.__name__} has no primary key")

ryx-python/ryx/cache.py

@@ -34,11 +34,14 @@
 import asyncio
 import hashlib
 import json
+import logging
 import time
 from abc import ABC, abstractmethod
 from collections import OrderedDict
 from typing import Any, Optional
 
+logger = logging.getLogger("ryx.cache")
+
 
 ####
 ##      ABSTRACT CACHE BACKEND
@@ -175,6 +178,10 @@ def configure_cache(
     global _cache_backend, _auto_invalidate
     _cache_backend   = backend
     _auto_invalidate = auto_invalidate
+    logger.info(
+        "Cache configured: backend=%s, auto_invalidate=%s",
+        type(backend).__name__, auto_invalidate,
+    )
 
     if auto_invalidate:
         _register_invalidation_signals()
@@ -215,6 +222,7 @@ async def invalidate(key: str) -> None:
     """
     if _cache_backend:
         await _cache_backend.delete(key)
+        logger.debug("Cache invalidate: %s", key)
 
 
 async def invalidate_model(model: type) -> None:
@@ -231,12 +239,14 @@ async def invalidate_model(model: type) -> None:
     keys    = await _cache_backend.keys(prefix)
     if keys:
         await _cache_backend.delete_many(keys)
+        logger.debug("Cache invalidate model %s: %d keys", model.__name__, len(keys))
 
 
 async def invalidate_all() -> None:
     """Clear the entire cache."""
     if _cache_backend:
         await _cache_backend.clear()
+        logger.debug("Cache invalidate all")
 
 
 ####
@@ -269,9 +279,11 @@ async def _execute(self) -> list:
         # Try cache first
         cached = await backend.get(key)
         if cached is not None:
+            logger.debug("Cache HIT: %s", key)
             return cached
 
         # Cache miss → hit DB
+        logger.debug("Cache MISS: %s", key)
         result = await super()._execute()  # type: ignore[misc]
 
         # Serialise model instances to plain dicts for caching

ryx-python/ryx/cli/commands/makemigrations.py

@@ -4,6 +4,7 @@
 import sys
 
 from ryx.cli.commands.base import Command
+from ryx.cli.style import PREFIX, OK, WARN, green, red, yellow
 
 
 class MakeMigrationsCommand(Command):
@@ -28,6 +29,11 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None:
             metavar="DIR",
             help="Migrations directory (default: migrations)",
         )
+        parser.add_argument(
+            "--alias",
+            metavar="ALIAS",
+            help="Database alias to generate migrations for (creates subdirectory)",
+        )
         parser.add_argument(
             "--name", metavar="NAME", help="Override migration name slug"
         )
@@ -44,30 +50,34 @@ async def execute(self, args: argparse.Namespace) -> int:
         cfg = getattr(args, "resolved_config", None) or resolve_config(args)
         models = self._load_models(args.models or cfg.models)
         if not models:
-            print("[ryx] No models found. Pass --models myapp.models or set [models].files in ryx.toml")
+            print(f"{PREFIX} {WARN} No models found. Pass {yellow('--models myapp.models')} or set [models].files in ryx.toml")
             return 1
 
         from ryx.migrations.autodetect import Autodetector
 
-        detector = Autodetector(models=models, migrations_dir=args.dir)
+        detector = Autodetector(
+            models=models,
+            migrations_dir=args.dir,
+            alias=getattr(args, "alias", None),
+        )
         operations = detector.detect()
 
         if not operations:
-            print("[ryx] No changes detected.")
+            print(f"{PREFIX} No changes detected.")
             if args.check:
                 return 0
             return 0
 
         if args.check:
-            print(f"[ryx] {len(operations)} change(s) detected:")
+            print(f"{PREFIX} {red(str(len(operations)))} change(s) detected:")
             for op in operations:
-                print(f"  - {op.describe()}")
+                print(f"      {op.describe()}")
             return 1
 
         path = detector.write_migration(operations)
-        print(f"[ryx] Created migration: {path}")
+        print(f"{PREFIX} {OK} Created {green(str(path.name))}")
         for op in operations:
-            print(f"  - {op.describe()}")
+            print(f"      {op.describe()}")
 
         return 0
 

ryx-python/ryx/cli/commands/migrate.py

@@ -1,13 +1,12 @@
 from __future__ import annotations
 
 import argparse
-import asyncio
 import sys
-from pathlib import Path
-from typing import List, Optional
+from typing import Optional
 
 from ryx.cli.commands.base import Command
 from ryx.cli.config import get_config, Config
+from ryx.cli.style import PREFIX, OK, FAIL, cyan, green
 
 
 class MigrateCommand(Command):
@@ -38,6 +37,11 @@ def add_arguments(self, parser: argparse.ArgumentParser) -> None:
             metavar="ALIAS",
             help="Run migrations for a specific database alias",
         )
+        parser.add_argument(
+            "--no-interactive",
+            action="store_true",
+            help="Fail if no migration files found (for CI)",
+        )
 
     async def execute(self, args: argparse.Namespace) -> int:
         cfg = getattr(args, "resolved_config", None)
@@ -52,7 +56,7 @@ async def execute(self, args: argparse.Namespace) -> int:
 
         # Masking the first URL for the log
         first_url = list(urls.values())[0] if isinstance(urls, dict) else urls
-        print(f"[ryx] Connecting to {self._mask_url(first_url)} ...")
+        print(f"{PREFIX} Connecting to {cyan(self._mask_url(first_url))} ...")
 
         import ryx
 
@@ -66,22 +70,17 @@ async def execute(self, args: argparse.Namespace) -> int:
             models,
             dry_run=getattr(args, "dry_run", False),
             alias_filter=getattr(args, "database", None) or (cfg.db_alias if cfg else None),
+            migrations_dir=getattr(args, "dir", "migrations"),
+            no_interactive=getattr(args, "no_interactive", False),
         )
 
-        if getattr(args, "plan", False):
-            # For plan, we just want to see what would happen
-            # In a real implementation, this would be a separate runner method
-            print("[ryx] --plan is active. Running in dry-run mode...")
-            # We could force dry_run = True here
-
         changes = await runner.migrate()
 
         if changes:
-            print(
-                f"[ryx] Applied {len(changes)} change(s) across configured databases."
-            )
+            count = green(str(len(changes)))
+            print(f"{PREFIX} {OK} Applied {count} change(s)")
         else:
-            print("[ryx] No pending migrations.")
+            print(f"{PREFIX} No pending migrations")
 
         return 0
 
@@ -129,11 +128,12 @@ def _mask_url(self, url: str) -> str:
         return re.sub(r"(:)[^:@/]+(@)", r"\1***\2", url)
 
     def _print_missing_url(self) -> None:
+        from ryx.cli.style import FAIL, yellow, cyan
         print(
-            "[ryx] No database URL found.\n"
-            "  Set RYX_DATABASE_URL environment variable, or\n"
-            "  pass --url postgres://user:pass@host/db, or\n"
-            "  create ryx_settings.py with DATABASE_URL = '...'"
+            f"{PREFIX} {FAIL} No database URL found.\n"
+            f"  Set {cyan('RYX_DATABASE_URL')} environment variable, or\n"
+            f"  pass {yellow('--url postgres://user:pass@host/db')}, or\n"
+            f"  create {cyan('ryx_settings.py')} with {cyan('DATABASE_URL')} = '...'"
         )
 
 

ryx-python/ryx/cli/config.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
+import logging
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, Optional, List
 
 from ryx.cli.config_loader import get_loader, load_config
 
+_ryx_logger = logging.getLogger("ryx")
+_logger = logging.getLogger("ryx.cli")
+
 
 @dataclass
 class Config:
@@ -54,6 +58,14 @@ def from_args(cls, args) -> "Config":
         config.debug = getattr(args, "debug", False)
         config.verbose = getattr(args, "verbose", False)
 
+        # Wire CLI flags to logging levels
+        if config.debug:
+            _ryx_logger.setLevel(logging.DEBUG)
+            _logger.debug("Debug mode enabled via CLI --debug")
+        elif config.verbose:
+            _ryx_logger.setLevel(logging.INFO)
+            _logger.info("Verbose mode enabled via CLI --verbose")
+
         # Load config file if specified
         config_file = getattr(args, "config_file", None)
         if config_file: