fix(migrations): improve async migration handling by adapting to existing event loops

[m-freelance]

Summary

Replace the error-catch approach in _run_async_engine_migrations with proactive loop detection, and remove the now-unused is_running_loop_error helper from migration_loop.py.

Problem

The previous implementation called asyncio.run() and caught the resulting RuntimeError to detect an already-running event loop, then fell back to a thread-based migration path. This approach:

• Relied on fragile string-matching against exception messages that differ across Python versions and loop implementations
• Swallowed unexpected RuntimeErrors that matched neither known message pattern
• Added unnecessary error-path complexity

Changes

src/basic_memory/alembic/env.py

• Extract _loop_is_running() helper that proactively calls asyncio.get_running_loop() to check loop state before attempting migrations
• Rewrite _run_async_engine_migrations() to branch on _loop_is_running() up front:
  • Running loop → _run_async_migrations_in_thread() (safe thread offload)
  • No loop → _run_async_migrations_with_asyncio_run() directly, letting unexpected errors propagate
• Add decision-point comments explaining trigger / why / outcome for each branch

src/basic_memory/migration_loop.py

• Remove is_running_loop_error() — no longer needed

tests/test_alembic_env.py / tests/test_migration_loop.py

• Update tests to cover _loop_is_running() and the new branch logic
• Remove tests for the deleted is_running_loop_error helper
• Add coverage for the no-running-loop path

Testing

just fast-check && pytest tests/test_alembic_env.py tests/test_migration_loop.py -v

[CLAassistant]

All committers have signed the CLA.

[Copilot]

Pull request overview

This PR updates Alembic’s async-migration dispatcher in env.py to avoid attempting asyncio.run() when an event loop is already active, addressing failures seen in environments where a loop is running (e.g., nest_asyncio + uvloop) and preventing “cannot reuse already awaited coroutine” retry issues.

Changes:

• Switch migration execution-path selection from exception-driven fallback to an upfront asyncio.get_running_loop() check.
• Always offload async migrations to a dedicated thread when a loop is already running; otherwise use asyncio.run().

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d470d26be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".