autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/sqlx-rust.md

@@ -0,0 +1,408 @@
+# SQLx Skill
+
+## Setup and Configuration
+\`\`\`bash
+# Add to Cargo.toml
+[dependencies]
+sqlx = { version = "0.7", features = ["runtime-tokio", "postgres", "uuid", "chrono", "migrate"] }
+
+# Install sqlx-cli
+cargo install sqlx-cli --no-default-features --features postgres
+
+# Create database
+sqlx database create
+
+# Create migration
+sqlx migrate add create_users
+
+# Run migrations
+sqlx migrate run
+
+# Prepare for offline compile-time checking
+cargo sqlx prepare
+\`\`\`
+
+## Connection Pool
+\`\`\`rust
+use sqlx::postgres::{PgPool, PgPoolOptions};
+use std::time::Duration;
+
+pub async fn create_pool() -> Result<PgPool, sqlx::Error> {
+    let database_url = std::env::var("DATABASE_URL")
+        .expect("DATABASE_URL must be set");
+
+    PgPoolOptions::new()
+        .max_connections(100)
+        .min_connections(5)
+        .acquire_timeout(Duration::from_secs(10))
+        .idle_timeout(Duration::from_secs(300))
+        .connect(&database_url)
+        .await
+}
+
+// Run migrations at startup
+pub async fn run_migrations(pool: &PgPool) -> Result<(), sqlx::migrate::MigrateError> {
+    sqlx::migrate!("./migrations")
+        .run(pool)
+        .await
+}
+\`\`\`
+
+## Model Definitions
+\`\`\`rust
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::FromRow;
+use uuid::Uuid;
+
+#[derive(Debug, Clone, FromRow, Serialize)]
+pub struct User {
+    pub id: Uuid,
+    pub email: String,
+    pub name: String,
+    #[serde(skip_serializing)]
+    pub password_hash: String,
+    pub is_active: bool,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+#[derive(Debug, Clone, FromRow, Serialize)]
+pub struct Post {
+    pub id: Uuid,
+    pub title: String,
+    pub content: String,
+    pub published: bool,
+    pub author_id: Uuid,
+    pub created_at: DateTime<Utc>,
+    pub updated_at: DateTime<Utc>,
+}
+
+// For partial selects
+#[derive(Debug, FromRow, Serialize)]
+pub struct UserSummary {
+    pub id: Uuid,
+    pub email: String,
+    pub name: String,
+}
+\`\`\`
+
+## Compile-Time Checked Queries (query_as!)
+\`\`\`rust
+use sqlx::PgPool;
+
+pub struct UserRepository {
+    pool: PgPool,
+}
+
+impl UserRepository {
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+
+    // Create - compile-time checked
+    pub async fn create(
+        &self,
+        email: &str,
+        name: &str,
+        password: &str,
+    ) -> Result<User, AppError> {
+        let id = Uuid::new_v4();
+        let password_hash = hash_password(password)?;
+        let now = Utc::now();
+
+        sqlx::query_as!(
+            User,
+            r#"
+            INSERT INTO users (id, email, name, password_hash, is_active, created_at, updated_at)
+            VALUES ($1, $2, $3, $4, true, $5, $5)
+            RETURNING id, email, name, password_hash, is_active, created_at, updated_at
+            "#,
+            id,
+            email,
+            name,
+            password_hash,
+            now
+        )
+        .fetch_one(&self.pool)
+        .await
+        .map_err(AppError::from)
+    }
+
+    // Find by ID
+    pub async fn find_by_id(&self, id: Uuid) -> Result<Option<User>, AppError> {
+        sqlx::query_as!(
+            User,
+            "SELECT id, email, name, password_hash, is_active, created_at, updated_at FROM users WHERE id = $1",
+            id
+        )
+        .fetch_optional(&self.pool)
+        .await
+        .map_err(AppError::from)
+    }
+
+    // List with pagination
+    pub async fn list(&self, page: i64, per_page: i64) -> Result<Vec<User>, AppError> {
+        let offset = (page - 1) * per_page;
+
+        sqlx::query_as!(
+            User,
+            r#"
+            SELECT id, email, name, password_hash, is_active, created_at, updated_at
+            FROM users
+            WHERE is_active = true
+            ORDER BY created_at DESC
+            LIMIT $1 OFFSET $2
+            "#,
+            per_page,
+            offset
+        )
+        .fetch_all(&self.pool)
+        .await
+        .map_err(AppError::from)
+    }
+
+    // Count
+    pub async fn count_active(&self) -> Result<i64, AppError> {
+        let result = sqlx::query_scalar!(
+            "SELECT COUNT(*) FROM users WHERE is_active = true"
+        )
+        .fetch_one(&self.pool)
+        .await?;
+
+        Ok(result.unwrap_or(0))
+    }
+
+    // Update
+    pub async fn update(
+        &self,
+        id: Uuid,
+        name: Option<&str>,
+        email: Option<&str>,
+    ) -> Result<User, AppError> {
+        sqlx::query_as!(
+            User,
+            r#"
+            UPDATE users
+            SET
+                name = COALESCE($2, name),
+                email = COALESCE($3, email),
+                updated_at = NOW()
+            WHERE id = $1
+            RETURNING id, email, name, password_hash, is_active, created_at, updated_at
+            "#,
+            id,
+            name,
+            email
+        )
+        .fetch_one(&self.pool)
+        .await
+        .map_err(AppError::from)
+    }
+
+    // Delete
+    pub async fn delete(&self, id: Uuid) -> Result<bool, AppError> {
+        let result = sqlx::query!("DELETE FROM users WHERE id = $1", id)
+            .execute(&self.pool)
+            .await?;
+
+        Ok(result.rows_affected() > 0)
+    }
+}
+\`\`\`
+
+## Dynamic Queries (query_as with QueryBuilder)
+\`\`\`rust
+use sqlx::QueryBuilder;
+
+pub async fn search_users(
+    &self,
+    query: Option<&str>,
+    is_active: Option<bool>,
+    page: i64,
+    per_page: i64,
+) -> Result<Vec<User>, AppError> {
+    let mut builder = QueryBuilder::new(
+        "SELECT id, email, name, password_hash, is_active, created_at, updated_at FROM users WHERE 1=1"
+    );
+
+    if let Some(q) = query {
+        builder.push(" AND (name ILIKE ");
+        builder.push_bind(format!("%{}%", q));
+        builder.push(" OR email ILIKE ");
+        builder.push_bind(format!("%{}%", q));
+        builder.push(")");
+    }
+
+    if let Some(active) = is_active {
+        builder.push(" AND is_active = ");
+        builder.push_bind(active);
+    }
+
+    builder.push(" ORDER BY created_at DESC");
+    builder.push(" LIMIT ");
+    builder.push_bind(per_page);
+    builder.push(" OFFSET ");
+    builder.push_bind((page - 1) * per_page);
+
+    builder
+        .build_query_as::<User>()
+        .fetch_all(&self.pool)
+        .await
+        .map_err(AppError::from)
+}
+
+// Bulk insert
+pub async fn bulk_create(&self, users: Vec<NewUser>) -> Result<Vec<User>, AppError> {
+    let mut builder = QueryBuilder::new(
+        "INSERT INTO users (id, email, name, password_hash, is_active, created_at, updated_at) "
+    );
+
+    builder.push_values(users, |mut b, user| {
+        b.push_bind(Uuid::new_v4())
+            .push_bind(&user.email)
+            .push_bind(&user.name)
+            .push_bind(&user.password_hash)
+            .push_bind(true)
+            .push_bind(Utc::now())
+            .push_bind(Utc::now());
+    });
+
+    builder.push(" RETURNING id, email, name, password_hash, is_active, created_at, updated_at");
+
+    builder
+        .build_query_as::<User>()
+        .fetch_all(&self.pool)
+        .await
+        .map_err(AppError::from)
+}
+\`\`\`
+
+## Transactions
+\`\`\`rust
+use sqlx::Acquire;
+
+pub async fn create_user_with_profile(
+    &self,
+    email: &str,
+    name: &str,
+    password: &str,
+    bio: &str,
+) -> Result<(User, Profile), AppError> {
+    let mut tx = self.pool.begin().await?;
+
+    let user = sqlx::query_as!(
+        User,
+        r#"
+        INSERT INTO users (id, email, name, password_hash, is_active, created_at, updated_at)
+        VALUES ($1, $2, $3, $4, true, NOW(), NOW())
+        RETURNING id, email, name, password_hash, is_active, created_at, updated_at
+        "#,
+        Uuid::new_v4(),
+        email,
+        name,
+        hash_password(password)?
+    )
+    .fetch_one(&mut *tx)
+    .await?;
+
+    let profile = sqlx::query_as!(
+        Profile,
+        r#"
+        INSERT INTO profiles (id, user_id, bio)
+        VALUES ($1, $2, $3)
+        RETURNING id, user_id, bio
+        "#,
+        Uuid::new_v4(),
+        user.id,
+        bio
+    )
+    .fetch_one(&mut *tx)
+    .await?;
+
+    tx.commit().await?;
+
+    Ok((user, profile))
+}
+
+// Transaction with savepoint
+pub async fn complex_operation(&self) -> Result<(), AppError> {
+    let mut tx = self.pool.begin().await?;
+
+    // First operation
+    create_user(&mut *tx, user1).await?;
+
+    // Nested transaction (savepoint)
+    let savepoint = tx.begin().await?;
+    match create_user(&mut *savepoint, user2).await {
+        Ok(_) => savepoint.commit().await?,
+        Err(e) => {
+            // Savepoint rolled back, outer transaction continues
+            tracing::warn!("Savepoint failed: {:?}", e);
+        }
+    }
+
+    tx.commit().await?;
+    Ok(())
+}
+\`\`\`
+
+## Streaming Results
+\`\`\`rust
+use futures::TryStreamExt;
+
+pub async fn process_all_users(&self) -> Result<(), AppError> {
+    let mut stream = sqlx::query_as!(
+        User,
+        "SELECT id, email, name, password_hash, is_active, created_at, updated_at FROM users"
+    )
+    .fetch(&self.pool);
+
+    while let Some(user) = stream.try_next().await? {
+        // Process each user without loading all into memory
+        process_user(&user).await?;
+    }
+
+    Ok(())
+}
+
+// With batching
+pub async fn export_users(&self) -> Result<(), AppError> {
+    let mut stream = sqlx::query_as!(User, "SELECT * FROM users")
+        .fetch(&self.pool);
+
+    let mut batch = Vec::with_capacity(100);
+
+    while let Some(user) = stream.try_next().await? {
+        batch.push(user);
+
+        if batch.len() >= 100 {
+            export_batch(&batch).await?;
+            batch.clear();
+        }
+    }
+
+    // Process remaining
+    if !batch.is_empty() {
+        export_batch(&batch).await?;
+    }
+
+    Ok(())
+}
+\`\`\`
+
+## ✅ DO
+- Use \`query_as!\` for compile-time checked queries
+- Use \`query_scalar!\` for single values
+- Use \`fetch_optional\` for queries that may return no results
+- Use transactions for multi-step operations
+- Use \`QueryBuilder\` for dynamic queries
+- Run \`cargo sqlx prepare\` before building for offline mode
+- Use streaming for large result sets
+
+## ❌ DON'T
+- Don't use \`fetch_one\` unless you're certain a row exists
+- Don't forget to handle \`sqlx::Error\` properly
+- Don't build SQL strings manually - use \`QueryBuilder\`
+- Don't hold transactions longer than necessary
+- Don't forget \`&mut *tx\` when passing transaction to queries