کتابخانه flask-migrate در پایتون

flask-migrate یک افزونه برای فریم‌ورک Flask است که روی Alembic (ابزار مهاجرت پایگاه‌داده برای SQLAlchemy) سوار می‌شود و مدیریت نسخه‌بندی اسکیمای پایگاه‌داده را ساده می‌کند. این کتابخانه به توسعه‌دهندگان اجازه می‌دهد تغییرات مدل‌های SQLAlchemy را به راحتی ثبت، تولید اسکریپت مهاجرت و اعمال یا بازگردانی آن‌ها بر روی پایگاه‌داده انجام دهند.

چرا از flask-migrate استفاده کنیم؟

• خودکارسازی تبدیل مدل‌ها به اسکریپت‌های مهاجرت با دستور autogenerate
• همکاری تیمی راحت‌تر و قابل رهگیری شدن تغییرات اسکیمای پایگاه‌داده
• پشتیبانی از عملیات upgrade و downgrade برای بازگردانی تغییرات
• یکپارچگی با الگوهای رایج Flask مثل app factory و CLI

نصب و راه‌اندازی اولیه

pip install Flask-Migrate

دستور بالا flask-migrate را نصب می‌کند. پس از نصب، باید Migrate را به اپلیکیشن Flask و SQLAlchemy متصل کنید.

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

db = SQLAlchemy()
migrate = Migrate()

def create_app():
    app = Flask(__name__)
    app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
    db.init_app(app)
    migrate.init_app(app, db)
    return app

در این قطعه کد یک الگوی app factory نشان داده شده است. ابتدا SQLAlchemy و Migrate را بدون اپلیکیشن مقداردهی اولیه می‌کنیم و سپس در create_app آن‌ها را به اپ متصل می‌کنیم. این الگو با تست و دپلویمنتی که چند اپ ایجاد می‌کند سازگار است.

یک مثال عملی: تعریف مدل و ایجاد اولین مهاجرت

from yourapp import db

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)

مدل سادهٔ User را تعریف می‌کنیم. پس از تعریف مدل‌ها می‌توان دستورات زیر را اجرا کرد:

flask db init
flask db migrate -m "create user table"
flask db upgrade

توضیح: flask db init یک پوشه migrations ایجاد می‌کند. flask db migrate یک فایل مهاجرت با تشخیص تغییرات از مدل‌ها تولید می‌کند و flask db upgrade آن اسکریپت را روی پایگاه‌داده اعمال می‌کند.

فرمان‌های مهم (مرور سریع)

توضیحات تکمیلی درباره autogenerate

قابلیت autogenerate بسیار مفید است اما 100% بی‌خطا نیست. برای مثال تغییر نام ستون یا ترکیب جداول ممکن است نیاز به اصلاح دستی اسکریپتِ تولید شده داشته باشد. همیشه فایل مهاجرت تولید شده را بازبینی کنید تا عملیات خطرناکی مثل حذف داده‌ها به‌طور ناخواسته رخ ندهد.

نمونه مهاجرت دستی (rename column)

"""rename username to user_name

Revision ID: 1234567890ab
Revises: None
Create Date: 2025-01-01 00:00:00.000000

"""
from alembic import op
import sqlalchemy as sa

revision = '1234567890ab'
down_revision = None
branch_labels = None
depends_on = None

def upgrade():
    op.alter_column('user', 'username', new_column_name='user_name')

def downgrade():
    op.alter_column('user', 'user_name', new_column_name='username')

در این مثال تغییر نام ستون به‌صورت دستی در اسکریپت Alembic نوشته شده است. گاهی autogenerate توانایی تشخیص rename را ندارد و آن را به عنوان حذف + اضافه نشان می‌دهد؛ بنابراین نوشتن alter_column دستی بهتر و ایمن‌تر است.

نکات پیشرفته و بهترین شیوه‌ها

• همیشه فایل‌های migrations را در کنترل نسخه (git) نگهدارید تا تیم بتواند تغییرات را دنبال کند.
• قبل از apply کردن روی دیتابیس تولید، روی یک دیتابیس محلی یا staging تست کنید.
• برای عملیات حساس مانند تغییر نوع ستون یا حذف ستون حاوی داده، اسکریپتِ مبدل (data migration) جداگانه بنویسید.
• در پروژه‌هایی با چندین اپلیکیشن یا چندین پایگاه‌داده، هر کدام را با حوصله پیکربندی کنید و از پارامترهای Alembic استفاده کنید.
• از پیام‌های واضح در migrate -m استفاده کنید تا تاریخچه خوانا باشد.

اشتباهات رایج و راه‌حل‌ها

• خطای “Target database is not up to date”: ابتدا migrations محلی را بررسی کنید و سپس flask db upgrade را اجرا کنید.
• مشکل ImportError هنگام اجرای flask db migrate: مطمئن شوید FLASK_APP یا ساختار app factory به درستی تنظیم شده و مسیرها درست هستند.
• تغییرات اتوماتیک بزرگ و پیچیده: همیشه فایل تولید شده را بررسی و اصلاح کنید.

نمونه کامل‌تر با CLI سفارشی

from flask.cli import with_appcontext
import click
from flask import current_app

@click.command('create-sample-user')
@with_appcontext
def create_sample_user():
    from yourapp import db
    from yourapp.models import User
    u = User(username='alice', email='alice@example.com')
    db.session.add(u)
    db.session.commit()
    click.echo("Sample user created")

def create_app():
    app = Flask(__name__)
    # ... init db and migrate
    app.cli.add_command(create_sample_user)
    return app

در این قطعه یک فرمان CLI سفارشی تعریف می‌کنیم که داخل کانتکست اپ اجرا می‌شود. افزودن چنین فرمان‌هایی به توسعه و تست مهاجرت‌ها کمک می‌کند (مثلاً پس از upgrade اجرا کنیم تا داده‌های اولیه درست شوند).

جمع‌بندی

flask-migrate ابزاری قدرتمند برای مدیریت اسکیمای پایگاه‌داده در پروژه‌های Flask است. با ترکیب autogenerate و توانایی ویرایش دستی، می‌توانید تغییرات ساختاری را قابل ردیابی و قابل بازگشت نگه دارید. توجه به بهترین شیوه‌ها، تست روی محیط‌های غیرتولید و بررسی دستی فایل‌های مهاجرت، کلید استفاده موفق از این کتابخانه است.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال