Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

เลเยอร์ฐานข้อมูล

หากคุณเคยทำงานในโปรเจกต์ที่มีคิวรี SQL กระจัดกระจายอยู่ตามฟังก์ชันแฮนด์เลอร์ต่างๆ คุณคงรู้ดีว่ามันกลายเป็นฝันร้ายได้เร็วขนาดไหน ในช่วงแรกมันอาจดูเหมือนทำงานได้รวดเร็ว ฟีเจอร์ต่างๆ ถูกปล่อยออกไปได้อย่างราบรื่น แต่เมื่อผ่านไปไม่กี่เดือน คุณกลับต้องมานั่งไล่ค้นหาไฟล์นับสิบเพื่อแก้ชื่อคอลัมน์เพียงจุดเดียว แถมชุดทดสอบยังต้องพึ่งพาฐานข้อมูลที่กำลังรันอยู่แทบทุกการทดสอบ ซึ่งผมเองก็เคยเจอปัญหานี้มาแล้ว และบอกได้เลยว่าไม่ใช่เรื่องน่าอภิรมย์เลย

ในบทนี้ เราจะมาสร้างเลเยอร์ฐานข้อมูลที่สะอาดและแยกความรับผิดชอบอย่างเป็นระเบียบด้วย SQLx ซึ่งเป็นตัวเลือกยอดนิยมที่สุดสำหรับแอปพลิเคชัน Axum อย่างไรก็ดี หลักการเหล่านี้สามารถนำไปประยุกต์ใช้ได้กับทุกเครตฐานข้อมูลที่คุณเลือกใช้

การตั้งค่าพูลการเชื่อมต่อ

เราคงไม่ต้องการให้ทุกคำขอที่ส่งเข้ามาต้องเปิดการเชื่อมต่อฐานข้อมูลใหม่ตั้งแต่ต้น เพราะนั่นหมายถึง overhead จากกระบวนการ TCP handshake, การเจรจา TLS และอาจรวมถึงการยืนยันตัวตน (authentication) ทั้งหมดนี้เกิดขึ้นก่อนที่คุณจะได้เริ่มรันคิวรีด้วยซ้ำ เราจึงต้องดูแลรักษาพูลการเชื่อมต่อ (connection pool) ที่สร้างเตรียมไว้ล่วงหน้า เพื่อให้แต่ละคำขอสามารถยืมการเชื่อมต่อไปใช้งานแล้วส่งคืนกลับเข้าพูลได้

#![allow(unused)]
fn main() {
use anyhow::Context;
use sqlx::postgres::{PgPool, PgPoolOptions};
use std::time::Duration;

pub async fn create_pool(database_url: &str) -> anyhow::Result<PgPool> {
    let pool = PgPoolOptions::new()
        .max_connections(10)
        .min_connections(2)
        .acquire_timeout(Duration::from_secs(3))
        .idle_timeout(Duration::from_secs(600))
        .connect(database_url)
        .await
        .context("failed to connect to the database")?;

    Ok(pool)
}
}

เราควรกำหนดจำนวนการเชื่อมต่อไว้เท่าไรดี? คำตอบขึ้นอยู่กับระดับการทำงานพร้อมกัน (concurrency) ของระบบและขีดความสามารถที่เซิร์ฟเวอร์ฐานข้อมูลจะรับไหว โดยปกติ PostgreSQL จะมีขีดจำกัดเริ่มต้นที่ 100 การเชื่อมต่อ และแต่ละการเชื่อมต่อก็สิ้นเปลืองหน่วยความจำฝั่งเซิร์ฟเวอร์ จุดเริ่มต้นที่ดีคือการกำหนดไว้ที่ 2 ถึง 4 การเชื่อมต่อต่อ 1 คอร์ CPU บนแอปพลิเคชันเซิร์ฟเวอร์ของคุณ จากนั้นค่อยปรับจูนตามสัดส่วนเวลาจริงที่คำขอใช้รอผลลัพธ์จากฐานข้อมูลเทียบกับเวลาที่ใช้ประมวลผลงานอื่น ตัวอย่างเช่น บนอินสแตนซ์ขนาด 4 คอร์ทั่วไป คุณอาจเริ่มต้นที่ 8 ถึง 16 การเชื่อมต่อ และหากคุณรันหลายอินสแตนซ์อยู่หลัง Load Balancer อย่าลืมคำนวณจำนวนการเชื่อมต่อรวมทั้งหมดของทุกอินสแตนซ์ให้อยู่ต่ำกว่าขีดจำกัดสูงสุดของฐานข้อมูลเสมอ

