Built-in Database Migration Tool For Robyn by Charlie-BU · Pull Request #1205 · sparckles/Robyn

Charlie-BU · 2025-07-10T09:40:21Z

Description

This PR adds a built-in database migration tool to Robyn, powered by Alembic. It introduces a new robyn db CLI command group that provides a full suite of migration capabilities, including init, migrate, upgrade, downgrade, stamp, and more.

Summary

This PR does the following:

Adds a fully integrated migration CLI (robyn db) for SQLAlchemy-based projects
Wraps Alembic’s command interface with a consistent Robyn-style CLI structure
Auto-generates and configures alembic.ini and env.py based on user input or intelligent detection (e.g., database URL, model metadata path)
Supports common Alembic commands: init, revision, migrate, upgrade, downgrade, merge, edit, stamp, show, history, etc.
Includes support for migration templates (e.g., --template robyn)
Handles command-line errors gracefully with user-friendly messages
Provides extension class Migrate that can be optionally used inside Robyn apps for future integration

This aims to make database versioning and schema evolution first-class citizens in the Robyn developer workflow, reducing friction for backend developers.

PR Checklist

Please ensure that:

The PR contains a descriptive title
The PR contains a descriptive summary of the changes
You build and test your changes before submitting a PR.
You have added relevant documentation
You have added relevant tests. We prefer integration tests wherever possible

Pre-Commit Instructions:

Ensure that you have run the pre-commit hooks on your PR.

vercel · 2025-07-10T09:40:29Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
robyn	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 19, 2025 6:55am

recurseml · 2025-07-10T09:41:16Z

✨ No issues found! Your code is sparkling clean! ✨

⚠️ Only 5 files were analyzed due to processing limits.

