https://github.com/typelevel/grackle
Grackle: Functional GraphQL for the Typelevel stack
https://github.com/typelevel/grackle
Last synced: 9 months ago
JSON representation
Grackle: Functional GraphQL for the Typelevel stack
- Host: GitHub
- URL: https://github.com/typelevel/grackle
- Owner: typelevel
- License: apache-2.0
- Created: 2019-09-09T16:26:29.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-04-12T11:14:52.000Z (9 months ago)
- Last Synced: 2025-04-13T04:59:21.607Z (9 months ago)
- Language: Scala
- Homepage: http://typelevel.org/grackle/
- Size: 3.32 MB
- Stars: 180
- Watchers: 19
- Forks: 28
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - gsp-graphql - hlsw | 42 | (Scala)
README
# Grackle - GraphQL for the Typelevel stack 
[](https://github.com/typelevel/grackle/actions?query=branch%3Amain+workflow%3A%22Continuous+Integration%22)
[](https://img.shields.io/maven-central/v/org.typelevel/grackle-core_2.13?versionPrefix=0)
[](https://javadoc.io/doc/org.typelevel/grackle-core_2.13)
[](https://typelevel.org/projects/#grackle)
[](https://codecov.io/gh/typelevel/grackle)
[][grackle-dev]
## Overview
Grackle is a [GraphQL](https://graphql.org) server written in functional [Scala](https://www.scala-lang.org), built on
the [Typelevel](https://typelevel.org) stack.
It's powered by [cats](https://typelevel.org/cats), [cats-effect](https://typelevel.org/cats-effect/),
[fs2](https://github.com/typelevel/fs2) and [http4s](https://http4s.org/), 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](https://tpolecat.github.io/doobie/) or [Skunk](https://typelevel.org/skunk/) and Oracle and SQL Server via
Doobie.
Grackle is an [Apache 2.0 licensed](https://www.apache.org/licenses/LICENSE-2.0) Typelevel project and is available
for Scala 2/3 and for [Scala.js](https://www.scala-js.org/) and [Scala Native](https://scala-native.org/en/stable/).
Work has been generously sponsored by
[Aura/Gemini](https://www.aura-astronomy.org/centers/nsfs-oir-lab/gemini-observatory/), [ITV](https://www.itv.com)
and [imbus AG](https://www.imbus.de/) over the last five years.
## Getting Started
- See the [tutorial](https://typelevel.org/grackle) and accompanying [demo](https://github.com/typelevel/grackle/tree/main/demo/src/main).
- Online Scaladoc is available [here](https://javadoc.io/doc/org.typelevel/grackle-core_2.13).
- Ask us anything the in **#grackle** channel on the Typelevel [discord server][grackle-dev].
To add Grackle to your project you should add the following to your `build.sbt`,
```scala
// 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"
```
## Running tests for database backed mappings
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.
## Community
Grackle is proud to be a [Typelevel](https://typelevel.org/) 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](https://typelevel.org/code-of-conduct.html) in all venues.
Conversations around Grackle are currently happening on [GitHub issues][grackle-issues], [PR
discussions][grackle-pulls], and [discord][grackle-dev].
The Typelevel [discord][grackle-dev] 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)](https://www.youtube.com/watch?v=BXTkvwZ-7Xg)
- [Functional GraphQL for the Typelevel Stack (NEScala 2023)](https://www.youtube.com/watch?v=c1_WHBs9M5U)
## Contributing
This project exists thanks to [all the people who
contribute](https://github.com/typelevel/grackle/graphs/contributors).
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][grackle-issues]).
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][grackle-dev].
More information, including on how to build locally and submit pull requests, can be found
[here](https://typelevel.org/grackle/CONTRIBUTING.html).
[grackle-issues]: https://github.com/typelevel/grackle/issues
[grackle-pulls]: https://github.com/typelevel/grackle/pulls
[grackle-dev]: https://discord.gg/GYD4J9w8EK