ไมเกรชัน

ไฟล์ไมเกรชัน (migration) ของเราควรมีการกำหนดเวอร์ชัน ทำซ้ำได้ (reproducible) และในทางอุดมคติคือสามารถรันได้โดยอัตโนมัติตอนเริ่มต้นระบบ โดย SQLx มีระบบไมเกรชันในตัวที่จะอ่านไฟล์ .sql จากไดเรกทอรีที่กำหนดและนำไปประยุกต์ใช้ตามลำดับเวลา

migrations/
├── 20240101000000_create_users.sql
├── 20240102000000_create_posts.sql
└── 20240103000000_add_user_bio.sql

โครงสร้างไมเกรชันที่ดีควรมีหน้าตาอย่างไร? โดยส่วนตัวผมมักจะกำหนดค่าเริ่มต้น (default values) ที่สมเหตุสมผลให้กับคอลัมน์ใหม่เสมอ เลือกใช้ UUID แทนเลขจำนวนเต็มที่เพิ่มค่าอัตโนมัติ (auto-incrementing integers) สำหรับคีย์หลัก (ซึ่งช่วยให้การสุ่มเดา ID ทำได้ยากขึ้น แม้ว่าแท้จริงแล้วระบบตรวจสอบสิทธิ์ต่างหากที่เป็นปราการปกป้องข้อมูลของคุณ) และจัดเก็บไทม์สแตมป์พร้อมข้อมูลเขตเวลา (timezone) เสมอ:

CREATE TABLE users (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email       VARCHAR(255) UNIQUE NOT NULL,
    name        VARCHAR(100) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    bio         TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);

-- Automatically update the updated_at timestamp on row modification
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = NOW();
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER update_users_updated_at
    BEFORE UPDATE ON users
    FOR EACH ROW
    EXECUTE FUNCTION update_updated_at_column();

ทำไมจึงควรใช้ทริกเกอร์ของฐานข้อมูลในการจัดการ updated_at? เพราะวิธีนี้ช่วยรับประกันความถูกต้องสม่ำเสมอ ไม่ว่าโค้ดเส้นทางใดจะเข้ามาแก้ไขแถวข้อมูลก็ตาม แม้กระทั่งในกรณีที่มีคนรันคำสั่ง SQL แก้ไขข้อมูลในฐานข้อมูลโดยตรงด้วยมือ (ซึ่งเชื่อผมเถอะว่าเกิดขึ้นจริงแน่นอน) ไทม์สแตมป์ก็จะยังคงได้รับการอัปเดตอย่างถูกต้องเสมอ

การปั้นสกีมาอย่างประณีต

ไมเกรชันตัวอย่างด้านบนเป็นเพียงจุดเริ่มต้น ยังมีเทคนิคสำคัญอีกสองสามประการที่สามารถเพิ่มเข้าไปในไมเกรชันตั้งแต่ตอนนี้ได้อย่างง่ายดาย แต่หากปล่อยไว้แล้วต้องมาย้อนแก้ในภายหลังจะยุ่งยากและน่าปวดหัวอย่างมาก ผมจะขอสรุปเทคนิคที่พบว่ามีประโยชน์มากที่สุดดังนี้:

ความเป็นเอกลักษณ์โดยไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ (Case-insensitive uniqueness) หากชื่อผู้ใช้และอีเมลต้องไม่ซ้ำกันโดยไม่สนใจตัวพิมพ์เล็กใหญ่ ควรกำหนดข้อจำกัดนี้ไว้ที่ระดับฐานข้อมูลโดยตรง การใช้ส่วนขยาย citext ของ PostgreSQL หรือใช้ ICU collation เช่น COLLATE "und-ci-ai-ks-kc" จะช่วยป้องกันไม่ให้ระบบยอมรับทั้ง “Alice” และ “alice” เข้ามาพร้อมกัน ผมเคยเจอบั๊กจากการพึ่งพาการแปลงสตริงเป็นตัวพิมพ์เล็กในเลเยอร์แอปพลิเคชันเพียงอย่างเดียวมาแล้ว เพราะการ insert ด้วยคำสั่ง SQL โดยตรงหรือการเข้าถึงจากเซอร์วิสอื่นสามารถข้ามการตรวจสอบนี้ไปได้อย่างสิ้นเชิง

ฟังก์ชันทริกเกอร์ที่นำกลับมาใช้ซ้ำได้ หากมีหลายตารางที่ต้องอัปเดตฟิลด์ updated_at ในลักษณะเดียวกัน ให้เขียนฟังก์ชันทริกเกอร์แยกไว้เพียงจุดเดียวแล้วนำไปผูกซ้ำกับตารางต่างๆ นั่นคือสิ่งที่ฟังก์ชัน update_updated_at_column() ด้านบนทำไว้ คุณเพียงแค่สร้างทริกเกอร์ไปผูกกับแต่ละตารางที่มีคอลัมน์ updated_at ก็เพียงพอ

เลือกประเภทดัชนี (Index) ให้เหมาะสม สำหรับคอลัมน์ชนิดอาร์เรย์ เช่น แท็ก การใช้อินเด็กซ์แบบ GIN จะช่วยให้คิวรีตรวจสอบการมีอยู่ของสมาชิก (@>, &&) ทำงานได้อย่างรวดเร็ว สำหรับคอลัมน์ค้นหาข้อความ ให้พิจารณาใช้ tsvector ร่วมกับอินเด็กซ์ GIN ส่วนอินเด็กซ์มาตรฐานแบบ B-tree จะเหมาะสมที่สุดสำหรับคิวรีเปรียบเทียบความเท่ากัน (equality) และการค้นหาแบบช่วง (range queries) บนคอลัมน์ข้อมูลทั่วไป

การเลือกประเภท ID อย่างรอบคอบ แม้ UUID จะเป็นตัวเลือกเริ่มต้นที่ผมแนะนำในคู่มือนี้ แต่ก็มีบางกรณีที่ ID แบบเรียงลำดับตัวเลข (bigserial) เหมาะสมกว่า เช่น เมื่อระบบภายนอกกำหนดให้ต้องใช้ตัวเลข หรือในตารางที่มีการเขียนข้อมูลสูงมาก (write-heavy) ซึ่งความสุ่มของ UUID ทั่วไปอาจส่งผลให้เกิดการแยกหน้า (page split) บนอินเด็กซ์ B-tree แต่สำหรับตารางที่เน้นการเขียน UUIDv7 คือทางเลือกที่น่าสนใจอย่างยิ่ง เพราะให้ทั้งความเป็นเอกลักษณ์ระดับสากลและยังเรียงลำดับตามเวลาได้ดีต่อการทำดัชนี (index-friendly) เนื่องจากมีการฝังไทม์สแตมป์ไว้ภายใน ทั้งนี้ PostgreSQL 18+ รองรับฟังก์ชัน uuidv7() ในตัว ส่วน PostgreSQL 17 หรือรุ่นก่อนหน้า คุณสามารถสร้างค่า UUIDv7 ในเลเยอร์แอปพลิเคชันผ่านเครต uuid (เปิดฟีเจอร์ v7) หรือติดตั้งส่วนขยายของฐานข้อมูลเพิ่มเติมได้

หากคุณต้องการดูตัวอย่างการนำแพตเทิร์นเหล่านี้ไปใช้จริงในแอปพลิเคชัน คลังโค้ด launchbadge/realworld-axum-sqlx มีคำอธิบายไมเกรชันที่เขียนไว้อย่างยอดเยี่ยมและคุ้มค่าแก่การศึกษาเป็นอย่างยิ่ง

การรันไมเกรชัน

โดยทั่วไป ผมนิยมรันไมเกรชันในจังหวะเริ่มต้นการทำงานของแอปพลิเคชัน:

#![allow(unused)]
fn main() {
sqlx::migrate!("./migrations")
    .run(&pool)
    .await
    .context("failed to run database migrations")?;
}

แมโคร migrate! จะฝังไฟล์ไมเกรชันเข้าไปในไบนารีตั้งแต่ตอนคอมไพล์ ทำให้คุณไม่จำเป็นต้องคัดลอกไดเรกทอรีไมเกรชันตามไปพร้อมกับแอปพลิเคชัน ช่วยลดภาระและขั้นตอนที่ต้องกังวลในระหว่างการดีพลอยต์ลงไปได้หนึ่งอย่าง

การตรวจสอบควิวรีตอนคอมไพล์ใน CI

