78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
cargo test --features mysql
|
|
```
|
|
|
|
### Working with workspace members
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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 `?`
|