2.9 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in 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.

Architecture

Workspace Structure

Main library (src/): Core entity CRUD and change tracking functionality
sqlx-record-derive (sqlx-record-derive/): Procedural macro crate for deriving Entity and Update traits
sqlx-record-ctl (sqlx-record-ctl/): Command-line utility for managing audit tables

Core Components

models.rs: Defines EntityChange struct and Action enum for tracking entity modifications
repositories.rs: Database query functions for creating and retrieving entity changes by various criteria (ID, entity, session, actor, change set)
value.rs: Type-safe value system supporting SQL types (integers, strings, UUIDs, dates, etc.) with Value enum and Updater for SQL operations
filter.rs: Query filter system with Filter enum supporting SQL operations (Equal, Like, In, And, Or, etc.)
helpers.rs: Utility functions and macros for the library

Features

derive: Enables procedural macro support for Entity and Update traits
static-validation: Enables static SQLx validation during compilation
mysql: MySQL database support
postgres: PostgreSQL database support
sqlite: SQLite database support

Development Commands

Building

# Build with MySQL support (default for backwards compatibility)
cargo build --features mysql

# Build with PostgreSQL support
cargo build --features postgres

# Build with SQLite support
cargo build --features sqlite

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

Testing

cargo test --features mysql

Working with workspace members

# Build specific workspace member
cargo build -p sqlx-record-derive --features mysql
cargo build -p sqlx-record-ctl --features mysql

# Test specific workspace member
cargo test -p sqlx-record --features mysql

Releasing

The project uses a Makefile for tagging releases:

make tag

This creates a git tag based on the version in Cargo.toml and pushes it to the remote repository.

Important Notes

The library supports MySQL, PostgreSQL, and SQLite databases via SQLx feature flags
All entity changes include metadata: actor_id, session_id, change_set_id, and timestamps
The new_value field stores JSON data for tracking actual changes
Procedural macros are optional and gated behind the "derive" feature
The library uses UUIDs for all entity identifiers
Query filters support both simple field-value pairs and complex nested And/Or logic
PostgreSQL uses $1, $2, ... placeholders; MySQL/SQLite use ?

2.9 KiB Raw Blame History