มีจุดหนึ่งที่อาจทำให้คุณสะดุดได้: แมโคร query! และ query_as! ของ SQLx จะตรวจสอบความถูกต้องของคำสั่ง SQL เทียบกับฐานข้อมูลจริงตั้งแต่ตอนคอมไพล์ นั่นหมายความว่าสภาพแวดล้อม CI ของคุณจะต้องสามารถเข้าถึงฐานข้อมูลได้ในระหว่างการบิลด์ ซึ่งเราสามารถจัดการปัญหานี้ได้ 2 แนวทาง

แนวทางที่ผมแนะนำสำหรับ CI คือการใช้ โหมดออฟไลน์ (offline mode) โดยให้รันคำสั่ง cargo sqlx prepare บนเครื่องของคุณ (คำสั่งนี้จะเชื่อมต่อไปยังฐานข้อมูลที่กำลังรันอยู่เพื่อสร้างไดเรกทอรี .sqlx/ ซึ่งเก็บแคชเมตาดาตาของคิวรีไว้) จากนั้นจึง commit ไดเรกทอรีดังกล่าวเข้าสู่ระบบควบคุมเวอร์ชัน (version control) และใน CI ให้ตั้งค่าตัวแปรสภาพแวดล้อม SQLX_OFFLINE=true ซึ่งจะทำให้แมโครหันมาใช้เมตาดาตาจากแคชแทนการเชื่อมต่อฐานข้อมูลจริง นอกจากนี้ควรเพิ่มขั้นตอน cargo sqlx prepare --check ใน CI pipeline เพื่อตรวจสอบว่าแคชเมตาดาตายังคงซิงก์ตรงกับคำสั่งคิวรีและไฟล์ไมเกรชันล่าสุดอยู่เสมอ

อีกทางเลือกหนึ่งคือการสตาร์ตฐานข้อมูลจำลองขึ้นมาใน CI (ผ่าน Docker หรือ service container ของ CI) แล้วกำหนด DATABASE_URL เพื่อให้แมโครเชื่อมต่อไปตรวจสอบได้โดยตรง วิธีนี้ตั้งค่าง่ายกว่า แต่อาจทำให้การบิลด์ช้าลงและเสี่ยงต่อปัญหาความไม่เสถียร (flaky) มากกว่า

หมายเหตุเรื่องไมเกรชันตอนเริ่มระบบ

การสั่งรันไมเกรชันตอนเริ่มต้นระบบทำงานได้ดีเยี่ยมสำหรับการดีพลอยต์แบบอินสแตนซ์เดี่ยวและในระหว่างการพัฒนา แต่หากคุณรันหลายอินสแตนซ์พร้อมกันบน Production คุณควรรู้ว่าทุกอินสแตนซ์จะพยายามรันไมเกรชันพร้อมกันตอนเปิดเครื่อง แม้ว่า SQLx จะป้องกันปัญหานี้ด้วยการใช้ Advisory Lock เพื่อให้มีเพียงอินสแตนซ์เดียวเท่านั้นที่ได้รันไมเกรชันจริง แต่ในบางสถานการณ์ (โดยเฉพาะการดีพลอยต์แบบ Rolling Update) การแยกกระบวนการไมเกรชันออกมาเป็นงานเดี่ยวๆ (Migration Job) หรือรันผ่าน Kubernetes Init Container จะช่วยให้ควบคุมกระบวนการและจัดการข้อผิดพลาดได้รัดกุมกว่า เราจะไปเจาะลึกประเด็นนี้กันต่อในบท การดีพลอยต์

แพตเทิร์นรีพอสิทอรี

นี่เป็นหนึ่งในแพตเทิร์นที่ผมชอบมากที่สุดในการจัดระเบียบตรรกะการเข้าถึงฐานข้อมูล รีพอสิทอรี (Repository) คือ struct ที่ทำหน้าที่เป็นเจ้าของและควบคุมการเข้าถึงฐานข้อมูลทั้งหมดสำหรับแนวคิดของโดเมนนั้นๆ โดยจะถือการอ้างอิงไปยังพูลการเชื่อมต่อ และมีเมธอดที่ตรงกับความต้องการทางธุรกิจจริงๆ เช่น การสร้างข้อมูล, การค้นหาตามเงื่อนไข, การอัปเดต และการลบ

