.\" Man page generated from reStructuredText .\" by the Docutils 0.22.3 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "FLASK-MIGRATE" "1" "Dec 15, 2025" "" "Flask-Migrate" .SH "نام (NAME)" flask-migrate \- مستندات Flask-Migrate .sp \fBFlask\-Migrate\fP افزونه‌ای است که با استفاده از Alembic، فرآیند مهاجرت‌های پایگاه‌داده مبتنی بر SQLAlchemy را برای برنامه‌های Flask مدیریت می‌کند. عملیات‌های پایگاه‌داده از طریق رابط خط فرمان Flask در دسترس قرار می‌گیرند. .SH "چرا استفاده از FLASK-MIGRATE به‌جای ALEMBIC؟ (WHY USE FLASK-MIGRATE VS. ALEMBIC DIRECTLY?)" .sp \fBFlask\-Migrate\fP افزونه‌ای است که Alembic را به شیوه مناسب برای کار با برنامه Flask و Flask\-SQLAlchemy شما پیکربندی می‌کند. از نظر فرآیند واقعی مهاجرت‌های پایگاه‌داده، همه چیز توسط Alembic مدیریت می‌شود؛ بنابراین دقیقاً همان قابلیت‌ها را دریافت خواهید کرد. .SH "نصب (INSTALLATION)" .sp نصب Flask\-Migrate با \fIpip\fP: .INDENT 0.0 .INDENT 3.5 .sp .EX pip install Flask\-Migrate .EE .UNINDENT .UNINDENT .SH "مثال (EXAMPLE)" .sp این یک برنامه نمونه است که مهاجرت‌های پایگاه‌داده را از طریق Flask\-Migrate مدیریت می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX from flask import Flask from flask_sqlalchemy import SQLAlchemy from flask_migrate import Migrate app = Flask(__name__) app.config[\(aqSQLALCHEMY_DATABASE_URI\(aq] = \(aqsqlite:///app.db\(aq 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)) .EE .UNINDENT .UNINDENT .sp با استفاده از برنامه بالا می‌توانید با دستور زیر یک مخزن مهاجرت ایجاد کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX $ flask db init .EE .UNINDENT .UNINDENT .sp این دستور یک پوشه \fImigrations\fP را به برنامه شما اضافه می‌کند. محتویات این پوشه باید به همراه سایر فایل‌های منبع به سیستم کنترل نسخه اضافه شوند. .sp سپس می‌توانید یک مهاجرت اولیه ایجاد کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX $ flask db migrate \-m \(dqInitial migration.\(dq .EE .UNINDENT .UNINDENT .sp اسکریپت مهاجرت باید بازبینی و ویرایش شود، زیرا Alembic همیشه قادر به تشخیص تمامی تغییراتی که در مدل‌های خود اعمال می‌کنید نیست. به‌ویژه، در حال حاضر Alembic قادر به تشخیص تغییر نام جدول‌ها، تغییر نام ستون‌ها یا قیدهای بدون نام نیست. خلاصه کاملی از این محدودیت‌ها را می‌توانید در مستندات تولید خودکار Alembic در \%\& مشاهده کنید. پس از نهایی شدن، اسکریپت مهاجرت نیز باید به سیستم کنترل نسخه افزوده شود. .sp سپس می‌توانید تغییرات توصیف‌شده توسط اسکریپت مهاجرت را بر روی پایگاه‌داده خود اعمال کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX $ flask db upgrade .EE .UNINDENT .UNINDENT .sp هر بار که مدل‌های پایگاه‌داده تغییر می‌کنند، دستورهای \fBmigrate\fP و \fBupgrade\fP را تکرار کنید. .sp برای همگام‌سازی پایگاه‌داده در سیستمی دیگر، کافی است پوشه \fImigrations\fP را از سیستم کنترل نسخه بازخوانی کرده و دستور \fBupgrade\fP را اجرا کنید. .sp برای مشاهده تمامی دستورهای موجود، این دستور را اجرا کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX $ flask db \-\-help .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که همان‌طور که دستور \fBflask\fP نیاز دارد، اسکریپت برنامه باید در متغیر محیطی \fBFLASK_APP\fP تنظیم شده باشد تا همه دستورهای بالا کار کنند. .sp اگر نام گروه دستورهای \fBdb\fP نامناسب است، می‌توان آن را با فرستادن آرگومان \fBcommand\fP به کلاس \fBMigrate\fP به نام دیگری تغییر داد: .INDENT 0.0 .INDENT 3.5 .sp .EX migrate = Migrate(app, db, command=\(aqmigrate\(aq) .EE .UNINDENT .UNINDENT.SH "گزینه‌های پیکربندی ALEMBIC (ALEMBIC CONFIGURATION OPTIONS)" .sp از نگارش ۴.۰ به بعد، Flask\-Migrate به‌طور خودکار گزینه‌های زیر را که به‌صورت پیش‌فرض در Alembic غیرفعال هستند، فعال می‌کند: .INDENT 0.0 .IP \(bu 2 \fBcompare_type=True\fP: این گزینه زیرسیستم تولید خودکار مهاجرت را برای تشخیص تغییرات نوع ستون‌ها پیکربندی می‌کند. .IP \(bu 2 \fBrender_as_batch=True\fP: این گزینه اسکریپت‌های مهاجرت را با استفاده از حالت دسته‌ای (batch mode) \% تولید می‌کند؛ یک حالت عملیاتی که با پیاده‌سازی جریان کاری \(dqانتقال و رونوشت\(dq (move and copy)، محدودیت‌های بسیاری از دستورات \fBALTER\fP را در پایگاه‌داده SQLite دور می‌زند. فعال‌سازی این حالت نباید هنگام کار با سایر پایگاه‌های داده تفاوتی ایجاد کند. .UNINDENT .sp برای پیکربندی دستی این گزینه‌ها یا سایر گزینه‌های Alembic \%، آن‌ها را به‌عنوان آرگومان‌های کلیدواژه‌ای به سازنده \fBMigrate\fP ارسال کنید. مثال: .INDENT 0.0 .INDENT 3.5 .sp .EX migrate = Migrate(app, db, render_as_batch=False) .EE .UNINDENT .UNINDENT .SH "فراخوانی‌های بازگشتی پیکربندی (CONFIGURATION CALLBACKS)" .sp گاهی برنامه‌ها نیاز دارند که تنظیمات خود را به‌صورت پویا وارد پیکربندی Alembic کنند. تابعی که با کالبک \fBconfigure\fP تزیین شده باشد، پس از خوانده شدن پیکربندی و پیش از اعمال آن فراخوانی خواهد شد. این تابع می‌تواند شیء پیکربندی را تغییر دهد یا آن را با شیء دیگری جایگزین کند. .INDENT 0.0 .INDENT 3.5 .sp .EX @migrate.configure def configure_alembic(config): # modify config object return config .EE .UNINDENT .UNINDENT .sp چندین فراخوانی بازگشتی پیکربندی را می‌توان به‌سادگی با تزیین چندین تابع تعریف کرد. ترتیب فراخوانی چندین کالبک نامشخص است. .SH "پشتیبانی از چندین پایگاه‌داده (MULTIPLE DATABASE SUPPORT)" .sp افزونه Flask\-Migrate می‌تواند با ویژگی پیوندها (binds) در Flask\-SQLAlchemy \% یکپارچه شود و امکان ردیابی مهاجرت‌ها را برای چندین پایگاه‌داده مرتبط با یک برنامه فراهم سازد. .sp برای ایجاد یک مخزن مهاجرت چند پایگاه‌داده‌ای، آرگومان \fB\-\-multidb\fP را به دستور \fBinit\fP اضافه کنید: .INDENT 0.0 .INDENT 3.5 .sp .EX $ flask db init \-\-multidb .EE .UNINDENT .UNINDENT .sp با این دستور، مخزن مهاجرت برای ردیابی مهاجرت‌ها روی پایگاه‌داده اصلی شما و هر پایگاه‌داده اضافی تعریف‌شده در گزینه پیکربندی \fBSQLALCHEMY_BINDS\fP برپا خواهد شد. .SH "مرجع دستورات (COMMAND REFERENCE)" .sp بسته Flask\-Migrate کلاسی به نام \fBMigrate\fP ارائه می‌دهد. این کلاس شامل تمام عملکردهای این افزونه است. .sp مثال زیر این افزونه را با واسط خط فرمان استاندارد Flask راه‌اندازی می‌کند: .INDENT 0.0 .INDENT 3.5 .sp .EX from flask_migrate import Migrate migrate = Migrate(app, db) .EE .UNINDENT .UNINDENT .sp دو آرگومان ورودی به \fBMigrate\fP عبارتند از نمونه برنامه و نمونه پایگاه‌داده Flask\-SQLAlchemy. سازنده \fBMigrate\fP همچنین آرگومان‌های کلیدواژه‌ای دیگری را می‌پذیرد که به متد \fBEnvironmentContext.configure()\fP در Alembic ارسال می‌شوند. همان‌طور که برای همه افزونه‌های Flask استاندارد است، Flask\-Migrate را می‌توان با استفاده از متد \fBinit_app\fP نیز راه‌اندازی کرد: .INDENT 0.0 .INDENT 3.5 .sp .EX from flask_sqlalchemy import SQLAlchemy from flask_migrate import Migrate db = SQLAlchemy() migrate = Migrate() def create_app(): \(dq\(dq\(dqApplication\-factory pattern\(dq\(dq\(dq ... ... db.init_app(app) migrate.init_app(app, db) ... ... return app .EE .UNINDENT .UNINDENT .sp پس از راه‌اندازی افزونه، گروه \fBdb\fP با چندین زیردستور به گزینه‌های خط فرمان اضافه خواهد شد. در زیر فهرستی از زیردستورهای موجود آمده است: .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db \-\-help\fP فهرستی از دستورات موجود را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db list\-templates\fP فهرستی از قالب‌های موجود مخزن پایگاه‌داده را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db init [\-\-multidb] [\-\-template TEMPLATE] [\-\-package]\fP پشتیبانی از مهاجرت را برای برنامه راه‌اندازی می‌کند. گزینه اختیاری \fB\-\-multidb\fP مهاجرت‌ها را برای چندین پایگاه‌داده پیکربندی‌شده به‌عنوان پیوندهای Flask\-SQLAlchemy \%\& فعال می‌سازد. گزینه \fB\-\-template\fP به شما امکان می‌دهد صریحاً یک قالب مخزن پایگاه‌داده را از میان قالب‌های پیش‌فرض ارائه‌شده توسط این بسته، یا یک قالب سفارشی به‌صورت مسیری به دایرکتوری قالب انتخاب کنید. گزینه \fB\-\-package\fP به Alembic اعلام می‌کند که فایل‌های \fB__init__.py\fP را در دایرکتوری‌های migrations و versions اضافه کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db revision [\-\-message MESSAGE] [\-\-autogenerate] [\-\-sql] [\-\-head HEAD] [\-\-splice] [\-\-branch\-label BRANCH_LABEL] [\-\-version\-path VERSION_PATH] [\-\-rev\-id REV_ID]\fP یک اسکریپت بازبینی خالی ایجاد می‌کند. این اسکریپت باید به‌صورت دستی با تغییرات ارتقا و تنزل ویرایش شود. برای دستورالعمل‌های مربوط به نحوه نوشتن اسکریپت‌های مهاجرت، به مستندات Alembic \% مراجعه کنید. یک پیام مهاجرت اختیاری نیز می‌تواند اضافه شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db migrate [\-\-message MESSAGE] [\-\-sql] [\-\-head HEAD] [\-\-splice] [\-\-branch\-label BRANCH_LABEL] [\-\-version\-path VERSION_PATH] [\-\-rev\-id REV_ID]\fP معادل با \fBrevision \-\-autogenerate\fP\&. اسکریپت مهاجرت با تغییراتی که به‌صورت خودکار شناسایی شده‌اند پر می‌شود. اسکریپت تولیدشده باید بازبینی و ویرایش شود، زیرا همه انواع تغییرات به‌طور خودکار شناسایی نمی‌شوند. این دستور تغییری در پایگاه‌داده ایجاد نمی‌کند و صرفاً اسکریپت بازبینی را می‌سازد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db check\fP بررسی می‌کند که آیا اجرای دستور \fBmigrate\fP تغییری تولید نمی‌کند یا خیر. در صورت تشخیص تغییرات معوق، دستور با کد وضعیت غیرصفر خارج می‌شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db edit \fP ویرایش یک اسکریپت بازبینی با استفاده از $EDITOR. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db upgrade [\-\-sql] [\-\-tag TAG] \fP پایگاه‌داده را ارتقا می‌دهد. اگر \fBrevision\fP داده نشود، مقدار \fB\(dqhead\(dq\fP فرض می‌شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db downgrade [\-\-sql] [\-\-tag TAG] \fP پایگاه‌داده را تنزل می‌دهد. اگر \fBrevision\fP داده نشود، مقدار \fB\-1\fP فرض می‌شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db stamp [\-\-sql] [\-\-tag TAG] \fP بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را روی مقدار داده‌شده به‌عنوان آرگومان تنظیم می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db current [\-\-verbose]\fP بازبینی کنونی پایگاه‌داده را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db history [\-\-rev\-range REV_RANGE] [\-\-verbose]\fP فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشود، کل تاریخچه نمایش داده می‌شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db show \fP بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db merge [\-\-message MESSAGE] [\-\-branch\-label BRANCH_LABEL] [\-\-rev\-id REV_ID] \fP ادغام دو بازبینی با یکدیگر. یک فایل بازبینی جدید ایجاد می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db heads [\-\-verbose] [\-\-resolve\-dependencies]\fP سرشاخه‌های (heads) موجود کنونی در دایرکتوری اسکریپت بازبینی را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBflask db branches [\-\-verbose]\fP نقاط انشعاب (branch points) کنونی را نمایش می‌دهد. .UNINDENT .UNINDENT .sp نکات: .INDENT 0.0 .IP \(bu 2 همه دستورات یک یا چند گزینه \fB\-\-x\-arg ARG=VALUE\fP یا \fB\-x ARG=VALUE\fP را با آرگومان‌های سفارشی می‌پذیرند که می‌توان از آن‌ها در \fBenv.py\fP استفاده کرد. .IP \(bu 2 همه دستورات گزینه \fB\-\-directory DIRECTORY\fP را می‌پذیرند که به دایرکتوری حاوی اسکریپت‌های مهاجرت اشاره دارد. در صورت حذف این آرگومان، دایرکتوری استفاده‌شده \fBmigrations\fP خواهد بود. .IP \(bu 2 دایرکتوری را همچنین می‌توان به‌عنوان آرگومان \fBdirectory\fP در سازنده \fBMigrate\fP یا در متغیر محیطی \fBFLASK_DB_DIRECTORY\fP مشخص کرد. .IP \(bu 2 گزینه \fB\-\-sql\fP موجود در چندین دستور، یک مهاجرت در حالت \(aqآفلاین\(aq (offline) انجام می‌دهد. به‌جای اجرای مستقیم دستورات پایگاه‌داده، دستورات SQL که باید اجرا شوند در کنسول چاپ می‌شوند. .IP \(bu 2 مستندات دقیق درباره این دستورات را می‌توانید در صفحه مرجع دستورات Alembic \% بیابید. .UNINDENT.SH "مرجع API (API REFERENCE)" .sp دستورهایی که توسط رابط خط فرمان Flask\-Migrate ارائه می‌شوند، با وارد کردن توابع از ماژول \fBflask_migrate\fP نیز به‌صورت برنامه‌نویسی قابل دسترسی هستند. توابع موجود عبارتند از: .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBinit(directory=\(aqmigrations\(aq, multidb=False)\fP پشتیبانی از مهاجرت را برای برنامه مقداردهی اولیه می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBrevision(directory=\(aqmigrations\(aq, message=None, autogenerate=False, sql=False, head=\(aqhead\(aq, splice=False, branch_label=None, version_path=None, rev_id=None)\fP یک اسکریپت بازبینی خالی ایجاد می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBmigrate(directory=\(aqmigrations\(aq, message=None, sql=False, head=\(aqhead\(aq, splice=False, branch_label=None, version_path=None, rev_id=None)\fP یک اسکریپت بازبینی خودکار ایجاد می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBedit(directory=\(aqmigrations\(aq, revision=\(aqhead\(aq)\fP اسکریپت(های) بازبینی را با استفاده از $EDITOR ویرایش می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBmerge(directory=\(aqmigrations\(aq, revisions=\(aq\(aq, message=None, branch_label=None, rev_id=None)\fP دو بازبینی را با یکدیگر ادغام می‌کند. یک فایل مهاجرت جدید ایجاد می‌کند. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBupgrade(directory=\(aqmigrations\(aq, revision=\(aqhead\(aq, sql=False, tag=None)\fP پایگاه‌داده را ارتقا می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBdowngrade(directory=\(aqmigrations\(aq, revision=\(aq\-1\(aq, sql=False, tag=None)\fP پایگاه‌داده را تنزیل می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBshow(directory=\(aqmigrations\(aq, revision=\(aqhead\(aq)\fP بازبینی مشخص‌شده توسط نماد داده‌شده را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBhistory(directory=\(aqmigrations\(aq, rev_range=None, verbose=False)\fP فهرست مهاجرت‌ها را نمایش می‌دهد. اگر محدوده‌ای مشخص نشده باشد، کل تاریخچه نمایش داده می‌شود. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBheads(directory=\(aqmigrations\(aq, verbose=False, resolve_dependencies=False)\fP سرهای (heads) موجود در دایرکتوری اسکریپت را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBbranches(directory=\(aqmigrations\(aq, verbose=False)\fP نقاط شاخه فعلی را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBcurrent(directory=\(aqmigrations\(aq, verbose=False, head_only=False)\fP بازبینی فعلی پایگاه‌داده را نمایش می‌دهد. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBstamp(directory=\(aqmigrations\(aq, revision=\(aqhead\(aq, sql=False, tag=None)\fP بدون انجام هیچ مهاجرتی، بازبینی موجود در پایگاه‌داده را به مقدار مشخص‌شده به عنوان آرگومان تنظیم می‌کند. .UNINDENT .UNINDENT .sp نکات: .INDENT 0.0 .IP \(bu 2 این دستورها همان عملکردهایی را فراخوانی می‌کنند که از خط فرمان اجرا می‌شوند، از جمله خروجی به ترمینال. پیکربندی لاگ‌گیری (logging) فرایند بر اساس محتویات فایل alembic.ini توسط Alembic بازنویسی خواهد شد. .IP \(bu 2 برای انعطاف‌پذیری بیشتر در اسکریپت‌نویسی، می‌توانید مستقیماً از API ارائه‌شده توسط Alembic نیز استفاده کنید. .UNINDENT .SH "نویسندگان (AUTHORS)" Miguel Grinberg .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 2019, Miguel Grinberg .\" End of generated man page.