Hướng dẫn cài đặt và sử dụng SQLAlchemy 2.0 với Python: ORM, Core API và Alembic Migration

Database tutorial - IT technology blog
Database tutorial - IT technology blog

Vấn đề: Nỗi đau mang tên Raw SQL và sửa DB thủ công

Hồi mới học Python, chắc hẳn nhiều người từng quen tay nối chuỗi raw SQL dạng f"SELECT * FROM users WHERE id = {user_id}" qua sqlite3 hay psycopg2. Cách này nhanh thật khi viết script cá nhân vài chục dòng. Nhưng hễ dự án chạm mốc 50 đến 100 API endpoints, rắc rối sẽ kéo đến ngay.

Code truy vấn nằm rải rác khắp các file khiến việc refactor trở thành ác mộng. Bạn dễ để lọt lỗ hổng SQL Injection chỉ vì một input quên validate. Tệ hơn, kiểu dữ liệu giữa database và Python thường xuyên lệch pha nhau.

Chưa dừng lại ở đó, quản lý schema database mới thực sự là bài toán hóc búa. Hãy tưởng tượng server production đang có 100.000 người dùng hoạt động. Bạn phải SSH trực tiếp vào server và gõ tay lệnh ALTER TABLE. Rủi ro cực kỳ cao. Chỉ cần lệch một cột giữa máy dev và server staging, đợt deploy lúc nửa đêm sẽ lập tức crash toàn bộ ứng dụng.

Gốc rễ vấn đề nằm ở việc thiếu một tầng trừu tượng hóa dữ liệu (Data Layer Abstraction) và công cụ quản lý phiên bản database độc lập. Đó là lý do bộ đôi SQLAlchemy 2.0 và Alembic trở thành tiêu chuẩn bắt buộc cho hầu hết dự án backend Python hiện nay.

Bốn khái niệm cốt lõi cần nhớ

Để không bị ngợp giữa hàng tá tài liệu, bạn chỉ cần nắm chắc 4 khối nền tảng sau:

  • Engine & Connection Pool: Cầu nối trực tiếp với database. Thành phần này quản lý pool kết nối (mặc định mở sẵn 5 đến 10 kết nối tái sử dụng), chuyển đổi dialect theo từng hệ quản trị (PostgreSQL, MySQL, SQLite) và đẩy query xuống database driver.
  • SQLAlchemy Core: Tầng truy vấn dạng biểu thức (SQL Expression Language). Core thao tác thẳng với các hàm như select() hay insert() mà không cần bọc qua class model. Khi cần viết batch job xử lý 500.000 dòng hoặc câu query phân tích nặng, Core cho tốc độ vượt trội hơn hẳn ORM.
  • SQLAlchemy ORM: Tầng ánh xạ bảng dữ liệu thành các class Python. Bản 2.0 đã chuẩn hóa với cú pháp Mapped và mapped_column. Nhờ đó, IDE gợi ý code rất mượt và các công cụ như mypy có thể bắt lỗi kiểu dữ liệu ngay từ lúc gõ phím.
  • Alembic: Công cụ quản lý schema migration do chính tác giả SQLAlchemy phát triển. Alembic tự động so sánh trạng thái model trong code với schema database thực tế. Sau đó, nó sinh ra file migration kèm hai hàm upgrade() và downgrade() để rollback an toàn khi có sự cố.

Thực hành từng bước

Bước 1: Khởi tạo môi trường và cài đặt thư viện

Hãy bắt đầu với một virtual environment sạch sẽ, sau đó cài đặt SQLAlchemy 2.0 cùng driver PostgreSQL (psycopg2-binary) và Alembic:

# Tạo và kích hoạt venv
python3 -m venv venv
source venv/bin/activate

# Cài đặt phiên bản mới nhất từ nhánh 2.0
pip install "sqlalchemy>=2.0" psycopg2-binary alembic

Bước 2: Thiết lập Engine, Base Model và Data Models

SQLAlchemy 2.0 loại bỏ hoàn toàn cú pháp Column(Integer, ...) rườm rà của bản 1.4 cũ để chuyển hẳn sang Type Annotations theo chuẩn PEP 484. Hãy tạo file database.py:

from datetime import datetime
from typing import Optional, List
from sqlalchemy import create_engine, String, ForeignKey, func
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship, sessionmaker

# Kết nối tới database PostgreSQL cục bộ
DATABASE_URL = "postgresql+psycopg2://postgres:secret@localhost:5432/itfromzero_db"
engine = create_engine(DATABASE_URL, echo=False, pool_size=10, max_overflow=20)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# Base class chuẩn theo cú pháp 2.0
class Base(DeclarativeBase):
    pass

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(100), unique=True, nullable=False)
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())

    # Quan hệ One-to-Many với bảng Post
    posts: Mapped[List["Post"]] = relationship(back_populates="author", cascade="all, delete-orphan")

    def __repr__(self) => str:
        return f"<User(id={self.id}, username='{self.username}')>"

class Post(Base):
    __tablename__ = "posts"

    id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
    title: Mapped[str] = mapped_column(String(200), nullable=False)
    content: Mapped[str] = mapped_column(nullable=False)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))

    author: Mapped["User"] = relationship(back_populates="posts")

    def __repr__(self) => str:
        return f"<Post(id={self.id}, title='{self.title}')>"

Bước 3: Khởi tạo và cấu hình Alembic để tự động hóa migration

Nhiều bài hướng dẫn khuyên bạn gọi Base.metadata.create_all(engine). Đừng làm vậy trên dự án thật! Lệnh này chỉ tạo bảng mới chứ không thể theo dõi hay sửa đổi cột về sau. Hãy để Alembic đảm nhận việc này:

alembic init alembic

Lệnh trên sẽ tạo ra file alembic.ini và thư mục alembic/. Mở file alembic/env.py và chỉnh sửa hai chỗ sau để Alembic nhận diện models của bạn:

# alembic/env.py
from logging.config import fileConfig
from sqlalchemy import engine_from_config, pool
from alembic import context

# 1. Import Base metadata từ project của bạn
from database import Base, DATABASE_URL

config = context.config

# Ghi đè URL kết nối từ database.py thay vì hardcode trong alembic.ini
config.set_main_option("sqlalchemy.url", DATABASE_URL)

if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# 2. Gán target_metadata để autogenerate so khớp được models
target_metadata = Base.metadata

# (Giữ nguyên các hàm run_migrations_offline và run_migrations_online mặc định)

Tiếp theo, tạo file migration đầu tiên và đồng bộ schema vào database:

# Quét model và tự động sinh mã migration
alembic revision --autogenerate -m "create_users_and_posts_tables"

# Đẩy thay đổi vào database
alembic upgrade head

Một lưu ý sống còn từ thực tế: đừng bao giờ tin tưởng tuyệt đối vào cờ --autogenerate. Trong một hệ thống database 100GB mình từng vận hành, có bạn dev đổi tên cột fullname thành full_name. Alembic không tự hiểu đây là thao tác đổi tên. Thay vào đó, nó sinh ra lệnh DROP COLUMN fullname rồi ADD COLUMN full_name. Nếu chạy thẳng lệnh này trên production, toàn bộ dữ liệu tên người dùng sẽ biến mất vĩnh viễn! Hãy luôn mở file trong alembic/versions/ ra kiểm tra trước khi gõ lệnh upgrade.

Bước 4: Thao tác CRUD chuẩn SQLAlchemy 2.0

Thay đổi lớn nhất ở bản 2.0 là việc khai tử cú pháp session.query(User). Giờ đây, cả ORM lẫn Core đều dùng chung cú pháp nhất quán session.execute(select(...)) hoặc session.scalars(...). Hãy tạo file crud_example.py để chạy thử:

from sqlalchemy import select, update, delete
from database import SessionLocal, User, Post

def run_orm_operations():
    # Quản lý session bằng context manager để tự động giải phóng kết nối
    with SessionLocal() as session:
        # 1. CREATE: Thêm mới dữ liệu kèm relationship
        new_user = User(username="thanhloc", email="[email protected]")
        post1 = Post(title="Làm chủ SQLAlchemy 2.0", content="Nội dung hướng dẫn ORM...", author=new_user)
        post2 = Post(title="Quản lý Migration bằng Alembic", content="Cách auto generate schema...", author=new_user)
        
        session.add(new_user)
        session.commit()
        print(f"Đã tạo User ID: {new_user.id}")

        # 2. READ: Dùng session.scalars() cho ORM model
        stmt = select(User).where(User.username == "thanhloc")
        user = session.scalars(stmt).first()
        if user:
            print(f"Tìm thấy user: {user.username} với {len(user.posts)} bài viết")

        # 3. UPDATE: Cập nhật trực tiếp trên object
        if user:
            user.email = "[email protected]"
            session.commit()
            print("Đã cập nhật email thành công!")

        # 4. READ với Core API: Trả về Row/tuple trực tiếp, không qua ORM
        core_stmt = select(User.id, User.username).where(User.id >= 1)
        rows = session.execute(core_stmt).all()
        for row in rows:
            print(f"[Core API Result] ID: {row.id}, Username: {row.username}")

        # 5. DELETE: Xóa dữ liệu
        delete_stmt = delete(Post).where(Post.id == post2.id)
        session.execute(delete_stmt)
        session.commit()
        print(f"Đã xóa post ID {post2.id}")

if __name__ == "__main__":
    run_orm_operations()

Tổng kết và checklist an toàn

Chuyển từ raw SQL sang SQLAlchemy 2.0 và Alembic ban đầu có thể khiến bạn mất chút thời gian làm quen cú pháp mới. Tuy nhiên, codebase của dự án sẽ gọn gàng, an toàn và dễ scale hơn rất nhiều. Trước khi triển khai lên production, hãy tự kiểm tra 3 nguyên tắc sau:

  1. Đọc kỹ file migration: Luôn review từng dòng code trong alembic/versions/ trước khi chạy lệnh upgrade head để tránh mất mát dữ liệu ngoài ý muốn.
  2. Ưu tiên session.scalars(): Với các câu truy vấn ORM lấy thực thể, hãy dùng scalars() thay vì session.execute() để nhận thẳng model object mà không cần giải nén tuple.
  3. Bọc session trong Context Manager: Luôn viết theo cú pháp with SessionLocal() as session:. Thói quen này đảm bảo session luôn được đóng chuẩn xác kể cả khi gặp lỗi, giúp connection pool không bao giờ bị nghẽn.
Share: