آموزش کار با SQLAlchemy 2.0 و Alembic در پایتون (معماری مدرن Async ORM)
در توسعه سیستمهای بکاند با پایتون، ارتباط اصولی با پایگاه داده، نگهداری ساختار جداول و اجرای بهینه کوئریها از اساسیترین مباحث معماری نرمافزار به شمار میرود. نسخه SQLAlchemy 2.0 به عنوان یک بازنویسی انقلابی، استانداردهای قدیمی نسخههای 1.x را کنار گذاشته و امکاناتی نظیر مدلسازی تایپسیف با Mapped و mapped_column، سینتکس یکپارچه select() و پشتیبانی بومی از برنامهنویسی ناهمگام (AsyncIO) را به ارمغان آورده است.
در کنار آن، ابزار Alembic به عنوان ابزار رسمی مدیریت مایگریشنها، فرآیند اعمال تغییرات اسکیمای دیتابیس (Migrations) را بدون از دست رفتن دادهها و به شکل اتوماتیک مدیریت میکند.
پاسخ کوتاه: در SQLAlchemy 2.0، متد منسوخ session.query() به طور کامل با select() جایگزین شده است. تعریف ستونها با تایپهای نیتیو پایتون (Mapped[int]) انجام میشود و برای پروژههای ناهمگام مدرن (مانند FastAPI) از create_async_engine و asyncpg استفاده میگردد.
چرا مهاجرت به SQLAlchemy 2.0 ضروری است؟
- پشتیبانی کامل از Static Type Checking: مدلها و کوئریها با mypy و Pyright سازگاری کامل دارند؛ در نتیجه خطاهای نام ستونها یا نوع داده در محیط IDE بلافاصله مشخص میشوند.
- معماری نیتیو Async: پردازش همزمان درخواستهای I/O دیتابیس بدون مسدود شدن Event Loop با درایورهای مثل
asyncpgیاpsycopg3. - حذف سینتکسهای چندگانه: در نسخه ۲ تنها یک روش استاندارد بر پایه دستور
select()برای کوئری زدن وجود دارد که کدبیس را بسیار یکدست و خوانا میکند.
گام اول: نصب پکیجهای مورد نیاز
برای پروژههای مدرن وب بر پایه PostgreSQL، پکیجهای زیر را نصب میکنیم:
pip install "sqlalchemy>=2.0.0" "alembic>=1.13.0" "asyncpg>=0.29.0" python-dotenv
- sqlalchemy: کتابخانه اصلی ORM و Core.
- alembic: ابزار کنترل نسخه پایگاه داده.
- asyncpg: سریعترین درایور ارتباط ناهمگام با PostgreSQL در پایتون.
گام دوم: ساخت موتور اتصال و سشن ناهمگام (database.py)
در ساختار پروژه، لایه اتصال به پایگاه داده را به صورت زیر پیادهسازی میکنیم:
import os
from collections.abc import AsyncGenerator
from dotenv import load_dotenv
from sqlalchemy.ext.asyncio import (
AsyncSession,
async_sessionmaker,
create_async_engine,
)
from sqlalchemy.orm import DeclarativeBase
load_dotenv()
DATABASE_URL = os.getenv(
"DATABASE_URL",
"postgresql+asyncpg://postgres:password@localhost:5432/my_project_db"
)
# ایجاد Engine ناهمگام با تنظیمات Pool
engine = create_async_engine(
DATABASE_URL,
echo=False, # برای لاگ کوئریهای SQL در محیط توسعه روی True بگذارید
pool_size=10, # تعداد اتصالات همزمان در Pool
max_overflow=20,
pool_pre_ping=True, # بررسی سلامت اتصال پیش از واگذاری به سشن
)
# فکتوری تولید Sessionهای ناهمگام
AsyncSessionFactory = async_sessionmaker(
bind=engine,
class_=AsyncSession,
expire_on_commit=False, # جلوگیری از رفرش ناخواسته آبجکتها بعد از کامیت
)
# کلاس پایه Declarative برای تعریف مدلها
class Base(DeclarativeBase):
pass
# جنریتور دریافت سشن جهت استفاده در Dependency Injection فریمورکها
async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
async with AsyncSessionFactory() as session:
try:
yield session
except Exception:
await session.rollback()
raise
گام سوم: تعریف مدلهای دیتابیس با سینتکس مدرن 2.0
در SQLAlchemy 2.0، ستونها به کمک Mapped تعریف میشوند که نوع داده پایتونی را مستقیماً به نوع داده SQL متصل میکند:
from datetime import datetime
from sqlalchemy import ForeignKey, String, Text, func
from sqlalchemy.orm import Mapped, mapped_column, relationship
from database import Base
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
username: Mapped[str] = mapped_column(String(50), unique=True, index=True, nullable=False)
email: Mapped[str] = mapped_column(String(255), unique=True, index=True, nullable=False)
is_active: Mapped[bool] = mapped_column(default=True)
created_at: Mapped[datetime] = mapped_column(server_default=func.now())
# رابطه یکبهچند با مقالات
articles: Mapped[list["Article"]] = relationship(back_populates="author", cascade="all, delete-orphan")
class Article(Base):
__tablename__ = "articles"
id: Mapped[int] = mapped_column(primary_key=True)
title: Mapped[str] = mapped_column(String(250), nullable=False)
slug: Mapped[str] = mapped_column(String(250), unique=True, index=True)
body: Mapped[str] = mapped_column(Text, nullable=False)
author_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
author: Mapped[User] = relationship(back_populates="articles")
گام چهارم: اجرای کوئریهای مدرن با select()
عملیات رایج CRUD در نسخه جدید بسیار تمیز و قابل فهم است:
from sqlalchemy import select
from sqlalchemy.orm import selectinload
from database import AsyncSessionFactory
async def query_examples():
async with AsyncSessionFactory() as session:
# ۱. دریافت یک رکورد بر اساس شناسه
stmt = select(User).where(User.id == 1)
result = await session.execute(stmt)
user = result.scalar_one_or_none()
# ۲. فچ کردن لیست همراه با روابط (Eager Loading با selectinload)
stmt_with_articles = (
select(User)
.options(selectinload(User.articles))
.where(User.is_active.is_(True))
.order_by(User.created_at.desc())
)
users = (await session.scalars(stmt_with_articles)).all()
# ۳. درج رکورد جدید
new_user = User(username="taha", email="taha@example.com")
session.add(new_user)
await session.commit()
await session.refresh(new_user)
گام پنجم: راهاندازی و اجرای Alembic
برای راهاندازی سیستم مایگریشن در مسیر ریشه پروژه:
alembic init -t async alembic
تنظیم alembic/env.py
در فایل alembic/env.py، متغیر target_metadata را به Base پروژه متصل کنید:
from database import Base
import models # ایمپورت تمام مدلها تا در متادیتا ثبت شوند
target_metadata = Base.metadata
سپس دستورات ایجاد و اعمال مایگریشن را اجرا نمایید:
# ساخت اتوماتیک فایل مایگریشن با بررسی تفاوت مدلها و دیتابیس
alembic revision --autogenerate -m "create users and articles tables"
# اعمال تغییرات بر روی پایگاه داده
alembic upgrade head
سوالات متداول
تفاوت scalar_one_or_none() با first() چیست؟
متد first() اولین نتیجه را برمیگرداند؛ اما scalar_one_or_none() اطمینان حاصل میکند که حداکثر یک رکورد با این شرط وجود دارد و در صورت وجود رکوردهای چندگانه استثنا صادر میکند که برای اعتبارسنجی فیلدهای Unique بسیار مناسبتر است.
چرا باید از expire_on_commit=False استفاده کرد؟
در محیط Async، اگر این گزینه غیرفعال باشد، SQLAlchemy بعد از کامیت صفات آبجکت را منقضی میکند و تلاش برای خواندن مجدد آنها نیازمند دسترسی به دیتابیس در سشن بسته شده بوده و منجر به خطای MissingGreenlet میشود.
برچسبهای این مقاله:
