Python SQLAlchemy ORM 框架入門完整指南

SQLAlchemy 是 Python 最知名的 ORM（Object-Relational Mapping）框架，將關聯式資料表映射為 Python 類別，讓資料庫操作更直觀、安全。本文從安裝、模型定義、CRUD 操作到關聯關係完整說明。

核心概念：ORM 是什麼？

傳統 DB-API 回傳元組列表：

[('1', 'Michael'), ('2', 'Bob'), ('3', 'Adam')]

ORM 映射為物件：

class User(object):
    def __init__(self, id, name):
        self.id = id
        self.name = name

[User('1', 'Michael'), User('2', 'Bob'), User('3', 'Adam')]

ORM 框架自動處理「資料列 ⇄ 物件」雙向轉換。

安裝與初始化

# 安裝
$ easy_install sqlalchemy
# 或
$ pip install sqlalchemy

from sqlalchemy import Column, String, create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.declarative import declarative_base

# 基類
Base = declarative_base()

# 定義模型
class User(Base):
    __tablename__ = 'user'
    id = Column(String(20), primary_key=True)
    name = Column(String(20))

# 資料庫連線
engine = create_engine('mysql+mysqlconnector://root:password@localhost:3306/test')
DBSession = sessionmaker(bind=engine)

連線字串格式：dialect+driver://user:pass@host:port/dbname

新增資料

session = DBSession()
new_user = User(id='5', name='Bob')
session.add(new_user)
session.commit()
session.close()

查詢資料

session = DBSession()
user = session.query(User).filter(User.id=='5').one()
print('type:', type(user))
print('name:', user.name)
session.close()

輸出：

type: 
name: Bob

關聯關係：一對多

class User(Base):
    __tablename__ = 'user'
    id = Column(String(20), primary_key=True)
    name = Column(String(20))
    books = relationship('Book')  # 一對多

class Book(Base):
    __tablename__ = 'book'
    id = Column(String(20), primary_key=True)
    name = Column(String(20))
    user_id = Column(String(20), ForeignKey('user.id'))  # 外鍵

查詢 user.books 即獲取該使用者所有書籍物件列表。

Session 管理最佳實踐

# 使用 context manager 確保關閉
from contextlib import contextmanager

@contextmanager
def session_scope():
    session = DBSession()
    try:
        yield session
        session.commit()
    except:
        session.rollback()
        raise
    finally:
        session.close()

# 使用
with session_scope() as session:
    user = session.query(User).filter_by(id='5').first()
    user.name = 'Updated'

常用查詢 API 速查

總結

• ORM 讓資料庫操作物件化，減少 SQL 注入風險
• SQLAlchemy 提供完整的映射、查詢、關聯、遷移功能
• 正確使用 ORM 前提是理解關聯式資料庫原理
• 生產環境建議配合 Alembic 進行資料庫遷移管理