feat: run db migrations offline (optionally) (#114)

* feat: run db migrations offline (optionally)

* fix

Author: nicoloboschi

hindsight-api/hindsight_api/admin/cli.py

@@ -214,6 +214,36 @@ def restore(
     typer.echo("Restore complete")
 
 
+async def _run_migration(db_url: str, schema: str = "public") -> None:
+    """Resolve database URL and run migrations."""
+    from ..migrations import run_migrations
+
+    is_pg0, instance_name, _ = parse_pg0_url(db_url)
+    if is_pg0:
+        typer.echo(f"Starting embedded PostgreSQL (instance: {instance_name})...")
+    resolved_url = await resolve_database_url(db_url)
+    run_migrations(resolved_url, schema=schema)
+
+
+@app.command(name="run-db-migration")
+def run_db_migration(
+    schema: str = typer.Option("public", "--schema", "-s", help="Database schema to run migrations on"),
+):
+    """Run database migrations to the latest version."""
+    config = HindsightConfig.from_env()
+
+    if not config.database_url:
+        typer.echo("Error: Database URL not configured.", err=True)
+        typer.echo("Set HINDSIGHT_API_DATABASE_URL environment variable.", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"Running database migrations (schema: {schema})...")
+
+    asyncio.run(_run_migration(config.database_url, schema))
+
+    typer.echo("Database migrations completed successfully")
+
+
 def main():
     app()
 

hindsight-api/hindsight_api/config.py

@@ -54,6 +54,9 @@
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
 ENV_LAZY_RERANKER = "HINDSIGHT_API_LAZY_RERANKER"
 
+# Database migrations
+ENV_RUN_MIGRATIONS_ON_STARTUP = "HINDSIGHT_API_RUN_MIGRATIONS_ON_STARTUP"
+
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
 DEFAULT_LLM_PROVIDER = "openai"
@@ -83,6 +86,9 @@
 # Retain settings
 DEFAULT_RETAIN_MAX_COMPLETION_TOKENS = 64000  # Max tokens for fact extraction LLM call
 
+# Database migrations
+DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
+
 # Default MCP tool descriptions (can be customized via env vars)
 DEFAULT_MCP_RETAIN_DESCRIPTION = """Store important information to long-term memory.
 
@@ -152,6 +158,9 @@ class HindsightConfig:
     skip_llm_verification: bool
     lazy_reranker: bool
 
+    # Database migrations
+    run_migrations_on_startup: bool
+
     @classmethod
     def from_env(cls) -> "HindsightConfig":
         """Create configuration from environment variables."""
@@ -192,6 +201,8 @@ def from_env(cls) -> "HindsightConfig":
             retain_max_completion_tokens=int(
                 os.getenv(ENV_RETAIN_MAX_COMPLETION_TOKENS, str(DEFAULT_RETAIN_MAX_COMPLETION_TOKENS))
             ),
+            # Database migrations
+            run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
         )
 
     def get_llm_base_url(self) -> str:

hindsight-api/hindsight_api/main.py

@@ -187,6 +187,7 @@ def release_lock():
             retain_max_completion_tokens=config.retain_max_completion_tokens,
             skip_llm_verification=config.skip_llm_verification,
             lazy_reranker=config.lazy_reranker,
+            run_migrations_on_startup=config.run_migrations_on_startup,
         )
     config.configure_logging()
     if not args.daemon:
@@ -212,7 +213,11 @@ def release_lock():
         logging.info(f"Loaded tenant extension: {tenant_extension.__class__.__name__}")
 
     # Create MemoryEngine (reads configuration from environment)
-    _memory = MemoryEngine(operation_validator=operation_validator, tenant_extension=tenant_extension)
+    _memory = MemoryEngine(
+        operation_validator=operation_validator,
+        tenant_extension=tenant_extension,
+        run_migrations=config.run_migrations_on_startup,
+    )
 
     # Set extension context on tenant extension (needed for schema provisioning)
     if tenant_extension: