FLASK-MIGRATE(1) Flask-Migrate FLASK-MIGRATE(1)

flask-migrate - مستندات Flask-Migrate

Flask-Migrate افزونه‌ای است که با استفاده از Alembic، فرآیند مهاجرت‌های پایگاه‌داده مبتنی بر SQLAlchemy را برای برنامه‌های Flask مدیریت می‌کند. عملیات‌های پایگاه‌داده از طریق رابط خط فرمان Flask در دسترس قرار می‌گیرند.

Flask-Migrate افزونه‌ای است که Alembic را به شیوه مناسب برای کار با برنامه Flask و Flask-SQLAlchemy شما پیکربندی می‌کند. از نظر فرآیند واقعی مهاجرت‌های پایگاه‌داده، همه چیز توسط Alembic مدیریت می‌شود؛ بنابراین دقیقاً همان قابلیت‌ها را دریافت خواهید کرد.

نصب Flask-Migrate با pip:

pip install Flask-Migrate

این یک برنامه نمونه است که مهاجرت‌های پایگاه‌داده را از طریق Flask-Migrate مدیریت می‌کند:

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'
db = SQLAlchemy(app)
migrate = Migrate(app, db)
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(128))

با استفاده از برنامه بالا می‌توانید با دستور زیر یک مخزن مهاجرت ایجاد کنید:

$ flask db init

این دستور یک پوشه migrations را به برنامه شما اضافه می‌کند. محتویات این پوشه باید به همراه سایر فایل‌های منبع به سیستم کنترل نسخه اضافه شوند.

سپس می‌توانید یک مهاجرت اولیه ایجاد کنید:

$ flask db migrate -m "Initial migration."

اسکریپت مهاجرت باید بازبینی و ویرایش شود، زیرا Alembic همیشه قادر به تشخیص تمامی تغییراتی که در مدل‌های خود اعمال می‌کنید نیست. به‌ویژه، در حال حاضر Alembic قادر به تشخیص تغییر نام جدول‌ها، تغییر نام ستون‌ها یا قیدهای بدون نام نیست. خلاصه کاملی از این محدودیت‌ها را می‌توانید در مستندات تولید خودکار Alembic در https://alembic.sqlalchemy.org/en/latest/autogenerate.html#what-does-autogenerate-detect-and-what-does-it-not-detect مشاهده کنید. پس از نهایی شدن، اسکریپت مهاجرت نیز باید به سیستم کنترل نسخه افزوده شود.

سپس می‌توانید تغییرات توصیف‌شده توسط اسکریپت مهاجرت را بر روی پایگاه‌داده خود اعمال کنید:

$ flask db upgrade

هر بار که مدل‌های پایگاه‌داده تغییر می‌کنند، دستورهای migrate و upgrade را تکرار کنید.

برای همگام‌سازی پایگاه‌داده در سیستمی دیگر، کافی است پوشه migrations را از سیستم کنترل نسخه بازخوانی کرده و دستور upgrade را اجرا کنید.

برای مشاهده تمامی دستورهای موجود، این دستور را اجرا کنید:

$ flask db --help

توجه داشته باشید که همان‌طور که دستور flask نیاز دارد، اسکریپت برنامه باید در متغیر محیطی FLASK_APP تنظیم شده باشد تا همه دستورهای بالا کار کنند.

اگر نام گروه دستورهای db نامناسب است، می‌توان آن را با فرستادن آرگومان command به کلاس Migrate به نام دیگری تغییر داد:

migrate = Migrate(app, db, command='migrate')

از نگارش ۴.۰ به بعد، Flask-Migrate به‌طور خودکار گزینه‌های زیر را که به‌صورت پیش‌فرض در Alembic غیرفعال هستند، فعال می‌کند:

  • compare_type=True: این گزینه زیرسیستم تولید خودکار مهاجرت را برای تشخیص تغییرات نوع ستون‌ها پیکربندی می‌کند.
  • render_as_batch=True: این گزینه اسکریپت‌های مهاجرت را با استفاده از حالت دسته‌ای (batch mode) https://alembic.sqlalchemy.org/en/latest/batch.html تولید می‌کند؛ یک حالت عملیاتی که با پیاده‌سازی جریان کاری "انتقال و رونوشت" (move and copy)، محدودیت‌های بسیاری از دستورات ALTER را در پایگاه‌داده SQLite دور می‌زند. فعال‌سازی این حالت نباید هنگام کار با سایر پایگاه‌های داده تفاوتی ایجاد کند.

