feat: implement declarative struct-based additive migrations and cascading soft deletes

Author: venelouis

CHANGELOG.md

@@ -5,11 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [6.2.0] - 2026-07-28
+## [6.2.0] - unreleased
 
 ### Added
 - **Cascading Soft Deletes (Phase 6):** Added `cascade_soft_delete` option to `has_many` and `has_one` relations. When a parent model is soft-deleted, all dependent children are now automatically soft-deleted in a recursive, transactional manner, ensuring referential logic integrity without breaking changes.
-- **Declarative Struct-Based Migrations (MVP):** Introduced the foundational AST-parsing engine (`schema_diff.rs`) to power the new `artisan make:migration:auto` command. This engine leverages `syn` to read local `.rs` files and dynamically compare Rust structs against the live database, scaffolding missing tables and columns automatically. As an MVP, this engine prioritizes data safety by solely generating additive SQL (CREATE TABLE / ADD COLUMN) and intentionally bypassing destructive operations.
+- **Declarative Struct-Based Migrations (Safe Additive):** Introduced the foundational AST-parsing engine (`schema_diff.rs`) to power the new `artisan make:migration:auto` command. This engine leverages `syn` to read local `.rs` files and dynamically compare Rust structs against the live database, scaffolding missing tables and columns automatically. Currently, this engine prioritizes data safety by solely generating additive SQL (CREATE TABLE / ADD COLUMN) and intentionally bypassing destructive operations. (Note: Full destructive capabilities will be implemented in future versions protected by 'Safe by Default' mechanisms like `--allow-destructive` flags).
 
 ## [6.1.1] - 2026-07-26
 

README.md

@@ -57,6 +57,8 @@ In traditional Rust database handling, you have to write raw SQL queries, manage
 - **Data Governance & Privacy**: Compile-time GDPR/LGPD compliance with at-rest encryption and log masking.
 - **Scout Search**: Seamlessly sync models to full-text search engines.
 - **Database-First Introspection**: The official framework CLI (`cargo rullst generate:models`) connects to legacy databases and generates your `#[derive(Orm)]` Rust structs automatically.
+- **Declarative Struct-Based Migrations**: Safely auto-generate additive SQL migrations (`make:migration:auto`) directly from your Rust struct definitions.
+- **Cascading Soft Deletes**: Configure relationships to automatically soft-delete dependent children records in a single transaction.
 - **Type-Safe Partial Updates**: Virtual dirty checking with `.update_partial()` to intelligently modify only changed columns.
 - **Model Policies (Authorization)**: Laravel-style fine-grained access control securely tied to your structs via `#[orm(policy = "MyPolicy")]`.
 - **Strict Lazy Loading Prevention**: Enable a global toggle to instantly panic on N+1 queries during development.

ROADMAP.md

@@ -77,7 +77,8 @@ We introduced the `strict-postgres`, `strict-mysql`, and `strict-sqlite` feature
 Our goal is to provide tools that normally cost thousands of dollars, completely free and open-source, ensuring `rullst-orm` stands unrivaled in the Rust ecosystem.
 
 - [x] **Native Core Multi-tenancy (Global Scopes)**: Automatic Global Scopes isolate tenant data in SaaS. With `#[orm(global_scope = "tenant")]`, the ORM injects `WHERE tenant_id = X` and prevents leaks; requiring global access demands explicit and noisy calls like `.unscoped()`.
-- [ ] **Declarative Struct-Based Migrations (AST-Driven)**: Automatic bidirectional synchronization reading Rust structs to generate corresponding SQL migrations, supporting codemods to apply perfectly formatted `ALTER TABLE` via the `cargo rullst upgrade` command.
+- [x] **Declarative Struct-Based Migrations (Safe Additive)**: Automatic synchronization reading Rust structs to generate corresponding SQL migrations (tables and columns) via the `make:migration:auto` command, guaranteeing data safety.
+- [ ] **Declarative Migrations (Destructive Operations)**: Implement full resource synchronization (dropping columns and tables) protected by "Safe by Default" patterns (e.g., `--allow-destructive` flag or commented-out SQL generation) to prevent accidental data loss.
 - [x] **Strict Lazy Loading Prevention**: A Laravel-inspired feature (`Orm::prevent_lazy_loading(true)`) that throws a loud runtime error during development/testing if a relationship is accessed without being eager-loaded, completely preventing N+1 issues without polluting the codebase with strict typestates.
 - [x] **Type-Safe Partial Updates (Virtual Dirty Checking)**: A macro-driven mechanism that tracks changed properties in memory, generating an `UPDATE` only for modified columns without overhead, using typing to honor database constraints (e.g., not null).
 - [x] **Automated Compliance & Data Governance (GDPR/LGPD)**: `#[derive(PersonalData)]` macro for out-of-the-box privacy reports, and `SecretString` for transparent AES-256-GCM encryption at rest, preventing accidental data leakage.
@@ -88,7 +89,7 @@ Our goal is to provide tools that normally cost thousands of dollars, completely
 - [x] **Rullst ORM Admin Panel**: A drop-in function that generates a beautiful web dashboard to manage your data without writing frontend code.
 - [x] **API Resources & Transformers**: A declarative way to transform Rullst Models and eager-loaded relationships into clean JSON API responses, handling hidden fields, date formatting, and nested relations effortlessly.
 - [x] **Schema Visualizer (Mermaid ER Diagrams)**: A CLI command (`cargo rullst generate:diagram`) that reads models and outputs a Mermaid markdown file showing database architecture and relationships.
-- [ ] **Cascading Soft Deletes**: Automatic recursive soft deletion. If a parent is soft-deleted, automatically apply soft deletes to dependent children (`ON DELETE CASCADE` equivalent for logical deletes).
+- [x] **Cascading Soft Deletes**: Automatic recursive soft deletion. If a parent is soft-deleted, automatically apply soft deletes to dependent children (`ON DELETE CASCADE` equivalent for logical deletes).
 - [x] **Native Enum Mapping**: Clean, type-safe mapping of Rust `enum` to database `ENUM` types (PostgreSQL/MySQL) or secure string constraints (SQLite).
 
 ## 🧠 Phase 7: The Future (AI, Quantum & Infrastructure)

website/docs/2-relationships.md

@@ -56,6 +56,21 @@ pub struct Post {
 }
 ```
 
+### Cascading Soft Deletes
+
+When using Soft Deletes (`deleted_at`), you can configure relationships to automatically soft-delete dependent children when the parent is soft-deleted.
+
+```rust
+#[derive(Debug, Clone, FromRow, Orm)]
+pub struct User {
+    pub id: i32,
+    
+    // If the User is soft-deleted, all their posts will be soft-deleted automatically!
+    #[orm(has_many(model = "Post", foreign_key = "user_id", local_key = "id", cascade_soft_delete = true))]
+    pub posts: Vec<Post>,
+}
+```
+
 ---
 
 ## Eager Loading (With)

website/docs/4-migrations-schema.md

@@ -88,3 +88,9 @@ Reverts the last batch of executed migrations by triggering their `down()` or `d
 cargo run -- make:audit
 ```
 Automatically seeds the `rullst_audits` tracking table into your schema to support the `#[orm(auditable)]` feature.
+
+#### 5. Declarative Migrations (Auto MVP)
+```bash
+cargo run -- make:migration:auto
+```
+An experimental MVP feature that compares your Rust structs (`#[derive(Orm)]`) directly against the live database and automatically generates additive SQL (creating missing tables and columns) without manual intervention. It prioritizes data safety by ignoring destructive operations (like drops).