Rust-based SQL development tooling POC

[tobyhede]

Description:

💪 What

Adds a proof-of-concept Rust-based development framework for EQL that demonstrates improved testing, documentation generation, and multi-database
support using the Config module.

• Implements type-safe dependency resolution via compile-time graph walking - components declare dependencies through associated types,
  eliminating manual dependency ordering
• Adds transaction-isolated test harness (TestDb) - tests run in auto-rollback transactions, removing need for manual database cleanup
• Creates automatic build tool that generates SQL installers (280 lines) by walking the component dependency graph
• Migrates Config module to new structure - add_column function works end-to-end with all dependencies loaded automatically
• Generates customer-facing documentation via rustdoc with SQL code examples inline with trait definitions
• Implements structured error handling with thiserror - errors include query context for better debugging
• Passes all 16 tests across 4 crates (eql-core, eql-postgres, eql-test, eql-build)

Workspace Structure

• eql-core: Trait definitions (Component, Config, Dependencies)
• eql-postgres: PostgreSQL implementation of Config module
• eql-test: Test harness with transaction isolation
• eql-build: Build tool for SQL extraction

🤔 Why

• Current pain: Manual dependency management with REQUIRE comments is error-prone and requires topological sort
• Current pain: Tests require manual database resets, causing interference between test runs
• Current pain: Documentation lives separately from code, leading to drift
• Rust solution: Type system enforces dependency relationships at compile time
• Rust solution: TestDb RAII pattern ensures automatic cleanup via Drop
• Rust solution: Rustdoc keeps documentation with trait definitions

This POC proves the approach is viable before investing in full migration. The Config module serves as a representative example of how all EQL modules
could be structured.

👀 Usage

Running Tests

cd .worktrees/rust-sql-tooling
cargo test --all

Building SQL Installer

cargo run --bin eql-build postgres
# Output: release/cipherstash-encrypt-postgres-poc.sql

Generating Documentation

cargo doc --no-deps --open
# Navigate to eql_core::config::Config to see SQL examples

👩‍🔬 How to validate

1. Verify automatic dependency resolution works

cd .worktrees/rust-sql-tooling
cargo run --bin eql-build postgres
Observe the output shows 8 dependencies resolved in correct order (types.sql before functions_private.sql, etc.). Open
release/cipherstash-encrypt-postgres-poc.sql and verify types are defined before functions that use them.

2. Verify transaction isolation in tests

cargo test --package eql-test test_testdb_transaction_isolation -- --nocapture
Run the test multiple times - it should pass consistently without manual cleanup. The test creates a table, inserts data, queries it, then drops the
transaction.

3. Verify add_column works end-to-end

cargo test --package eql-postgres test_add_column_creates_config -- --nocapture
This test loads all SQL dependencies automatically, calls add_column, and verifies:
- Config JSONB has correct structure
- Configuration stored in database
- Encrypted constraint added to table

4. Verify documentation includes SQL examples

cargo doc --no-deps
open target/doc/eql_core/trait.Config.html
Navigate to the add_column method - documentation should show SQL usage examples, not Rust code.

🔗 Related links

- Implementation plan: docs/plans/2025-01-20-rust-sql-tooling-poc-v2.md