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

نام (NAME)
       flask-migrate - مستندات Flask-Migrate

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

چرا استفاده از FLASK-MIGRATE به‌جای ALEMBIC؟ (WHY USE FLASK-MIGRATE VS. ALEMBIC
       DIRECTLY?)
       Flask-Migrate افزونه‌ای است که Alembic را به شیوه مناسب برای کار با
       برنامه Flask و Flask-SQLAlchemy شما پیکربندی می‌کند. از نظر فرآیند واقعی
       مهاجرت‌های پایگاه‌داده، همه چیز توسط Alembic مدیریت می‌شود؛ بنابراین دقیقاً
       همان قابلیت‌ها را دریافت خواهید کرد.

نصب (INSTALLATION)
       نصب Flask-Migrate با pip:

          pip install Flask-Migrate

مثال (EXAMPLE)
       این یک برنامه نمونه است که مهاجرت‌های پایگاه‌داده را از طریق
       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)

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

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

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

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

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

          $ flask db init --multidb

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

مرجع دستورات (COMMAND REFERENCE)
       بسته 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 با چندین زیردستور به گزینه‌های خط فرمان
       اضافه خواهد شد. در زیر فهرستی از زیردستورهای موجود آمده است:

       •

         flask db --help
                فهرستی از دستورات موجود را نمایش می‌دهد.

       •

         flask db list-templates
                فهرستی از قالب‌های موجود مخزن پایگاه‌داده را نمایش می‌دهد.

       •

         flask db init [--multidb] [--template TEMPLATE] [--package]
                پشتیبانی از مهاجرت را برای برنامه راه‌اندازی می‌کند. گزینه
                اختیاری --multidb مهاجرت‌ها را برای چندین پایگاه‌داده
                پیکربندی‌شده به‌عنوان پیوندهای Flask-SQLAlchemy <http://flask-
                sqlalchemy.pocoo.org/binds> فعال می‌سازد. گزینه --template به
                شما امکان می‌دهد صریحاً یک قالب مخزن پایگاه‌داده را از میان
                قالب‌های پیش‌فرض ارائه‌شده توسط این بسته، یا یک قالب سفارشی
                به‌صورت مسیری به دایرکتوری قالب انتخاب کنید. گزینه --package به
                Alembic اعلام می‌کند که فایل‌های __init__.py را در دایرکتوری‌های
                migrations و versions اضافه کند.

       •

         flask db revision [--message MESSAGE] [--autogenerate] [--sql]
         [--head HEAD] [--splice] [--branch-label BRANCH_LABEL]
         [--version-path VERSION_PATH] [--rev-id REV_ID]
                یک اسکریپت بازبینی خالی ایجاد می‌کند. این اسکریپت باید به‌صورت
                دستی با تغییرات ارتقا و تنزل ویرایش شود. برای دستورالعمل‌های
                مربوط به نحوه نوشتن اسکریپت‌های مهاجرت، به مستندات Alembic
                <http://alembic.zzzcomputing.com/en/latest/index.html> مراجعه
                کنید. یک پیام مهاجرت اختیاری نیز می‌تواند اضافه شود.

       •

         flask db migrate [--message MESSAGE] [--sql] [--head HEAD] [--splice]
         [--branch-label BRANCH_LABEL] [--version-path VERSION_PATH] [--rev-id
         REV_ID]
                معادل با revision --autogenerate. اسکریپت مهاجرت با تغییراتی
                که به‌صورت خودکار شناسایی شده‌اند پر می‌شود. اسکریپت تولیدشده
                باید بازبینی و ویرایش شود، زیرا همه انواع تغییرات به‌طور خودکار
                شناسایی نمی‌شوند. این دستور تغییری در پایگاه‌داده ایجاد نمی‌کند و
                صرفاً اسکریپت بازبینی را می‌سازد.

       •

         flask db check
                بررسی می‌کند که آیا اجرای دستور migrate تغییری تولید نمی‌کند یا
                خیر. در صورت تشخیص تغییرات معوق، دستور با کد وضعیت غیرصفر خارج
                می‌شود.

       •

         flask db edit <revision>
                ویرایش یک اسکریپت بازبینی با استفاده از $EDITOR.

       •

         flask db upgrade [--sql] [--tag TAG] <revision>
                پایگاه‌داده را ارتقا می‌دهد. اگر revision داده نشود، مقدار
                "head" فرض می‌شود.

       •

         flask db downgrade [--sql] [--tag TAG] <revision>
                پایگاه‌داده را تنزل می‌دهد. اگر revision داده نشود، مقدار -1 فرض
                می‌شود.

       •

         flask db stamp [--sql] [--tag TAG] <revision>
                بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را روی
                مقدار داده‌شده به‌عنوان آرگومان تنظیم می‌کند.

       •

         flask db current [--verbose]
                بازبینی کنونی پایگاه‌داده را نمایش می‌دهد.

       •

         flask db history [--rev-range REV_RANGE] [--verbose]
                فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشود، کل
                تاریخچه نمایش داده می‌شود.

       •

         flask db show <revision>
                بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد.

       •

         flask db merge [--message MESSAGE] [--branch-label BRANCH_LABEL]
         [--rev-id REV_ID] <revisions>
                ادغام دو بازبینی با یکدیگر. یک فایل بازبینی جدید ایجاد می‌کند.

       •

         flask db heads [--verbose] [--resolve-dependencies]
                سرشاخه‌های (heads) موجود کنونی در دایرکتوری اسکریپت بازبینی را
                نمایش می‌دهد.

       •

         flask db branches [--verbose]
                نقاط انشعاب (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 نیز به‌صورت برنامه‌نویسی قابل دسترسی
         هستند. توابع موجود عبارتند از:

       •

         init(directory='migrations', multidb=False)
                پشتیبانی از مهاجرت را برای برنامه مقداردهی اولیه می‌کند.

       •

         revision(directory='migrations', message=None, autogenerate=False,
         sql=False, head='head', splice=False, branch_label=None,
         version_path=None, rev_id=None)
                یک اسکریپت بازبینی خالی ایجاد می‌کند.

       •

         migrate(directory='migrations', message=None, sql=False, head='head',
         splice=False, branch_label=None, version_path=None, rev_id=None)
                یک اسکریپت بازبینی خودکار ایجاد می‌کند.

       •

         edit(directory='migrations', revision='head')
                اسکریپت(های) بازبینی را با استفاده از $EDITOR ویرایش می‌کند.

       •

         merge(directory='migrations', revisions='', message=None,
         branch_label=None, rev_id=None)
                دو بازبینی را با یکدیگر ادغام می‌کند. یک فایل مهاجرت جدید ایجاد
                می‌کند.

       •

         upgrade(directory='migrations', revision='head', sql=False, tag=None)
                پایگاه‌داده را ارتقا می‌دهد.

       •

         downgrade(directory='migrations', revision='-1', sql=False, tag=None)
                پایگاه‌داده را تنزیل می‌دهد.

       •

         show(directory='migrations', revision='head')
                بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد.

       •

         history(directory='migrations', rev_range=None, verbose=False)
                فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشده باشد، کل
                تاریخچه نمایش داده می‌شود.

       •

         heads(directory='migrations', verbose=False,
         resolve_dependencies=False)
                سرهای (heads) موجود در دایرکتوری اسکریپت را نمایش می‌دهد.

       •

         branches(directory='migrations', verbose=False)
                نقاط شاخه فعلی را نمایش می‌دهد.

       •

         current(directory='migrations', verbose=False, head_only=False)
                بازبینی فعلی پایگاه‌داده را نمایش می‌دهد.

       •

         stamp(directory='migrations', revision='head', sql=False, tag=None)
                بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را به
                مقدار مشخص‌شده به عنوان آرگومان تنظیم می‌کند.

       نکات:

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

       • برای انعطاف‌پذیری بیشتر در اسکریپت‌نویسی، می‌توانید مستقیماً از API
         ارائه‌شده توسط Alembic نیز استفاده کنید.

نویسندگان (AUTHORS)
       Miguel Grinberg

کپی‌رایت و تکثیر (COPYRIGHT)
       2019, Miguel Grinberg

                               December 15, 2025              FLASK-MIGRATE(1)