SQLAlchemy 使用簡介
SQLAlchemy 是 Python 最主流的資料庫工具包，同時提供直接組 SQL 的 Core 與以物件操作資料的 ORM（Object Relational Mapper，物件關聯對映）。使用 SQLAlchemy 最大的好處是：之後想更換資料庫伺服器時，通常只需要修改資料庫網址，其他程式碼大致上不需要變動。本頁以 SQLAlchemy 2.x 的寫法，介紹安裝、連線、定義模型、建立資料表與增刪查改。
安裝 SQLAlchemy
依想要連接的資料庫，還需要安裝對應的資料庫驅動（SQLite 使用 Python 內建的 sqlite3，不必另外安裝）：
# MySQL
pip install pymysql
# 或
pip install mysql-connector-python
# PostgreSQL（建議使用 psycopg 3）
pip install "psycopg[binary]"
# 或舊版 psycopg2；psycopg2-binary 內含編譯好的相依程式庫，方便開發
pip install psycopg2-binary
連線資料庫
from sqlalchemy import create_engine
engine_url = "dialect+driver://username:password@host:port/database"
engine = create_engine(engine_url, echo=True)
create_engine()：建立資料庫引擎（Engine）。引擎負責管理連線池（Connection Pool），並把 SQL 送到資料庫執行。echo=True：把執行的 SQL 語句印到標準輸出，方便除錯；正式環境請關閉。
常見的資料庫網址格式：
| 資料庫 | 網址範例 |
|---|---|
| SQLite | sqlite:///example.db（相對路徑）、sqlite:///:memory: |
| PostgreSQL（psycopg 3） | postgresql+psycopg://user:pass@localhost:5432/app_db |
| PostgreSQL（psycopg2） | postgresql+psycopg2://user:pass@localhost:5432/app_db |
| MySQL（PyMySQL） | mysql+pymysql://user:pass@localhost:3306/app_db?charset=utf8mb4 |
密碼含特殊字元
密碼中若有 @、/、: 等字元，要先用 urllib.parse.quote_plus() 編碼，或改用 sqlalchemy.URL.create() 分別傳入各參數。
定義模型
SQLAlchemy 2.x 以 DeclarativeBase 建立模型基底類別，並用 Mapped 型別註記搭配 mapped_column() 定義欄位：
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
class Base(DeclarativeBase):
pass
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(String(50))
age: Mapped[int | None]
def __repr__(self) -> str:
return f"User(id={self.id}, name={self.name!r}, age={self.age})"
Mapped[int]代表必填欄位（NOT NULL），Mapped[int | None]代表可為空值。- 舊教學常見的
declarative_base()與Column(...)寫法在 2.x 仍可使用，但新專案建議採用上面的寫法，編輯器的型別提示也比較完整。
建立資料表
create_all() 會為所有繼承 Base 的模型建立資料表；已存在的資料表會略過，不會被覆蓋。正式專案若需要修改既有資料表結構，建議使用 Alembic 管理資料庫遷移（Migration）。
建立及使用 Session
SQLAlchemy ORM 透過 Session 管理與資料庫的互動。Session 提供一個緩衝區，讓你在提交（commit）之前累積多個操作，並以一個交易一起寫入，有助於控制交易與減少直接操作資料庫的次數。
新增資料
from sqlalchemy.orm import Session
with Session(engine) as session:
user1 = User(name="John", age=25)
user2 = User(name="Mary", age=20)
user3 = User(name="Alex", age=28)
session.add(user1)
session.add_all([user2, user3])
session.commit()
上面的例子中，只有在 session.commit() 執行時，資料才會真的被寫入資料庫；with 區塊結束時 Session 會自動關閉。模型類別會自動產生接受關鍵字參數的建構子，因此要寫成 User(name="John", age=25)。
查詢資料
2.x 統一使用 select() 組查詢，再交給 session.scalars() 或 session.execute() 執行：
from sqlalchemy import select
with Session(engine) as session:
# 查詢多筆
stmt = select(User).where(User.age > 21).order_by(User.age)
for user in session.scalars(stmt):
print(user)
# 依主鍵取得一筆
user = session.get(User, 1)
# 查詢單一筆（找不到回傳 None）
mary = session.scalars(select(User).where(User.name == "Mary")).first()
修改與刪除
with Session(engine) as session:
user = session.get(User, 1)
user.age = 26 # 直接修改屬性
session.delete(session.get(User, 2))
session.commit() # 一起寫入
Session 會追蹤物件的變更，commit() 時自動產生對應的 UPDATE 與 DELETE 語句。
切換資料庫只要改網址
同一份模型與查詢程式，只要換掉 create_engine() 的網址，就能從開發用的 SQLite 換到正式環境的 PostgreSQL 或 MySQL：
import os
from sqlalchemy import create_engine
engine = create_engine(os.environ.get("DATABASE_URL", "sqlite:///dev.db"))
推薦影音
TUTORIAL: SQLAlchemy 2.0（Mike Bayer，Six Feet Up）
簡述：由 SQLAlchemy 作者 Mike Bayer 親自講授的 2.0 教學，內容與官網的 SQLAlchemy Unified Tutorial 一致，從 Engine、Core 到 ORM 完整說明，是最權威的學習影片。
SQLAlchemy Crash Course - Master Databases in Python（NeuralNine）
簡述：以實作為主的快速入門，示範建立模型、關聯（relationship）與各種查詢，節奏明快，適合看完本頁後想再多練幾個範例的人。
相關資料
- SQLAlchemy 官方網站與 Unified Tutorial
- ORM Quick Start
- 不使用 ORM 的寫法：Python DB-API