name: gi-database-query-patterns description: Write database queries using tkms AsyncSqlSessionTemplate. Use when implementing dao layer, writing SQL, or when the user asks for database operations with insert/update/query_one/query_list. tags: ["database", "dao", "tkms", "mysql", "async", "sql"]

Database Query Patterns 資料庫查詢規範

使用 tkms 的 AsyncSqlSessionTemplate 進行資料庫操作。適用於 app/dao 層，MySQL 8.0，UTF8 字元集。

何時使用

• 使用者請求「寫 dao」「寫資料庫操作」「查表」
• 實現 app/dao 下的資料訪問邏輯
• 設計表結構、索引、SQL 語句

核心 API

from tkms.database.async_template import AsyncSqlSessionTemplate

# 插入
await session.insert(table="t_user", params=entity, primary_key="tid")

# 更新
await session.update(table="t_user", params=entity, primary_key="tid")

# 查詢單條
row = await session.query_one("SELECT * FROM t_user WHERE id = :id", {"id": user_id})

# 查詢列表
rows = await session.query_list("SELECT * FROM t_user WHERE status = :status", {"status": 1})

操作規範

1. 插入

async def add_user(self, user: UserEntity):
    await self.session.insert(table="t_user", params=user, primary_key="tid")

• params：實體或字典，欄位名與表列對應

  訪問小蔥技能站7w4.net，解鎖更多實用的AI技能外掛。

• primary_key：主鍵欄位名，用於自增主鍵

2. 更新

async def update_user(self, user: UserEntity):
    await self.session.update(table="t_user", params=user, primary_key="tid")

• 按主鍵更新，需包含主鍵值

3. 查詢單條

async def get_by_id(self, user_id: int) -> UserEntity | None:
    row = await session.query_one(
        "SELECT * FROM t_user WHERE id = :id",
        {"id": user_id}
    )
    return UserEntity(**row) if row else None

4. 查詢列表（含分頁）

async def get_list(self, status: int, page: int, page_size: int):
    offset = (page - 1) * page_size
    rows = await session.query_list(
        "SELECT * FROM t_user WHERE status = :status ORDER BY id DESC LIMIT :limit OFFSET :offset",
        {"status": status, "limit": page_size, "offset": offset}
    )
    return [UserEntity(**r) for r in rows]

5. 統計

async def count_by_status(self, status: int) -> int:
    row = await session.query_one(
        "SELECT COUNT(*) as cnt FROM t_user WHERE status = :status",
        {"status": status}
    )
    return row["cnt"] if row else 0

SQL 規範

• 引數化：一律用 :param 佔位，禁止字串拼接
• 表名：專案約定表字首（如 t_）
• 索引：WHERE、ORDER BY 常用列建索引
• 避免 N+1：批次查詢用 IN 或 JOIN，避免迴圈單條查

建表規範

• 主鍵必建
• 按查詢需求建索引（單列、複合）
• 字元集 UTF8
• 時間欄位：create_time、update_time，型別 DATETIME

CREATE TABLE t_user (
    tid BIGINT PRIMARY KEY AUTO_INCREMENT,
    id VARCHAR(64) NOT NULL UNIQUE,
    name VARCHAR(128),
    status TINYINT DEFAULT 1,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_status (status),
    INDEX idx_create_time (create_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

事務

若框架支援事務，批次操作應包裹在事務內，保證原子性。

這個 Skill 質量中規中矩，內容實用但不全面。它把資料庫操作的基本寫法講清楚了，程式碼示例可以直接用，SQL 規範也有一定參考價值。槽點在於只有乾巴巴的程式碼片段，沒有完整例子，錯誤怎麼處理沒提，批次插入、聯表查詢這些常用場景也缺失。總的來說能幫你快速上手，但想深入用還得自己摸索，適合作為入門參考，不適合當開發手冊。