Guides

Each guide works through one task with ZIO Blocks from start to finish. When you need the full description of a data type along the way, the reference has a page for it.

📄️How to Add ZIO Blocks to Your Build

Pick the ZIO Blocks modules you need and add them to an sbt or scala-cli build, for any Scala version and for Scala.js.

📄️Your First Schema: Round-Trip a Type Through JSON

Describe a Scala type once with Schema, then encode it to JSON, decode it back, and read decode errors.

📄️How to Customize JSON Field Names, ADT Encoding and Optional Fields

Change the JSON shape a Schema produces: snake_case names, renamed fields, type discriminators, null handling and strict decoding.

📄️How to Read and Modify JSON Without Case Classes

Parse JSON into a tree, read and change values by path, print it back, and decode only the part you need into a case class.

📄️How to Build a Schema Registry with DynamicSchema

Store versioned event schemas as data, check incoming events against them, rebind them to Scala types, and compare versions.

📄️How to Override the Codec for One Type Everywhere

Encode LocalDate (or any type) your own way in every derived codec by registering one custom codec on the deriver.

📄️How to Tune JSON Encoding and Decoding for Throughput

Decode JSON straight from bytes, buffers and streams, reuse derived codecs, size reader and writer buffers, and measure with JMH.

📄️How to Define Validated Newtypes and Collect Every Validation Error

Wrap ISBNs, titles and prices in types that only a check can build, enforce the check in every codec, and report all errors at once.

📄️How to Compute, Store and Replay Changes with Diff and Patch

Diff two versions of a value, store the patch as JSON, apply it with the right PatchMode, replay an edit history, and send JSON patches.

📄️How to Derive Your Own Type Class from a Schema

Write a Deriver for your own type class, here a log redactor that masks sensitive fields, and derive it for any type with a Schema.

📄️Navigate and Update Nested Data with Optics

Read and update fields deep inside immutable Scala data with lenses, optionals and traversals, without nested copy calls.

📄️One Type, Many Formats

Derive JSON, YAML, XML, TOON, MessagePack, Avro and CSV codecs from one Schema and round-trip a book catalog through each.

📄️How to Read and Write CSV and TSV Files

Read CSV and TSV files into case classes by header name, report every bad row, write records back out and process large files row by row.

📄️How to Read and Write YAML Documents

Read YAML files into case classes, write CI-style YAML from Scala values, convert to JSON, and guard against the YAML that schema-yaml silently misreads.

📄️Build a Typed Configuration Loader

Load a typed case class from YAML, environment overrides and defaults, report every error at once, and see where each value came from.

📄️How to Feed Configuration into a Wire Dependency Graph

Give each service in a Wire graph its own typed, checked settings from one layered ConfigSource, and shut everything down in order.

📄️How to Load Configuration Files on the JVM and in the Browser

Load HOCON, JSON and YAML configuration files into a typed case class, split them with includes, load them safely, and run the same settings in the browser.

📄️How to Roll Out a Feature Gradually with Flags

Ship a feature to 10% of readers, target one region, widen the rollout at runtime, and test the code that reads the flag.

📄️Build Your First Database Repository on SQLite

Connect to SQLite, derive a table and a repository from one schema, write your own queries and roll back a transaction.

📄️How to Test Database Code Against SQLite

Give every test its own SQLite database, create the schema from code, seed fixtures and roll back writes in ZIO Test specs.

📄️How to Connect to PostgreSQL with a Connection Pool

Set up a HikariCP pool for PostgreSQL, build a JdbcTransactor on it, size it for virtual threads and close it with a Scope.

📄️How to Upsert Rows and Paginate with Keyset Cursors

Insert or update rows in one statement, choose which columns an upsert changes, and walk large tables page by page with keyset cursors.

📄️How to Map Custom Column Types

Store newtypes, opaque types, enums, JSON documents, PostgreSQL arrays and timestamps in SQL columns with the ZIO Blocks sql module.

📄️How to Stream Large Query Results

Read a large SQL result set as a stream of row chunks, aggregate it, export it to a file and handle its errors without loading every row.

📄️How to Write Joins and Inspect the Generated SQL

Join related tables with SqlQuery and Rel, read the rows as tuples, and print or dump the SQL each join generates.

📄️How to Use the sql Module from a ZIO Application

Provide a ZIO Blocks transactor as a ZLayer, run queries off ZIO's main threads, and mix database writes with other effects in one transaction.

