Frag

zio.blocks.sql.Frag
See theFrag companion object
final case class Frag(parts: IndexedSeq[String], params: IndexedSeq[DbValue])

A SQL fragment composed of literal text interleaved with typed parameter values.

parts(i) is a literal SQL string and params(i) is the value bound at the ? placeholder that follows it. The invariant is parts.length == params.length + 1: the fragment begins and ends with a literal segment (which may be empty).

Fragments are assembled via ++ and rendered to a dialect-specific SQL string with sql. Use the extension methods on Frag (e.g. query, queryOne, update) to execute them against a live DbCon.

The sql"..." string interpolator is the primary way to construct fragments; use Frag.literal for parameter-free SQL.

Attributes

Companion
object
Source
Frag.scala
Graph
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Members list

Value members

Concrete methods

def ++(other: Frag): Frag

Concatenates two fragments, merging the adjacent literal boundary so the result remains a valid Frag (i.e. parts.length == params.length + 1).

Concatenates two fragments, merging the adjacent literal boundary so the result remains a valid Frag (i.e. parts.length == params.length + 1).

Attributes

Source
Frag.scala
def isEmpty: Boolean

Attributes

Source
Frag.scala
def query[A](using con: DbCon, codec: DbCodec[A]): List[A]
Extension method from Frag

Executes this fragment as a SELECT and returns all decoded rows.

Executes this fragment as a SELECT and returns all decoded rows.

Attributes

Source
Frag.scala
def queryChunked[A](chunkSize: Int)(using con: DbCon, codec: DbCodec[A]): Stream[Throwable, Chunk[A]]
Extension method from Frag

Executes this fragment as a SELECT and returns the decoded rows as a stream of Chunks, each holding up to chunkSize rows.

Executes this fragment as a SELECT and returns the decoded rows as a stream of Chunks, each holding up to chunkSize rows.

The statement and result set are acquired lazily on the first pull and released when the stream is closed or fully drained (via Stream.fromAcquireRelease). Rows are batched by the streams layer's Reader.readN inside Stream.chunked rather than a manual List.newBuilder loop. SQL failures surface as typed errors (Left) from terminal operations such as runCollect.

Because acquisition is lazy, the stream must be consumed within the scope that provides the DbCon: leaving Transactor.connect/transact closes the captured connection, and pulling afterwards fails.

Type parameters

A

the row type, decoded through codec's column mapping

Value parameters

chunkSize

maximum number of rows per emitted Chunk; must be >= 1

codec

decoder for the expected row shape

con

the connection context providing the connection, dialect, and logger

Attributes

Returns

a lazy stream of decoded row chunks; terminal operations answer Left(error) on SQL failure

Throws
IllegalArgumentException

if chunkSize is less than 1

Example
Transactor.connect(transactor) {
 sql"SELECT id, name FROM users"
   .queryChunked[User](500)
   .runFold(0)((acc, chunk) => acc + chunk.size)
}
Source
Frag.scala
def queryLimit[A](limit: Int)(using con: DbCon, codec: DbCodec[A]): List[A]
Extension method from Frag

Executes this fragment as a SELECT with a row limit.

Executes this fragment as a SELECT with a row limit.

Attributes

Source
Frag.scala
def queryOne[A](using con: DbCon, codec: DbCodec[A]): Maybe[A]
Extension method from Frag

Executes this fragment as a SELECT and returns the first row, if any.

Executes this fragment as a SELECT and returns the first row, if any.

Attributes

Source
Frag.scala
def queryParams: IndexedSeq[DbValue]

Attributes

Source
Frag.scala
def queryStream[A](using con: DbCon, codec: DbCodec[A]): Stream[Throwable, Chunk[A]]
Extension method from Frag

Executes this fragment as a SELECT and returns the decoded rows as a stream of Chunks, each holding up to DefaultQueryChunkSize rows.

Executes this fragment as a SELECT and returns the decoded rows as a stream of Chunks, each holding up to DefaultQueryChunkSize rows.

Equivalent to queryChunked[A](DefaultQueryChunkSize).

Type parameters

A

the row type, decoded through codec's column mapping

Value parameters

codec

decoder for the expected row shape

con

the connection context providing the connection, dialect, and logger

Attributes

Returns

a lazy stream of decoded row chunks; see queryChunked for the acquisition lifetime and error behavior

Example
val chunks: Stream[Throwable, Chunk[User]] =
 sql"SELECT id, name FROM users".queryStream[User]
val total = chunks.runFold(0)((n, chunk) => n + chunk.size)
Source
Frag.scala
def sql(dialect: SqlDialect): String

Renders the fragment to a SQL string using the given dialect's placeholder syntax.

Renders the fragment to a SQL string using the given dialect's placeholder syntax.

The rendered SQL depends only on the fragment's literal parts, the number of params, and the dialect — param values are bound separately — so the result is memoized per shape in Frag.renderedSql and reused across executions. Repeated execution of the same fragment therefore returns the cached String instead of rebuilding it with a StringBuilder each time.

Attributes

Source
Frag.scala
def update(using con: DbCon): Int
Extension method from Frag

Executes this fragment as an INSERT/UPDATE/DELETE and returns the affected row count.

Executes this fragment as an INSERT/UPDATE/DELETE and returns the affected row count.

Attributes

Source
Frag.scala
def updateReturningKeys[A](using con: DbCon, codec: DbCodec[A]): List[A]
Extension method from Frag

Executes this fragment as an INSERT and returns auto-generated keys.

Executes this fragment as an INSERT and returns auto-generated keys.

Attributes

Source
Frag.scala

Inherited methods

def productElementNames: Iterator[String]

An iterator over the names of all the elements of this product.

An iterator over the names of all the elements of this product.

Attributes

Inherited from:
Product
Source
Product.scala
def productIterator: Iterator[Any]

An iterator over all the elements of this product.

An iterator over all the elements of this product.

Attributes

Returns

in the default implementation, an Iterator[Any]

Inherited from:
Product
Source
Product.scala