#![allow(unused)]
fn main() {
#[derive(Clone)]
pub struct UserRepository {
    pool: PgPool,
}

impl UserRepository {
    pub fn new(pool: PgPool) -> Self {
        Self { pool }
    }

    pub async fn create(&self, req: &CreateUserRequest) -> Result<User, CreateUserError> {
        let row = sqlx::query_as!(
            UserRow,
            r#"
            INSERT INTO users (id, email, name, password_hash)
            VALUES ($1, $2, $3, $4)
            RETURNING id, email, name, password_hash, bio, created_at, updated_at
            "#,
            Uuid::new_v4(),
            req.email.as_str(),
            req.name.as_str(),
            &req.password_hash,
        )
        .fetch_one(&self.pool)
        .await
        .map_err(|e| match e {
            sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
                CreateUserError::Duplicate { email: req.email.clone() }
            }
            other => CreateUserError::Unknown(other.into()),
        })?;

        row.try_into()
            .map_err(|e: anyhow::Error| CreateUserError::Unknown(e))
    }

    pub async fn find_by_id(&self, id: &UserId) -> anyhow::Result<Option<User>> {
        let row = sqlx::query_as!(
            UserRow,
            r#"
            SELECT id, email, name, password_hash, bio, created_at, updated_at
            FROM users
            WHERE id = $1
            "#,
            id.as_uuid(),
        )
        .fetch_optional(&self.pool)
        .await
        .context("failed to fetch user by id")?;

        row.map(TryInto::try_into).transpose()
    }

    pub async fn find_by_email(&self, email: &Email) -> anyhow::Result<Option<User>> {
        let row = sqlx::query_as!(
            UserRow,
            r#"
            SELECT id, email, name, password_hash, bio, created_at, updated_at
            FROM users
            WHERE email = $1
            "#,
            email.as_str(),
        )
        .fetch_optional(&self.pool)
        .await
        .context("failed to fetch user by email")?;

        row.map(TryInto::try_into).transpose()
    }

    pub async fn update(
        &self,
        id: &UserId,
        name: Option<&UserName>,
        bio: Option<&str>,
    ) -> anyhow::Result<Option<User>> {
        let row = sqlx::query_as!(
            UserRow,
            r#"
            UPDATE users
            SET name = COALESCE($2, name),
                bio = COALESCE($3, bio)
            WHERE id = $1
            RETURNING id, email, name, password_hash, bio, created_at, updated_at
            "#,
            id.as_uuid(),
            name.map(|n| n.as_str()),
            bio,
        )
        .fetch_optional(&self.pool)
        .await
        .context("failed to update user")?;

        row.map(TryInto::try_into).transpose()
    }
}
}

มีข้อสังเกตและแพตเทิร์นสำคัญหลายประการในโค้ดชุดนี้ที่ควรเน้นย้ำ:

คิวรีที่ตรวจสอบความถูกต้องตั้งแต่ตอนคอมไพล์ (Compile-time verified queries) แมโคร query_as! จะตรวจสอบความถูกต้องของคำสั่ง SQL เทียบกับสกีมาจริงในฐานข้อมูลตั้งแต่ตอนคอมไพล์ พร้อมสร้างโค้ดสำหรับแมปชนิดข้อมูลระหว่างคอลัมน์ผลลัพธ์กับฟิลด์ของ struct ให้โดยอัตโนมัติ โดยไม่ต้องอาศัยเทรต FromRow เพราะแมโครจะสร้างการแมปให้โดยตรงตามชื่อและชนิดข้อมูลของแต่ละคอลัมน์ หากคุณเปลี่ยนชื่อคอลัมน์ในไมเกรชันแต่ลืมตามไปแก้ในคิวรี โค้ดจะคอมไพล์ไม่ผ่านทันที ซึ่งผมมองว่านี่คือฟีเจอร์ที่ทรงพลังและมีประโยชน์ที่สุดของ SQLx (แต่หากคุณเลือกใช้ฟังก์ชัน query_as::<_, UserRow>(sql) แบบไม่ผ่านแมโคร การแมปข้อมูลจะใช้เทรต FromRow ณ เวลาทำงานหรือรันไทม์แทน)

