async-graphql/README.md

<div align="center">
<samp>

# async-graphql

**a high-performance graphql server library that's fully specification compliant**

</samp>

[Book](https://async-graphql.github.io/async-graphql/en/index.html) • [中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html) • [Docs](https://docs.rs/async-graphql) • [GitHub repository](https://github.com/async-graphql/async-graphql) • [Cargo package](https://crates.io/crates/async-graphql)

---

![ci status](https://github.com/async-graphql/async-graphql/workflows/CI/badge.svg)
[![code coverage](https://codecov.io/gh/async-graphql/async-graphql/branch/master/graph/badge.svg)](https://codecov.io/gh/async-graphql/async-graphql/)
[![Unsafe Rust forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
[![Crates.io version](https://img.shields.io/crates/v/async-graphql.svg)](https://crates.io/crates/async-graphql)
[![docs.rs docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://docs.rs/async-graphql)
[![downloads](https://img.shields.io/crates/d/async-graphql.svg)](https://crates.io/crates/async-graphql)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/async-graphql/async-graphql/compare)

_This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust._

</div>

```rs
struct Query;

#[Object]
impl Query {
  fn howdy(&self) -> &'static str {
    "partner"
  }
}

async fn main() {
    let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();

    let app = Route::new()
      .at("/",
          get(graphiql)
            .post(GraphQL::new(schema))
       );

    println!("GraphiQL: http://localhost:8000");
    Server::new(TcpListener::bind("0.0.0.0:8000"))
        .run(app)
        .await
        .unwrap();
}
```

## Features

- Fully supports async/await
- Type safety
- Rustfmt friendly (Procedural Macro)
- Custom scalars
- Minimal overhead
- Easy integration ([poem](https://crates.io/crates/poem), actix_web, tide, warp, rocket ...)
- Upload files (Multipart request)
- Subscriptions (WebSocket transport)
- Custom extensions
- Error extensions
- Limit query complexity/depth
- Batch queries
- Apollo Persisted Queries
- Apollo Tracing extension
- Apollo Federation(v2)

> **Note**: Minimum supported Rust version: 1.59.0 or later

## Examples

All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory.

```shell
git submodule update # update the examples repo
cd examples && cargo run --bin [name]
```

## Integrations

Integrations are what glue `async-graphql` with your web server, here are provided ones, or you can build your own!

- Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem)
- Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web)
- Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp)
- Tide [async-graphql-tide](https://crates.io/crates/async-graphql-tide)
- Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket)
- Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum)

## Crate features

This crate offers the following features, all of which are not activated by default:

| feature                        | enables                                                                                                                                                                                       |
|:-------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **`apollo_tracing`**           | Enable the [Apollo tracing extension](extensions/struct.ApolloTracing.html).                                                                                                                  |
| **`apollo_persisted_queries`** | Enable the [Apollo persisted queries extension](extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html).                                                                      |
| **`log`**                      | Enable the [logger extension](extensions/struct.Logger.html).                                                                                                                                 |
| **`tracing`**                  | Enable the [tracing extension](extensions/struct.Tracing.html).                                                                                                                               |
| **`opentelemetry`**            | Enable the [OpenTelemetry extension](extensions/struct.OpenTelemetry.html).                                                                                                                   |
| **`unblock`**                  | Support [asynchronous reader for Upload](types/struct.Upload.html)                                                                                                                            |
| **`bson`**                     | Integrate with the [`bson` crate](https://crates.io/crates/bson).                                                                                                                             |
| **`chrono`**                   | Integrate with the [`chrono` crate](https://crates.io/crates/chrono).                                                                                                                         |
| **`chrono-tz`**                | Integrate with the [`chrono-tz` crate](https://crates.io/crates/chrono-tz).                                                                                                                   |
| **`url`**                      | Integrate with the [`url` crate](https://crates.io/crates/url).                                                                                                                               |
| **`uuid`**                     | Integrate with the [`uuid` crate](https://crates.io/crates/uuid).                                                                                                                             |
| **`uuid08`**                   | Integrate with the [`uuid 0.8` crate](https://crates.io/crates/uuid/0.8.2).                                                                                                                   |
| **`string_number`**            | Enable the [StringNumber](types/struct.StringNumber.html).                                                                                                                                    |
| **`dataloader`**               | Support [DataLoader](dataloader/struct.DataLoader.html).                                                                                                                                      |
| **`secrecy`**                  | Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy).                                                                                                                       |
| **`decimal`**                  | Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal).                                                                                                             |
| **`bigdecimal`**               | Integrate with the [`bigdecimal` crate](https://crates.io/crates/bigdecimal).                                                                                                                 |
| **`cbor`**                     | Support for [serde_cbor](https://crates.io/crates/serde_cbor).                                                                                                                                |
| **`smol_str`**                 | Integrate with the [`smol_str` crate](https://crates.io/crates/smol_str).                                                                                                                     |
| **`hashbrown`**                | Integrate with the [`hashbrown` crate](https://github.com/rust-lang/hashbrown).                                                                                                               |
| **`time`**                     | Integrate with the [`time` crate](https://github.com/time-rs/time).                                                                                                                           |
| **`tokio-sync`**               | Integrate with the [`tokio::sync::RwLock`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.RwLock.html) and [`tokio::sync::Mutex`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.Mutex.html). |
| **`fast_chemail`**             | Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail).                                                                                                             |

### Observability

One of the tools used to monitor your graphql server in production is Apollo Studio. Apollo Studio is a cloud platform that helps you build, monitor, validate, and secure your organization's data graph.
Add the extension crate [`async_graphql_apollo_studio_extension`](https://github.com/async-graphql/async_graphql_apollo_studio_extension) to make this avaliable.

## Who's using `async-graphql` in production?

- [Vector](https://vector.dev/)
- [DiveDB](https://divedb.net)
- [Kairos Sports tech](https://kairostech.io/)
- [AxieInfinity](https://axieinfinity.com/)
- [Nando's](https://www.nandos.co.uk/)
- [Prima.it](https://www.prima.it/)
- [VoxJar](https://voxjar.com/)
- [Zenly](https://zen.ly/)
- [Brevz](https://brevz.io/)
- [thorndyke](https://www.thorndyke.ai/)
- [My Data My Consent](https://mydatamyconsent.com/)

## Community Showcase

- [rust-actix-graphql-sqlx-postgresql](https://github.com/camsjams/rust-actix-graphql-sqlx-postgresql)
  Using GraphQL with Rust and Apollo Federation
- [entity-rs](https://github.com/chipsenkbeil/entity-rs) A simplistic framework based on TAO, Facebook's distributed database for Social Graph.
- [vimwiki-server](https://github.com/chipsenkbeil/vimwiki-rs/tree/master/vimwiki-server) Provides graphql server to inspect and manipulate vimwiki files.
- [Diana](https://github.com/arctic-hen7/diana) Diana is a GraphQL system for Rust that's designed to work as simply as possible out of the box, without sacrificing configuration ability.
- [cindythink](https://www.cindythink.com/)
- [sudograph](https://github.com/sudograph/sudograph)

## Blog Posts

- [Async GraphQL with Rust](https://formidable.com/blog/2022/async-graphql-with-rust-1/)
- [GraphQL in Rust](https://romankudryashov.com/blog/2020/12/graphql-rust/)
- [How to implement a Rust micro-service using Rocket, GraphQL, PostgreSQL](https://lionkeng.medium.com/how-to-implement-a-rust-micro-service-using-rocket-graphql-postgresql-a3f455f2ae8b)
- [Running GraphQL on Lambda with Rust](https://dylananthony.com/posts/graphql-lambda-rust)

## References

- [GraphQL](https://graphql.org)
- [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec)
- [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm)
- [GraphQL over WebSocket Protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)
- [Apollo Tracing](https://github.com/apollographql/apollo-tracing)
- [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction)

## License

Licensed under either of

- Apache License, Version 2.0,
  ([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT)
  at your option.
add some files 2020-03-01 13:56:14 +00:00			`<div align="center">`
docs: updates readme 2022-09-01 06:11:33 +00:00			`<samp>`
add some files 2020-03-01 13:56:14 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`# async-graphql`
Update README.md 2020-03-12 09:21:49 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`a high-performance graphql server library that's fully specification compliant`
add some files 2020-03-01 13:56:14 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`</samp>`
Add #![forbid(unsafe_code)] to all sub crates 2020-05-29 09:33:19 +00:00
Release 4.0.15 async-graphql@4.0.15 async-graphql-actix-web@4.0.15 async-graphql-axum@4.0.15 async-graphql-derive@4.0.15 async-graphql-parser@4.0.15 async-graphql-poem@4.0.15 async-graphql-rocket@4.0.15 async-graphql-tide@4.0.15 async-graphql-value@4.0.15 async-graphql-warp@4.0.15 Generated by cargo-workspaces 2022-10-07 08:48:24 +00:00			`[Book](https://async-graphql.github.io/async-graphql/en/index.html) • [中文文档](https://async-graphql.github.io/async-graphql/zh-CN/index.html) • [Docs](https://docs.rs/async-graphql) • [GitHub repository](https://github.com/async-graphql/async-graphql) • [Cargo package](https://crates.io/crates/async-graphql)`
Add #![forbid(unsafe_code)] to all sub crates 2020-05-29 09:33:19 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`---`
Update README.md 2020-06-02 23:46:34 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`![ci status](https://github.com/async-graphql/async-graphql/workflows/CI/badge.svg)`
			`[![code coverage](https://codecov.io/gh/async-graphql/async-graphql/branch/master/graph/badge.svg)](https://codecov.io/gh/async-graphql/async-graphql/)`
			`[![Unsafe Rust forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)`
			`[![Crates.io version](https://img.shields.io/crates/v/async-graphql.svg)](https://crates.io/crates/async-graphql)`
			`[![docs.rs docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://docs.rs/async-graphql)`
			`[![downloads](https://img.shields.io/crates/d/async-graphql.svg)](https://crates.io/crates/async-graphql)`
			`[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/async-graphql/async-graphql/compare)`
Update readme 2020-09-26 03:25:21 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			_This crate uses `#![forbid(unsafe_code)]` to ensure everything is implemented in 100% safe Rust._
Now all features are not activated by default. 2021-03-22 02:39:17 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`</div>`

			```rs
			`struct Query;`

			`#[Object]`
			`impl Query {`
docs: readme example be correct rust 2022-09-01 10:09:15 +00:00			`fn howdy(&self) -> &'static str {`
docs: updates readme 2022-09-01 06:11:33 +00:00			`"partner"`
			`}`
			`}`

			`async fn main() {`
			`let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();`

			`let app = Route::new()`
			`.at("/",`
			`get(graphiql)`
docs: readme example be correct rust 2022-09-01 10:09:15 +00:00			`.post(GraphQL::new(schema))`
			`);`
docs: updates readme 2022-09-01 06:11:33 +00:00
			`println!("GraphiQL: http://localhost:8000");`
			`Server::new(TcpListener::bind("0.0.0.0:8000"))`
			`.run(app)`
			`.await`
			`.unwrap();`
			`}`
			```

			`## Features`
Now all features are not activated by default. 2021-03-22 02:39:17 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`- Fully supports async/await`
			`- Type safety`
			`- Rustfmt friendly (Procedural Macro)`
			`- Custom scalars`
			`- Minimal overhead`
			`- Easy integration ([poem](https://crates.io/crates/poem), actix_web, tide, warp, rocket ...)`
			`- Upload files (Multipart request)`
			`- Subscriptions (WebSocket transport)`
			`- Custom extensions`
			`- Error extensions`
			`- Limit query complexity/depth`
			`- Batch queries`
			`- Apollo Persisted Queries`
			`- Apollo Tracing extension`
Federation v1 is no longer supported 2022-09-22 15:34:49 +00:00			`- Apollo Federation(v2)`
docs: updates readme 2022-09-01 06:11:33 +00:00
			`> Note: Minimum supported Rust version: 1.59.0 or later`
misc: update readme to add apollo studio 2021-07-22 14:25:40 +00:00
v1.9.0 2020-04-14 01:53:17 +00:00			`## Examples`
Update README.md 2020-03-09 12:44:31 +00:00
Update readme 2020-10-16 01:21:16 +00:00			`All examples are in the [sub-repository](https://github.com/async-graphql/examples), located in the examples directory.`

			```shell
			`git submodule update # update the examples repo`
			`cd examples && cargo run --bin [name]`
			```
Update README.md 2020-03-09 12:44:31 +00:00
Update some documents 2020-03-18 00:44:41 +00:00			`## Integrations`

docs: updates readme 2022-09-01 06:11:33 +00:00			Integrations are what glue `async-graphql` with your web server, here are provided ones, or you can build your own!
Update some documents 2020-03-18 00:44:41 +00:00
docs: updates readme 2022-09-01 06:11:33 +00:00			`- Poem [async-graphql-poem](https://crates.io/crates/async-graphql-poem)`
			`- Actix-web [async-graphql-actix-web](https://crates.io/crates/async-graphql-actix-web)`
			`- Warp [async-graphql-warp](https://crates.io/crates/async-graphql-warp)`
			`- Tide [async-graphql-tide](https://crates.io/crates/async-graphql-tide)`
			`- Rocket [async-graphql-rocket](https://github.com/async-graphql/async-graphql/tree/master/integrations/rocket)`
			`- Axum [async-graphql-axum](https://github.com/async-graphql/async-graphql/tree/master/integrations/axum)`

			`## Crate features`

			`This crate offers the following features, all of which are not activated by default:`

			`\| feature \| enables \|`
Federation v1 is no longer supported 2022-09-22 15:34:49 +00:00			`\|:-------------------------------\|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------\|`
docs: updates readme 2022-09-01 06:11:33 +00:00			\| `apollo_tracing` \| Enable the [Apollo tracing extension](extensions/struct.ApolloTracing.html). \|
			\| `apollo_persisted_queries` \| Enable the [Apollo persisted queries extension](extensions/apollo_persisted_queries/struct.ApolloPersistedQueries.html). \|
			\| `log` \| Enable the [logger extension](extensions/struct.Logger.html). \|
			\| `tracing` \| Enable the [tracing extension](extensions/struct.Tracing.html). \|
			\| `opentelemetry` \| Enable the [OpenTelemetry extension](extensions/struct.OpenTelemetry.html). \|
			\| `unblock` \| Support [asynchronous reader for Upload](types/struct.Upload.html) \|
			\| `bson` \| Integrate with the [`bson` crate](https://crates.io/crates/bson). \|
			\| `chrono` \| Integrate with the [`chrono` crate](https://crates.io/crates/chrono). \|
			\| `chrono-tz` \| Integrate with the [`chrono-tz` crate](https://crates.io/crates/chrono-tz). \|
			\| `url` \| Integrate with the [`url` crate](https://crates.io/crates/url). \|
			\| `uuid` \| Integrate with the [`uuid` crate](https://crates.io/crates/uuid). \|
			\| `uuid08` \| Integrate with the [`uuid 0.8` crate](https://crates.io/crates/uuid/0.8.2). \|
			\| `string_number` \| Enable the [StringNumber](types/struct.StringNumber.html). \|
			\| `dataloader` \| Support [DataLoader](dataloader/struct.DataLoader.html). \|
			\| `secrecy` \| Integrate with the [`secrecy` crate](https://crates.io/crates/secrecy). \|
			\| `decimal` \| Integrate with the [`rust_decimal` crate](https://crates.io/crates/rust_decimal). \|
			\| `bigdecimal` \| Integrate with the [`bigdecimal` crate](https://crates.io/crates/bigdecimal). \|
			\| `cbor` \| Support for [serde_cbor](https://crates.io/crates/serde_cbor). \|
			\| `smol_str` \| Integrate with the [`smol_str` crate](https://crates.io/crates/smol_str). \|
			\| `hashbrown` \| Integrate with the [`hashbrown` crate](https://github.com/rust-lang/hashbrown). \|
			\| `time` \| Integrate with the [`time` crate](https://github.com/time-rs/time). \|
			\| `tokio-sync` \| Integrate with the [`tokio::sync::RwLock`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.RwLock.html) and [`tokio::sync::Mutex`](https://docs.rs/tokio/1.18.1/tokio/sync/struct.Mutex.html). \|
			\| `fast_chemail` \| Integrate with the [`fast_chemail` crate](https://crates.io/crates/fast_chemail). \|

			`### Observability`

			`One of the tools used to monitor your graphql server in production is Apollo Studio. Apollo Studio is a cloud platform that helps you build, monitor, validate, and secure your organization's data graph.`
			Add the extension crate [`async_graphql_apollo_studio_extension`](https://github.com/async-graphql/async_graphql_apollo_studio_extension) to make this avaliable.

			## Who's using `async-graphql` in production?
Update README.md 2021-09-11 00:57:38 +00:00
			`- [Vector](https://vector.dev/)`
Update README.md 2021-09-24 03:20:47 +00:00			`- [DiveDB](https://divedb.net)`
Update README.md 2021-09-11 00:57:38 +00:00			`- [Kairos Sports tech](https://kairostech.io/)`
			`- [AxieInfinity](https://axieinfinity.com/)`
			`- [Nando's](https://www.nandos.co.uk/)`
			`- [Prima.it](https://www.prima.it/)`
			`- [VoxJar](https://voxjar.com/)`
			`- [Zenly](https://zen.ly/)`
			`- [Brevz](https://brevz.io/)`
			`- [thorndyke](https://www.thorndyke.ai/)`
Update README.md (#990) 2022-07-22 16:12:44 +00:00			`- [My Data My Consent](https://mydatamyconsent.com/)`
Update README.md 2021-09-11 00:57:38 +00:00
Update README.md 2021-09-24 03:20:47 +00:00			`## Community Showcase`

			`- [rust-actix-graphql-sqlx-postgresql](https://github.com/camsjams/rust-actix-graphql-sqlx-postgresql)`
			`Using GraphQL with Rust and Apollo Federation`
			`- [entity-rs](https://github.com/chipsenkbeil/entity-rs) A simplistic framework based on TAO, Facebook's distributed database for Social Graph.`
			`- [vimwiki-server](https://github.com/chipsenkbeil/vimwiki-rs/tree/master/vimwiki-server) Provides graphql server to inspect and manipulate vimwiki files.`
			`- [Diana](https://github.com/arctic-hen7/diana) Diana is a GraphQL system for Rust that's designed to work as simply as possible out of the box, without sacrificing configuration ability.`
			`- [cindythink](https://www.cindythink.com/)`
Update README.md 2021-12-06 01:28:00 +00:00			`- [sudograph](https://github.com/sudograph/sudograph)`
Update README.md 2021-09-24 03:20:47 +00:00
Update README.md 2021-07-14 04:24:50 +00:00			`## Blog Posts`

Update README.md (#1010) Add Formidable blog post for Async GraphQL w/ Rust. I found this to be an incredibly "real-world" example of using this library and I think lots of others will find similar value. 2022-08-05 06:41:47 +00:00			`- [Async GraphQL with Rust](https://formidable.com/blog/2022/async-graphql-with-rust-1/)`
Update README.md 2021-07-14 04:24:50 +00:00			`- [GraphQL in Rust](https://romankudryashov.com/blog/2020/12/graphql-rust/)`
			`- [How to implement a Rust micro-service using Rocket, GraphQL, PostgreSQL](https://lionkeng.medium.com/how-to-implement-a-rust-micro-service-using-rocket-graphql-postgresql-a3f455f2ae8b)`
			`- [Running GraphQL on Lambda with Rust](https://dylananthony.com/posts/graphql-lambda-rust)`

docs: updates readme 2022-09-01 06:11:33 +00:00			`## References`

			`- [GraphQL](https://graphql.org)`
			`- [GraphQL Multipart Request](https://github.com/jaydenseric/graphql-multipart-request-spec)`
			`- [GraphQL Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm)`
			`- [GraphQL over WebSocket Protocol](https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md)`
			`- [Apollo Tracing](https://github.com/apollographql/apollo-tracing)`
			`- [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction)`

create type info 2020-03-03 03:48:00 +00:00			`## License`

			`Licensed under either of`

docs: updates readme 2022-09-01 06:11:33 +00:00			`- Apache License, Version 2.0,`
Add link to license files 2021-04-19 14:38:46 +00:00			`([LICENSE-APACHE](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)`
docs: updates readme 2022-09-01 06:11:33 +00:00			`- MIT license ([LICENSE-MIT](./LICENSE-MIT) or http://opensource.org/licenses/MIT)`
create type info 2020-03-03 03:48:00 +00:00			`at your option.`