owlen/SQLX_MIGRATION_GUIDE.md

SQLx 0.7 to 0.8 Migration Guide for Owlen

Executive Summary

The Owlen project has been successfully upgraded from SQLx 0.7 to SQLx 0.8. The migration was straightforward as Owlen uses SQLite, which is not affected by the security vulnerability CVE-2024-0363.

Key Changes Made

1. Cargo.toml Update

Before (SQLx 0.7):

sqlx = { version = "0.7", default-features = false, features = ["runtime-tokio-rustls", "sqlite", "macros", "uuid", "chrono", "migrate"] }

After (SQLx 0.8):

sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "tls-rustls", "sqlite", "macros", "uuid", "chrono", "migrate"] }

Key change: Split runtime-tokio-rustls into runtime-tokio and tls-rustls

Important Notes for Owlen

1. Security Status

• CVE-2024-0363 (Binary Protocol Misinterpretation): This vulnerability DOES NOT AFFECT SQLite users
  • Only affects PostgreSQL and MySQL that use binary network protocols
  • SQLite uses an in-process C API, not a network protocol
  • No security risk for Owlen's SQLite implementation

2. Date/Time Handling

Owlen uses chrono types directly, not through SQLx's query macros for datetime columns. The current implementation:

• Uses INTEGER columns for timestamps (Unix epoch seconds)
• Converts between SystemTime and epoch seconds manually
• No changes needed for datetime handling

3. Database Schema

The existing migrations work without modification:

• /crates/owlen-core/migrations/0001_create_conversations.sql
• /crates/owlen-core/migrations/0002_create_secure_items.sql

4. Offline Mode Changes

For CI/CD pipelines:

• Offline mode is now always enabled (no separate flag needed)
• Use SQLX_OFFLINE=true environment variable to force offline builds
• Run cargo sqlx prepare --workspace to regenerate query metadata
• The .sqlx directory should be committed to version control

Testing Checklist

After the upgrade, perform these tests:

• Run all unit tests: cargo test --all
• Test database operations:
  • Create new conversation
  • Save existing conversation
  • Load conversation by ID
  • List all conversations
  • Search conversations
  • Delete conversation
• Test migrations: cargo sqlx migrate run
• Test offline compilation (CI simulation):

  rm -rf .sqlx
  cargo sqlx prepare --workspace
  SQLX_OFFLINE=true cargo build --release
  

Migration Code Patterns

Connection Pool Setup (No Changes Required)

The connection pool setup remains identical:

use sqlx::sqlite::{SqlitePool, SqlitePoolOptions, SqliteConnectOptions};

let options = SqliteConnectOptions::from_str(&format!("sqlite://{}", path))?
    .create_if_missing(true)
    .journal_mode(SqliteJournalMode::Wal)
    .synchronous(SqliteSynchronous::Normal);

let pool = SqlitePoolOptions::new()
    .max_connections(5)
    .connect_with(options)
    .await?;

Query Execution (No Changes Required)

Standard queries work the same:

sqlx::query(
    r#"
    INSERT INTO conversations (id, name, description, model, message_count, created_at, updated_at, data)
    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
    ON CONFLICT(id) DO UPDATE SET
        name = excluded.name,
        description = excluded.description,
        model = excluded.model,
        message_count = excluded.message_count,
        updated_at = excluded.updated_at,
        data = excluded.data
    "#
)
.bind(&id)
.bind(&name)
.bind(&description)
.bind(&model)
.bind(message_count)
.bind(created_at)
.bind(updated_at)
.bind(&data)
.execute(&self.pool)
.await?;

Transaction Handling (No Changes Required)

let mut tx = pool.begin().await?;

sqlx::query("INSERT INTO users (name) VALUES (?)")
    .bind("Alice")
    .execute(&mut *tx)
    .await?;

tx.commit().await?;

Performance Improvements in 0.8

1. SQLite-specific fixes: Version 0.8.6 fixed a performance regression for SQLite
2. Better connection pooling: More efficient connection reuse
3. Improved compile-time checking: Faster query validation

Common Pitfalls to Avoid

1. Feature flag splitting: Don't forget to split runtime-tokio-rustls into two separate features
2. Dependency conflicts: Check for libsqlite3-sys version conflicts with cargo tree -i libsqlite3-sys
3. Offline mode: Remember that offline mode is always on - no need to enable it separately

Future Considerations

If Moving to query! Macro

If you decide to use compile-time checked queries in the future:

// Instead of manual query building
let row = sqlx::query("SELECT * FROM conversations WHERE id = ?")
    .bind(&id)
    .fetch_one(&pool)
    .await?;

// Use compile-time checked queries
let conversation = sqlx::query_as!(
    ConversationRow,
    "SELECT * FROM conversations WHERE id = ?",
    id
)
.fetch_one(&pool)
.await?;

If Adding DateTime Columns

If you add proper DATETIME columns in the future (instead of INTEGER timestamps):

// With SQLx 0.8 + chrono feature, you'll use time crate types
use time::PrimitiveDateTime;

// Instead of chrono::NaiveDateTime
#[derive(sqlx::FromRow)]
struct MyModel {
    created_at: PrimitiveDateTime,  // Not chrono::NaiveDateTime
}

Verification Steps

1. Build successful: ✅ SQLx 0.8 compiles without errors
2. Tests pass: Run cargo test -p owlen-core to verify
3. Migrations work: Run cargo sqlx migrate info to check migration status
4. Runtime works: Start the application and perform basic operations

Resources

• SQLx 0.8 Release Notes
• SQLx Migration Guide
• CVE-2024-0363 Details