ProtoQuill

ProtoQuill allows you to define custom parsing logic so that regular Scala methods (not just quoted ones) can be used within quote blocks. This prevents the need to define duplicate logic for both Scala and Quill.

Workflow:

1. Define Business Logic: Create an object containing the methods you want to use. Ensure the implementation is not inline in this object.
2. Define a Parser: Implement a Parser.Clause[Ast] that intercepts the specific syntax (e.g., an infix operator) and translates it into a Quill Ast (like Infix).
3. Register the Parser: Create a ParserLibrary that includes your custom parser in the operationsParser series.
4. Use in Application: Define your custom parser as a given in your application code to enable the syntax within quote blocks.

Important: The parser definition must reside in a separate compilation unit (e.g., a separate SBT project) that is compiled before your main application code.

// 1. Define business logic (NOT inline)
object MyBusinessLogic:
  extension (i: Int)
    def **(exponent: Int) = Math.pow(i, exponent)

// 2. Define the parser (in a separate compilation unit)
import io.getquill.parser._
import io.getquill.ast.{ Ast, Infix }
import io.getquill.quat.Quat

case class CustomOperationsParser(root: Parser[Ast] = Parser.empty)(override implicit val qctx: Quotes) extends Parser.Clause[Ast] {
  import quotes.reflect._
  import CustomOps._
  def reparent(newRoot: Parser[Ast]) = this.copy(root = newRoot)
  def delegate: PartialFunction[Expr[_], Ast] =
    case '{ ($i: Int)**($j: Int) } =>
      Infix(
        List("power(", " ,", ")"),
        List(astParse(i), astParse(j)), true, Quat.Value)
}

object CustomParser extends ParserLibrary:
  import Parser._
  override def operationsParser(using qctx: Quotes) =
    Series.of(new OperationsParser, new CustomOperationsParser)

// 3. Use in application
given myParser: CustomParser.type = CustomParser
import MyBusinessLogic._

inline def q = quote { query[Person].map(p => p.age ** 2) }

ProtoQuill supports Co-Products (sum types) using a "Table Per Class-Hierarchy" model, where all data for the co-product must be encodable within a single row.

Requirements:

1. Static Enums: Currently, all Enums used for Co-Product rows must be defined in a static namespace (e.g., inside an object).
2. Sealed Traits: Any sealed traits used must be sealed in a separate object to ensure the sum-type mirror is found.

Steps to implement:

1. Define the Co-Product (e.g., an enum inside an object).
2. Create a RowTyper (a given RowTyper[T]) that inspects a database row (e.g., via a type column) to determine which element of the co-product to decode.
3. Run your query using quote and ctx.run.

// 1. Create the Coproduct in a static namespace
object StaticEnumExample {
  enum Shape(val id: Int):
    case Square(override val id: Int, width: Int, height: Int) extends Shape(id)
    case Circle(override val id: Int, radius: Int) extends Shape(id)
}

// 2. Create a row-typer to decode the row
given RowTyper[Shape] with
  def apply(row: Row) =
    row.apply[String]("type") match
      case "square" => classTag[Shape.Square]
      case "circle" => classTag[Shape.Circle]

// 3. Run the query
inline def q = quote { query[Shape].filter(s => s.id == 18) }
val result: List[Shape] = ctx.run(q)

The quill-caliban module allows you to create Caliban GraphQL endpoints that support filter-pushdown (filtering by columns) and predicate-pushdown (including/excluding columns). This ensures that GraphQL requests only fetch and filter the data requested by the client at the database level.

Key Methods:

• .filterColumns(columns: List[String]): Limits the SQL SELECT clause to the specified columns.
• .filterByKeys(filters: Map[String, String]): Adds WHERE clause conditions based on the provided key-value pairs.
• quillColumns(productArgs): A helper from io.getquill.CalibanIntegration to extract requested columns from Caliban arguments.

Implementation Pattern:

1. Add .filterColumns and .filterByKeys to your quote block.
2. In your Caliban resolver, use quillColumns(productArgs) to pass the requested columns and productArgs.keyValues to pass the filters to your data service.

import io.getquill._
import io.getquill.CalibanIntegration._

// 1. Define query with pushdown methods
inline def peopleAndAddresses(inline columns: List[String], inline filters: Map[String, String]) =
  quote {
    query[Person].leftJoin(query[Address]).on((p, a) => p.id == a.ownerId)
      .map((p, a) => PersonAddress(p.id, p.first, p.last, p.age, a.map(_.street)))
      .filterColumns(columns)
      .filterByKeys(filters)
  }

// 2. Use in Caliban Resolver
val endpoint = graphQL(
  RootResolver(
    Queries(
      personAddress => (productArgs => 
        DataService.personAddress(
          quillColumns(productArgs), // Extract columns from Caliban
          productArgs.keyValues      // Extract filters from Caliban
        )
      )
    )
  )
).interpreter

The TypedEntityQuery[T] API provides a way to build queries using Record[T, Col] for structural field access. This approach is designed to offer better compile times compared to the standard macro-based query[T] API by deriving schema information via type-level NamedTuple instead of heavy AST inspection.

Key characteristics:

• Field Access: Uses Record[T, Col] in lambdas to allow accessing fields of type T.
• Result Type: The map operation currently only supports column selection or reordering within the same entity type T. It does not yet support projecting to a different type (e.g., a different case class).
• Integration: Use .toQuoted to convert the builder into a Quoted[EntityQuery[T]], which can then be passed to existing ctx.run() infrastructure.

// Conceptual usage pattern
val query = TypedQueryMacro[User]
  .filter(r => r.id === 1)
  .sortBy(r => r.name)
  .take(10)
  .toQuoted

ctx.run(query)

When using Ctx.run(query), the resulting ZIO effect often requires a specific environment (like a DataSource or a Session) to execute. Instead of calling .provide(Has(ds)) manually for every single query, you can use the implicitly extension method.

To use this, you must:

1. Import io.getquill.context.qzio.Ctx._ and io.getquill.context.qzio.ImplicitSyntax._.
2. Define an implicit val env = Implicit(Has(yourDependency)) in your scope.
3. Call .implicitly on the query effect, passing the required Tag.

This is particularly useful in JDBC contexts where you need to provide a DataSource, or in specialized drivers like quill-zio-cassandra where you only need to provide the session.

import io.getquill.context.qzio.Ctx._
import io.getquill.context.qzio.ImplicitSyntax._

case class MyQueryService(ds: DataSource with Closeable) {
  // Define the implicit context wrapper
  implicit val env = Implicit(Has(ds))

  // Use .implicitly to automatically provide the environment to the query
  val joes = Ctx.run(query[Person].filter(p => p.name == "Joe")).onDataSource.implicitly
}

The project uses a docker-compose.yml file to orchestrate a local development environment containing multiple database engines. You can use this file to spin up the necessary infrastructure for testing or development with zio-protoquill.

Supported services include:

• Postgres: Port 15432.
• MySQL: Port 13306.
• Cassandra: Port 19042.
• OrientDB: Port 12424.
• SQL Server: Port 11433.
• Oracle: Port 11521.

Note that some services like cassandra and orientdb have specific JVM memory settings configured to enable NativeMemoryTracking and manage CompressedClassSpaceSize for local builds.

version: '2.2'

services:
  postgres:
    ports:
      - "15432:5432"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_HOST_AUTH_METHOD=trust

  mysql:
    ports:
      - "13306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_ALLOW_EMPTY_PASSWORD=yes
      - MYSQL_ROOT_HOST=%"

  cassandra:
    ports:
      - "19042:9042"
    environment:
      - MAX_HEAP_SIZE=256m
      - HEAP_NEWSIZE=64m
      - JVM_OPTS=-XX:NativeMemoryTracking=summary -XX:CompressedClassSpaceSize=200m

  sqlserver:
    ports:
      - "11433:1433"
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=QuillRocks!