^{Need help? Join our Discord for support!
https://discord.gg/qEjHQk64Z9}

codspeed-hq · 2025-07-10T09:48:24Z

CodSpeed Performance Report

Merging #1205 will not alter performance

_{Comparing Charlie-BU:main (2c0a4aa) with main (d8339a7)}

Summary

✅ 150 untouched benchmarks

sansyrox · 2025-07-11T09:10:27Z

acknowledging the PR 😄

Will need to learn a few things before review

robyn/__init__.py

sansyrox · 2025-07-14T16:32:19Z

robyn/argument_parser.py

+        parser.add_argument(
+            "db",
+            nargs="?",
+            default=None,
+            help="Database migration commands. Use 'robyn db' to see more information.",
+        )


@Charlie-BU , this supposed to invoke alembic cli?

yeah, but the alembic cli is being encapsulated in migrate.py. The arguments passed by robyn and that passed by alembic are not exactly the same, so i need to preprocess the robyn cli argument to make it available to alembic. The details are all in migrate.py.

Here, it just adds a positional argument for robyn. Then user would be able to revoke the encapsulated alembic cli using robyn db ..., which being handled here:

sansyrox · 2025-07-15T09:41:50Z

robyn/cli.py

 import subprocess
 import sys
 import webbrowser
+import argparse


do we need this?

I think we need this to define a sub-argument for robyn, which is robyn db .... We might need argparse to process the argument passed after robyn db.

sansyrox · 2025-07-15T10:50:04Z

robyn/cli.py

+    if db_migration == "Y":
+        print("Installing the latest version of alembic...")
+        try:
+            subprocess.run([sys.executable, "-m", "pip", "install", "alembic", "-q"], check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)


there should be a better way here, no?

I was considering to add alembic as a dependency when people execute pip install robyn. But in view that not everyone needs this database migration tool, I decided to make it an option for people when they do robyn create. If they said yes then alembic is a must in this case.
I modified this self-installing process like this:

Pls check if there's something that could be optimized. Thx! :D

@Charlie-BU , maybe we can allow it to be installed like pip install robyn[db] and then it installs alembic too?

Cool! I removed this as you said. And set the pyproject.toml like this. So people will install alembic when they do pip install robyn[db]

robyn/cli.py

sansyrox · 2025-07-15T10:51:50Z

robyn/migrate.py

+def catch_errors(f):
+    """Decorator to catch and handle errors."""
+
+    @wraps(f)
+    def wrapped(*args, **kwargs):
+        try:
+            return f(*args, **kwargs)
+        except Exception as e:
+            print(f"ERROR: {str(e)}")
+            sys.exit(1)
+
+    return wrapped


I don't like this pattern tbh. We should have specific exception handling. not a generic catch all at the library level.

Let me think how to refactor this...😊

I optimized my decorator. Let it catch specific exception while executing alembic commands with command.*, and inform the exception detail. Thanks for your advice!!:D

sansyrox · 2025-07-15T10:52:21Z

robyn/migrate.py

+        if template is None:
+            return Path(__file__).parent / "templates" / "robyn"
+        return Path(template)


This path validation might be incorrect.

Could you possibly explain more? I think it works.

robyn/migrate.py

sansyrox · 2025-07-15T10:54:03Z

robyn/migrate.py

+                import_statement = f"sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))\nfrom {module_path} import {class_name}\ntarget_metadata = {class_name}.metadata"
+
+                # Replace the import statement
+                content = content.replace(
+                    "# add your model's MetaData object here\n# for 'autogenerate' support\n# from myapp import mymodel\n# target_metadata = mymodel.Base.metadata",
+                    f"# add your model's MetaData object here\n# for 'autogenerate' support\n{import_statement}",
+                )
+
+                # Replace the target_metadata setting
+                content = content.replace(
+                    "target_metadata = config.attributes.get('sqlalchemy.metadata', None)",
+                    "# target_metadata = config.attributes.get('sqlalchemy.metadata', None)\n# Already set by the import above",


This file can be rewritten.

This env.py file and alembic.ini file are automatically created by alembic when handling alembic init alembic, which is robyn db init now. And we have to modify the configuration here to adapt it to the real case.

@Charlie-BU , so do we need to commit this file?

yeah I think we do. That's a template whose path is needed passing into alembic init alembic, which is command.init(config, directory, template=template_path, package=package) in our case.

So that's why I wrote a _get_template_path() method in class Config. It's a must when we initialize the alembic using python code instead of command alembic init alembic.

robyn/migrate.py

sansyrox · 2025-07-15T10:56:17Z

robyn/migrate.py

might be better to create a db module. This file will be incredible hard to test otherwise.

@Charlie-BU , what do you think here?

I'm really sorrrrrrrry I'm not quite familiar about to design a separate module. I don't know if i need to redesign the whole robyn-db-migration structure to do that?

robyn/templates/robyn/env.py

sansyrox · 2025-07-15T10:58:11Z

Hey @Charlie-BU 👋

Thanks for the PR. This is a good start :D But I have some inline comments.

robyn/cli.py

sansyrox · 2025-07-18T09:38:39Z

robyn/templates/robyn/env.py

is this file autogenerated @Charlie-BU ?

yeah, autogenerated by alembic init alembic.

…ion module - Replace generic error decorator with typed migration-specific error handling - Add proper type hints and validation for migration operations - Rename database dependency key from "database" to "db" for consistency - Remove redundant db_migration option from CLI - Improve error messages and logging for migration operations

for more information, see https://pre-commit.ci

Charlie-BU · 2025-07-19T07:00:03Z

@sansyrox I double tested almost every possible situation on my localhost. With alembic installed, without alembic installed, pip install robyn[db], before robyn db init, after robyn db init, wrong commands like robyn db c8iufbfsa, ... All worked out fine! ☺️

sansyrox · 2025-07-30T14:45:17Z

@recurseml re-review

Charlie-BU added 2 commits July 10, 2025 16:33

robyn-db-migrate

15db512

build: robyn-db-migrate

29a164a

vercel bot deployed to Preview July 10, 2025 09:41 View deployment

fix: add-db_migration-to-test-cli

d0f9f66

Charlie-BU force-pushed the main branch from 63e6465 to d0f9f66 Compare July 10, 2025 09:57

vercel bot deployed to Preview July 10, 2025 09:57 View deployment

vercel bot deployed to Preview July 10, 2025 09:59 View deployment

sansyrox reviewed Jul 14, 2025

View reviewed changes

robyn/__init__.py Outdated Show resolved Hide resolved

sansyrox reviewed Jul 14, 2025

View reviewed changes

fix: remove redundant Migrate class and add special configure for sqlite

02ee414

Charlie-BU force-pushed the main branch from cc2b78a to 02ee414 Compare July 15, 2025 06:20

vercel bot deployed to Preview July 15, 2025 06:21 View deployment