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 and Oracle and SQL Server via Doobie.

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, ITV and imbus AG over the last five years.

• 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.23.0"

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

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

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

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

// Optional: support for Oracle backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-oracle" % "0.23.0"

// Optional: support for SQL Server backend via Doobie (JVM only)
libraryDependencies += "org.typelevel" %% "grackle-doobie-mssql" % "0.23.0"

Database backed mappings are tested against dockerized instances of Postgres, Oracle and SQL Server. This requires Docker 2.20.2 or later to be installed and running on the test machine.

Running tests (eg. rootJVM/test) will automatically spin up the relevant containers, which will stay up and can be reused across multiple tests runs, significantly speeding up the test cycle. I recommend running allUp initially, to pull images and initialise databases, before running tests the first time. Note that Oracle in particular takes quite a long time to initialise, so expect allUp to take several minutes to complete the first time around.

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!

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

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.