برای پیکربندی دستی این گزینه‌ها یا سایر گزینه‌های Alembic https://alembic.sqlalchemy.org/en/latest/api/runtime.html#alembic.runtime.environment.EnvironmentContext.configure، آن‌ها را به‌عنوان آرگومان‌های کلیدواژه‌ای به سازنده Migrate ارسال کنید. مثال:

migrate = Migrate(app, db, render_as_batch=False)

گاهی برنامه‌ها نیاز دارند که تنظیمات خود را به‌صورت پویا وارد پیکربندی Alembic کنند. تابعی که با کالبک configure تزیین شده باشد، پس از خوانده شدن پیکربندی و پیش از اعمال آن فراخوانی خواهد شد. این تابع می‌تواند شیء پیکربندی را تغییر دهد یا آن را با شیء دیگری جایگزین کند.

@migrate.configure
def configure_alembic(config):
    # modify config object
    return config

چندین فراخوانی بازگشتی پیکربندی را می‌توان به‌سادگی با تزیین چندین تابع تعریف کرد. ترتیب فراخوانی چندین کالبک نامشخص است.

افزونه Flask-Migrate می‌تواند با ویژگی پیوندها (binds) در Flask-SQLAlchemy http://flask-sqlalchemy.pocoo.org/binds یکپارچه شود و امکان ردیابی مهاجرت‌ها را برای چندین پایگاه‌داده مرتبط با یک برنامه فراهم سازد.

برای ایجاد یک مخزن مهاجرت چند پایگاه‌داده‌ای، آرگومان --multidb را به دستور init اضافه کنید:

$ flask db init --multidb

با این دستور، مخزن مهاجرت برای ردیابی مهاجرت‌ها روی پایگاه‌داده اصلی شما و هر پایگاه‌داده اضافی تعریف‌شده در گزینه پیکربندی SQLALCHEMY_BINDS برپا خواهد شد.

بسته Flask-Migrate کلاسی به نام Migrate ارائه می‌دهد. این کلاس شامل تمام عملکردهای این افزونه است.

مثال زیر این افزونه را با واسط خط فرمان استاندارد Flask راه‌اندازی می‌کند:

from flask_migrate import Migrate
migrate = Migrate(app, db)

دو آرگومان ورودی به Migrate عبارتند از نمونه برنامه و نمونه پایگاه‌داده Flask-SQLAlchemy. سازنده Migrate همچنین آرگومان‌های کلیدواژه‌ای دیگری را می‌پذیرد که به متد EnvironmentContext.configure() در Alembic ارسال می‌شوند. همان‌طور که برای همه افزونه‌های Flask استاندارد است، Flask-Migrate را می‌توان با استفاده از متد init_app نیز راه‌اندازی کرد:

from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
db = SQLAlchemy()
migrate = Migrate()
def create_app():
     """Application-factory pattern"""
     ...
     ...
     db.init_app(app)
     migrate.init_app(app, db)
     ...
     ...
     return app

پس از راه‌اندازی افزونه، گروه db با چندین زیردستور به گزینه‌های خط فرمان اضافه خواهد شد. در زیر فهرستی از زیردستورهای موجود آمده است:

•
فهرستی از دستورات موجود را نمایش می‌دهد.
•
فهرستی از قالب‌های موجود مخزن پایگاه‌داده را نمایش می‌دهد.
•
پشتیبانی از مهاجرت را برای برنامه راه‌اندازی می‌کند. گزینه اختیاری --multidb مهاجرت‌ها را برای چندین پایگاه‌داده پیکربندی‌شده به‌عنوان پیوندهای Flask-SQLAlchemy http://flask-sqlalchemy.pocoo.org/binds فعال می‌سازد. گزینه --template به شما امکان می‌دهد صریحاً یک قالب مخزن پایگاه‌داده را از میان قالب‌های پیش‌فرض ارائه‌شده توسط این بسته، یا یک قالب سفارشی به‌صورت مسیری به دایرکتوری قالب انتخاب کنید. گزینه --package به Alembic اعلام می‌کند که فایل‌های __init__.py را در دایرکتوری‌های migrations و versions اضافه کند.
•
یک اسکریپت بازبینی خالی ایجاد می‌کند. این اسکریپت باید به‌صورت دستی با تغییرات ارتقا و تنزل ویرایش شود. برای دستورالعمل‌های مربوط به نحوه نوشتن اسکریپت‌های مهاجرت، به مستندات Alembic http://alembic.zzzcomputing.com/en/latest/index.html مراجعه کنید. یک پیام مهاجرت اختیاری نیز می‌تواند اضافه شود.
•
معادل با revision --autogenerate. اسکریپت مهاجرت با تغییراتی که به‌صورت خودکار شناسایی شده‌اند پر می‌شود. اسکریپت تولیدشده باید بازبینی و ویرایش شود، زیرا همه انواع تغییرات به‌طور خودکار شناسایی نمی‌شوند. این دستور تغییری در پایگاه‌داده ایجاد نمی‌کند و صرفاً اسکریپت بازبینی را می‌سازد.
•
بررسی می‌کند که آیا اجرای دستور migrate تغییری تولید نمی‌کند یا خیر. در صورت تشخیص تغییرات معوق، دستور با کد وضعیت غیرصفر خارج می‌شود.
•
ویرایش یک اسکریپت بازبینی با استفاده از $EDITOR.
•
پایگاه‌داده را ارتقا می‌دهد. اگر revision داده نشود، مقدار "head" فرض می‌شود.
•
پایگاه‌داده را تنزل می‌دهد. اگر revision داده نشود، مقدار -1 فرض می‌شود.
•
بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را روی مقدار داده‌شده به‌عنوان آرگومان تنظیم می‌کند.
•
بازبینی کنونی پایگاه‌داده را نمایش می‌دهد.
•
فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشود، کل تاریخچه نمایش داده می‌شود.
•
بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد.
•
ادغام دو بازبینی با یکدیگر. یک فایل بازبینی جدید ایجاد می‌کند.
•
سرشاخه‌های (heads) موجود کنونی در دایرکتوری اسکریپت بازبینی را نمایش می‌دهد.
•
نقاط انشعاب (branch points) کنونی را نمایش می‌دهد.

