3squaredcircles/voda repository overview

Visit https://docs.3squaredcircles.com⁠ for a deep dive into configuration.

The Authoritative "Schema-as-Code" Engine for Your Database.

3SC Voda is an enterprise-grade utility that automates the creation and validation of database migration scripts. It connects the world of your application code to the world of your relational database by using your ORM's own model as the single source of truth for your database schema.

The tool analyzes your codebase's build artifacts (e.g., .NET DLLs) or source code to discover your ORM's final, runtime schema model. It then compares this model against a live database, produces a precise, multi-phase SQL deployment script, and performs a comprehensive risk assessment on the changes. The result is a fully automated, safe, and auditable process for managing your database schema lifecycle.

⁠A Note on the Name

Voda is a Slavic word for "water." This name was chosen because the tool helps manage the "flow" of schema changes from the application code to the database. Like water shaping a landscape over time, Voda ensures that changes to your database schema are deliberate, controlled, and predictable, carving a clear and auditable path from development to production.

---

⁠For the Manager (VP, Director, Database & Platform Leads)

As a leader, you are accountable for the stability of your critical data systems, yet you face constant pressure to accelerate development. Database schema changes are a major bottleneck and source of risk. Manual processes are slow and error-prone, while "schema drift" between the application and the database can lead to catastrophic production failures.

Voda answers your critical questions:

• "How do we stop our application code and database schema from silently drifting apart, causing production incidents?"
• "How can we automate our manual, ticket-based process for database schema updates without sacrificing safety and control?"
• "How do we ensure that a destructive change, like dropping a table, receives mandatory, human review before it ever reaches production?"
• "How do our auditors see a clear, version-controlled history of every database schema change that has ever been proposed and deployed?"

⁠Key Business Values:

• Eliminate Schema Drift: The application's ORM model becomes the single, verifiable source of truth for your database schema, preventing mismatches that cause production failures.
• Automate Schema Migrations Safely: The tool automatically generates the precise SQL script needed to migrate the database and performs a built-in risk assessment on every change.
• Enforce Governance with Approval Gates: The risk assessment allows you to build powerful, automated governance, halting pipelines for risky changes until a human provides approval via an external tool like 3SC Custos.
• Create a Git-Based Audit Trail: Voda commits the generated migration.sql and risk-assessment.json files back to the repository, creating a perfect, immutable, and auditable log of every proposed change.

---

⁠For the Architect & Engineer

Voda embraces your existing ORM workflow. You continue to define your schema using the tools you already know; the generator provides a powerful, governable engine to handle the migration.

You don't need to learn any proprietary attributes or change how you code.

The generate command reads the final model directly from your ORM's runtime or schema definition files.

⁠The GitOps Workflow:

1. A developer modifies an ORM model (e.g., adds a new property to an Entity Framework class) and pushes the change in a Pull Request.
2. The CI pipeline runs Voda in generate mode.
3. The tool analyzes the compiled code, compares it to the database, generates the precise migration.sql script and a risk-assessment.json file, and commits them back to the developer's branch.
4. The Pull Request now contains both the application code change and the exact, human-readable SQL migration artifacts for review, providing perfect traceability.