Persistence
Introduction
The blocks in this group store and evolve application data. They work from the data types the rest of the program already uses: the SQL module derives its codecs and repositories from a schema, and migrations are typed conversions between two such types. All four blocks require Scala 3.
The Blocks
The group has four blocks.
| Block | Artifact | What It Is For |
|---|---|---|
| SQL Module | zio-blocks-sql | Type-safe JDBC wrapper with schema-derived codecs and a CRUD repository |
| ZIO Integration | zio-blocks-sql-zio | ZIO integration with ZIO.attemptBlocking and ZLayer |
| Data Migration | zio-blocks-data-migration | Typed, online database schema migrations in three execution models, with no hand-written SQL |
| Projection | zio-blocks-projection | Event-sourced projections with per-entity SQLite storage |
How the Blocks Fit Together
The SQL Module is the foundation. Codecs map Scala types to database columns, fragments carry parameterized SQL, and repositories expose CRUD operations derived at compile time from a schema. ZIO Integration is an adapter for that module: it lets a ZIO application use the same fragments, repositories and tables, and runs the JDBC calls off ZIO's main thread pool.
Data Migration builds on the SQL module's repositories and on Migration for the typed row conversion, and it offers three execution models for evolving a schema online. Projection takes a different approach to storage: it turns an append-only event log into queryable read models that are described declaratively.
Where to Start
Start with the SQL Module. Add ZIO Integration when the application uses ZIO, Data Migration when a schema has to change under load, and Projection when the source of truth is an event log.