📄️Render Your First Server-Side HTML Page

Build a book detail page with the ZIO Blocks HTML DSL, escape user input, add CSS and JSON state, and save it as an HTML file.

📄️How to Serve http-model Requests with the JDK HTTP Server

Serve a Request => Response function built on ZIO Blocks http-model with the HTTP server that ships with the JDK.

📄️How to Validate Query Parameters and Headers and Answer 400

Read query parameters and headers as typed values with http-model-schema and answer bad input with a JSON 400 that names every problem.

📄️How to Stream Files and Sockets Without Leaking Resources

Read files, NIO channels and sockets as streams that close their handles on success, failure, early stop and missing input.

📄️Getting Started with Async

Learn to create, compose, and run async effects in Scala with the zero-allocation Async[A] type.

📄️Compile-Time Resource Safety with Scope

Welcome to ZIO Blocks Scope—a library that makes resource management safe, composable, and verifiable at compile time. If you've ever struggled with try/finally chains, wondered when to close a database connection, or worried about resources outliving their owners, this tutorial is for you. You don't need any prior experience with Scope or advanced type system concepts to follow along.

📄️How to Fix Common Scope and Wire Compile Errors

Look up a Scope or Wire compile error by its message, see why the macro rejected your code, and apply the fix.

📄️Coming from cats-effect Resource, ZIO Scope/ZLayer, macwire or Using

Move resource handling and dependency wiring from cats-effect, ZIO, macwire or scala.util.Using to ZIO Blocks Scope, Resource and Wire.

📄️Getting Started with Mux

Learn how to manage multiplexed bidirectional message streams with capacity limits.

📄️Build a Small JSON Backend from Blocks

Combine schema, config, scope, sql, http-model and telemetry into one small bookstore JSON backend, from settings to shutdown.

📄️Instrument a Program with Logs, Traces and Metrics

Add structured logs, nested spans, a counter and a histogram to a batch job, switch to JSON logs, and test the spans.

📄️How to Test Code That Logs, Traces and Records Metrics

Capture spans, log records and counter values in memory during tests, assert on them, and keep tests from leaking into each other.

📄️Telemetry: Architecture, Patterns, and Real-World Usage

zio-blocks-telemetry is an effect-free, zero-allocation observability library that gives you structured logging, distributed tracing, and metrics without pulling in the OpenTelemetry SDK or any effect system. This guide explains why it works the way it does, shows what happens inside each operation, and walks through patterns for production systems.

📄️Migrating from ZIO Schema to ZIO Blocks Schema

This guide helps you migrate an application that uses ZIO Schema (version 1.x) to ZIO Blocks Schema (the schema module of ZIO Blocks). It covers the conceptual differences between the two libraries, provides a systematic mapping of data types, and shows how to rewrite the most common patterns in the idiomatic ZIO Blocks style.

📄️Coming from PureConfig, Typesafe Config or zio-config

Move a PureConfig, Typesafe Config or zio-config application to ZIO Blocks config while keeping its existing application.conf.

📄️Coming from circe, zio-json or jsoniter-scala

Move JSON codecs from circe, zio-json or jsoniter-scala to one ZIO Blocks Schema, keeping your field names, discriminators and custom formats.

📄️Coming from fs2, ZIO Streams or Ox

Move streaming pipelines from fs2, ZIO Streams or Ox to ZIO Blocks Stream, Sink and Pipeline, without an effect system.

📄️How to Generate JSON Schema from a Type and Validate Payloads Against It

Derive a draft 2020-12 JSON Schema contract from a case class, publish it, and validate raw JSON payloads against it or an external schema.

📄️How to Write an OpenAPI Document and Export It as JSON or YAML

Describe a REST API as a typed OpenAPI value, generate its schemas from the same Schema used for JSON, and export it as JSON and YAML.

📄️How to Send Compact Data to an LLM with TOON and Parse the Reply

Encode records as tabular TOON for an LLM prompt, then decode the model's TOON reply back into case classes.

🗃Query DSL

4 items

📄️SQL Transactions: Isolation, Read-Only and Savepoints

This guide covers ZIO Blocks' SQL transaction system: how transact works under the hood, which isolation levels are available on each database, and how nested transactions use savepoints. To set up a connection pool, see How to Connect to PostgreSQL with a Connection Pool.