نکات:

  • همه دستورات یک یا چند گزینه --x-arg ARG=VALUE یا -x ARG=VALUE را با آرگومان‌های سفارشی می‌پذیرند که می‌توان از آن‌ها در env.py استفاده کرد.
  • همه دستورات گزینه --directory DIRECTORY را می‌پذیرند که به دایرکتوری حاوی اسکریپت‌های مهاجرت اشاره دارد. در صورت حذف این آرگومان، دایرکتوری استفاده‌شده migrations خواهد بود.
  • دایرکتوری را همچنین می‌توان به‌عنوان آرگومان directory در سازنده Migrate یا در متغیر محیطی FLASK_DB_DIRECTORY مشخص کرد.
  • گزینه --sql موجود در چندین دستور، یک مهاجرت در حالت 'آفلاین' (offline) انجام می‌دهد. به‌جای اجرای مستقیم دستورات پایگاه‌داده، دستورات SQL که باید اجرا شوند در کنسول چاپ می‌شوند.
  • مستندات دقیق درباره این دستورات را می‌توانید در صفحه مرجع دستورات Alembic http://alembic.zzzcomputing.com/en/latest/api/commands.html بیابید.

    دستورهایی که توسط رابط خط فرمان Flask-Migrate ارائه می‌شوند، با وارد کردن توابع از ماژول flask_migrate نیز به‌صورت برنامه‌نویسی قابل دسترسی هستند. توابع موجود عبارتند از:

•
پشتیبانی از مهاجرت را برای برنامه مقداردهی اولیه می‌کند.
•
یک اسکریپت بازبینی خالی ایجاد می‌کند.
•
یک اسکریپت بازبینی خودکار ایجاد می‌کند.
•
اسکریپت(های) بازبینی را با استفاده از $EDITOR ویرایش می‌کند.
•
دو بازبینی را با یکدیگر ادغام می‌کند. یک فایل مهاجرت جدید ایجاد می‌کند.
•
پایگاه‌داده را ارتقا می‌دهد.
•
پایگاه‌داده را تنزیل می‌دهد.
•
بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد.
•
فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشده باشد، کل تاریخچه نمایش داده می‌شود.
•
سرهای (heads) موجود در دایرکتوری اسکریپت را نمایش می‌دهد.
•
نقاط شاخه فعلی را نمایش می‌دهد.
•
بازبینی فعلی پایگاه‌داده را نمایش می‌دهد.
•
بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را به مقدار مشخص‌شده به عنوان آرگومان تنظیم می‌کند.

نکات:

  • این دستورها همان عملکردهایی را فراخوانی می‌کنند که از خط فرمان اجرا می‌شوند، از جمله خروجی به ترمینال. پیکربندی لاگ‌گیری (logging) فرایند بر اساس محتویات فایل alembic.ini توسط Alembic بازنویسی خواهد شد.
  • برای انعطاف‌پذیری بیشتر در اسکریپت‌نویسی، می‌توانید مستقیماً از API ارائه‌شده توسط Alembic نیز استفاده کنید.

Miguel Grinberg

2019, Miguel Grinberg

December 15, 2025