แยกชนิดข้อมูลสำหรับแถวฐานข้อมูลออกจากโดเมน (Dedicated row types) struct UserRow มีโครงสร้างที่ตรงกับคอลัมน์ในตารางฐานข้อมูลโดยตรง การ derive sqlx::FromRow นั้นไม่จำเป็นเมื่อใช้ query_as! แต่การใส่ไว้ก็ไม่มีผลเสีย และยังมีประโยชน์หากคุณต้องการเรียกใช้ฟังก์ชันคิวรีแบบปกติในจุดอื่นด้วย ส่วนชนิดข้อมูลระดับโดเมนอย่าง User จะใช้ประโยชน์จากนิวไทป์ (newtype) สำหรับฟิลด์ต่างๆ และอาจมีชื่อฟิลด์ที่แตกต่างออกไป การสร้างการแปลงข้อมูลผ่าน TryFrom<UserRow> for User จึงทำหน้าที่เป็นสะพานเชื่อมระหว่างสองโลกนี้ ดังที่เราได้อธิบายไว้ในบท การสร้างแบบจำลองโดเมน ว่าทำไมเราจึงเลือกใช้ TryFrom แทน From เพราะข้อมูลในฐานข้อมูลเก่าอาจมีบางค่าที่ไม่สอดคล้องกับเงื่อนไขคงสภาพ (invariant) ของโดเมนในปัจจุบัน

เลือกใช้ fetch_optional สำหรับการค้นหา เมื่อค้นหาข้อมูลด้วย ID หรืออีเมล ควรเลือกใช้ fetch_optional แทน fetch_one เสมอ เนื่องจากการไม่พบเรคคอร์ดถือเป็นกรณีปกติทั่วไป ไม่ใช่ข้อผิดพลาดของระบบ การคืนค่าเป็น Option<User> จะเปิดโอกาสให้โค้ดส่วนที่เรียกใช้ตัดสินใจเองว่ากรณี ‘หาไม่พบ’ นั้นถือเป็นปัญหาในบริบทดังกล่าวหรือไม่

ใช้ COALESCE สำหรับการอัปเดตข้อมูลบางส่วน (Partial updates) ฟังก์ชัน SQL COALESCE จะช่วยรักษาค่าเดิมเอาไว้หากพารามิเตอร์ที่ส่งเข้ามาเป็น NULL ทำให้คุณสามารถทำ partial update ได้โดยไม่จำเป็นต้องอ่านข้อมูลเดิมขึ้นมาก่อน อย่างไรก็ดี มีข้อจำกัดสำคัญที่ต้องตระหนัก: วิธีนี้ไม่สามารถแยกความแตกต่างระหว่าง ‘ผู้ใช้เจตนาส่ง null มาเพื่อล้างข้อมูลในฟิลด์นั้น’ กับ ‘ผู้ใช้ไม่ได้ส่งฟิลด์นี้มาในคำขอ’ เพราะทั้งสองกรณีจะถูกแปลงเป็น None ในฝั่ง Rust และถูกมองว่าให้ ‘คงค่าเดิมไว้’ ทั้งสิ้น หาก API ของคุณจำเป็นต้องรองรับการล้างข้อมูลฟิลด์ที่ระบุ คุณอาจต้องใช้เทคนิคค่า sentinel, ส่งพารามิเตอร์ระบุรายชื่อฟิลด์ที่ต้องการล้างแยกต่างหาก หรือสร้างคำสั่ง SQL แบบไดนามิกที่เจาะจงชัดเจนยิ่งขึ้น

ใช้ Parameterized Queries เสมอ ทุกค่าที่รับมาจากผู้ใช้จะต้องส่งผ่านตัวแทนพารามิเตอร์ ($1, $2, ฯลฯ) ผ่าน .bind() เสมอ และต้องไม่มีการต่อสตริง (string interpolation) เข้าไปในคำสั่ง SQL เด็ดขาด ซึ่งจะช่วยป้องกันปัญหา SQL Injection ได้อย่างเด็ดขาดตั้งแต่การออกแบบ

แพตเทิร์น FromRef เพื่อการเข้าถึงที่สะดวก

คุณอาจพบว่าตัวเองต้องดึง AppState ทั้งก้อนออกมาในทุกๆ แฮนด์เลอร์ เพียงเพื่อจะหยิบพูลฐานข้อมูลหรือรีพอสิทอรีออกมาใช้งาน ซึ่งโค้ดจะเริ่มซ้ำซ้อนและดูเทอะทะอย่างรวดเร็ว แพตเทิร์น FromRef นำเสนอทางออกที่สะอาดตาและเป็นระเบียบกว่ามาก โดยเปิดทางให้คุณดึงเฉพาะคอมโพเนนต์ย่อยของ State ที่ต้องการออกมาได้โดยตรง

#![allow(unused)]
fn main() {
use axum::extract::FromRef;

#[derive(Clone)]
pub struct AppState {
    pub db: PgPool,
    pub user_repo: UserRepository,
    // ... other fields
}

impl FromRef<AppState> for UserRepository {
    fn from_ref(state: &AppState) -> Self {
        state.user_repo.clone()
    }
}

impl FromRef<AppState> for PgPool {
    fn from_ref(state: &AppState) -> Self {
        state.db.clone()
    }
}
}

