db 對象（Flask-SQLAlchemy 實例）是數據庫操作的核心入口，通過它可以完成 CRUD（增刪改查）、事務管理、表結構操作等所有數據庫相關任務。以下是具體使用方法和示例：

一、核心操作對象

db 對象的核心功能通過以下子對象 / 方法實現：

  • db.Model：所有數據模型的基類（用於定義表結構）。
  • db.session：數據庫會話（用於執行增刪改查、提交事務）。
  • db.Column：定義表字段（如 id、username）。
  • db.create_all() / db.drop_all()：創建 / 刪除所有表（基於模型定義）。

二、基本數據庫操作（CRUD）

假設已定義 User 模型（繼承 db.Model）：

python

運行

# app/models/user.py
from app import db

class User(db.Model):
    __tablename__ = "users"
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
1. 新增數據（Create）

通過 db.session.add() 添加記錄，db.session.commit() 提交事務：

python

運行

from app import db
from app.models.user import User

# 創建新用户對象
new_user = User(
    username="test_user",
    email="test@example.com"
)

# 步驟1：添加到會話（暫存內存，未寫入數據庫）
db.session.add(new_user)

# 步驟2：提交事務（寫入數據庫，此時才會生成id）
db.session.commit()

print(f"新增用户ID：{new_user.id}")  # 提交後可獲取自增ID
2. 查詢數據（Read）

通過模型類的 query 方法（繼承自 db.Model）執行查詢：

python

運行

# 1. 查詢所有記錄
all_users = User.query.all()  # 返回列表，包含所有User對象
for user in all_users:
    print(user.username, user.email)

# 2. 按條件查詢（單條記錄）
user = User.query.filter_by(username="test_user").first()  # 返回第一個匹配對象
if user:
    print(f"找到用户：{user.username}")

# 3. 按主鍵查詢（常用）
user = User.query.get(1)  # 查詢id=1的用户，不存在返回None

# 4. 複雜條件查詢（使用filter而非filter_by）
from sqlalchemy import or_
users = User.query.filter(
    or_(User.username == "test_user", User.email.endswith("@example.com"))
).all()  # 或條件：用户名是test_user 或 郵箱以@example.com結尾
3. 更新數據（Update）

先查詢到對象，修改屬性後提交事務：

python

運行

# 步驟1：查詢要更新的對象
user = User.query.get(1)
if not user:
    print("用户不存在")

# 步驟2：修改屬性
user.email = "new_email@example.com"

# 步驟3：提交事務（自動更新數據庫）
db.session.commit()
print(f"更新後郵箱：{user.email}")
4. 刪除數據（Delete）

通過 db.session.delete() 移除記錄，再提交事務：

python

運行

# 步驟1：查詢要刪除的對象
user = User.query.get(1)
if not user:
    print("用户不存在")

# 步驟2：從會話中刪除
db.session.delete(user)

# 步驟3：提交事務（數據庫中刪除記錄）
db.session.commit()
print("用户已刪除")

三、事務管理

db.session 內置事務支持，確保一組操作的原子性（要麼全成功，要麼全失敗）：

python

運行

try:
    # 操作1：新增用户A
    user_a = User(username="a", email="a@test.com")
    db.session.add(user_a)
    
    # 操作2：新增用户B（假設郵箱重複，會觸發唯一約束錯誤）
    user_b = User(username="b", email="a@test.com")  # 郵箱與user_a衝突
    db.session.add(user_b)
    
    # 提交事務：若任何一步失敗，自動回滾
    db.session.commit()
    print("所有操作成功")
except Exception as e:
    # 發生錯誤時回滾（撤銷所有未提交的操作）
    db.session.rollback()
    print(f"操作失敗，已回滾：{str(e)}")

四、表結構操作

1. 創建所有表

基於模型類自動生成數據庫表（首次運行時使用）：

python

運行

# 需在Flask應用上下文中執行（如create_app函數中）
with app.app_context():
    db.create_all()  # 檢查並創建所有未存在的表
    print("表創建成功")
2. 刪除所有表（謹慎使用！）

刪除所有模型對應的表（數據會丟失）：

python

運行

with app.app_context():
    db.drop_all()  # 刪除所有表
    print("表已刪除")

五、高級操作

1. 分頁查詢

處理大量數據時使用分頁：

python

運行

page = 1  # 第1頁
per_page = 10  # 每頁10條
pagination = User.query.paginate(page=page, per_page=per_page)

# 獲取當前頁數據
users = pagination.items  # 列表：當前頁的User對象
# 分頁信息
print(f"總頁數：{pagination.pages}")
print(f"總記錄數：{pagination.total}")
print(f"是否有下一頁：{pagination.has_next}")
2. 排序查詢

按字段排序（升序 / 降序）：

python

運行

from sqlalchemy import desc

# 按username升序（默認）
users_asc = User.query.order_by(User.username).all()

# 按id降序（最新的在前）
users_desc = User.query.order_by(desc(User.id)).all()

六、注意事項

  1. 必須在應用上下文中操作所有數據庫操作（查詢、提交等）必須在 Flask 應用上下文（app.app_context()）中執行，否則會報錯。例如在腳本中：
    python
    運行
from app import create_app, db

app = create_app()
with app.app_context():  # 激活上下文
    # 在這裏執行數據庫操作（如查詢、新增）
    users = User.query.all()
  1. 避免長時間未提交的會話db.session 會保持數據庫連接，長時間不提交（commit）或回滾（rollback）可能導致連接泄露，建議及時處理事務。
  2. 查詢性能複雜查詢建議使用 db.session.execute() 直接執行 SQL 語句，例如：
    python
    運行
result = db.session.execute("SELECT username FROM users WHERE id > :id", {"id": 5})
for row in result:
    print(row.username)

總結

db 對象的使用遵循 “模型定義 → 會話操作 → 事務提交” 的流程：

  • 通過 db.Model 和 db.Column 定義表結構；
  • 通過 db.session 執行增刪改查；
  • 通過 commit()/rollback() 管理事務；
  • 通過 create_all()/drop_all() 管理表結構。

掌握這些操作後，即可完成絕大多數數據庫交互需求。