sqlx-record/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

sqlx-record is a Rust library that provides derive macros for automatic CRUD operations and comprehensive audit trails for SQL entities. It supports MySQL, PostgreSQL, and SQLite via SQLx, tracking who changed what, when, and why with actor, session, and change set metadata.

Repository: https://git.awesomike.com/pub/sqlx-record.git

Architecture

Workspace Structure

sqlx-record/
├── src/                      # Core library
│   ├── lib.rs                # Public API exports and prelude
│   ├── models.rs             # EntityChange struct, Action enum
│   ├── repositories.rs       # Database query functions for entity changes
│   ├── value.rs              # Type-safe Value enum, bind functions
│   ├── filter.rs             # Filter enum for query conditions
│   └── helpers.rs            # Utility macros
├── sqlx-record-derive/       # Procedural macro crate
│   └── src/
│       ├── lib.rs            # #[derive(Entity, Update)] implementation
│       └── string_utils.rs   # Pluralization helpers
├── sqlx-record-ctl/          # CLI tool for audit table management
│   └── src/main.rs
└── Cargo.toml                # Workspace root

Feature Flags

• derive: Enables #[derive(Entity, Update)] procedural macros
• static-validation: Enables compile-time SQLx query validation
• mysql: MySQL database support
• postgres: PostgreSQL database support
• sqlite: SQLite database support

Note: You must enable at least one database feature.

Development Commands

# Build with MySQL
cargo build --features mysql

# Build with derive macros
cargo build --features "mysql,derive"

# Build CLI tool
cargo build -p sqlx-record-ctl --features mysql

# Test
cargo test --features mysql

# Release tag
make tag

Derive Macro API

Entity Attributes

#[derive(Entity, FromRow)]
#[table_name = "users"]           // or #[table_name("users")]
struct User {
    #[primary_key]                // Mark primary key field
    id: Uuid,

    #[rename("user_name")]        // Map to different DB column
    name: String,

    #[version]                    // Auto-increment on update
    version: u32,

    #[field_type("BIGINT")]       // SQLx type hint
    count: i64,
}

Generated Methods

Insert:

• insert(&pool) -> Result<PkType, Error>

Get:

• get_by_{pk}(&pool, &pk) -> Result<Option<Self>, Error>
• get_by_{pks}(&pool, &[pk]) -> Result<Vec<Self>, Error>
• get_by_primary_key(&pool, &pk) -> Result<Option<Self>, Error>

Find:

• find(&pool, filters, index) -> Result<Vec<Self>, Error>
• find_one(&pool, filters, index) -> Result<Option<Self>, Error>
• find_ordered(&pool, filters, index, order_by) -> Result<Vec<Self>, Error>
• find_ordered_with_limit(&pool, filters, index, order_by, offset_limit) -> Result<Vec<Self>, Error>
• count(&pool, filters, index) -> Result<u64, Error>

Update:

• update(&self, &pool, form) -> Result<(), Error>
• update_by_{pk}(&pool, &pk, form) -> Result<(), Error>
• update_by_{pks}(&pool, &[pk], form) -> Result<(), Error>
• update_form() -> UpdateForm - Creates builder

Diff:

• model_diff(&form, &model) -> serde_json::Value
• db_diff(&form, &pk, &pool) -> Result<serde_json::Value, Error>
• diff_modify(&mut form, &model) -> serde_json::Value
• to_update_form(&self) -> UpdateForm
• initial_diff(&self) -> serde_json::Value

Metadata:

• table_name() -> &'static str
• entity_key(&pk) -> String
• entity_changes_table_name() -> String
• primary_key_field() -> &'static str
• primary_key_db_field() -> &'static str
• primary_key(&self) -> &PkType
• select_fields() -> Vec<&'static str>

Version (if #[version] field exists):

• get_version(&pool, &pk) -> Result<Option<VersionType>, Error>
• get_versions(&pool, &[pk]) -> Result<HashMap<PkType, VersionType>, Error>

Filter API

use sqlx_record::prelude::*;

// Simple filters
let f = filters![("active", true), ("role", "admin")];

// Compound filters
let f = filter_or![("status", "active"), ("status", "pending")];
let f = filter_and![("age", 18), ("verified", true)];

// Filter enum variants
Filter::Equal("field", value)
Filter::NotEqual("field", value)
Filter::GreaterThan("field", value)
Filter::LessThan("field", value)
Filter::Like("field", pattern)
Filter::ILike("field", pattern)  // Case-insensitive
Filter::In("field", vec![values])
Filter::NotIn("field", vec![values])
Filter::IsNull("field")
Filter::IsNotNull("field")
Filter::And(vec![filters])
Filter::Or(vec![filters])

Database Differences

Feature	MySQL	PostgreSQL	SQLite
Placeholder	?	$1, $2, ...	?
Table quote	`	"	"
UUID type	BINARY(16)	UUID	BLOB
JSON type	JSON	JSONB	TEXT
ILIKE	LOWER() LIKE LOWER()	Native	LOWER() LIKE LOWER()
Index hints	USE INDEX()	N/A	N/A

Value Types

The Value enum supports:

• Integers: Int8, Uint8, Int16, Uint16, Int32, Uint32, Int64, Uint64
• String, Bool, VecU8
• Uuid
• NaiveDate, NaiveDateTime

Entity Changes (Audit Trail)

The EntityChange struct tracks:

• id: Change record UUID
• entity_id: Target entity UUID
• action: insert/update/delete/restore/hard-delete
• changed_at: Timestamp (milliseconds)
• actor_id: Who made the change
• session_id: Session context
• change_set_id: Transaction grouping
• new_value: JSON payload of changes

Important Notes

• Always enable a database feature (mysql, postgres, or sqlite)
• The prelude module exports commonly used items including placeholder() function
• Query filters use Filter::build_where_clause() internally
• Version fields auto-increment with overflow wrapping
• The CLI tool requires a entity_changes_metadata table with table_name and is_auditable columns