.\" 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-SQLALCHEMY" "1" "Dec 15, 2025" "3.1.x" "Flask-SQLAlchemy"
.SH "نام (NAME)"
flask-sqlalchemy \- افزونه‌ی Flask برای پشتیبانی از SQLAlchemy
[تصویر]
.sp
افزونه‌ی Flask\-SQLAlchemy یک افزونه برای Flask \%<https://\:flask\:.palletsprojects\:.com> است که پشتیبانی از SQLAlchemy \%<https://\:www\:.sqlalchemy\:.org> را به برنامه‌ی شما اضافه می‌کند. این افزونه با راه‌اندازی اشیاء و الگوهای رایج برای استفاده از آن‌ها، مانند نشست (session) متصل به هر درخواست وب، مدل‌ها (models) و موتورها (engines)، استفاده از SQLAlchemy را به همراه Flask ساده‌تر می‌کند.
.sp
افزونه‌ی Flask\-SQLAlchemy نحوه‌ی کارکرد یا استفاده از SQLAlchemy را تغییر نمی‌دهد. برای یادگیری عمیق نحوه‌ی کار با ORM، مستندات SQLAlchemy را در \%<https://\:docs\:.sqlalchemy\:.org> مطالعه کنید. مستندات ارائه‌شده در اینجا تنها به راه‌اندازی افزونه می‌پردازد، نه نحوه‌ی استفاده از SQLAlchemy.
.SH "راهنمای کاربر (USER GUIDE)"
.SS شروع سریع
.sp
افزونه‌ی Flask\-SQLAlchemy با مدیریت خودکار ایجاد، استفاده و پاک‌سازی اشیاء SQLAlchemy که معمولاً با آن‌ها کار می‌کنید، استفاده از SQLAlchemy را ساده می‌کند. اگرچه این افزونه چند ویژگی کاربردی اضافه می‌کند، اما همچنان مانند SQLAlchemy کار می‌کند.
.sp
این صفحه شما را با استفاده‌ی پایه‌ای از Flask\-SQLAlchemy آشنا می‌کند. برای دسترسی به همه‌ی قابلیت‌ها و شخصی‌سازی‌ها، باقی این مستندات از جمله مستندات API برای شیء \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> را مطالعه کنید.
.SS بررسی مستندات SQLAlchemy
.sp
افزونه‌ی Flask\-SQLAlchemy یک پوسته‌ساز (wrapper) پیرامون SQLAlchemy است. شما باید آموزش SQLAlchemy \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:tutorial/\:index\:.html> را برای یادگیری نحوه‌ی استفاده از آن دنبال کرده و برای اطلاعات دقیق‌تر درباره‌ی قابلیت‌هایش، مستندات آن را بررسی کنید. این مستندات نحوه‌ی پیکربندی خود Flask\-SQLAlchemy را نشان می‌دهند، نه نحوه‌ی کار با SQLAlchemy. از آنجا که Flask\-SQLAlchemy موتور و نشست دامنه‌دار (scoped session) را به‌طور خودکار راه‌اندازی می‌کند، می‌توانید از آن بخش‌های آموزش SQLAlchemy صرف‌نظر کنید.
.sp
این راهنما فرض می‌کند که شما از SQLAlchemy 2.x استفاده می‌کنید که دارای یک API جدید برای تعریف مدل‌ها و پشتیبانی بهتر از راهنماهای نوع (type hints) و کلاس‌های داده (data classes) در پایتون است. اگر از SQLAlchemy 1.x استفاده می‌کنید، بخش شروع سریع موروثی (Legacy Quickstart) \%<>\& را ببینید.
.SS نصب
.sp
افزونه‌ی Flask\-SQLAlchemy در PyPI \%<https://\:pypi\:.org/\:project/\:Flask-SQLAlchemy> در دسترس است و می‌توان آن را با ابزارهای مختلف پایتون نصب کرد. برای نمونه، جهت نصب یا به‌روزرسانی به آخرین نسخه با استفاده از pip:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pip install \-U Flask\-SQLAlchemy
.EE
.UNINDENT
.UNINDENT
.SS مقداردهی اولیه افزونه
.sp
ابتدا شیء \fBdb\fP را با استفاده از سازنده‌ی \fBSQLAlchemy\fP ایجاد کنید.
.sp
یک زیرکلاس از DeclarativeBase \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBase> یا DeclarativeBaseNoMeta \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBaseNoMeta> را به سازنده پاس دهید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
  pass