ตอนนี้แฮนด์เลอร์ของเราจึงสามารถดึงเฉพาะรีพอสิทอรีที่ต้องการออกมาใช้งานได้โดยตรง:

#![allow(unused)]
fn main() {
async fn get_user(
    State(repo): State<UserRepository>,
    Path(id): Path<Uuid>,
) -> AppResult<Json<UserResponse>> {
    let user = repo.find_by_id(&UserId::from_uuid(id))
        .await?
        .ok_or(AppError::NotFound)?;
    Ok(Json(user.into()))
}
}

สิ่งที่ทำให้ผมชอบแนวทางนี้มากคือ ลายเซ็นของฟังก์ชันแฮนด์เลอร์จะระบุเฉพาะสิ่งที่ฟังก์ชันนั้นต้องใช้งานจริงๆ อย่างชัดเจน แทนที่จะต้องผูกติดอยู่กับ State ก้อนใหญ่ของแอปพลิเคชันทั้งหมด

รีพอสิทอรีแบบเทรตเพื่อความสามารถในการทดสอบ

สำหรับกรณีทั่วไป การใช้ struct รูปธรรมอย่าง UserRepository ที่เรียกใช้ SQLx โดยตรงก็ทำงานได้ดีและเพียงพอแล้ว แต่หากคุณต้องการเขียน Unit Test ให้กับเลเยอร์เซอร์วิสโดยไม่ต้องสตาร์ตฐานข้อมูลจริงขึ้นมา คุณสามารถกำหนดรีพอสิทอรีให้อยู่ในรูปของเทรต (trait) แล้วสร้างทั้งอิมพลีเมนเทชันจริงสำหรับใช้งานและ mock สำหรับการทดสอบได้

เราได้อธิบายรายละเอียดเรื่องนี้ไว้อย่างเจาะลึกในบท แพตเทิร์นสถาปัตยกรรม หากสรุปให้กระชับคือ: กำหนดเทรตขึ้นในเลเยอร์โดเมน, อิมพลีเมนต์เทรตนั้นด้วย SQLx ในเลเยอร์อินฟราสตรัคเจอร์ แล้วส่งเข้ามายังเลเยอร์เซอร์วิสผ่าน Generic หรือ Trait Object ซึ่งจะทำให้ชุดทดสอบของคุณสามารถส่ง In-memory implementation ที่เก็บข้อมูลลงใน HashMap ธรรมดาเข้ามาแทนที่ได้อย่างง่ายดาย

ธุรกรรม

เมื่อคุณมีคำสั่งเขียนข้อมูลลงฐานข้อมูลหลายรายการที่จำเป็นต้องสำเร็จทั้งหมดหรือล้มเหลวร่วมกัน ให้ครอบการทำงานทั้งหมดไว้ภายในทรานแซกชัน (transaction):

#![allow(unused)]
fn main() {
pub async fn transfer_credits(
    &self,
    from: &UserId,
    to: &UserId,
    amount: i64,
) -> anyhow::Result<()> {
    let mut tx = self.pool.begin().await.context("failed to begin transaction")?;

    sqlx::query!(
        "UPDATE accounts SET credits = credits - $1 WHERE user_id = $2",
        amount,
        from.as_uuid(),
    )
    .execute(&mut *tx)
    .await
    .context("failed to debit source account")?;

    sqlx::query!(
        "UPDATE accounts SET credits = credits + $1 WHERE user_id = $2",
        amount,
        to.as_uuid(),
    )
    .execute(&mut *tx)
    .await
    .context("failed to credit target account")?;

    tx.commit().await.context("failed to commit transfer")?;

    Ok(())
}
}

หากขั้นตอนใดเกิดความล้มเหลว (หรือฟังก์ชันส่งค่าคืนเร็วกว่าปกติจากโอเปอเรเตอร์ ?) ทรานแซกชันจะถูก rollback กลับโดยอัตโนมัติทันทีที่ตัวแปร tx หลุดพ้นขอบเขต (drop) โดยที่คุณไม่ต้องเขียนโค้ดเพื่อ cleanup แต่อย่างใด

