Grackle - GraphQL for the Typelevel stack

Overview

Grackle is a GraphQL server written in functional Scala, built on the Typelevel stack.

It's powered by cats, cats-effect, fs2 and http4s, and supports GraphQL queries, mutations and subscriptions.

It has an abstract model of data sources implemented in terms of declarative mappings between GraphQL schemas and backing data, and cursors into that data. It supports in-memory, DB-backed, and effectful data sources.

Grackle is structured as a compiler/interpreter. Queries are type-checked against a GraphQL schema and compiled into an internal query algebra. The query algebra may be further compiled in a backend-specific way to materialize data. In particular it can be compiled to efficient SQL and in that regard currently supports Postgres via Doobie or Skunk.

Grackle is an Apache 2.0 licensed Typelevel project and is available for Scala 2/3 and for Scala.js and Scala Native.

Work has been generously sponsored by Aura/Gemini and ITV over the last four years.

Getting Started

• See the tutorial and accompanying demo.
• Online Scaladoc is available here.
• Ask us anything the in #grackle channel on the Typelevel discord server.

To add Grackle to your project you should add the following to your build.sbt,

// Required: Scala 2.13/3.3+
libraryDependencies += "org.typelevel" %% "grackle-core" % "0.22.0"

// Optional: support for in-memory Json backend using circe
libraryDependencies += "org.typelevel" %% "grackle-circe" % "0.22.0"

// Optional: support for in-memory generic Scala backend using shapeless
libraryDependencies += "org.typelevel" %% "grackle-generic" % "0.22.0"

// Optional: support for Postgres backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-pg" % "0.22.0"

// Optional: support for Postgres backend via Skunk
libraryDependencies += "org.typelevel" %% "grackle-skunk" % "0.22.0"

Community

Grackle is proud to be a Typelevel project. We are committed to providing a friendly, safe and welcoming environment for all, and ask that the community adhere to the Typelevel Code of Conduct in all venues.

Conversations around Grackle are currently happening on GitHub issues, PR discussions, and discord.

The Typelevel discord has a #grackle channel, as well as channels for related projects such as #cats, #cats-effect, #fs2, #doobie and #skunk. If you're new to the Typelevel ecosystem the #beginners channel might also be useful. Please join us!

Talks

• Grackle GraphQL server - Rafał Piotrowski & Miles Sabin (ScalaCon 2022)
• Functional GraphQL for the Typelevel Stack (NEScala 2023)

Contributing

This project exists thanks to all the people who contribute.

We welcome all kinds of contribution, including but not limited to,

• documentation improvements, explanatory images/diagrams, fixes in typos, useful links
• refactorings of messy code, build structure, increasing test coverage or quality
• new features and bugfixes (including bug reports and feature requests).

Writing documentation is valuable for learning, so if you find some explanation insufficient, overly complicated or incorrect, it's a perfect opportunity to make a change to it!

If at any point you run into problems, you can always ask a question on the #grackle channel on the Typelevel discord server.

More information, including on how to build locally and submit pull requests, can be found here.