db = SQLAlchemy(model_class=Base)
.EE
.UNINDENT
.UNINDENT
.sp
درباره‌ی سفارشی‌سازی کلاس مدل پایه، در مدل‌ها و جدول‌ها (Models and Tables) \%<>\& بیشتر بیاموزید..SS دربارهٔ شیء \fBSQLAlchemy\fP
.sp
پس از نمونه‌سازی، شیء \fBdb\fP دسترسی به کلاس \fBdb.Model\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.Model> جهت تعریف مدل‌ها، و \fBdb.session\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.session> برای اجرای پرس‌وجوها را فراهم می‌کند.
.sp
شیء \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> همچنین آرگومان‌های بیشتری را برای سفارشی‌سازی اشیایی که مدیریت می‌کند می‌پذیرد.
.SS پیکربندی افزونه
.sp
گام بعدی، متصل کردن افزونه به برنامهٔ Flask شما است.
تنها پیکربندی لازم برای برنامهٔ Flask، کلید \fBSQLALCHEMY_DATABASE_URI\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_DATABASE_URI> است. این کلید یک رشتهٔ اتصال است که به SQLAlchemy می‌گوید به چه پایگاه داده‌ای متصل شود.
.sp
شیء برنامهٔ Flask خود را ایجاد کرده، هرگونه پیکربندی را بارگذاری نمایید، و سپس با فراخوانی \fBdb.init_app\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.init_app>\&، کلاس افزونهٔ \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> را با برنامه مقداردهی اولیه کنید. این مثال به یک پایگاه دادهٔ SQLite متصل می‌شود که در پوشهٔ instance برنامه ذخیره شده است.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# create the app
app = Flask(__name__)
# configure the SQLite database, relative to the app instance folder
app.config[\(dqSQLALCHEMY_DATABASE_URI\(dq] = \(dqsqlite:///project.db\(dq
# initialize the app with the extension
db.init_app(app)
.EE
.UNINDENT
.UNINDENT
.sp
برای توضیحات مربوط به رشته‌های اتصال و این‌که چه کلیدهای پیکربندی دیگری استفاده می‌شوند، بخش Configuration \%<> را ببینید.
.SS تعریف مدل‌ها
.sp
برای تعریف یک کلاس مدل، از \fBdb.Model\fP ارث‌بری کنید.
مدل با تبدیل نام کلاس از حالت \fBCamelCase\fP به \fBsnake_case\fP\&، نام جدول را تولید خواهد کرد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy import Integer, String
from sqlalchemy.orm import Mapped, mapped_column

class User(db.Model):
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    username: Mapped[str] = mapped_column(String, unique=True, nullable=False)
    email: Mapped[str] = mapped_column(String)
.EE
.UNINDENT
.UNINDENT
.sp
برای اطلاعات بیشتر دربارهٔ تعریف و ایجاد مدل‌ها و جدول‌ها، بخش Models and Tables \%<> را ببینید.
.SS ساخت جدول‌ها
.sp
پس از اینکه تمام مدل‌ها و جدول‌ها تعریف شدند، \fBSQLAlchemy.create_all()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.create_all> را فراخوانی کنید تا طرح‌وارهٔ جدول در پایگاه داده ایجاد شود. این کار نیازمند بافتار برنامه (application context) است. از آنجا که در این مرحله در بافتار یک درخواست نیستید، یکی را به‌صورت دستی ایجاد نمایید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
with app.app_context():
    db.create_all()
.EE
.UNINDENT
.UNINDENT
.sp
اگر مدل‌ها را در ماژول‌های دیگری تعریف کرده‌اید، باید پیش از فراخوانی \fBcreate_all\fP آن‌ها را وارد (import) کنید؛ در غیر این صورت SQLAlchemy از آن‌ها مطلع نخواهد شد.
.sp
در صورتی که جدول‌ها از پیش در پایگاه داده موجود باشند، \fBcreate_all\fP آن‌ها را به‌روزرسانی نمی‌کند. اگر ستون‌های یک مدل را تغییر دادید، از یک کتابخانهٔ مهاجرت (migration) مانند Alembic \%<https://\:alembic\:.sqlalchemy\:.org> همراه با Flask\-Alembic \%<https://\:flask-alembic\:.readthedocs\:.io> یا Flask\-Migrate \%<https://\:flask-migrate\:.readthedocs\:.io> استفاده کنید تا مهاجرت‌هایی تولید شوند که طرح‌وارهٔ پایگاه داده را به‌روزرسانی می‌کنند.
.SS پرس‌وجوی داده‌ها
.sp
درون یک view در Flask یا یک فرمان CLI، می‌توانید از \fBdb.session\fP برای اجرای پرس‌وجوها و تغییر داده‌های مدل استفاده نمایید.
.sp
سامانهٔ SQLAlchemy به‌طور خودکار یک متد \fB__init__\fP برای هر مدل تعریف می‌کند که تمام آرگومان‌های کلیدواژه‌ای را به ستون‌های متناظر در پایگاه داده و سایر ویژگی‌ها اختصاص می‌دهد.
.sp
دستور \fBdb.session.add(obj)\fP یک شیء را برای درج شدن به نشست (session) اضافه می‌کند. ویرایش ویژگی‌های یک شیء، آن را به‌روزرسانی می‌نماید. دستور \fBdb.session.delete(obj)\fP یک شیء را حذف می‌کند. به یاد داشته باشید که پس از تغییر، افزودن یا حذف هرگونه داده، باید \fBdb.session.commit()\fP را فراخوانی کنید.
.sp
دستور \fBdb.session.execute(db.select(...))\fP یک پرس‌وجو برای گزینش داده‌ها از پایگاه داده می‌سازد. ساخت پرس‌وجوها قابلیت اصلی SQLAlchemy است، بنابراین توصیه می‌شود آموزش آن دربارهٔ select \%<https://\:docs\:.sqlalchemy\:.org/\:tutorial/\:data_select\:.html> را مطالعه کنید تا تمام جزئیات آن را فرا بگیرید. معمولاً از متد \fBResult.scalars()\fP برای دریافت فهرستی از نتایج، یا از متد \fBResult.scalar()\fP برای دریافت یک نتیجهٔ منفرد استفاده خواهید کرد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@app.route(\(dq/users\(dq)
def user_list():
    users = db.session.execute(db.select(User).order_by(User.username)).scalars()
    return render_template(\(dquser/list.html\(dq, users=users)

@app.route(\(dq/users/create\(dq, methods=[\(dqGET\(dq, \(dqPOST\(dq])
def user_create():
    if request.method == \(dqPOST\(dq:
        user = User(
            username=request.form[\(dqusername\(dq],
            email=request.form[\(dqemail\(dq],
        )
        db.session.add(user)
        db.session.commit()
        return redirect(url_for(\(dquser_detail\(dq, id=user.id))

    return render_template(\(dquser/create.html\(dq)

@app.route(\(dq/user/<int:id>\(dq)
def user_detail(id):
    user = db.get_or_404(User, id)
    return render_template(\(dquser/detail.html\(dq, user=user)

@app.route(\(dq/user/<int:id>/delete\(dq, methods=[\(dqGET\(dq, \(dqPOST\(dq])
def user_delete(id):
    user = db.get_or_404(User, id)

    if request.method == \(dqPOST\(dq:
        db.session.delete(user)
        db.session.commit()
        return redirect(url_for(\(dquser_list\(dq))

    return render_template(\(dquser/delete.html\(dq, user=user)
.EE
.UNINDENT
.UNINDENT
.sp
ممکن است استفاده‌هایی از \fBModel.query\fP را برای ساخت پرس‌وجوها ببینید. این یک واسط قدیمی‌تر برای پرس‌وجوها است که در SQLAlchemy منسوخ‌شده (legacy) به شمار می‌رود. ترجیحاً به‌جای آن از \fBdb.session.execute(db.select(...))\fP استفاده کنید.
.sp
برای اطلاعات بیشتر دربارهٔ پرس‌وجوها، بخش Modifying and Querying Data \%<> را ببینید..SS نکاتی که باید به خاطر داشت
.sp
در بیشتر موارد، باید از SQLAlchemy طبق روال معمول استفاده کنید. نمونه افزونه‌ی \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> موارد زیر را ایجاد و پیکربندی کرده و دسترسی به آن‌ها را فراهم می‌کند:
.INDENT 0.0
.IP \(bu 2
کلاس پایه مدل اعلانی \fBSQLAlchemy.Model\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.Model>\&. این کلاس به‌جای نیاز به \fB__tablename__\fP نام جدول را به‌طور خودکار تنظیم می‌کند.
.IP \(bu 2
نشست \fBSQLAlchemy.session\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.session> که محدوده‌اش به بافتار برنامه (application context) جاری Flask محدود است. این نشست پس از هر درخواست پاک‌سازی می‌شود.
.IP \(bu 2
\fBSQLAlchemy.metadata\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.metadata> و \fBSQLAlchemy.metadatas\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.metadatas> دسترسی به هر فراداده تعریف‌شده در پیکربندی را فراهم می‌کنند.
.IP \(bu 2
\fBSQLAlchemy.engine\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.engine> و \fBSQLAlchemy.engines\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.engines> دسترسی به هر موتور تعریف‌شده در پیکربندی را فراهم می‌کنند.
.IP \(bu 2
\fBSQLAlchemy.create_all()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.create_all> تمام جدول‌ها را ایجاد می‌کند.
.IP \(bu 2
برای اجرای پرس‌وجوها و دسترسی به نشست و موتور، باید در یک بافتار فعال برنامه Flask قرار داشته باشید.
.UNINDENT
.SS پیکربندی
.SS کلیدهای پیکربندی
.sp
پیکربندی هنگام فراخوانی \fBSQLAlchemy.init_app()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.init_app> از \fBapp.config\fP در Flask بارگذاری می‌شود. پس از آن پیکربندی مجدداً خوانده نخواهد شد. بنابراین، تمام تنظیمات پیکربندی باید پیش از راه‌اندازی اولیه برنامه انجام شوند.
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_DATABASE_URI
شناسه یکنواخت منبع (URI) اتصال پایگاه داده که برای موتور پیش‌فرض استفاده می‌شود. این مقدار می‌تواند یک رشته یا نمونه‌ای از \fBURL\fP در SQLAlchemy باشد. برای مشاهده مثال‌ها به ادامه متن و Engine Configuration \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:engines\:.html> مراجعه کنید.
.sp
حداقل یکی از این گزینه و \fBSQLALCHEMY_BINDS\fP باید تنظیم شود.
.sp
تغییر یافته در نسخه 3.0: در صورت تنظیم نشدن، دیگر به‌طور پیش‌فرض از یک پایگاه داده SQLite درون‌حافظه‌ای (in\-memory) استفاده نمی‌کند.

.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_ENGINE_OPTIONS
یک دیکشنری از آرگومان‌ها برای ارسال به \fBsqlalchemy.create_engine()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:engines\:.html#\:sqlalchemy\:.create_engine> برای موتور پیش‌فرض.
.sp
این گزینه بر آرگومان \fBengine_options\fP در \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy>، که می‌توان از آن برای تنظیم گزینه‌های پیش‌فرض تمام موتورها استفاده کرد، اولویت دارد.
.sp
تغییر یافته در نسخه 3.0: فقط به پیوند (bind) پیش‌فرض اعمال می‌شود.

.sp
اضافه‌شده در نسخه 2.4.

.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_BINDS
یک دیکشنری که کلیدهای پیوند (bind) را به گزینه‌های موتور نگاشت می‌کند. مقدار می‌تواند یک رشته یا یک نمونه \fBURL\fP در SQLAlchemy باشد، یا می‌تواند دیکشنری‌ای از آرگومان‌ها شامل کلید \fBurl\fP باشد که به \fBsqlalchemy.create_engine()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:engines\:.html#\:sqlalchemy\:.create_engine>\& ارسال خواهد شد. از کلید \fBNone\fP می‌توان برای پیکربندی پیوند پیش‌فرض استفاده کرد، اما \fBSQLALCHEMY_ENGINE_OPTIONS\fP و \fBSQLALCHEMY_DATABASE_URI\fP در اولویت هستند.
.sp
حداقل یکی از این گزینه و \fBSQLALCHEMY_DATABASE_URI\fP باید تنظیم شود.
.sp
اضافه‌شده در نسخه 0.12.

.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_ECHO
مقدار پیش‌فرض برای \fBecho\fP و \fBecho_pool\fP برای هر موتور. این گزینه برای اشکال‌زدایی سریع اتصالات و پرس‌وجوهای صادرشده از SQLAlchemy مفید است.
.sp
تغییر یافته در نسخه 3.0: علاوه بر \fBecho\fP، مقدار \fBecho_pool\fP را نیز تنظیم می‌کند\&.

.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_RECORD_QUERIES
در صورت فعال بودن، اطلاعات مربوط به هر پرس‌وجو در طول یک درخواست ثبت خواهد شد. برای دریافت فهرستی از پرس‌وجوهای صادرشده در طول درخواست، از \fBget_recorded_queries()\fP \%<#\:flask_sqlalchemy\:.record_queries\:.get_recorded_queries> استفاده کنید.
.sp
تغییر یافته در نسخه 3.0: دیگر به‌طور خودکار در حالت اشکال‌زدایی (debug) یا آزمایش (testing) فعال نمی‌شود.

.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.config.SQLALCHEMY_TRACK_MODIFICATIONS
در صورت فعال بودن، تمام عملیات‌های \fBinsert\fP، \fBupdate\fP و \fBdelete\fP روی مدل‌ها ثبت شده و سپس هنگام فراخوانی \fBsession.commit()\fP، در سیگنال‌های \fBmodels_committed\fP \%<#\:flask_sqlalchemy\:.track_modifications\:.models_committed> و \fBbefore_models_committed\fP \%<#\:flask_sqlalchemy\:.track_modifications\:.before_models_committed> ارسال می‌شوند.
.sp
این کار بار اضافی (overhead) چشمگیری به هر نشست اضافه می‌کند. ترجیحاً برای دسترسی به اطلاعات دقیقی که نیاز دارید، مستقیماً از رویدادهای SQLAlchemy\(aqs ORM Events \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:events\:.html> استفاده کنید.
.sp
تغییر یافته در نسخه 3.0: به‌طور پیش‌فرض غیرفعال است.

.sp
اضافه‌شده در نسخه 2.0.

.UNINDENT
.sp
تغییر یافته در نسخه 3.1: گزینه \fBSQLALCHEMY_COMMIT_ON_TEARDOWN\fP حذف شد\&.

.sp
تغییر یافته در نسخه 3.0: گزینه‌های \fBSQLALCHEMY_NATIVE_UNICODE\fP، \fBSQLALCHEMY_POOL_SIZE\fP، \fBSQLALCHEMY_POOL_TIMEOUT\fP، \fBSQLALCHEMY_POOL_RECYCLE\fP و \fBSQLALCHEMY_MAX_OVERFLOW\fP حذف شدند\&..SS قالب URL اتصال
.sp
برای توضیحات کامل درباره نحو (syntax)، گویش‌ها و گزینه‌ها، مستندات SQLAlchemy درباره پیکربندی موتور \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:engines\:.html> را ببینید.
.sp
یک URL اتصال پایگاه داده پایه از قالب زیر استفاده می‌کند. نام کاربری، گذرواژه، میزبان و درگاه بسته به نوع پایگاه داده و پیکربندی آن اختیاری هستند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
dialect://username:password@host:port/database
.EE
.UNINDENT
.UNINDENT
.sp
در اینجا چند نمونه رشته اتصال آورده شده است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# SQLite, relative to Flask instance path
sqlite:///project.db

# PostgreSQL
postgresql://scott:tiger@localhost/project

# MySQL / MariaDB
mysql://scott:tiger@localhost/project
.EE
.UNINDENT
.UNINDENT
.sp
پایگاه داده SQLite از کاربر یا میزبان استفاده نمی‌کند، بنابراین URLهای آن همیشه به‌جای دو اسلش با _سه_ اسلش آغاز می‌شوند. مقدار \fBdbname\fP یک مسیر فایل است. مسیرهای مطلق با اسلش _چهارم_ (در لینوکس یا مک) شروع می‌شوند. مسیرهای نسبی نسبت به \fBinstance_path\fP برنامه Flask سنجیده می‌شوند \%<https://\:flask\:.palletsprojects\:.com/\:en/\:stable/\:api/#\:flask\:.Flask\:.instance_path>\&.
.SS گزینه‌های پیش‌فرض درایور
.sp
برخی گزینه‌های پیش‌فرض برای موتورهای SQLite و MySQL تنظیم شده‌اند تا استفاده از آن‌ها به‌طور پیش‌فرض در برنامه‌های وب کاربردی‌تر باشد.
.sp
مسیرهای نسبی فایل SQLite به‌جای دایرکتوری کاری جاری، نسبت به مسیر نمونه (instance path) برنامه Flask سنجیده می‌شوند. پایگاه‌های داده در حافظه (In\-memory) از یک استخر ایستا و \fBcheck_same_thread\fP برای کارکرد در میان درخواست‌ها استفاده می‌کنند.
.sp
سرورهای MySQL (و MariaDB) طوری پیکربندی شده‌اند که اتصال‌هایی را که به مدت ۸ ساعت بدون فعالیت مانده‌اند قطع کنند، که این می‌تواند منجر به خطایی مانند \fB2013: Lost connection to MySQL server during query\fP شود\&. یک مقدار پیش‌فرض \fBpool_recycle\fP برابر با ۲ ساعت (۷۲۰۰ ثانیه) استفاده می‌شود تا اتصال‌ها پیش از سررسید آن وقفه زمانی مجدداً برقرار شوند.
.SS اولویت در پیکربندی موتور
.sp
از آنجا که Flask\-SQLAlchemy از چندین موتور پشتیبانی می‌کند، قوانینی برای اینکه کدام پیکربندی جایگزین دیگری می‌شود وجود دارد. بیشتر برنامه‌ها تنها یک پایگاه داده خواهند داشت و فقط نیاز به استفاده از \fBSQLALCHEMY_DATABASE_URI\fP و \fBSQLALCHEMY_ENGINE_OPTIONS\fP دارند\&.
.INDENT 0.0
.IP \(bu 2
اگر آرگومان \fBengine_options\fP به \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> داده شود، گزینه‌های پیش‌فرض را برای \fIهمه\fP موتورها تنظیم می‌کند. \fBSQLALCHEMY_ECHO\fP مقدار پیش‌فرض را برای هر دو گزینه \fBecho\fP و \fBecho_pool\fP برای تمام موتورها تعیین می‌کند.
.IP \(bu 2
گزینه‌های مربوط به هر موتور در \fBSQLALCHEMY_BINDS\fP بر این مقادیر پیش‌فرض اولویت دارند.
.IP \(bu 2
\fBSQLALCHEMY_ENGINE_OPTIONS\fP بر کلید \fBNone\fP در \fBSQLALCHEMY_BINDS\fP اولویت دارد، و \fBSQLALCHEMY_DATABASE_URI\fP بر کلید \fBurl\fP در گزینه‌های آن موتور اولویت می‌یابد.
.UNINDENT
.SS وقفه‌های زمانی
.sp
برخی از پایگاه‌های داده ممکن است طوری پیکربندی شده باشند که اتصالات غیرفعال را پس از گذشت مدتی ببندند. MySQL و MariaDB به‌طور پیش‌فرض برای این منظور پیکربندی شده‌اند، اما سرویس‌های پایگاه داده نیز ممکن است چنین محدودیتی را پیکربندی کنند. این موضوع می‌تواند به خطایی مانند \fB2013: Lost connection to MySQL server during query\fP منجر شود\&.
.sp
اگر با این خطا مواجه شدید، مقدار \fBpool_recycle\fP را در گزینه‌های موتور به مقداری کمتر از وقفه زمانی پایگاه داده تنظیم کنید.
.sp
همچنین، اگر انتظار دارید پایگاه داده مکرراً اتصالات را ببندد، مانند زمانی که درون یک کانتینر در حال اجراست که ممکن است بازراه‌اندازی شود، می‌توانید \fBpool_pre_ping\fP را تنظیم کنید.
.sp
برای اطلاعات بیشتر، مستندات SQLAlchemy درباره مدیریت قطع اتصال \%<https://\:docs\:.sqlalchemy\:.org/\:core/\:pooling\:.html#\:dealing-with-disconnects> را ببینید..SS مدل‌ها و جدول‌ها (Models and Tables)
.sp
برای تعریف مدل‌ها از کلاس \fBdb.Model\fP یا برای ایجاد جدول‌ها از کلاس \fBdb.Table\fP استفاده کنید.
هر دو مورد کلیدهای مقیدسازی (bind keys) در Flask\-SQLAlchemy را برای انتساب به یک موتور (engine) مشخص مدیریت می‌کنند.
.SS مقداردهی اولیه کلاس پایه (Initializing the Base Class)
.sp
\fBSQLAlchemy\fP نسخهٔ 2.x چند کلاس پایهٔ ممکن را برای مدل‌های شما ارائه می‌دهد:
DeclarativeBase \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBase> یا DeclarativeBaseNoMeta \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBaseNoMeta>\&.
.sp
یک زیرکلاس از یکی از این کلاس‌ها ایجاد کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
  pass
.EE
.UNINDENT
.UNINDENT
.sp
در صورت تمایل، می‌توانید پشتیبانی درونی SQLAlchemy از کلاس‌های داده (data classes) \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:changelog/\:whatsnew_20\:.html#\:native-support-for-dataclasses-mapped-as-orm-models>
را با افزودن \fIMappedAsDataclass\fP به عنوان یک کلاس والد دیگر فعال کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass

class Base(DeclarativeBase, MappedAsDataclass):
  pass
.EE
.UNINDENT
.UNINDENT
.sp
به صورت اختیاری می‌توانید شیء \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> را با یک شیء سفارشی
\fBMetaData\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.MetaData> بسازید. این کار به شما امکان می‌دهد یک قرارداد
نام‌گذاری قیدها (constraint naming convention) سفارشی \%<https://\:docs\:.sqlalchemy\:.org/\:core/\:constraints\:.html#\:constraint-naming-conventions>\& مشخص کنید. این قابلیت نام‌های قیدها را یکدست و قابل پیش‌بینی می‌کند که
هنگام استفاده از مهاجرت‌ها (migrations) طبق توضیحات Alembic \%<https://\:alembic\:.sqlalchemy\:.org/\:en/\:latest/\:naming\:.html>\& بسیار سودمند است.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy import MetaData

class Base(DeclarativeBase):
    metadata = MetaData(naming_convention={
        \(dqix\(dq: \(aqix_%(column_0_label)s\(aq,
        \(dquq\(dq: \(dquq_%(table_name)s_%(column_0_name)s\(dq,
        \(dqck\(dq: \(dqck_%(table_name)s_%(constraint_name)s\(dq,
        \(dqfk\(dq: \(dqfk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s\(dq,
        \(dqpk\(dq: \(dqpk_%(table_name)s\(dq
    })
.EE
.UNINDENT
.UNINDENT
.SS مقداردهی اولیه افزونه (Initialize the Extension)
.sp
پس از تعریف کلاس پایه، شیء \fBdb\fP را با استفاده از سازندهٔ \fBSQLAlchemy\fP ایجاد کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
db = SQLAlchemy(model_class=Base)
.EE
.UNINDENT
.UNINDENT
.SS تعریف مدل‌ها (Defining Models)
.sp
برای دریافت اطلاعات کامل پیرامون تعریف اعلانی (declarative) کلاس‌های مدل، به مستندات اعلانی SQLAlchemy \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:declarative_tables\:.html>
مراجعه کنید.
.sp
برای ساخت یک کلاس مدل، از \fBdb.Model\fP ارث‌بری کنید. بر خلاف SQLAlchemy خام،
اگر \fB__tablename__\fP تنظیم نشده باشد و ستون کلید اصلی تعریف شده باشد، مدل Flask\-SQLAlchemy
به طور خودکار نام جدول را تولید می‌کند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy.orm import Mapped, mapped_column

class User(db.Model):
    id: Mapped[int] = mapped_column(db.Integer, primary_key=True)
    username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False)
    email: Mapped[str] = mapped_column(db.String)
.EE
.UNINDENT
.UNINDENT
.sp
تعریف یک مدل، آن را در پایگاه داده ایجاد نمی‌کند. پس از تعریف آن‌ها، از \fBcreate_all()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.create_all>
برای ایجاد مدل‌ها و جدول‌ها استفاده کنید. اگر مدل‌ها را در زیرماژول‌ها تعریف کرده‌اید،
باید پیش از فراخوانی \fBcreate_all\fP آن‌ها را وارد (import) کنید تا SQLAlchemy از آن‌ها آگاه باشد\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
with app.app_context():
    db.create_all()
.EE
.UNINDENT
.UNINDENT.SS تعریف جدول‌ها (Defining Tables)
.sp
برای اطلاعات کامل درباره تعریف اشیاء جدول، به مستندات جدول SQLAlchemy در \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html> مراجعه کنید.
.sp
برای تعریف جدول‌ها، نمونه‌هایی از \fBdb.Table\fP ایجاد کنید. این کلاس نام جدول و سپس هر ستون و سایر اجزای جدول مانند ستون‌ها و محدودیت‌ها را می‌پذیرد. برخلاف SQLAlchemy خام، آرگومان \fBmetadata\fP الزامی نیست. یک metadata بر اساس آرگومان \fBbind_key\fP انتخاب خواهد شد، یا از مقدار پیش‌فرض استفاده می‌شود.
.sp
یک دلیل رایج برای ایجاد مستقیم جدول، هنگام تعریف روابط چند‌به‌چند (many-to-many) است. جدول رابط (association table) نیازی به کلاس مدل اختصاصی خود ندارد، چرا که از طریق ویژگی‌های رابطه مرتبط در مدل‌های مربوطه در دسترس خواهد بود.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import sqlalchemy as sa

user_book_m2m = db.Table(
    \(dquser_book\(dq,
    sa.Column(\(dquser_id\(dq, sa.ForeignKey(User.id), primary_key=True),
    sa.Column(\(dqbook_id\(dq, sa.ForeignKey(Book.id), primary_key=True),
)
.EE
.UNINDENT
.UNINDENT
.SS بازتاب جدول‌ها (Reflecting Tables)
.sp
اگر به پایگاه‌داده‌ای متصل می‌شوید که از قبل دارای جدول است، SQLAlchemy می‌تواند آن طرح‌واره (schema) را شناسایی کرده و جدول‌ها را به همراه ستون‌هایشان به‌طور خودکار بسازد. به این عمل بازتاب (reflection) گفته می‌شود. این جدول‌ها همچنین می‌توانند به جای تعریف مدل کامل، با استفاده از ویژگی \fB__table__\fP به کلاس‌های مدل تخصیص داده شوند.
.sp
متد \fBreflect()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.reflect> را روی افزونه فراخوانی کنید. این متد تمام جدول‌ها را برای هر bind key بازتاب می‌دهد. ویژگی \fBtables\fP مربوط به هر metadata شامل اشیاء جدول شناسایی‌شده خواهد بود.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
with app.app_context():
    db.reflect()

class User:
    __table__ = db.metadatas[\(dqauth\(dq].tables[\(dquser\(dq]
.EE
.UNINDENT
.UNINDENT
.sp
در بیشتر موارد، تعریف کلاس‌های مدل توسط خودتان نگه‌داری‌پذیرتر خواهد بود. شما تنها نیاز دارید مدل‌ها و ستون‌هایی را که واقعاً استفاده می‌کنید تعریف نمایید، حتی اگر به یک طرح‌واره گسترده‌تر متصل شوید. محیط‌های توسعه یکپارچه (IDEها) ویژگی‌های موجود را شناسایی می‌کنند و ابزارهای مهاجرت مانند Alembic می‌توانند تغییرات را تشخیص داده و مهاجرت‌های طرح‌واره را تولید کنند.
.SS اصلاح و پرس‌وجوی داده‌ها (Modifying and Querying Data)
.SS درج، به‌روزرسانی، حذف (Insert, Update, Delete)
.sp
برای کسب اطلاعات بیشتر پیرامون اصلاح داده‌ها با ORM، به آموزش ORM در SQLAlchemy در \%<https://\:docs\:.sqlalchemy\:.org/\:tutorial/\:orm_data_manipulation\:.html> و سایر مستندات SQLAlchemy مراجعه کنید.
.sp
برای درج داده، شیء مدل را به \fBdb.session.add()\fP ارسال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
user = User()
db.session.add(user)
db.session.commit()
.EE
.UNINDENT
.UNINDENT
.sp
برای به‌روزرسانی داده، ویژگی‌های روی اشیاء مدل را تغییر دهید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
user.verified = True
db.session.commit()
.EE
.UNINDENT
.UNINDENT
.sp
برای حذف داده، شیء مدل را به \fBdb.session.delete()\fP ارسال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
db.session.delete(user)
db.session.commit()
.EE
.UNINDENT
.UNINDENT
.sp
پس از اصلاح داده‌ها، باید \fBdb.session.commit()\fP را فراخوانی کنید تا تغییرات در پایگاه‌داده اعمال (commit) شوند. در غیر این صورت، در پایان درخواست نادیده گرفته شده و دور ریخته خواهند شد..SS Select
.sp
برای اطلاعات بیشتر در مورد پرس‌وجوی داده‌ها با استفاده از ORM، به راهنمای پرس‌وجوی SQLAlchemy \%<https://\:docs\:.sqlalchemy\:.org/\:orm/\:queryguide\:.html> و سایر مستندات SQLAlchemy مراجعه کنید.
.sp
پرس‌وجوها از طریق \fBdb.session.execute()\fP اجرا می‌شوند. آن‌ها را می‌توان با استفاده از \fBselect()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:selectable\:.html#\:sqlalchemy\:.sql\:.expression\:.select> ساخت. اجرای یک select شیء \fBResult\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Result> را بازمی‌گرداند که متدهای متعددی برای کار با ردیف‌های بازگردانده‌شده دارد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
user = db.session.execute(db.select(User).filter_by(username=username)).scalar_one()

users = db.session.execute(db.select(User).order_by(User.username)).scalars()
.EE
.UNINDENT
.UNINDENT
.SS پرس‌وجوها برای نماها (Queries for Views)
.sp
اگر یک تابع view در Flask می‌نویسید، اغلب مفید است که برای ورودی‌های ناموجود، خطای \fB404 Not Found\fP بازگردانید. Flask\-SQLAlchemy چند متد پرس‌وجوی اضافی در اختیارتان می‌گذارد.
.INDENT 0.0
.IP \(bu 2
متد \fBSQLAlchemy.get_or_404()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.get_or_404> در صورتی که ردیف با شناسه داده‌شده وجود نداشته باشد یک خطای 404 ایجاد می‌کند، در غیر این صورت نمونه مورد نظر را بازمی‌گرداند.
.IP \(bu 2
متد \fBSQLAlchemy.first_or_404()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.first_or_404> در صورتی که پرس‌وجو هیچ نتیجه‌ای بازنگرداند یک خطای 404 ایجاد می‌کند، در غیر این صورت اولین نتیجه را بازمی‌گرداند.
.IP \(bu 2
متد \fBSQLAlchemy.one_or_404()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.one_or_404> در صورتی که پرس‌وجو دقیقاً یک نتیجه بازنگرداند یک خطای 404 ایجاد می‌کند، در غیر این صورت نتیجه را بازمی‌گرداند.
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
@app.route(\(dq/user\-by\-id/<int:id>\(dq)
def user_by_id(id):
    user = db.get_or_404(User, id)
    return render_template(\(dqshow_user.html\(dq, user=user)

@app.route(\(dq/user\-by\-username/<username>\(dq)
def user_by_username(username):
    user = db.one_or_404(db.select(User).filter_by(username=username))
    return render_template(\(dqshow_user.html\(dq, user=user)
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید یک پیام سفارشی به خطای 404 اضافه کنید:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.EX
user = db.one_or_404(
    db.select(User).filter_by(username=username),
    description=f\(dqNo user named \(aq{username}\(aq.\(dq
)
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS رابط پرس‌وجوی قدیمی (Legacy Query Interface)
.sp
ممکن است استفاده از \fBModel.query\fP یا \fBsession.query\fP را برای ساخت پرس‌وجوها مشاهده کنید. این رابط پرس‌وجو در SQLAlchemy قدیمی (legacy) محسوب می‌شود. ترجیحاً به جای آن از \fBsession.execute(select(...))\fP استفاده کنید.
.sp
برای دیدن مستندات به Legacy Query Interface \%<> مراجعه کنید.
.SS صفحه‌بندی نتایج پرس‌وجو (Paging Query Results)
.sp
اگر نتایج زیادی دارید، ممکن است بخواهید در هر نوبت فقط تعداد مشخصی را نمایش دهید، تا به کاربر اجازه دهید با کلیک روی پیوندهای بعدی و قبلی صفحات داده را ببیند. به این عمل گاهی \fIpagination\fP (صفحه‌بندی) گفته می‌شود و از فعل \fIpaginate\fP استفاده می‌کند.
.sp
متد \fBSQLAlchemy.paginate()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.paginate> را روی یک عبارت select فراخوانی کنید تا یک شیء \fBPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination> دریافت کنید.
.sp
در طول یک درخواست، این متد آرگومان‌های \fBpage\fP و \fBper_page\fP را از رشته پرس‌وجوی \fBrequest.args\fP دریافت می‌کند. برای جلوگیری از درخواست بیش از حد نتایج در یک صفحه واحد توسط کاربران، مقدار \fBmax_per_page\fP را ارسال کنید. در صورت عدم تعیین، مقادیر پیش‌فرض صفحه ۱ با ۲۰ آیتم در هر صفحه خواهد بود.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
page = db.paginate(db.select(User).order_by(User.join_date))
return render_template(\(dquser/list.html\(dq, page=page)
.EE
.UNINDENT
.UNINDENT.SS نمایش آیتم‌ها
.sp
صفت \fBPagination.items\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination\:.items> شیء \fBPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination>، فهرست آیتم‌های صفحه جاری است. همچنین می‌توان مستقیماً روی خود شیء پیمایش کرد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
<ul>
  {% for user in page %}
    <li>{{ user.username }}
  {% endfor %}
</ul>
.EE
.UNINDENT
.UNINDENT
.SS ویجت انتخاب صفحه
.sp
شیء \fBPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination> صفت‌هایی دارد که می‌توان با پیمایش روی شماره صفحات و بررسی صفحه جاری، از آن‌ها برای ایجاد یک ویجت انتخاب صفحه استفاده کرد. متد \fBiter_pages()\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination\:.iter_pages> حداکثر سه گروه از اعداد را که با \fBNone\fP\& جدا شده‌اند تولید می‌کند. حالت پیش‌فرض آن نمایش ۲ شماره صفحه در هر دو انتها، ۲ شماره پیش از صفحه جاری، خود صفحه جاری، و ۴ شماره پس از صفحه جاری است. برای نمونه، اگر ۲۰ صفحه وجود داشته باشد و صفحه جاری ۷ باشد، مقادیر زیر حاصل می‌شوند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
users.iter_pages()
[1, 2, None, 5, 6, 7, 8, 9, 10, 11, None, 19, 20]
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید از صفت \fBtotal\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination\:.total> برای نمایش تعداد کل نتایج، و از \fBfirst\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination\:.first> و \fBlast\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination\:.last> برای نمایش محدوده آیتم‌های صفحه جاری استفاده کنید.
.sp
ماکروی Jinja زیر یک ویجت صفحه‌بندی ساده را ارائه می‌دهد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{% macro render_pagination(pagination, endpoint) %}
  <div class=page\-items>
    {{ pagination.first }} \- {{ pagination.last }} of {{ pagination.total }}
  </div>
  <div class=pagination>
    {% for page in pagination.iter_pages() %}
      {% if page %}
        {% if page != pagination.page %}
          <a href=\(dq{{ url_for(endpoint, page=page) }}\(dq>{{ page }}</a>
        {% else %}
          <strong>{{ page }}</strong>
        {% endif %}
      {% else %}
        <span class=ellipsis>…</span>
      {% endif %}
    {% endfor %}
  </div>
{% endmacro %}
.EE
.UNINDENT
.UNINDENT
.SS کانتکست برنامه Flask
.sp
برای اجرای پرس‌وجوها و دسترسی به \fBdb.engine\fP و \fBdb.session\fP\& به یک کانتکست فعال برنامه Flask نیاز است. دلیل این امر آن است که محدوده نشست به کانتکست محدود شده است تا پس از هر درخواست یا دستور CLI به‌درستی پاک‌سازی شود.
.sp
صرف‌نظر از نحوه مقداردهی اولیه برنامه با این افزونه، برنامه برای استفاده‌های بعدی ذخیره نمی‌شود. در عوض، این افزونه از پروکسی \fBcurrent_app\fP فلاسک برای دریافت برنامه فعال استفاده می‌کند، که این امر نیازمند یک کانتکست برنامه فعال است.
.SS کانتکست خودکار
.sp
هنگامی که Flask در حال مدیریت یک درخواست یا یک دستور CLI است، کانتکست برنامه به‌طور خودکار اعمال (push) می‌شود. بنابراین برای استفاده از پایگاه‌داده هنگام درخواست‌ها یا دستورهای CLI نیازی به انجام کار خاصی ندارید.
.SS کانتکست دستی
.sp
اگر در زمانی که کانتکست برنامه فعال نیست سعی در استفاده از پایگاه‌داده داشته باشید، با خطای زیر مواجه خواهید شد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
RuntimeError: Working outside of application context.

This typically means that you attempted to use functionality that needed
the current application. To solve this, set up an application context
with app.app_context(). See the documentation for more information.
.EE
.UNINDENT
.UNINDENT
.sp
اگر در موقعیتی قرار گرفتید که به پایگاه‌داده نیاز دارید اما کانتکست فعالی وجود ندارد، می‌توانید با استفاده از \fBapp_context\fP\& یکی را فعال (push) کنید. برای نمونه، این کار هنگام فراخوانی \fBdb.create_all\fP جهت ساخت جدول‌ها متداول است.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def create_app():
    app = Flask(__name__)
    app.config.from_object(\(dqproject.config\(dq)

    import project.models

    with app.app_context():
        db.create_all()

    return app
.EE
.UNINDENT
.UNINDENT.SS "آزمون‌ها (Tests)"
.sp
اگر برنامهٔ خود را با استفاده از کلاینت آزمایشی Flask جهت ارسال درخواست به endpointهای خود می‌آزمایید، کانتکست به عنوان بخشی از درخواست در دسترس خواهد بود. اگر نیاز دارید موردی را مستقیماً روی پایگاه داده یا مدل‌های خود بیازمایید، به‌جای اقدام از طریق یک درخواست، باید کانتکست را به‌صورت دستی اعمال (push) کنید.
.sp
کانتکست را دقیقاً در همان‌جایی و به همان میزانی که برای هر آزمون مورد نیاز است push کنید. کانتکست برنامه (application context) را به‌صورت سراسری برای تمام آزمون‌ها پوش نکنید، چرا که می‌تواند در روند پاک‌سازی session تداخل ایجاد کند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def test_user_model(app):
    user = User()

    with app.app_context():
        db.session.add(user)
        db.session.commit()
.EE
.UNINDENT
.UNINDENT
.sp
اگر متوجه شدید که آزمون‌های بسیاری را به این شکل می‌نویسید، می‌توانید از یک fixture در pytest برای پوش کردن کانتکست جهت یک آزمون مشخص استفاده کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
import pytest

@pytest.fixture
def app_ctx(app):
    with app.app_context():
        yield

@pytest.mark.usefixtures(\(dqapp_ctx\(dq)
def test_user_model():
    user = User()
    db.session.add(user)
    db.session.commit()
.EE
.UNINDENT
.UNINDENT
.SS "چندین پایگاه داده با پیوندها (Multiple Databases with Binds)"
.sp
SQLAlchemy می‌تواند به‌طور هم‌زمان به بیش از یک پایگاه داده متصل شود. این ابزار به موتورهای مختلف با عنوان \(dqbinds\(dq (پیوندها) اشاره می‌کند. Flask\-SQLAlchemy سازوکار پیوندها را با مرتبط ساختن هر موتور با یک رشتهٔ کوتاه تحت عنوان یک \(dqbind key\(dq، و سپس پیوند دادن هر مدل و جدول با یک bind key ساده‌سازی می‌کند. نشست (session) بر اساس bind key مربوط به موردی که مورد پرس‌وجو قرار می‌گیرد، موتور مورد استفاده را انتخاب خواهد کرد. اگر هیچ bind key تعیین نشده باشد، از موتور پیش‌فرض استفاده می‌شود.
.SS "پیکربندی پیوندها (Configuring Binds)"
.sp
پیوند پیش‌فرض همچنان با مقداردهی \fBSQLALCHEMY_DATABASE_URI\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_DATABASE_URI> و \fBSQLALCHEMY_ENGINE_OPTIONS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_ENGINE_OPTIONS> برای هرگونه گزینه‌های موتور پیکربندی می‌شود. پیوندهای اضافی در \fBSQLALCHEMY_BINDS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_BINDS> تعیین می‌شوند که یک دیکشنری نگاشت‌کنندهٔ bind keyها به URLهای موتور است. برای تعیین گزینه‌های موتور برای یک پیوند، مقدار می‌تواند به‌جای تنها یک رشتهٔ URL، دیکشنری‌ای از گزینه‌های موتور همراه با کلید \fB\(dqurl\(dq\fP باشد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
SQLALCHEMY_DATABASE_URI = \(dqpostgresql:///main\(dq
SQLALCHEMY_BINDS = {
    \(dqmeta\(dq: \(dqsqlite:////path/to/meta.db\(dq,
    \(dqauth\(dq: {
        \(dqurl\(dq: \(dqmysql://localhost/users\(dq,
        \(dqpool_recycle\(dq: 3600,
    },
}
.EE
.UNINDENT
.UNINDENT
.SS "تعریف مدل‌ها و جدول‌ها با پیوندها (Defining Models and Tables with Binds)"
.sp
Flask\-SQLAlchemy برای هر پیوندِ پیکربندی‌شده، یک metadata و موتور ایجاد خواهد کرد. مدل‌ها و جدول‌های دارای یک bind key در metadata مربوطه ثبت می‌شوند، و session با استفاده از موتور متناظر روی آن‌ها پرس‌وجو انجام می‌دهد.
.sp
برای تنظیم پیوند برای یک مدل، صفت کلاسی \fB__bind_key__\fP را تنظیم کنید. تعیین نکردن bind key معادل تنظیم آن روی \fBNone\fP، یعنی کلید پیش‌فرض است.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class User(db.Model):
    __bind_key__ = \(dqauth\(dq
    id = db.Column(db.Integer, primary_key=True)
.EE
.UNINDENT
.UNINDENT
.sp
مدل‌هایی که از این مدل ارث‌بری می‌کنند، همان bind key را به اشتراک خواهند گذاشت، یا می‌توانند آن را بازنویسی (override) کنند.
.sp
برای تنظیم پیوند برای یک جدول، آرگومان کلیدواژه‌ای \fBbind_key\fP را پاس دهید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
user_table = db.Table(
    \(dquser\(dq,
    db.Column(\(dqid\(dq, db.Integer, primary_key=True),
    bind_key=\(dqauth\(dq,
)
.EE
.UNINDENT
.UNINDENT
.sp
در نهایت، session مقدار bind key را در metadata مرتبط با مدل یا جدول جستجو می‌کند. این وابستگی در زمان ایجاد شکل می‌گیرد؛ بنابراین، تغییر bind key پس از ایجاد یک مدل یا جدول هیچ تأثیری نخواهد داشت..SS دسترسی به فراداده و موتورها (Accessing Metadata and Engines)
.sp
ممکن است نیاز به بررسی فراداده یا موتور برای یک bind داشته باشید. توجه داشته باشید که باید پرس‌وجوها را از طریق session اجرا کنید، نه مستقیماً روی engine.
.sp
موتور پیش‌فرض \fBSQLAlchemy.engine\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.engine> و فراداده پیش‌فرض
\fBSQLAlchemy.metadata\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.metadata>\& است. \fBSQLAlchemy.engines\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.engines> و
\fBSQLAlchemy.metadatas\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.metadatas> دیکشنری‌هایی هستند که تمام کلیدهای bind را نگاشت می‌کنند.
.SS ایجاد و حذف جدول‌ها (Creating and Dropping Tables)
.sp
متدهای \fBcreate_all()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.create_all> و \fBdrop_all()\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy\:.drop_all> به‌طور
پیش‌فرض بر روی تمام bindها عمل می‌کنند. آرگومان \fBbind_key\fP در این متدها می‌تواند یک رشته یا
\fBNone\fP برای عمل روی یک bind تکی، یا فهرستی از رشته‌ها یا \fBNone\fP برای عمل بر روی
زیرمجموعه‌ای از bindها باشد. از آنجا که این متدها به engineها دسترسی دارند، باید درون یک
application context فراخوانی شوند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# create tables for all binds
db.create_all()

# create tables for the default and \(dqauth\(dq binds
db.create_all(bind_key=[None, \(dqauth\(dq])

# create tables for the \(dqmeta\(dq bind
db.create_all(bind_key=\(dqmeta\(dq)

# drop tables for the default bind
db.drop_all(bind_key=None)
.EE
.UNINDENT
.UNINDENT
.SS ثبت اطلاعات پرس‌وجو (Recording Query Information)
.sp
\fBهشدار:\fP
.INDENT 0.0
.INDENT 3.5
این ویژگی صرفاً برای اشکال‌زدایی در نظر گرفته شده است.
.UNINDENT
.UNINDENT
.sp
ابزار Flask\-SQLAlchemy می‌تواند برخی اطلاعات را درباره هر پرس‌وجویی که در طول یک
درخواست اجرا می‌شود ثبت کند. این اطلاعات را می‌توان سپس برای کمک به اشکال‌زدایی کارایی بازیابی کرد. برای
مثال، می‌تواند نشان دهد که یک رابطه تعداد زیادی دستور select مجزا اجرا کرده است، یا
پرس‌وجویی را که اجرای آن زمان زیادی برده آشکار سازد.
.sp
برای فعال‌سازی این ویژگی، \fBSQLALCHEMY_RECORD_QUERIES\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_RECORD_QUERIES> را در پیکربندی
برنامه Flask روی \fBTrue\fP تنظیم کنید. از \fBget_recorded_queries()\fP \%<#\:flask_sqlalchemy\:.record_queries\:.get_recorded_queries> برای دریافت فهرستی از اشیاء حاوی اطلاعات پرس‌وجو استفاده کنید. هر
شیء دارای مشخصه‌های زیر است:
.INDENT 0.0
.TP
.B \fBstatement\fP
رشته SQL تولیدشده توسط SQLAlchemy همراه با جایگزین‌های پارامتر.
.TP
.B \fBparameters\fP
پارامترهای ارسال‌شده همراه با عبارت SQL.
.TP
.B \fBstart_time\fP / \fBend_time\fP
اطلاعات زمان‌بندی درباره زمان آغاز اجرای پرس‌وجو و زمان بازگشت نتایج.
دقت و مقدار آن به سیستم‌عامل بستگی دارد.
.TP
.B \fBduration\fP
مدت‌زمانی که اجرای پرس‌وجو به ثانیه طول کشیده است.
.TP
.B \fBlocation\fP
توضیحی متنی درباره اینکه پرس‌وجو در کجای کد برنامه اجرا شده است. این مقدار
ممکن است در برخی موارد نامشخص باشد.
.UNINDENT
.SS ردیابی تغییرات (Tracking Modifications)
.sp
\fBهشدار:\fP
.INDENT 0.0
.INDENT 3.5
ردیابی تغییرات، سربار پردازشی قابل توجهی به همراه دارد. در بیشتر موارد، استفاده مستقیم
از رویدادهای SQLAlchemy \%<https://\:docs\:.sqlalchemy\:.org/\:core/\:event\:.html> نتیجه بهتری به همراه خواهد داشت.
.UNINDENT
.UNINDENT
.sp
ابزار Flask\-SQLAlchemy می‌تواند session خود را طوری تنظیم کند که درج‌ها، به‌روزرسانی‌ها و حذف‌های
مدل‌ها را ردیابی کرده و سپس یک سیگنال Blinker را به همراه فهرستی از این تغییرات، پیش از فراخوانی‌های
\fBsession.flush()\fP و \fBsession.commit()\fP یا در حین آن‌ها ارسال نماید.
.sp
برای فعال‌سازی این ویژگی، \fBSQLALCHEMY_TRACK_MODIFICATIONS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_TRACK_MODIFICATIONS> را در پیکربندی برنامه Flask
تنظیم کنید. سپس یک شنونده به \fBmodels_committed\fP \%<#\:flask_sqlalchemy\:.track_modifications\:.models_committed> (که پس از commit منتشر می‌شود) یا
\fBbefore_models_committed\fP \%<#\:flask_sqlalchemy\:.track_modifications\:.before_models_committed> (که پیش از commit منتشر می‌شود) اضافه کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from flask_sqlalchemy.track_modifications import models_committed

def get_modifications(sender: Flask, changes: list[tuple[t.Any, str]]) \-> None:
    ...

models_committed.connect(get_modifications)
.EE
.UNINDENT
.UNINDENT.SS سفارشی‌سازی پیشرفته
.sp
اشیای مختلفی که توسط افزونه مدیریت می‌شوند را می‌توان با ارسال آرگومان‌ها به
سازندهٔ \fBSQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy> سفارشی‌سازی کرد.
.SS کلاس مدل
.sp
تمام مدل‌های SQLAlchemy از یک کلاس پایهٔ اعلانی ارث‌بری می‌کنند. این کلاس در
Flask\-SQLAlchemy به‌صورت \fBdb.Model\fP ارائه می‌شود که همهٔ مدل‌ها آن را گسترش می‌دهند. این رفتار را می‌توان با
ایجاد زیرکلاس از حالت پیش‌فرض و ارسال کلاس سفارشی به \fBmodel_class\fP\& سفارشی‌سازی کرد.
.sp
مثال زیر به هر مدل یک کلید اصلی عدد صحیح، یا یک کلید خارجی برای
وراثت جدول پیوسته (joined\-table inheritance) اختصاص می‌دهد.
.sp
\fBنکته:\fP
.INDENT 0.0
.INDENT 3.5
استفاده از کلید اصلی عدد صحیح برای همه چیز لزوماً بهترین طراحی پایگاه داده نیست
(این موضوع به نیازمندی‌های پروژهٔ شما بستگی دارد)، این تنها یک مثال است.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy import Integer, String, ForeignKey
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, declared_attr

class Base(DeclarativeBase):
    @declared_attr.cascading
    @classmethod
    def id(cls):
        for base in cls.__mro__[1:\-1]:
            if getattr(base, \(dq__table__\(dq, None) is not None:
                    return mapped_column(ForeignKey(base.id), primary_key=True)
            else:
                return mapped_column(Integer, primary_key=True)

db = SQLAlchemy(app, model_class=Base)

class User(db.Model):
    name: Mapped[str] = mapped_column(String)

class Employee(User):
    title: Mapped[str] = mapped_column(String)
.EE
.UNINDENT
.UNINDENT
.SS مدل‌های انتزاعی و میکسین‌ها
.sp
اگر رفتاری تنها برای برخی مدل‌ها مورد نیاز است و نه همهٔ آن‌ها، از یک کلاس پایهٔ مدل
انتزاعی برای سفارشی‌سازی همان مدل‌ها استفاده کنید. برای مثال، اگر لازم باشد برخی مدل‌ها زمان
ایجاد یا به‌روزرسانی شدن خود را پیگیری کنند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from datetime import datetime
from sqlalchemy import DateTime, Integer, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, declared_attr

class TimestampModel(db.Model):
    __abstract__ = True
    created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
    updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

class Author(db.Model):
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    username: Mapped[str] = mapped_column(String, unique=True, nullable=False)

class Post(TimestampModel):
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    title: Mapped[str] = mapped_column(String, nullable=False)
.EE
.UNINDENT
.UNINDENT
.sp
این کار را می‌توان با یک کلاس میکسین (mixin) و ارث‌بری جداگانه از \fBdb.Model\fP نیز انجام داد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class TimestampMixin:
    created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow)
    updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)

class Post(TimestampMixin, db.Model):
    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    title: Mapped[str] = mapped_column(String, nullable=False)
.EE
.UNINDENT
.UNINDENT.SS غیرفعال‌سازی تولید نام جدول (Disabling Table Name Generation)
.sp
برخی پروژه‌ها ترجیح می‌دهند مقدار \fB__tablename__\fP هر مدل را به صورت دستی تعیین کنند و به تشخیص و تولید خودکار Flask\-SQLAlchemy متکی نباشند. روش ساده برای این کار، تنظیم \fB__tablename__\fP برای هر مدل و دست نزدن به کلاس پایه است. با این حال، تولید نام جدول را می‌توان با تنظیم \fIdisable_autonaming=True\fP در سازنده \fISQLAlchemy\fP غیرفعال کرد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class Base(sa_orm.DeclarativeBase):
    pass

db = SQLAlchemy(app, model_class=Base, disable_autonaming=True)
.EE
.UNINDENT
.UNINDENT
.SS کلاس Session (Session Class)
.sp
کلاس \fBSession\fP \%<#\:flask_sqlalchemy\:.session\:.Session> در Flask\-SQLAlchemy بر اساس کلید bind مرتبط با مدل یا جدول، موتور مناسب را برای اجرای پرس‌وجو انتخاب می‌کند. با این حال، استراتژی‌های دیگری مانند شاردینگ افقی (horizontal sharding) وجود دارند که می‌توان آن‌ها را با یک کلاس session متفاوت پیاده‌سازی کرد. از کلید \fBclass_\fP در آرگومان \fBsession_options\fP افزونه برای تغییر کلاس session استفاده می‌شود.
.sp
Flask\-SQLAlchemy همواره نمونه افزونه را به عنوان آرگومان \fBdb\fP به session ارسال می‌کند، بنابراین این کلاس برای ادامه کار باید آن را بپذیرد. از این موضوع می‌توان برای دسترسی به \fBdb.engines\fP\& استفاده کرد.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from sqlalchemy.ext.horizontal_shard import ShardedSession
from flask_sqlalchemy.session import Session

class CustomSession(ShardedSession, Session):
    ...

db = SQLAlchemy(session_options={\(dqclass_\(dq: CustomSession})
.EE
.UNINDENT
.UNINDENT
.SS کلاس Query (Query Class)
.sp
\fBهشدار:\fP
.INDENT 0.0
.INDENT 3.5
رابط query در SQLAlchemy قدیمی (legacy) محسوب می‌شود. این شامل
\fBsession.query\fP، \fBModel.query\fP، \fBdb.Query\fP و رابطه‌های \fBlazy=\(dqdynamic\(dq\fP
است. ترجیحاً به جای آن از \fBsession.execute(select(...))\fP استفاده کنید.
.UNINDENT
.UNINDENT
.sp
سفارشی‌سازی رابط پرس‌وجوی (query) مورد استفاده توسط session، مدل‌ها و
رابطه‌ها امکان‌پذیر است. این قابلیت می‌تواند برای افزودن متدهای query بیشتر به کار رود.
برای مثال، می‌توانید متد \fBget_or\fP را اضافه کنید که یک سطر را دریافت کرده یا یک مقدار پیش‌فرض را برمی‌گرداند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
from flask_sqlalchemy.query import Query

class GetOrQuery(Query):
    def get_or(self, ident, default=None):
        out = self.get(ident)

        if out is None:
            return default

        return out

db = SQLAlchemy(query_class=GetOrQuery)

user = User.query.get_or(user_id, anonymous_user)
.EE
.UNINDENT
.UNINDENT
.sp
ارسال آرگومان \fBquery_class\fP موجب سفارشی‌سازی \fBdb.Query\fP، \fBdb.session.query\fP،
\fBModel.query\fP و رابطه‌های \fBdb.relationship(lazy=\(dqdynamic\(dq)\fP می‌شود. همچنین
سفارشی‌سازی این موارد به ازای هر شیء به صورت جداگانه امکان‌پذیر است.
.sp
برای سفارشی‌سازی ویژگی \fBquery\fP یک مدل خاص، مشخصه \fBquery_class\fP را روی
کلاس مدل تنظیم کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class User(db.Model):
    query_class = GetOrQuery
.EE
.UNINDENT
.UNINDENT
.sp
برای سفارشی‌سازی یک رابطه پویای (dynamic) خاص، آرگومان \fBquery_class\fP را به
رابطه ارسال کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
db.relationship(User, lazy=\(dqdynamic\(dq, query_class=GetOrQuery)
.EE
.UNINDENT
.UNINDENT
.sp
برای سفارشی‌سازی صرفاً \fBsession.query\fP، کلید \fBquery_cls\fP را به
آرگومان \fBsession_options\fP در سازنده ارسال کنید.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
db = SQLAlchemy(session_options={\(dqquery_cls\(dq: GetOrQuery})
.EE
.UNINDENT
.UNINDENT.SH "مرجع API (API REFERENCE)"
.SS API
.SS "افزونه (Extension)"
.INDENT 0.0
.TP
.B class flask_sqlalchemy.SQLAlchemy(app=None, *, metadata=None, session_options=None, query_class=<class \(aqflask_sqlalchemy.query.Query\(aq>, model_class=<class \(aqflask_sqlalchemy.model.Model\(aq>, engine_options=None, add_models_to_shell=True, disable_autonaming=False)
ابزار SQLAlchemy را با Flask یکپارچه‌سازی می‌کند. این کلاس برپایی یک یا چند موتور (engine)، ارتباط جدول‌ها و مدل‌ها با موتورهای مشخص، و پاک‌سازی اتصال‌ها و نشست‌ها (sessions) را پس از هر درخواست مدیریت می‌کند.
.sp
تنها پیکربندی موتور به هر برنامه اختصاص دارد؛ سایر موارد مانند مدل، جدول، متادیتا و نشست بین تمام برنامه‌هایی که از آن نمونهٔ افزونه استفاده می‌کنند به اشتراک گذاشته می‌شود. متد \fBinit_app()\fP را برای پیکربندی افزونه روی یک برنامه فراخوانی کنید.
.sp
پس از ایجاد افزونه، کلاس‌های مدل را با زیرکلاس‌سازی از \fBModel\fP و کلاس‌های جدول را با \fBTable\fP\& بسازید. این موارد پیش از فراخوانی \fBinit_app()\fP نیز قابل دسترسی هستند، که تعریف مدل‌ها را به‌صورت جداگانه از برنامه ممکن می‌سازد.
.sp
دسترسی به \fBsession\fP و \fBengine\fP نیازمند یک بافت برنامه (application context) فعال Flask است. این شامل متدهایی مانند \fBcreate_all()\fP نیز می‌شود که از موتور استفاده می‌کنند.
.sp
این کلاس همچنین امکان دسترسی به شناسه‌های موجود در ماژول‌های \fBsqlalchemy\fP و \fBsqlalchemy.orm\fP متعلق به SQLAlchemy را فراهم می‌کند. برای نمونه، می‌توانید به جای وارد کردن \fBsqlalchemy.Column\fP و \fBsqlalchemy.orm.relationship\fP\&، از \fBdb.Column\fP و \fBdb.relationship\fP استفاده کنید. این قابلیت هنگام تعریف مدل‌ها بسیار مناسب و راحت است.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBapp\fP (\fIFlask\fP\fI | \fP\fINone\fP) \-\- فراخوانی فوری \fBinit_app()\fP روی این برنامهٔ Flask.
.IP \(bu 2
\fBmetadata\fP (\fIsa.MetaData\fP\fI | \fP\fINone\fP) \-\- استفاده از این مقدار به عنوان \fBsqlalchemy.schema.MetaData\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.MetaData>\& پیش‌فرض. برای تنظیم قواعد نام‌گذاری (naming convention) مفید است.
.IP \(bu 2
\fBsession_options\fP (\fIdict\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI, \fP\fIt.Any\fP\fI] \fP\fI| \fP\fINone\fP) \-\- آرگومان‌های مورد استفاده توسط \fBsession\fP برای ایجاد هر نمونهٔ نشست. کلید \fBscopefunc\fP به نشست محدوده‌بندی‌شده (scoped session) منتقل می‌شود، نه به نمونهٔ نشست. برای مشاهدهٔ فهرست آرگومان‌ها به \fBsqlalchemy.orm.sessionmaker\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:session_api\:.html#\:sqlalchemy\:.orm\:.sessionmaker> مراجعه کنید.
.IP \(bu 2
\fBquery_class\fP (\fItype\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:type>\fI[\fP\fIQuery\fP \%<#\:flask_sqlalchemy\:.query\:.Query>\fI]\fP) \-\- استفاده از این کلاس به عنوان کلاس پرس‌وجوی (query) پیش‌فرض برای مدل‌ها و رابطه‌های پویا. رابط پرس‌وجو در SQLAlchemy یک رابط قدیمی (legacy) محسوب می‌شود.
.IP \(bu 2
\fBmodel_class\fP (\fI_FSA_MCT\fP) \-\- استفاده از این مقدار به عنوان کلاس پایهٔ مدل هنگام ایجاد کلاس مدل اعلانی \fBModel\fP\&. همچنین می‌تواند یک کلاس مدل اعلانی کاملاً ایجاد شده برای سفارشی‌سازی بیشتر باشد.
.IP \(bu 2
\fBengine_options\fP (\fIdict\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI, \fP\fIt.Any\fP\fI] \fP\fI| \fP\fINone\fP) \-\- آرگومان‌های پیش‌فرض مورد استفاده هنگام ایجاد هر موتور. این‌ها اولویت کمتری نسبت به پیکربندی برنامه دارند. برای فهرست آرگومان‌ها به \fBsqlalchemy.create_engine()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:engines\:.html#\:sqlalchemy\:.create_engine> مراجعه کنید.
.IP \(bu 2
\fBadd_models_to_shell\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- افزودن نمونهٔ \fBdb\fP و تمام کلاس‌های مدل به \fBflask shell\fP\&.
.IP \(bu 2
\fBdisable_autonaming\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>)
.UNINDENT
.UNINDENT
.sp
تغییریافته در نسخهٔ 3.1.0: پارامتر \fBmetadata\fP همچنان می‌تواند با کلاس‌های SQLAlchemy 1.x استفاده شود، اما هنگام استفاده از سبک اعلانی کلاس‌های SQLAlchemy 2.x نادیده گرفته می‌شود. به جای آن، متادیتا را روی کلاس Base خود مشخص کنید.

.sp
تغییریافته در نسخهٔ 3.1.0: پارامتر \fBdisable_autonaming\fP اضافه شد.

.sp
تغییریافته در نسخهٔ 3.1.0: پارامتر \fBmodel_class\fP تغییر یافت تا زیرکلاس declarative base از SQLAlchemy 2.x را بپذیرد.

.sp
تغییریافته در نسخهٔ 3.0: برای دسترسی به \fBsession\fP و \fBengine\fP\& همیشه یک بافت برنامهٔ فعال Flask الزامی است.

.sp
تغییریافته در نسخهٔ 3.0: برای هر bind key از \fBmetadata\fP جداگانه‌ای استفاده می‌شود.

.sp
تغییریافته در نسخهٔ 3.0: پارامتر \fBengine_options\fP به عنوان پیش‌فرض پیش از پیکربندی هر موتور اعمال می‌شود.

.sp
تغییریافته در نسخهٔ 3.0: کلاس نشست را می‌توان در \fBsession_options\fP\& سفارشی‌سازی کرد.

.sp
تغییریافته در نسخهٔ 3.0: پارامتر \fBadd_models_to_shell\fP اضافه شد.

.sp
تغییریافته در نسخهٔ 3.0: موتورها هنگام فراخوانی \fBinit_app\fP ایجاد می‌شوند، نه در نخستین باری که به آن‌ها دسترسی پیدا می‌شود.

.sp
تغییریافته در نسخهٔ 3.0: تمام پارامترها به جز \fBapp\fP فقط به‌صورت کلیدواژه‌ای (keyword\-only) هستند.

.sp
تغییریافته در نسخهٔ 3.0: نمونهٔ افزونه مستقیماً به عنوان \fBapp.extensions[\(dqsqlalchemy\(dq]\fP\& ذخیره می‌شود.

.sp
تغییریافته در نسخهٔ 3.0: متدهای راه‌اندازی با زیرخط آغازین تغییر نام یافتند. این‌ها رابط‌های داخلی تلقی می‌شوند و ممکن است در هر زمان تغییر کنند.

.sp
تغییریافته در نسخهٔ 3.0: پارامتر و پیکربندی \fBuse_native_unicode\fP حذف شد.

.sp
تغییریافته در نسخهٔ 2.4: پارامتر \fBengine_options\fP اضافه شد.

.sp
تغییریافته در نسخهٔ 2.1: پارامترهای \fBmetadata\fP، \fBquery_class\fP و \fBmodel_class\fP اضافه شدند.

.sp
تغییریافته در نسخهٔ 2.1: استفاده از کلاس پرس‌وجوی یکسان در سراسر \fBsession\fP، \fBModel.query\fP و \fBQuery\fP\&.

.sp
تغییریافته در نسخهٔ 0.16: مقدار \fBscopefunc\fP در \fBsession_options\fP\& پذیرفته می‌شود.

.sp
تغییریافته در نسخهٔ 0.10: پارامتر \fBsession_options\fP اضافه شد.

.INDENT 7.0
.TP
.B Model
یک کلاس مدل اعلانی SQLAlchemy. از این کلاس برای تعریف مدل‌های پایگاه داده ارث‌بری کنید.
.sp
اگر مدلی \fB__tablename__\fP را تنظیم نکند، نام جدول با تبدیل نام کلاس از حالت \fBCamelCase\fP به \fBsnake_case\fP\& تولید خواهد شد. چنانچه به نظر برسد که مدل از توارث تک‌جدولی (single\-table inheritance) استفاده می‌کند، نام جدول تولید نخواهد شد.
.sp
اگر یک مدل یا کلاس والد آن \fB__bind_key__\fP را تنظیم کند، از متادیتا و موتور پایگاه داده مربوط به آن استفاده خواهد کرد. در غیر این صورت، از \fBmetadata\fP و \fBengine\fP\& پیش‌فرض استفاده می‌کند. اگر مدل \fBmetadata\fP یا \fB__table__\fP\& را تنظیم کرده باشد، این مقدار نادیده گرفته می‌شود.
.sp
برای کدهایی که از API نسخهٔ 1.x ابزار SQLAlchemy استفاده می‌کنند، این مدل را با ارث‌بری از \fBModel\fP و ارسال پارامتر \fBmodel_class\fP به افزونه سفارشی‌سازی کنید. همچنین می‌توان یک کلاس مدل اعلانی کاملاً ایجاد شده را برای استفاده از متاردهٔ (metaclass) سفارشی ارسال کرد.
.sp
برای کدهایی که از API نسخهٔ 2.x ابزار SQLAlchemy استفاده می‌کنند، این مدل را با ارث‌بری از \fBsqlalchemy.orm.DeclarativeBase\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBase> یا \fBsqlalchemy.orm.DeclarativeBaseNoMeta\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:mapping_api\:.html#\:sqlalchemy\:.orm\:.DeclarativeBaseNoMeta> و ارسال پارامتر \fBmodel_class\fP به افزونه سفارشی‌سازی نمایید.
.UNINDENT
.INDENT 7.0
.TP
.B Query
کلاس پرس‌وجوی پیش‌فرض مورد استفاده در \fBModel.query\fP و رابطه‌های \fBlazy=\(dqdynamic\(dq\fP\&.
.sp
\fBهشدار:\fP
.INDENT 7.0
.INDENT 3.5
رابط query در SQLAlchemy یک رابط قدیمی (legacy) در نظر گرفته می‌شود.
.UNINDENT
.UNINDENT
.sp
این کلاس را با ارسال پارامتر \fBquery_class\fP به افزونه سفارشی‌سازی کنید.
.UNINDENT
.INDENT 7.0
.TP
.B Table
یک کلاس \fBsqlalchemy.schema.Table\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.Table> که متادیتا را به‌صورت خودکار انتخاب می‌کند.
.sp
برخلاف کلاس پایهٔ \fBTable\fP، آرگومان \fBmetadata\fP الزامی نیست. اگر مشخص نشود، بر اساس آرگومان \fBbind_key\fP انتخاب خواهد شد.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBbind_key\fP \-\- برای انتخاب یک متادیتای متفاوت استفاده می‌شود.
.IP \(bu 2
\fBargs\fP \-\- آرگومان‌های ارسال‌شده به کلاس پایه. این موارد معمولاً نام جدول، ستون‌ها و قیدها (constraints) هستند.
.IP \(bu 2
\fBkwargs\fP \-\- آرگومان‌های ارسال‌شده به کلاس پایه.
.UNINDENT
.UNINDENT.sp
تغییریافته در نسخهٔ 3.0: این به جای یک تابع، یک زیرکلاس از \fBTable\fP در SQLAlchemy است.

.UNINDENT
.INDENT 7.0
.TP
.B create_all(bind_key=\(aq__all__\(aq)
جدول‌هایی که در پایگاه‌داده وجود ندارند را با فراخوانی
\fBmetadata.create_all()\fP برای همه یا برخی از کلیدهای bind ایجاد می‌کند. این متد
جدول‌های موجود را به‌روزرسانی نمی‌کند؛ برای این منظور از یک کتابخانهٔ مهاجرت (migration) استفاده کنید.
.sp
این عمل مستلزم فعال بودن یک بافت کاربرد (application context) در Flask است.
.INDENT 7.0
.TP
.B پارامترها
\fBbind_key\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI | \fP\fIlist\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:list>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI]\fP) \-\- یک کلید bind یا فهرستی از کلیدها برای ایجاد جدول‌ها. مقدار پیش‌فرض،
همهٔ bindها است.
.TP
.B نوع بازگشتی
None
.UNINDENT
.sp
تغییریافته در نسخهٔ 3.0: نام پارامتر \fBbind\fP به \fBbind_key\fP تغییر یافت. پارامتر \fBapp\fP
حذف شد.

.sp
تغییریافته در نسخهٔ 0.12: پارامترهای \fBbind\fP و \fBapp\fP افزوده شدند.

.UNINDENT
.INDENT 7.0
.TP
.B drop_all(bind_key=\(aq__all__\(aq)
جدول‌ها را با فراخوانی \fBmetadata.drop_all()\fP برای همه یا برخی از کلیدهای bind حذف می‌کند.
.sp
این عمل مستلزم فعال بودن یک بافت کاربرد (application context) در Flask است.
.INDENT 7.0
.TP
.B پارامترها
\fBbind_key\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI | \fP\fIlist\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:list>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI]\fP) \-\- یک کلید bind یا فهرستی از کلیدها برای حذف جدول‌ها از آن‌ها. مقدار پیش‌فرض،
همهٔ bindها است.
.TP
.B نوع بازگشتی
None
.UNINDENT
.sp
تغییریافته در نسخهٔ 3.0: نام پارامتر \fBbind\fP به \fBbind_key\fP تغییر یافت. پارامتر \fBapp\fP
حذف شد.

.sp
تغییریافته در نسخهٔ 0.12: پارامترهای \fBbind\fP و \fBapp\fP افزوده شدند.

.UNINDENT
.INDENT 7.0
.TP
.B dynamic_loader(argument, **kwargs)
یک \fBsqlalchemy.orm.dynamic_loader()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:relationship_api\:.html#\:sqlalchemy\:.orm\:.dynamic_loader> که کلاس
\fBQuery\fP این افزونه را برای رابطه‌ها و backrefها اعمال می‌کند.
.sp
تغییریافته در نسخهٔ 3.0: کلاس \fBQuery\fP روی \fBbackref\fP تنظیم می‌شود.

.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBargument\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.IP \(bu 2
\fBkwargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.UNINDENT
.TP
.B نوع بازگشتی
\fIRelationshipProperty\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:internals\:.html#\:sqlalchemy\:.orm\:.RelationshipProperty>[\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>]
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property engine: Engine \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine>
موتور پیش‌فرض (\fBEngine\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine>) برای برنامهٔ فعلی،
که در صورت عدم تنظیم کلید bind برای \fBModel\fP یا \fBTable\fP مورد پرس‌وجو،
توسط \fBsession\fP استفاده می‌شود.
.sp
برای سفارشی‌سازی، پیکربندی \fBSQLALCHEMY_ENGINE_OPTIONS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_ENGINE_OPTIONS> را تنظیم کرده و مقادیر
پیش‌فرض را با ارسال پارامتر \fBengine_options\fP به افزونه مشخص کنید.
.sp
این عمل مستلزم فعال بودن یک بافت کاربرد (application context) در Flask است.
.UNINDENT
.INDENT 7.0
.TP
.B property engines: Mapping \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Mapping>[str \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str> | None \%<https://\:docs\:.python\:.org/\:3/\:library/\:constants\:.html#\:None>, Engine \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine>]
نگاشتی از کلیدهای bind به نمونه‌های \fBsqlalchemy.engine.Engine\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine> برای برنامهٔ
فعلی. کلید \fBNone\fP به موتور پیش‌فرض اشاره دارد و به صورت
\fBengine\fP در دسترس است.
.sp
برای سفارشی‌سازی، پیکربندی \fBSQLALCHEMY_BINDS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_BINDS> را تنظیم کرده و مقادیر پیش‌فرض را با
ارسال پارامتر \fBengine_options\fP به افزونه مشخص کنید.
.sp
این عمل مستلزم فعال بودن یک بافت کاربرد (application context) در Flask است.
.sp
افزوده‌شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B first_or_404(statement, *, description=None)
مشابه \fBResult.scalar()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Result\:.scalar>، اما به جای بازگرداندن
\fBNone\fP، با خطای \fB404 Not Found\fP متوقف می‌شود.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBstatement\fP (\fISelect\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:selectable\:.html#\:sqlalchemy\:.sql\:.expression\:.Select>) \-\- دستور \fBselect\fP جهت اجرا.
.IP \(bu 2
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- پیامی سفارشی جهت نمایش در صفحهٔ خطا.
.UNINDENT
.TP
.B نوع بازگشتی
\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>
.UNINDENT
.sp
افزوده‌شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B get_engine(bind_key=None, **kwargs)
موتور مربوط به کلید bind ارائه‌شده را برای برنامهٔ فعلی دریافت می‌کند.
این عمل مستلزم فعال بودن یک بافت کاربرد (application context) در Flask است.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBbind_key\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- نام موتور.
.IP \(bu 2
\fBkwargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.UNINDENT
.TP
.B نوع بازگشتی
\fIEngine\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine>
.UNINDENT
.sp
منسوخ‌شده از نسخهٔ 3.0: در Flask\-SQLAlchemy 3.2 حذف خواهد شد. به جای آن از \fBengines[key]\fP استفاده کنید.

.sp
تغییریافته در نسخهٔ 3.0: نام پارامتر \fBbind\fP به \fBbind_key\fP تغییر یافت. پارامتر \fBapp\fP
حذف شد.

.UNINDENT
.INDENT 7.0
.TP
.B get_or_404(entity, ident, *, description=None, **kwargs)
مشابه \fBsession.get()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:session_api\:.html#\:sqlalchemy\:.orm\:.Session\:.get>، اما به جای بازگرداندن
\fBNone\fP، با خطای \fB404 Not Found\fP متوقف می‌شود.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBentity\fP (\fItype\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:type>\fI[\fP\fI_O\fP\fI]\fP) \-\- کلاس مدل مورد پرس‌وجو.
.IP \(bu 2
\fBident\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>) \-\- کلید اصلی مورد پرس‌وجو.
.IP \(bu 2
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- پیامی سفارشی جهت نمایش در صفحهٔ خطا.
.IP \(bu 2
\fBkwargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>) \-\- آرگومان‌های اضافی ارسال‌شده به \fBsession.get()\fP\&.
.UNINDENT
.TP
.B نوع بازگشتی
\fI_O\fP
.UNINDENT
.sp
تغییریافته در نسخهٔ 3.1: ارسال آرگومان‌های کلیدواژه‌ای اضافی به \fBsession.get()\fP\&.

.sp
افزوده‌شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B init_app(app)
راه‌اندازی یک برنامهٔ Flask جهت استفاده با نمونهٔ این افزونه. این
متد باید قبل از دسترسی به موتور یا session پایگاه‌داده با برنامه فراخوانی شود..sp
این متد مقادیر پیکربندی پیش‌فرض را تعیین می‌کند، سپس افزونه را روی برنامه
پیکربندی کرده و موتورها (engines) را برای هر bind key ایجاد می‌نماید. بنابراین، این متد
باید پس از پیکربندی برنامه فراخوانی شود. تغییرات اعمال‌شده در پیکربندی برنامه
پس از این فراخوانی منعکس نخواهند شد.
.sp
کلیدهای زیر از \fBapp.config\fP استفاده می‌شوند:
.INDENT 7.0
.IP \(bu 2
\fBSQLALCHEMY_DATABASE_URI\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_DATABASE_URI>
.IP \(bu 2
\fBSQLALCHEMY_ENGINE_OPTIONS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_ENGINE_OPTIONS>
.IP \(bu 2
\fBSQLALCHEMY_ECHO\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_ECHO>
.IP \(bu 2
\fBSQLALCHEMY_BINDS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_BINDS>
.IP \(bu 2
\fBSQLALCHEMY_RECORD_QUERIES\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_RECORD_QUERIES>
.IP \(bu 2
\fBSQLALCHEMY_TRACK_MODIFICATIONS\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_TRACK_MODIFICATIONS>
.UNINDENT
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBapp\fP (\fIFlask\fP \%<https://\:flask\:.palletsprojects\:.com/\:en/\:stable/\:api/#\:flask\:.Flask>) \-\- برنامهٔ Flask برای مقداردهی اولیه.
.TP
.B نوع بازگشتی (Return type)
None
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property metadata: MetaData \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.MetaData>
متادیتای پیش‌فرض مورداستفاده توسط \fBModel\fP و \fBTable\fP در صورتی که هیچ
bind key تعیین نشده باشد.
.UNINDENT
.INDENT 7.0
.TP
.B metadatas: dict \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>[str \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str> | None \%<https://\:docs\:.python\:.org/\:3/\:library/\:constants\:.html#\:None>, MetaData \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.MetaData>]
نگاشت bind keyها به نمونه‌های \fBsqlalchemy.schema.MetaData\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:metadata\:.html#\:sqlalchemy\:.schema\:.MetaData>\&. کلید
\fBNone\fP به متادیتای پیش‌فرض اشاره دارد و به صورت
\fBmetadata\fP در دسترس است.
.sp
متادیتای پیش‌فرض را با ارسال پارامتر \fBmetadata\fP به افزونه سفارشی‌سازی کنید.
این کار می‌تواند برای تنظیم یک قرارداد نام‌گذاری (naming convention) استفاده شود. هنگامی که متادیتا
برای یک bind key دیگر ایجاد می‌شود، قرارداد نام‌گذاری پیش‌فرض را کپی می‌کند.
.sp
اضافه‌شده در نسخه 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B one_or_404(statement, *, description=None)
مانند \fBResult.scalar_one()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Result\:.scalar_one> است،
اما به جای برانگیختن خطای \fBNoResultFound\fP یا \fBMultipleResultsFound\fP، با
یک خطای \fB404 Not Found\fP عملیات را متوقف می‌کند.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBstatement\fP (\fISelect\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:selectable\:.html#\:sqlalchemy\:.sql\:.expression\:.Select>) \-\- دستور \fBselect\fP برای اجرا.
.IP \(bu 2
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- یک پیام سفارشی برای نمایش در صفحهٔ خطا.
.UNINDENT
.TP
.B نوع بازگشتی (Return type)
\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>
.UNINDENT
.sp
اضافه‌شده در نسخه 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B paginate(select, *, page=None, per_page=None, max_per_page=None, error_out=True, count=True)
یک offset و limit را بر اساس صفحهٔ فعلی و تعداد آیتم‌ها در هر صفحه بر روی یک
عبارت select اعمال می‌کند و یک شیء \fBPagination\fP را بازمی‌گرداند.
.sp
عبارت باید یک کلاس مدل را انتخاب کند، مانند \fBselect(User)\fP\&. این کار
اصلاح‌کننده‌های \fBunique()\fP و \fBscalars()\fP را روی نتیجه اعمال می‌کند، بنابراین
selectهای مرکب نتایج مورد انتظار را بازنخواهند گرداند.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBselect\fP (\fISelect\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:selectable\:.html#\:sqlalchemy\:.sql\:.expression\:.Select>) \-\- عبارت \fBselect\fP برای صفحه‌بندی.
.IP \(bu 2
\fBpage\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- صفحهٔ فعلی، مورداستفاده برای محاسبهٔ offset. در طول یک درخواست، پیش‌فرض آرگومان پرس‌وجوی \fBpage\fP است، در غیر این صورت 1 است.
.IP \(bu 2
\fBper_page\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- حداکثر تعداد آیتم‌ها در یک صفحه، مورداستفاده برای محاسبهٔ offset و limit. در طول یک درخواست، پیش‌فرض آرگومان پرس‌وجوی \fBper_page\fP است، در غیر این صورت 20 است.
.IP \(bu 2
\fBmax_per_page\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- حداکثر مقدار مجاز برای \fBper_page\fP، جهت محدود کردن مقدار ارائه‌شده توسط کاربر. برای عدم اعمال محدودیت از \fBNone\fP استفاده کنید. پیش‌فرض 100 است.
.IP \(bu 2
\fBerror_out\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- توقف با خطای \fB404 Not Found\fP اگر هیچ آیتمی برگردانده نشود و \fBpage\fP برابر 1 نباشد، یا اگر \fBpage\fP یا \fBper_page\fP کمتر از 1 باشند، یا اگر هیچ‌کدام عدد صحیح نباشند.
.IP \(bu 2
\fBcount\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- محاسبهٔ تعداد کل مقادیر با اجرای یک پرس‌وجوی count اضافی. برای پرس‌وجوهای بسیار پیچیده ممکن است این کار نادرست یا کند باشد، بنابراین در صورت نیاز می‌تواند غیرفعال شده و به صورت دستی تنظیم شود.
.UNINDENT
.TP
.B نوع بازگشتی (Return type)
\fIPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination>
.UNINDENT
.sp
تغییریافته در نسخه 3.0: پرس‌وجوی \fBcount\fP کارآمدتر شده است.

.sp
اضافه‌شده در نسخه 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B reflect(bind_key=\(aq__all__\(aq)
بارگذاری تعاریف جدول‌ها از پایگاه داده با فراخوانی \fBmetadata.reflect()\fP
برای همه یا برخی از bind keyها.
.sp
این نیازمند فعال بودن کانتکست برنامهٔ Flask (application context) است.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBbind_key\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI | \fP\fIlist\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:list>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP\fI]\fP) \-\- یک bind key یا فهرستی از کلیدها برای بازتاب (reflect) جدول‌ها از آن. پیش‌فرض همهٔ bindها است.
.TP
.B نوع بازگشتی (Return type)
None
.UNINDENT
.sp
تغییریافته در نسخه 3.0: تغییر نام پارامتر \fBbind\fP به \fBbind_key\fP\&. پارامتر \fBapp\fP
حذف شد.

.sp
تغییریافته در نسخه 0.12: پارامترهای \fBbind\fP و \fBapp\fP اضافه شدند.

.UNINDENT
.INDENT 7.0
.TP
.B relationship(*args, **kwargs)
یک \fBsqlalchemy.orm.relationship()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:relationship_api\:.html#\:sqlalchemy\:.orm\:.relationship> که کلاس
\fBQuery\fP این افزونه را برای روابط پویا و backrefها اعمال می‌کند.
.sp
تغییریافته در نسخه 3.0: کلاس \fBQuery\fP روی \fBbackref\fP تنظیم می‌شود.

.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.IP \(bu 2
\fBkwargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.UNINDENT
.TP
.B نوع بازگشتی (Return type)
\fIRelationshipProperty\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:internals\:.html#\:sqlalchemy\:.orm\:.RelationshipProperty>[\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>]
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B session
یک \fBsqlalchemy.orm.scoping.scoped_session\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:contextual\:.html#\:sqlalchemy\:.orm\:.scoped_session> که نمونه‌هایی از
\fBSession\fP را با محدودهٔ کانتکست فعلی برنامهٔ Flask ایجاد می‌کند. این نشست
هنگام خروج از کانتکست برنامه حذف خواهد شد و اتصال موتور به استخر (pool) بازگردانده می‌شود.
.sp
این مورد را با ارسال \fBsession_options\fP به افزونه سفارشی‌سازی کنید.
.sp
این نیازمند فعال بودن کانتکست برنامهٔ Flask است.
.sp
تغییریافته در نسخه 3.0: نشست در محدودهٔ کانتکست برنامهٔ فعلی تعریف می‌شود.

.UNINDENT
.UNINDENT.SS "مدل (Model)"
.INDENT 0.0
.TP
.B class flask_sqlalchemy.model.Model
کلاس پایه برای کلاس مدل اعلانی \fBSQLAlchemy.Model\fP\&.
.sp
برای تعریف مدل‌ها، از \fBdb.Model\fP مشتق بگیرید، نه از این کلاس. برای
سفارشی‌سازی \fBdb.Model\fP، از این کلاس ارث‌بری کرده و آن را به عنوان \fBmodel_class\fP به
\fBSQLAlchemy\fP ارسال کنید. برای سفارشی‌سازی \fBdb.Model\fP در سطح متاکلاس، یک
کلاس مدل اعلانی که از قبل ایجاد شده را به عنوان \fBmodel_class\fP ارسال کنید.
.INDENT 7.0
.TP
.B __bind_key__
از این کلید پیوند (bind key) برای انتخاب متادیتا و موتوری که به جدول این مدل مرتبط
می‌شوند استفاده کنید. در صورت تنظیم \fBmetadata\fP یا \fB__table__\fP نادیده گرفته می‌شود. در صورت
ارائه نشدن، از کلید پیش‌فرض، یعنی \fBNone\fP، استفاده خواهد شد.
.UNINDENT
.INDENT 7.0
.TP
.B __tablename__
نام جدول در پایگاه داده. این مورد توسط SQLAlchemy الزامی است؛ هرچند
Flask\-SQLAlchemy در صورتی که برای مدلی یک کلید اصلی تعریف شده باشد، آن را به‌طور خودکار تنظیم خواهد کرد.
اگر \fB__table__\fP یا \fB__tablename__\fP به‌طور صریح تنظیم شوند، همان مقدار
به کار گرفته می‌شود.
.UNINDENT
.INDENT 7.0
.TP
.B query: t.ClassVar[Query \%<#\:flask_sqlalchemy\:.query\:.Query>]
یک پرس‌وجوی SQLAlchemy برای مدل. معادل با \fBdb.session.query(Model)\fP\&. می‌تواند
برای هر مدل با بازنویسی \fBquery_class\fP سفارشی‌سازی شود.
.sp
\fBهشدار:\fP
.INDENT 7.0
.INDENT 3.5
رابط پرس‌وجو (query interface) در SQLAlchemy یک قابلیت قدیمی (legacy) به شمار می‌رود. ترجیحاً
به جای آن از \fBsession.execute(select())\fP استفاده کنید.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B query_class
کلاس پرس‌وجو که توسط \fBquery\fP استفاده می‌شود. پیش‌فرض آن \fBSQLAlchemy.Query\fP است که
خود به طور پیش‌فرض روی \fBQuery\fP قرار دارد.
.sp
نام مستعار \fBQuery\fP
.UNINDENT
.UNINDENT
.SS "میکس‌این‌های متاکلاس (SQLAlchemy 1.x)"
.sp
اگر کد شما از API نگارش SQLAlchemy 1.x استفاده می‌کند (حالت پیش‌فرض برای کدهایی که \fBmodel_class\fP را مشخص نکرده‌اند)،
در این صورت این میکس‌این‌ها به‌طور خودکار روی کلاس \fBModel\fP اعمال می‌شوند.
.INDENT 0.0
.TP
.B class flask_sqlalchemy.model.DefaultMeta(name, bases, d, **kwargs)
متاکلاس اعلانی SQLAlchemy که پشتیبانی از \fB__bind_key__\fP و
\fB__tablename__\fP را فراهم می‌کند.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>)
.IP \(bu 2
\fBbases\fP (\fItuple\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:tuple>\fI[\fP\fItype\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:type>\fI, \fP\fI\&...\fP\fI]\fP)
.IP \(bu 2
\fBd\fP (\fIdict\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI, \fP\fIt.Any\fP\fI]\fP)
.IP \(bu 2
\fBkwargs\fP (\fIt.Any\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class flask_sqlalchemy.model.BindMetaMixin(name, bases, d, **kwargs)
میکس‌این متاکلاس که \fBmetadata\fP یک مدل را بر اساس \fB__bind_key__\fP آن تنظیم می‌کند.
.sp
اگر مدل مستقیماً \fBmetadata\fP یا \fB__table__\fP را تنظیم کند، \fB__bind_key__\fP
نادیده گرفته می‌شود. اگر \fBmetadata\fP با مدل والد یکسان باشد، مستقیماً
روی مدل فرزند تنظیم نخواهد شد.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>)
.IP \(bu 2
\fBbases\fP (\fItuple\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:tuple>\fI[\fP\fItype\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:type>\fI, \fP\fI\&...\fP\fI]\fP)
.IP \(bu 2
\fBd\fP (\fIdict\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI, \fP\fIt.Any\fP\fI]\fP)
.IP \(bu 2
\fBkwargs\fP (\fIt.Any\fP)
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class flask_sqlalchemy.model.NameMetaMixin(name, bases, d, **kwargs)
میکس‌این متاکلاس که \fB__tablename__\fP یک مدل را با تبدیل نام کلاس از
\fBCamelCase\fP به \fBsnake_case\fP تنظیم می‌کند. برای مدل‌های غیرانتزاعی (non\-abstract)
که مشخصاً نامی تعیین نکرده‌اند، \fB__tablename__\fP تنظیم می‌شود. اگر یک مدل کلید اصلی
تعریف نکرده باشد، به منظور وراثت تک‌جدولی (single\-table inheritance)، نام یا \fB__table__\fP تولید نخواهد شد.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBname\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>)
.IP \(bu 2
\fBbases\fP (\fItuple\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:tuple>\fI[\fP\fItype\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:type>\fI, \fP\fI\&...\fP\fI]\fP)
.IP \(bu 2
\fBd\fP (\fIdict\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:dict>\fI[\fP\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI, \fP\fIt.Any\fP\fI]\fP)
.IP \(bu 2
\fBkwargs\fP (\fIt.Any\fP)
.UNINDENT
.UNINDENT
.UNINDENT.SS Session
.INDENT 0.0
.TP
.B class flask_sqlalchemy.session.Session(db, **kwargs)
یک کلاس \fBSession\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:session_api\:.html#\:sqlalchemy\:.orm\:.Session> از SQLAlchemy که موتور (engine) مورد استفاده را بر اساس bind key مرتبط با متادیتای شیءِ در حال پرس‌وجو، انتخاب می‌کند.
.sp
برای سفارشی‌سازی \fBdb.session\fP، از این کلاس زیرکلاس بسازید و آن را به عنوان کلید \fBclass_\fP در \fBsession_options\fP به \fBSQLAlchemy\fP ارسال کنید\&.
.sp
تغییریافته در نسخهٔ 3.0: نام آن از \fBSignallingSession\fP تغییر یافت\&.

.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBdb\fP (\fISQLAlchemy\fP \%<#\:flask_sqlalchemy\:.SQLAlchemy>)
.IP \(bu 2
\fBkwargs\fP (\fIt.Any\fP)
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_bind(mapper=None, clause=None, bind=None, **kwargs)
یک engine را بر اساس \fBbind_key\fP متادیتای مرتبط با مدل یا جدولِ در حال پرس‌وجو انتخاب می‌کند. اگر هیچ bind keyای تنظیم نشده باشد، از bind پیش‌فرض استفاده می‌کند.
.sp
تغییریافته در نسخهٔ 3.0.3: رفع مشکل پیدا کردن bind برای یک مدل با ارث‌بری پیوسته (joined inheritance).

.sp
تغییریافته در نسخهٔ 3.0: پیاده‌سازی بیش از پیش با پیاده‌سازی پایهٔ SQLAlchemy منطبق شده است\&.

.sp
تغییریافته در نسخهٔ 2.1: پشتیبانی از پیوستن به یک تراکنش (transaction) خارجی.

.INDENT 7.0
.TP
.B پارامترها (Parameters)
.INDENT 7.0
.IP \(bu 2
\fBmapper\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>\fI | \fP\fINone\fP)
.IP \(bu 2
\fBclause\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>\fI | \fP\fINone\fP)
.IP \(bu 2
\fBbind\fP (\fIEngine\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine>\fI | \fP\fIConnection\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Connection>\fI | \fP\fINone\fP)
.IP \(bu 2
\fBkwargs\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>)
.UNINDENT
.TP
.B نوع بازگشتی (Return type)
\fIEngine\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Engine> | \fIConnection\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:core/\:connections\:.html#\:sqlalchemy\:.engine\:.Connection>
.UNINDENT
.UNINDENT
.UNINDENT
.SS Pagination
.INDENT 0.0
.TP
.B class flask_sqlalchemy.pagination.Pagination
برشی از کل آیتم‌های یک پرس‌وجو که با اعمال offset و limit بر اساس صفحهٔ جاری و تعداد آیتم‌ها در هر صفحه به دست می‌آید.
.sp
اشیاء صفحه‌بندی را به صورت دستی ایجاد نکنید. آن‌ها توسط \fBSQLAlchemy.paginate()\fP و \fBQuery.paginate()\fP ایجاد می‌شوند\&.
.sp
تغییریافته در نسخهٔ 3.0: پیمایش روی یک شیء صفحه‌بندی، روی آیتم‌های آن پیمایش می‌کند.

.sp
تغییریافته در نسخهٔ 3.0: ایجاد نمونه‌ها به صورت دستی، یک رابط برنامه‌نویسی عمومی (public API) نیست.

.INDENT 7.0
.TP
.B page: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>
صفحهٔ جاری.
.UNINDENT
.INDENT 7.0
.TP
.B per_page: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>
حداکثر تعداد آیتم‌ها در یک صفحه.
.UNINDENT
.INDENT 7.0
.TP
.B items: list \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:list>[Any \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>]
آیتم‌های موجود در صفحهٔ جاری. پیمایش روی شیء صفحه‌بندی معادل پیمایش روی این آیتم‌ها است.
.UNINDENT
.INDENT 7.0
.TP
.B total: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int> | None \%<https://\:docs\:.python\:.org/\:3/\:library/\:constants\:.html#\:None>
تعداد کل آیتم‌ها در تمام صفحه‌ها.
.UNINDENT
.INDENT 7.0
.TP
.B property first: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>
شمارهٔ نخستین آیتم در صفحه، با شروع از ۱، یا ۰ در صورتی که هیچ آیتمی وجود نداشته باشد.
.sp
اضافه شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B property last: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>
شمارهٔ آخرین آیتم در صفحه، با شروع از ۱ (شامل خود آن)، یا ۰ در صورتی که هیچ آیتمی وجود نداشته باشد.
.sp
اضافه شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B property pages: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>
تعداد کل صفحه‌ها.
.UNINDENT
.INDENT 7.0
.TP
.B property has_prev: bool \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>
برابر با \fBTrue\fP اگر این صفحه، صفحهٔ نخست نباشد.
.UNINDENT
.INDENT 7.0
.TP
.B property prev_num: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int> | None \%<https://\:docs\:.python\:.org/\:3/\:library/\:constants\:.html#\:None>
شمارهٔ صفحهٔ پیشین، یا \fBNone\fP اگر این صفحه، صفحهٔ نخست باشد.
.UNINDENT
.INDENT 7.0
.TP
.B prev(*, error_out=False)
پرس‌وجوی شیء \fBPagination\fP برای صفحهٔ پیشین.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBerror_out\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- توقف عملیات با خطای \fB404 Not Found\fP اگر هیچ آیتمی برگردانده نشود و \fBpage\fP برابر ۱ نباشد، یا اگر \fBpage\fP یا \fBper_page\fP کمتر از ۱ باشند، یا اگر هیچ‌کدام عدد صحیح (int) نباشند.
.TP
.B نوع بازگشتی (Return type)
\fIPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination>
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property has_next: bool \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>
برابر با \fBTrue\fP اگر این صفحه، صفحهٔ پایانی نباشد.
.UNINDENT
.INDENT 7.0
.TP
.B property next_num: int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int> | None \%<https://\:docs\:.python\:.org/\:3/\:library/\:constants\:.html#\:None>
شمارهٔ صفحهٔ بعدی، یا \fBNone\fP اگر این صفحه، صفحهٔ پایانی باشد.
.UNINDENT
.INDENT 7.0
.TP
.B next(*, error_out=False)
پرس‌وجوی شیء \fBPagination\fP برای صفحهٔ بعدی.
.INDENT 7.0
.TP
.B پارامترها (Parameters)
\fBerror_out\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- توقف عملیات با خطای \fB404 Not Found\fP اگر هیچ آیتمی برگردانده نشود و \fBpage\fP برابر ۱ نباشد، یا اگر \fBpage\fP یا \fBper_page\fP کمتر از ۱ باشند، یا اگر هیچ‌کدام عدد صحیح (int) نباشند.
.TP
.B نوع بازگشتی (Return type)
\fIPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination>
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B iter_pages(*, left_edge=2, left_current=2, right_current=4, right_edge=2)
تولید شماره‌های صفحه برای یک ویجت صفحه‌بندی. صفحه‌های رد شده میان لبه‌ها و بخش میانی با \fBNone\fP نشان داده می‌شوند\&.
.sp
برای مثال، اگر ۲۰ صفحه وجود داشته باشد و صفحهٔ جاری ۷ باشد، مقادیر زیر تولید می‌شوند.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
1, 2, None, 5, 6, 7, 8, 9, 10, 11, None, 19, 20
.EE
.UNINDENT
.UNINDENT
.INDENT 7.0.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBleft_edge\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>) \-\- تعداد صفحاتی که باید از صفحهٔ نخست نشان داده شوند.
.IP \(bu 2
\fBleft_current\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>) \-\- تعداد صفحاتی که باید در سمت چپ صفحهٔ جاری نشان داده شوند.
.IP \(bu 2
\fBright_current\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>) \-\- تعداد صفحاتی که باید در سمت راست صفحهٔ جاری نشان داده شوند.
.IP \(bu 2
\fBright_edge\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>) \-\- تعداد صفحاتی که باید از صفحهٔ پایانی نشان داده شوند.
.UNINDENT
.TP
.B نوع بازگشتی
\fIIterator\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Iterator>[int \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int> | None]
.UNINDENT
.sp
تغییر در نسخهٔ 3.0: بهبود کارایی در محاسبهٔ مقادیری که باید yield شوند.

.sp
تغییر در نسخهٔ 3.0: مرز \fBright_current\fP فراگیر (inclusive) است.

.sp
تغییر در نسخهٔ 3.0: همهٔ پارامترها فقط کلیدواژه‌ای (keyword\-only) هستند.

.UNINDENT
.UNINDENT
.SS Query
.INDENT 0.0
.TP
.B class flask_sqlalchemy.query.Query(entities, session=None)
زیرکلاسی از \fBQuery\fP در SQLAlchemy \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:queryguide/\:query\:.html#\:sqlalchemy\:.orm\:.Query> به همراه چند متد اضافی
که برای پرس‌وجو در یک برنامهٔ کاربردی وب مفید هستند.
.sp
این کلاس پرس‌وجوی پیش‌فرض برای \fBModel.query\fP\& است.
.sp
تغییر در نسخهٔ 3.0: از \fBBaseQuery\fP به \fBQuery\fP تغییر نام یافت.

.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBentities\fP (\fIUnion\fP\fI[\fP\fI_ColumnsClauseArgument\fP\fI[\fP\fIAny\fP\fI]\fP\fI, \fP\fISequence\fP\fI[\fP\fI_ColumnsClauseArgument\fP\fI[\fP\fIAny\fP\fI]\fP\fI]\fP\fI]\fP)
.IP \(bu 2
\fBsession\fP (\fIOptional\fP\fI[\fP\fISession\fP \%<#\:flask_sqlalchemy\:.session\:.Session>\fI]\fP)
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B first_or_404(description=None)
مشابه \fBfirst()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:queryguide/\:query\:.html#\:sqlalchemy\:.orm\:.Query\:.first> است اما به جای بازگرداندن \fBNone\fP\&، با خطای
\fB404 Not Found\fP عملیات را لغو می‌کند.
.INDENT 7.0
.TP
.B پارامترها
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- یک پیام سفارشی برای نمایش در صفحهٔ خطا.
.TP
.B نوع بازگشتی
\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_or_404(ident, description=None)
مشابه \fBget()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:queryguide/\:query\:.html#\:sqlalchemy\:.orm\:.Query\:.get> است اما به جای بازگرداندن \fBNone\fP\&، با خطای
\fB404 Not Found\fP عملیات را لغو می‌کند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBident\fP (\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>) \-\- کلید اصلی (primary key) برای پرس‌وجو.
.IP \(bu 2
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- یک پیام سفارشی برای نمایش در صفحهٔ خطا.
.UNINDENT
.TP
.B نوع بازگشتی
\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B one_or_404(description=None)
مشابه \fBone()\fP \%<https://\:docs\:.sqlalchemy\:.org/\:en/\:20/\:orm/\:queryguide/\:query\:.html#\:sqlalchemy\:.orm\:.Query\:.one> است اما به جای ایجاد استثنای \fBNoResultFound\fP یا \fBMultipleResultsFound\fP\&، با خطای \fB404 Not Found\fP
عملیات را لغو می‌کند.
.INDENT 7.0
.TP
.B پارامترها
\fBdescription\fP (\fIstr\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:str>\fI | \fP\fINone\fP) \-\- یک پیام سفارشی برای نمایش در صفحهٔ خطا.
.TP
.B نوع بازگشتی
\fIAny\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:typing\:.html#\:typing\:.Any>
.UNINDENT
.sp
افزوده شده در نسخهٔ 3.0.

.UNINDENT
.INDENT 7.0
.TP
.B paginate(*, page=None, per_page=None, max_per_page=None, error_out=True, count=True)
بر اساس صفحهٔ جاری و تعداد موارد در هر صفحه، یک offset و limit بر پرس‌وجو اعمال
می‌کند و یک شیء \fBPagination\fP برمی‌گرداند.
.INDENT 7.0
.TP
.B پارامترها
.INDENT 7.0
.IP \(bu 2
\fBpage\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- صفحهٔ جاری که برای محاسبهٔ offset استفاده می‌شود. در طول یک درخواست،
پیش‌فرض آن آرگومان پرس‌وجوی \fBpage\fP و در غیر این صورت 1 است.
.IP \(bu 2
\fBper_page\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- حداکثر تعداد موارد در یک صفحه که برای محاسبهٔ offset و limit
استفاده می‌شود. در طول یک درخواست، پیش‌فرض آن آرگومان پرس‌وجوی \fBper_page\fP و در غیر این صورت 20 است.
.IP \(bu 2
\fBmax_per_page\fP (\fIint\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:int>\fI | \fP\fINone\fP) \-\- حداکثر مقدار مجاز برای \fBper_page\fP، جهت محدود کردن مقدار ارائه‌شده
توسط کاربر. برای نداشتن محدودیت از \fBNone\fP استفاده کنید. پیش‌فرض 100 است.
.IP \(bu 2
\fBerror_out\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- در صورتی که هیچ موردی برگردانده نشود و \fBpage\fP برابر 1 نباشد، یا اگر
\fBpage\fP یا \fBper_page\fP کمتر از 1 باشند، یا اگر هر کدام int نباشند، با خطای \fB404 Not Found\fP عملیات را متوقف می‌کند.
.IP \(bu 2
\fBcount\fP (\fIbool\fP \%<https://\:docs\:.python\:.org/\:3/\:library/\:functions\:.html#\:bool>) \-\- تعداد کل مقادیر را با اجرای یک پرس‌وجوی count اضافی محاسبه می‌کند.
برای پرس‌وجوهای بسیار پیچیده این مقدار ممکن است نادقیق یا کند باشد، از این رو می‌توان در صورت نیاز آن را غیرفعال کرد و به صورت دستی مقداردهی نمود.
.UNINDENT
.TP
.B نوع بازگشتی
\fIPagination\fP \%<#\:flask_sqlalchemy\:.pagination\:.Pagination>
.UNINDENT
.sp
تغییر در نسخهٔ 3.0: همهٔ پارامترها فقط کلیدواژه‌ای (keyword\-only) هستند.

.sp
تغییر در نسخهٔ 3.0: پرس‌وجوی \fBcount\fP کارآمدتر شده است.

.sp
تغییر در نسخهٔ 3.0: پیش‌فرض \fBmax_per_page\fP برابر با 100 است.

.UNINDENT
.UNINDENT.SS "ثبت پرس‌وجوها (Record Queries)"
.INDENT 0.0
.TP
.B flask_sqlalchemy.record_queries.get_recorded_queries()
فهرست اطلاعات پرس‌وجوهای ثبت‌شده برای نشست (session) فعلی را دریافت می‌کند. پرس‌وجوها در
صورتی ثبت می‌شوند که پیکربندی \fBSQLALCHEMY_RECORD_QUERIES\fP \%<#\:flask_sqlalchemy\:.config\:.SQLALCHEMY_RECORD_QUERIES> فعال باشد.
.sp
هر شیء اطلاعات پرس‌وجو دارای مشخصه‌های زیر است:
.INDENT 7.0
.TP
.B \fBstatement\fP
رشتهٔ SQL تولیدشده توسط SQLAlchemy به همراه جای‌نگهدارنده‌های پارامتر.
.TP
.B \fBparameters\fP
پارامترهای ارسال‌شده به همراه عبارت SQL.
.TP
.B \fBstart_time\fP / \fBend_time\fP
اطلاعات زمان‌بندی دربارهٔ زمان آغاز اجرای پرس‌وجو و زمان بازگشت
نتایج. دقت و مقدار آن به سیستم‌عامل بستگی دارد.
.TP
.B \fBduration\fP
مدت‌زمان اجرای پرس‌وجو به ثانیه.
.TP
.B \fBlocation\fP
توضیحی رشته‌ای از مکانی در کد برنامهٔ شما که پرس‌وجو در آن اجرا شده است.
ممکن است محاسبهٔ این مورد امکان‌پذیر نباشد و قالب آن پایدار نیست.
.UNINDENT
.sp
تغییریافته در نسخهٔ 3.0: تغییر نام از \fBget_debug_queries\fP\&.

.sp
تغییریافته در نسخهٔ 3.0: شیء اطلاعات به جای یک تاپل یک \fBdataclass\fP است.

.sp
تغییریافته در نسخهٔ 3.0: مشخصهٔ \fBcontext\fP در شیء اطلاعات به \fBlocation\fP تغییر نام یافته است.

.sp
تغییریافته در نسخهٔ 3.0: در حالت اشکال‌زدایی یا آزمایش به‌طور خودکار فعال نمی‌شود.

.INDENT 7.0
.TP
.B نوع بازگشتی (Return type)
list \%<https://\:docs\:.python\:.org/\:3/\:library/\:stdtypes\:.html#\:list>[\fI_QueryInfo\fP]
.UNINDENT
.UNINDENT
.SS "ردیابی تغییرات (Track Modifications)"
.INDENT 0.0
.TP
.B flask_sqlalchemy.track_modifications.models_committed
این سیگنال Blinker پس از اعمال (commit) نشست در صورتی که مدل‌های تغییریافته‌ای
در نشست وجود داشته باشند، ارسال می‌شود.
.sp
ارسال‌کننده برنامهٔ کاربردی است که تغییرات را صادر کرده است. به دریافت‌کننده
آرگومان \fBchanges\fP به همراه فهرستی از تاپل‌ها به صورت \fB(instance, operation)\fP فرستاده می‌شود.
عملیات‌ها عبارت‌اند از \fB\(dqinsert\(dq\fP، \fB\(dqupdate\(dq\fP و \fB\(dqdelete\(dq\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B flask_sqlalchemy.track_modifications.before_models_committed
این سیگنال دقیقاً مانند \fBmodels_committed\fP عمل می‌کند اما قبل از
انجام commit صادر می‌شود.
.UNINDENT
.SH "اطلاعات تکمیلی (ADDITIONAL INFORMATION)"
.SS "مجوز BSD\-3\-Clause (BSD\-3\-Clause License)"
.sp
کپی‌رایت 2010 Pallets
.sp
توزیع مجدد و استفاده به اشکال سورس و باینری، با یا بدون
تغییر، مجاز است به شرطی که شرایط زیر
رعایت شوند:
.INDENT 0.0
.IP 1. 3
توزیع‌های مجدد سورس‌کد باید اعلان کپی‌رایت بالا،
این فهرست شرایط و سلب مسئولیت زیر را حفظ کنند.
.IP 2. 3
توزیع‌های مجدد در قالب باینری باید اعلان کپی‌رایت بالا،
این فهرست شرایط و سلب مسئولیت زیر را در مستندات
و/یا سایر موادی که همراه با توزیع ارائه می‌شوند بازتولید کنند.
.IP 3. 3
نه نام دارندهٔ کپی‌رایت و نه نام مشارکت‌کنندگان
آن نباید برای تأیید یا تبلیغ محصولات برگرفته از
این نرم‌افزار بدون اجازهٔ کتبی قبلی استفاده شود.
.UNINDENT
.sp
این نرم‌افزار توسط دارندگان کپی‌رایت و مشارکت‌کنندگان به‌صورت
«همان‌گونه که هست» (\(dqAS IS\(dq) ارائه می‌شود و هرگونه ضمانت صریح یا ضمنی، شامل، اما نه
محدود به، ضمانت‌های ضمنی قابلیت خریدوفروش و مناسب بودن برای یک
هدف خاص سلب می‌شود. در هیچ حالتی دارندهٔ کپی‌رایت
یا مشارکت‌کنندگان در قبال خسارت‌های مستقیم، غیرمستقیم،
اتفاقی، خاص، تنبیهی یا تبعی (شامل، اما نه محدود
به تهیهٔ کالاها یا خدمات جایگزین؛ عدم امکان استفاده، از دست رفتن داده‌ها یا
سود؛ یا وقفه در کسب‌وکار) به هر نحوی که ایجاد شده باشد و بر پایهٔ هر فرضیهٔ
مسئولیتی، چه در قرارداد، مسئولیت مدنی یا شبه‌جرم (شامل
اهمال یا موارد دیگر) ناشی از استفاده از این
نرم‌افزار مسئول نخواهند بود، حتی در صورتی که احتمال وقوع چنین خسارتی اطلاع داده شده باشد..SS "تغییرات (Changes)"
.SS "نسخه 3.1.1 (Version 3.1.1)"
.sp
منتشر شده در 2023\-09\-11
.INDENT 0.0
.IP \(bu 2
ویژگی \fB__version__\fP منسوخ شد. در عوض، از تشخیص ویژگی یا
\fBimportlib.metadata.version(\(dqflask\-sqlalchemy\(dq)\fP استفاده کنید. #5230 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:5230>
.UNINDENT
.SS "نسخه 3.1.0 (Version 3.1.0)"
.sp
منتشر شده در 2023\-09\-11
.INDENT 0.0
.IP \(bu 2
پایان پشتیبانی از Python 3.7. #1251 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:1251>
.IP \(bu 2
افزودن پشتیبانی از API نسخه 2.x در SQLAlchemy از طریق پارامتر \fBmodel_class\fP\&. #1140 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1140>
.IP \(bu 2
افزایش حداقل نسخه SQLAlchemy به 2.0.16.
.IP \(bu 2
حذف کدهای از پیش منسوخ‌شده.
.IP \(bu 2
ارسال آرگومان‌های کلیدواژه‌ای اضافی از \fBget_or_404\fP به \fBsession.get\fP\&. #1149 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1149>
.IP \(bu 2
رفع باگ در یافتن bind key مناسب برای دستورهای clause. #1211 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1211>
.UNINDENT
.SS "نسخه 3.0.5 (Version 3.0.5)"
.sp
منتشر شده در 2023\-06\-21
.INDENT 0.0
.IP \(bu 2
متد \fBPagination.next()\fP مقدار \fBmax_per_page\fP را اعمال می‌کند. #1201 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1201>
.IP \(bu 2
بهبود اعلان نوع (type hint) برای مقدار بازگشتی \fBget_or_404\fP به non\-optional. #1226 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:1226>
.UNINDENT
.SS "نسخه 3.0.4 (Version 3.0.4)"
.sp
منتشر شده در 2023\-06\-19
.INDENT 0.0
.IP \(bu 2
رفع مشکل اعلان نوع برای مقدار بازگشتی \fBget_or_404\fP\&. #1208 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:1208>
.IP \(bu 2
رفع اعلان‌های نوع برای pyright (مورد استفاده در افزونه Pylance برنامه VS Code). #1205 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1205>
.UNINDENT
.SS "نسخه 3.0.3 (Version 3.0.3)"
.sp
منتشر شده در 2023\-01\-31
.INDENT 0.0
.IP \(bu 2
نمایش خطاهای راهنما هنگام استفاده اشتباه از چندین نمونه \fBSQLAlchemy\fP برای
یک برنامه یکسان، یا بدون فراخوانی \fBinit_app\fP\&. #1151 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:1151>
.IP \(bu 2
رفع مشکل در دریافت engine مرتبط با مدلی که از وراثت جدول چندریختی (polymorphic)
استفاده می‌کند. #1155 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1155>
.UNINDENT
.SS "نسخه 3.0.2 (Version 3.0.2)"
.sp
منتشر شده در 2022\-10\-14
.INDENT 0.0
.IP \(bu 2
به‌روزرسانی سازگاری با SQLAlchemy 2. #1122 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1122>
.UNINDENT
.SS "نسخه 3.0.1 (Version 3.0.1)"
.sp
منتشر شده در 2022\-10\-11
.INDENT 0.0
.IP \(bu 2
برون‌ریزی اطلاعات نوع‌بندی (typing) به‌جای استفاده از تعاریف خارجی typeshed.
#1112 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1112>
.IP \(bu 2
اگر گزینه‌های پیش‌فرض engine تنظیم شده باشند، اما \fBSQLALCHEMY_DATABASE_URI\fP تعیین نشده باشد، یک
bind پیش‌فرض نامعتبر پیکربندی نخواهد شد. #1117 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1117>
.UNINDENT
.SS "نسخه 3.0.0 (Version 3.0.0)"
.sp
منتشر شده در 2022\-10\-04
.INDENT 0.0
.IP \(bu 2
پایان پشتیبانی از Python 2، 3.4، 3.5 و 3.6.
.IP \(bu 2
افزایش حداقل نسخه Flask به 2.2.
.IP \(bu 2
افزایش حداقل نسخه SQLAlchemy به 1.4.18.
.IP \(bu 2
حذف کدهای از پیش منسوخ‌شده.
.IP \(bu 2
محدوده نشست (session) اکنون به‌جای thread، به بافت فعلی برنامه (app context) مقید است. این امر
نیازمند فعال بودن یک app context است و تضمین می‌کند که session پس از هر درخواست
پاک‌سازی می‌شود.
.IP \(bu 2
برای دسترسی به \fBsession\fP و \fBengine\fP، صرف‌نظر از اینکه برنامه‌ای به سازنده داده شده باشد یا خیر،
همواره یک بافت فعال برنامه Flask مورد نیاز است.
#508 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:508>#944 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:944>
.IP \(bu 2
کلیدهای bind مختلف از ثبات‌های \fBMetaData\fP متفاوت در SQLAlchemy استفاده می‌کنند، که امکان هم‌نام
بودن جدول‌ها در پایگاه‌های داده مختلف را فراهم می‌سازد. کلیدهای bind به‌جای مدل یا جدول،
روی متادیتای حاصل ذخیره و بازیابی می‌شوند.
.IP \(bu 2
مقدار \fBSQLALCHEMY_DATABASE_URI\fP به‌طور پیش‌فرض به \fBsqlite:///:memory:\fP تنظیم نمی‌شود. اگر
نه این گزینه و نه \fBSQLALCHEMY_BINDS\fP هیچ engineای را تعریف نکنند، خطایی صادر می‌شود. #731 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:731>
.IP \(bu 2
پیکربندی SQLite با یک مسیر نسبی، نسبت به \fBapp.instance_path\fP سنجیده می‌شود و نه
\fBapp.root_path\fP\&. در صورت لزوم، پوشه instance ایجاد می‌شود. #462 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:462>
.IP \(bu 2
افزوده شدن متدهای \fBget_or_404\fP، \fBfirst_or_404\fP، \fBone_or_404\fP و \fBpaginate\fP به
شیء افزونه. این‌ها به‌جای رابط قدیمی query، از الگوی ترجیحی SQLAlchemy یعنی
\fBsession.execute(select())\fP استفاده می‌کنند. #1088 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1088>
.IP \(bu 2
متدهای راه‌اندازی که engineها و session را ایجاد می‌کنند، با یک خط زیر (underscore) در ابتدا
تغییر نام یافته‌اند. این متدها رابط‌های داخلی محسوب شده و ممکن است در هر زمانی تغییر کنند.
.IP \(bu 2
تمام پارامترهای \fBSQLAlchemy\fP به‌جز \fBapp\fP صرفاً به‌صورت کلیدواژه‌ای هستند.
.IP \(bu 2
تغییر نام پارامتر \fBbind\fP به \fBbind_key\fP و حذف پارامتر \fBapp\fP از متدهای مختلف \fBSQLAlchemy\fP\&.
.IP \(bu 2
شیء افزونه به‌جای رونوشت‌برداری از نام‌ها به‌عنوان ویژگی، از \fB__getattr__\fP برای نام‌های مستعار
از بسته SQLAlchemy استفاده می‌کند.
.IP \(bu 2
شیء افزونه مستقیماً به‌صورت \fBapp.extensions[\(dqsqlalchemy\(dq]\fP ذخیره می‌شود.
#698 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:698>
.IP \(bu 2
کلاس نشست می‌تواند با ارسال کلید \fBclass_\fP در پارامتر \fBsession_options\fP
سفارشی‌سازی شود. #327 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:327>
.IP \(bu 2
نام \fBSignallingSession\fP به \fBSession\fP تغییر یافت.
.IP \(bu 2
متد \fBSession.get_bind\fP تطابق بیشتری با پیاده‌سازی پایه دارد.
.IP \(bu 2
کلاس‌های مدل و نمونه \fBdb\fP بدون نیاز به واردسازی (import) در \fBflask shell\fP در دسترس هستند.
#1089 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1089>
.IP \(bu 2
تبدیل‌کننده نام جدول از \fBCamelCase\fP به \fBsnake_case\fP الگوهای بیشتری را به‌درستی مدیریت می‌کند.
اگر مدلی که پیش‌تر در پایگاه داده ایجاد شده بود تغییر کرده باشد، یا از Alembic برای تغییر نام جدول استفاده کنید،
یا \fB__tablename__\fP را تنظیم نمایید تا نام قبلی حفظ شود.
#406 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:406>
.IP \(bu 2
خروجی \fBrepr\fP در \fBModel\fP بین نمونه‌های گذرا (transient) و در انتظار (pending) تفاوت قائل می‌شود.
#967 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:967>
.IP \(bu 2
یک کلاس مدل سفارشی می‌تواند \fB__init_subclass__\fP را به همراه پارامترهای کلاس پیاده‌سازی کند.
#1002 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1002>
.IP \(bu 2
ویژگی \fBdb.Table\fP به‌جای تابع، یک زیرکلاس است.
.IP \(bu 2
پارامتر \fBengine_options\fP پیش از اعمال پیکربندی اختصاصی هر موتور به‌صورت مقادیر پیش‌فرض اعمال می‌شود.
.IP \(bu 2
مقادیر \fBSQLALCHEMY_BINDS\fP برای هر bind می‌توانند یک URL موتور یا یک دیکشنری از گزینه‌های موتور
شامل URL باشند. متغیرهای \fBSQLALCHEMY_DATABASE_URI\fP و \fBSQLALCHEMY_ENGINE_OPTIONS\fP متناظر با
کلید \fBNone\fP هستند و اولویت دارند.
#783 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:783>
.IP \(bu 2
موتورها به‌هنگام فراخوانی \fBinit_app\fP ایجاد می‌شوند، نه در نخستین باری که به آن‌ها
دسترسی پیدا می‌شود. #698 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:698>
.IP \(bu 2
ویژگی \fBdb.engines\fP نگاشت کلیدهای bind به موتورها را برای برنامه فعلی در دسترس قرار می‌دهد.
.IP \(bu 2
متدهای \fBget_engine\fP، \fBget_tables_for_bind\fP و \fBget_binds\fP منسوخ شده‌اند.
.IP \(bu 2
شناسه‌های URI در سطح درایور SQLite که شبیه به \fBsqlite:///file:name.db?uri=true\fP هستند
پشتیبانی می‌شوند. #998 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:998>#1045 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1045>
.IP \(bu 2
موتورهای SQLite اگر \fBpool_size\fP برابر با 0 باشد از \fBNullPool\fP استفاده نمی‌کنند.
.IP \(bu 2
موتورهای MySQL به‌طور پیش‌فرض از مجموعه نویسه \(dqutf8mb4\(dq استفاده می‌کنند. #875 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:875>
.IP \(bu 2
موتورهای MySQL مقدار \fBpool_size\fP را روی 10 تنظیم نمی‌کنند.
.IP \(bu 2
موتورهای MySQL در صورت عدم استفاده از queue pool، مقدار پیش‌فرضی برای \fBpool_recycle\fP تعیین نمی‌کنند.
#803 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:803>
.IP \(bu 2
نام \fBBaseQuery\fP به \fBQuery\fP تغییر یافت.
.IP \(bu 2
متد \fBQuery.one_or_404\fP افزوده شد.
.IP \(bu 2
کلاس query بر روی \fBbackref\fP در \fBrelationship\fP اعمال می‌شود. #417 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:417>
.IP \(bu 2
ایجاد دستی اشیاء \fBPagination\fP دیگر یک API عمومی نیست. آن‌ها باید
توسط \fBdb.paginate\fP یا \fBquery.paginate\fP ایجاد شوند. #1088 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1088>.IP \(bu 2
پارامترهای \fBPagination.iter_pages\fP و \fBQuery.paginate\fP تنها به‌صورت کلیدواژه‌ای (keyword\-only) هستند.
.IP \(bu 2
کلاس \fBPagination\fP قابل‌پیمایش (iterable) است و بر روی آیتم‌های خود پیمایش می‌کند. #70 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/70>
.IP \(bu 2
پرس‌وجوی شمارش صفحه‌بندی بهینه‌تر شده است.
.IP \(bu 2
متد \fBPagination.iter_pages\fP بهینه‌تر شده است. #622 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:622>
.IP \(bu 2
پارامتر \fBright_current\fP در \fBPagination.iter_pages\fP فراگیر (inclusive) است.
.IP \(bu 2
مقدار \fBper_page\fP در صفحه‌بندی نمی‌تواند 0 باشد. #1091 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1091>
.IP \(bu 2
مقدار پیش‌فرض \fBmax_per_page\fP در صفحه‌بندی 100 است. #1091 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1091>
.IP \(bu 2
ویژگی‌های \fBPagination.first\fP و \fBlast\fP اضافه شدند که شماره اولین و
آخرین آیتم صفحه را ارائه می‌دهند. #567 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:567>
.IP \(bu 2
متغیر \fBSQLALCHEMY_RECORD_QUERIES\fP به‌طور پیش‌فرض غیرفعال است و با
\fBapp.debug\fP یا \fBapp.testing\fP به‌طور خودکار فعال نمی‌شود\&. #1092 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:1092>
.IP \(bu 2
نام \fBget_debug_queries\fP به \fBget_recorded_queries\fP تغییر یافت تا با
پیکربندی و عملکرد همخوانی بهتری داشته باشد.
.IP \(bu 2
اطلاعات پرس‌وجوهای ضبط‌شده اکنون به جای یک tuple، یک dataclass است. مشخصه \fBcontext\fP به
\fBlocation\fP تغییر نام یافته است\&. یافتن مکان از بررسی جامع‌تری استفاده می‌کند.
.IP \(bu 2
متغیر \fBSQLALCHEMY_TRACK_MODIFICATIONS\fP به‌طور پیش‌فرض غیرفعال است. #727 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:727>
.IP \(bu 2
متغیر \fBSQLALCHEMY_COMMIT_ON_TEARDOWN\fP منسوخ شده است. این متغیر می‌تواند باعث مشکلات گوناگون طراحی
شود که اشکال‌زدایی آن‌ها دشوار است. در عوض مستقیماً \fBdb.session.commit()\fP را فراخوانی کنید.
#216 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:216>
.UNINDENT
.SS نسخه 2.5.1
.sp
منتشرشده در 2021\-03\-18
.INDENT 0.0
.IP \(bu 2
رفع مشکل سازگاری با Python 2.7.
.UNINDENT
.SS نسخه 2.5.0
.sp
منتشرشده در 2021\-03\-18
.INDENT 0.0
.IP \(bu 2
به‌روزرسانی برای پشتیبانی از SQLAlchemy 1.4.
.IP \(bu 2
اشیاء \fBURL\fP در SQLAlchemy تغییرناپذیر هستند. برخی از متدهای داخلی تغییر یافته‌اند تا
به جای \fBNone\fP، یک URL جدید بازگردانند\&. #885 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:885>
.UNINDENT
.SS نسخه 2.4.4
.sp
منتشرشده در 2020\-07\-14
.INDENT 0.0
.IP \(bu 2
تغییر کلاس پایه mixinهای متا به \fBtype\fP\&. این تغییر مشکلی را که در اثر
پس‌رفت در CPython 3.8.4 ایجاد شده بود برطرف می‌کند. #852 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:852>
.UNINDENT
.SS نسخه 2.4.3
.sp
منتشرشده در 2020\-05\-26
.INDENT 0.0
.IP \(bu 2
منسوخ شدن \fBSQLALCHEMY_COMMIT_ON_TEARDOWN\fP به دلیل اینکه می‌تواند باعث مشکلات گوناگون طراحی
شود که اشکال‌زدایی آن‌ها دشوار است. در عوض مستقیماً \fBdb.session.commit()\fP را فراخوانی کنید.
#216 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:216>
.UNINDENT
.SS نسخه 2.4.2
.sp
منتشرشده در 2020\-05\-25
.INDENT 0.0
.IP \(bu 2
رفع مشکل صفحه‌بندی نادرست در زمان یکتا‌سازی (de\-duped) رکوردها. #812 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:812>
.UNINDENT
.SS نسخه 2.4.1
.sp
منتشرشده در 2019\-09\-24
.INDENT 0.0
.IP \(bu 2
رفع خطای \fBAttributeError\fP هنگام استفاده از چندین bind با مدل‌های چندریختی (polymorphic). #651 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:651>
.UNINDENT.SS "نسخه 2.4.0 (Version 2.4.0)"
.sp
منتشرشده در 2019\-04\-24
.INDENT 0.0
.IP \(bu 2
حذف پشتیبانی از Python 2.6 و 3.3. #687 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:687>
.IP \(bu 2
رسیدگی به موارد منسوخ‌شده در SQLAlchemy 1.3. #684 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:684>
.IP \(bu 2
انعطاف‌پذیرتر کردن پیکربندی engine. پارامتر \fBengine_options\fP و
پیکربندی \fBSQLALCHEMY_ENGINE_OPTIONS\fP اضافه شدند. کلیدهای پیکربندی گزینه‌های مجزای engine شامل
\fBSQLALCHEMY_NATIVE_UNICODE\fP، \fBSQLALCHEMY_POOL_SIZE\fP،
\fBSQLALCHEMY_POOL_TIMEOUT\fP، \fBSQLALCHEMY_POOL_RECYCLE\fP و
\fBSQLALCHEMY_MAX_OVERFLOW\fP\& منسوخ شدند. #684 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:684>
.IP \(bu 2
توابع \fBget_or_404()\fP و \fBfirst_or_404()\fP اکنون پارامتر \fBdescription\fP را برای
کنترل پیام 404 می‌پذیرند. #636 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:636>
.IP \(bu 2
استفاده از \fBtime.perf_counter\fP برای Python 3 در Windows. #638 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:638>
.IP \(bu 2
افزودن نمونه‌ای از پروژه آموزشی Flask به نام Flaskr، که برای Flask\-SQLAlchemy سازگار شده است.
#720 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:720>
.UNINDENT
.SS "نسخه 2.3.2 (Version 2.3.2)"
.sp
منتشرشده در 2017\-10\-11
.INDENT 0.0
.IP \(bu 2
عدم پنهان‌سازی جدول والد برای مدل‌های وراثت تک‌جدولی (single\-table inheritance). #561 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:561>
.UNINDENT
.SS "نسخه 2.3.1 (Version 2.3.1)"
.sp
منتشرشده در 2017\-10\-05
.INDENT 0.0
.IP \(bu 2
اگر یک مدل نام جدولی داشته باشد که با جدول موجود در metadata مطابقت دارد، از همان
جدول استفاده می‌شود. رفع پس‌رفتی که در آن جدول‌های منعکس‌شده (reflected) توسط مدل‌ها شناسایی نمی‌شدند.
#551 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:551>
.IP \(bu 2
ایجاد خطای صحیح هنگامی که یک مدل دارای نام جدول است اما کلید اصلی (primary key) ندارد. #556 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:556>
.IP \(bu 2
رفع مشکل \fBrepr\fP در مدل‌هایی که به دلیل عدم flush شدن، هنوز هویتی ندارند. #555 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:555>
.IP \(bu 2
امکان تعیین حد \fBmax_per_page\fP برای صفحه‌بندی، به منظور جلوگیری از تعیین مقادیر بسیار بالا در آرگومان‌های درخواست توسط کاربران. #542 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:542>
.IP \(bu 2
برای تابع \fBpaginate\fP با \fBerror_out=False\fP، حداقل مقدار برای \fBpage\fP برابر 1 و برای \fBper_page\fP برابر 0 است. #558 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:558>
.UNINDENT
.SS "نسخه 2.3.0 (Version 2.3.0)"
.sp
منتشرشده در 2017\-09\-28
.INDENT 0.0
.IP \(bu 2
رفع چندین باگ در تولید خودکار \fB__tablename__\fP\&. نام‌ها برای مدل‌هایی که یک کلید اصلی تعریف
می‌کنند تولید خواهد شد، اما برای زیرکلاس‌های وراثت تک‌جدولی (single\-table inheritance) خیر.
نام‌ها ویژگی \fBdeclared_attr\fP\& را رونویسی نخواهند کرد. \fBPrimaryKeyConstraint\fP
شناسایی می‌شود. #541 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:541>
.IP \(bu 2
ارسال یک \fBdeclarative_base()\fP موجود به عنوان \fBmodel_class\fP به
\fBSQLAlchemy.__init__\fP باعث می‌شود از آن به عنوان کلاس پایه به جای ساخت کلاس جدید استفاده شود.
این امر اجازه سفارشی‌سازی metaclass مورد استفاده برای ساخت کلاس پایه را می‌دهد. #546 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:546>
.IP \(bu 2
بخش‌های درونی و مستندنیافته‌ی \fBDeclarativeMeta\fP که این افزونه برای bindها و
تولید نام جدول استفاده می‌کرد، به صورت mixin بازطراحی شدند. مستنداتی درباره چگونگی ایجاد
یک metaclass سفارشی که نام جدول را تولید نمی‌کند، اضافه شد.
#546 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:546>
.IP \(bu 2
کدهای مدل و metaclass به ماژول جدید \fBmodels\fP منتقل شدند.
نام \fB_BoundDeclarativeMeta\fP به \fBDefaultMeta\fP تغییر یافت؛ نام قبلی در
نسخه 3.0 حذف خواهد شد. #546 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:546>
.IP \(bu 2
مدل‌ها یک \fBrepr\fP پیش‌فرض دارند که نام مدل و کلید اصلی را نشان می‌دهد. #530 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:530>
.IP \(bu 2
رفع باگی که در آن استفاده از \fBinit_app\fP باعث می‌شد متصل‌کننده‌ها همیشه به جای برنامه‌ای
که برای آن ساخته شده‌اند از \fBcurrent_app\fP استفاده کنند. این امر هنگام ثبت چندین برنامه
در افزونه مشکلاتی ایجاد می‌کرد. #547 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:547>
.UNINDENT
.SS "نسخه 2.2 (Version 2.2)"
.sp
منتشرشده در 2017\-02\-27، با نام رمز Dubnium
.INDENT 0.0
.IP \(bu 2
حداقل نسخه SQLAlchemy به دلیل استفاده از \fBsqlalchemy.inspect\fP\& برابر 0.8 است.
.IP \(bu 2
افزودن پشتیبانی از \fBquery_class\fP و \fBmodel_class\fP سفارشی به عنوان آرگومان به
سازنده \fBSQLAlchemy\fP\&. #328 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:328>
.IP \(bu 2
امکان شنود رویدادهای SQLAlchemy روی \fBdb.session\fP\&. #364 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:364>
.IP \(bu 2
امکان استفاده از \fB__bind_key__\fP روی مدل‌های انتزاعی. #373 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:373>
.IP \(bu 2
امکان رشته‌ای بودن \fBSQLALCHEMY_ECHO\fP\&. #409 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:409>
.IP \(bu 2
هشدار در زمانی که \fBSQLALCHEMY_DATABASE_URI\fP تنظیم نشده است. #443 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:pull/\:443>
.IP \(bu 2
جلوگیری از تولید شماره صفحه‌های نامعتبر توسط صفحه‌بندی. #460 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:460>
.IP \(bu 2
حذف پشتیبانی از Flask < 0.10. این بدان معناست که نشست db همیشه به بافتار برنامه
(app context) و رویداد teardown آن متصل است. #461 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:461>
.IP \(bu 2
منطق تولید نام جدول دیگر به ویژگی‌های کلاس دسترسی پیدا نمی‌کند مگر اینکه
\fBdeclared_attr\fP\& باشند. #467 \%<https://\:github\:.com/\:pallets-eco/\:flask-sqlalchemy/\:issues/\:467>
.UNINDENT.SS نسخه 2.1
.sp
منتشرشده در 2015\-10\-23، با نام رمز Caesium
.INDENT 0.0
.IP \(bu 2
نام‌های جدول در موارد بیشتری، از جمله ارث‌بری از mixinها و مدل‌های انتزاعی، به‌طور خودکار تولید می‌شوند.
.IP \(bu 2
امکان استفاده از یک شیء سفارشی MetaData فراهم شد.
.IP \(bu 2
افزودن پشتیبانی از پارامتر binds برای session.
.UNINDENT
.SS نسخه 2.0
.sp
منتشرشده در 2014\-08\-29، با نام رمز Bohrium
.INDENT 0.0
.IP \(bu 2
تغییر نحوهٔ اشتراک در سیگنال‌های توکار به منظور نادیده گرفتن نشست‌های غیر Flask\-SQLAlchemy. این تغییر همچنین خطای مشخصه (attribute error) مبنی بر عدم وجود تغییرات مدل را رفع می‌کند.
.IP \(bu 2
افزودن روشی برای کنترل نحوهٔ ردیابی سیگنال‌های تغییرات مدل.
.IP \(bu 2
تبدیل \fBSignallingSession\fP به یک رابط عمومی و افزودن یک هوک (hook) برای سفارشی‌سازی ایجاد نشست.
.IP \(bu 2
اگر پارامتر \fBbind\fP به نشست سیگنال‌دهنده داده شود، دیگر خطایی مبنی بر ارسال دوبارهٔ یک پارامتر ایجاد نخواهد کرد.
.IP \(bu 2
افزودن پشتیبانی کاربردی از بازتاب جدول (table reflection).
.IP \(bu 2
فعال‌سازی پیش‌فرض autoflush.
.IP \(bu 2
مضر در نظر گرفتن \fBSQLALCHEMY_COMMIT_ON_TEARDOWN\fP و حذف آن از مستندات.
.UNINDENT
.SS نسخه 1.0
.sp
منتشرشده در 2013\-07\-20، با نام رمز Aurum
.INDENT 0.0
.IP \(bu 2
پشتیبانی از Python 3.3 اضافه شد.
.IP \(bu 2
سازگاری با Python 2.5 کنار گذاشته شد.
.IP \(bu 2
رفع اشکالات گوناگون.
.IP \(bu 2
تغییر قالب نسخه‌گذاری برای انتشار نسخه‌های اصلی (major) در هر به‌روزرسانی از این پس.
.UNINDENT
.SS نسخه 0.16
.INDENT 0.0
.IP \(bu 2
قالب توزیع جدید (flask_sqlalchemy).
.IP \(bu 2
افزودن پشتیبانی از ویژگی‌های خاص Flask 0.9.
.UNINDENT
.SS نسخه 0.15
.INDENT 0.0
.IP \(bu 2
افزودن پشتیبانی نشست (session) برای چندین پایگاه داده.
.UNINDENT
.SS نسخه 0.14
.INDENT 0.0
.IP \(bu 2
محاسبهٔ مسیرهای نسبی sqlite به‌صورت نسبی نسبت به ریشهٔ برنامه.
.UNINDENT
.SS نسخه 0.13
.INDENT 0.0
.IP \(bu 2
رفع مشکلی که در آن Flask\-SQLAlchemy متصل‌کننده‌های (binds) صحیح را انتخاب نمی‌کرد.
.UNINDENT
.SS نسخه 0.12
.INDENT 0.0
.IP \(bu 2
پشتیبانی از چندین پایگاه داده اضافه شد.
.IP \(bu 2
در دسترس قرار دادن \fBBaseQuery\fP به‌صورت \fBdb.Query\fP\&.
.IP \(bu 2
تنظیم مقدار پیش‌فرض \fBquery_class\fP برای \fBdb.relation\fP، \fBdb.relationship\fP و
\fBdb.dynamic_loader\fP روی \fBBaseQuery\fP\&.
.IP \(bu 2
بهبود سازگاری با Flask 0.7.
.UNINDENT.SS نسخه 0.11
.INDENT 0.0
.IP \(bu 2
رفع باگ ایجاد شده در نسخه 0.10 مربوط به سازنده‌های جایگزین جدول.
.UNINDENT
.SS نسخه 0.10
.INDENT 0.0
.IP \(bu 2
افزودن پشتیبانی از سیگنال‌ها.
.IP \(bu 2
نام‌های جدول اکنون به‌طور خودکار از نام کلاس تنظیم می‌شوند، مگر اینکه بازنویسی شوند.
.IP \(bu 2
اکنون \fBModel.query\fP همیشه برای برنامه‌هایی که مستقیماً به سازندهٔ \fBSQLAlchemy\fP ارسال می‌شوند کار می‌کند. علاوه بر این، این ویژگی اکنون به‌جای \fBNone\fP بودن، خطای \fBRuntimeError\fP صادر می‌کند\&.
.IP \(bu 2
افزودن گزینه‌های نشست (session) به سازنده.
.IP \(bu 2
رفع اشکال \fB__repr__\fP معیوب\&.
.IP \(bu 2
اکنون \fBdb.Table\fP یک تابع کارخانه‌ای است که اشیاء جدول را ایجاد می‌کند. این ویژگی امکان حذف متادیتا را ممکن می‌سازد.
.UNINDENT
.SS نسخه 0.9
.INDENT 0.0
.IP \(bu 2
اعمال تغییرات برای قبولی در فرآیند تأیید افزونهٔ Flask.
.UNINDENT
.SS نسخه 0.8
.INDENT 0.0
.IP \(bu 2
افزودن چند کلید پیکربندی برای ایجاد اتصالات.
.IP \(bu 2
فعال‌سازی خودکار بازیافت اتصال (connection recycling) برای اتصالات MySQL.
.IP \(bu 2
افزودن پشتیبانی از حالت آزمایشی Flask.
.UNINDENT
.SS نسخه 0.7
.INDENT 0.0
.IP \(bu 2
نخستین انتشار عمومی
.UNINDENT
.SH "نویسندگان (AUTHORS)"
Pallets
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
2010 Pallets
.\" End of generated man page.