และหากคุณต้องการให้การทำงานของแฮนด์เลอร์ทั้งฟังก์ชันอยู่ภายใต้ทรานแซกชันเดียวกัน โดยจะ commit เมื่อสำเร็จและ rollback เมื่อเกิดข้อผิดพลาดโดยอัตโนมัติ ลองศึกษาเครต axum-sqlx-tx ซึ่งมี extractor ช่วยจัดการวงจรชีวิตของทรานแซกชันให้คุณอย่างสะดวก เหมาะมากสำหรับทรานแซกชันที่มีขอบเขตเท่ากับหนึ่งคำขอ (request-scoped transactions)

การเลือกเครตฐานข้อมูล

หลายคนอาจสงสัยว่าควรเลือกใช้เครตฐานข้อมูลตัวใดดี ในระบบนิเวศของ Rust มีตัวเลือกที่แข็งแกร่งและเป็นที่นิยมอยู่หลายตัว ซึ่งแต่ละตัวมีข้อดีและข้อแลกเปลี่ยน (trade-offs) ที่แตกต่างกัน:

SQLx คือตัวเลือกที่ได้รับความนิยมสูงสุดเมื่อใช้งานร่วมกับ Axum รองรับ Asynchronous โดยกำเนิด ตรวจสอบความถูกต้องของคิวรีได้ตั้งแต่ตอนคอมไพล์ และทำงานกับคำสั่ง SQL ดิบโดยตรง คุณสามารถเขียน SQL ได้ด้วยตนเอง ซึ่งทำให้ควบคุมประสิทธิภาพได้เต็มที่และหมดปัญหาความไม่เข้ากันทางโครงสร้าง (object-relational impedance mismatch) ที่มักเกิดจาก ORM นอกจากนี้ การตรวจสอบตอนคอมไพล์ยังช่วยดักจับความไม่ตรงกันของชนิดข้อมูล, คอลัมน์ที่พิมพ์ผิดหรือไม่มีอยู่จริง และข้อผิดพลาดทางไวยากรณ์ ได้ก่อนที่โค้ดของคุณจะถูกนำไปรันจริง

Diesel เป็น ORM ที่มีประวัติยาวนานและสมบูรณ์ที่สุดในโลก Rust มี Query Builder ที่ปลอดภัยทางชนิดข้อมูล (type-safe) สูงมาก โดยสามารถตรวจจับข้อผิดพลาดได้ตั้งแต่ตอนคอมไพล์ผ่านระบบ Type System ของ Rust เอง โดยไม่ต้องต่อเชื่อมกับฐานข้อมูลจริง แม้เดิมที Diesel จะออกแบบมาสำหรับการทำงานแบบ Synchronous แต่ปัจจุบันมีเครต diesel-async ที่ช่วยรองรับงาน Asynchronous ได้อย่างยอดเยี่ยม เหมาะสำหรับผู้ที่ชื่นชอบการใช้ Query Builder มากกว่าการเขียน SQL ดิบ และต้องการการันตีความปลอดภัยระดับเข้มงวดจากคอมไพเลอร์

SeaORM นำเสนอแนวคิดที่ได้แรงบันดาลใจมาจาก ActiveRecord พร้อมรองรับ Async ในตัว สามารถสร้าง Entity structs จากสกีมาของฐานข้อมูลได้โดยอัตโนมัติ และมี High-level query API ที่ใช้งานง่าย เหมาะสำหรับการพัฒนาที่ต้องการความคล่องตัวและรวดเร็ว หรือโปรเจกต์ที่รู้สึกว่าการเขียน SQL ดิบซ้ำๆ เป็นเรื่องยุ่งยากเกินไป แม้อาจต้องแลกมาด้วยความยืดหยุ่นในการควบคุมแบบละเอียด (fine-grained control) ที่น้อยกว่า SQLx เล็กน้อย

สำหรับโปรเจกต์ Axum ใหม่ส่วนใหญ่ ผมยังคงแนะนำให้เลือกใช้ SQLx เป็นค่าเริ่มต้น เพราะสอดคล้องกับปรัชญาการออกแบบของ Axum ที่เน้นความชัดเจน ตรงไปตรงมา และการประกอบกันได้อย่างยืดหยุ่น (composable) มากกว่าการซ่อนความมหัศจรรย์ไว้เบื้องหลัง อีกทั้งฟีเจอร์การตรวจสอบคิวรีตอนคอมไพล์จะช่วยเพิ่ม productivity ในการพัฒนาขึ้นอย่างมหาศาลเมื่อคุณเริ่มคุ้นเคยกับมัน