1
0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-12-15 09:22:43 +03:00
graphql-engine/README.md

201 lines
8.9 KiB
Markdown
Raw Normal View History

2018-06-24 16:47:01 +03:00
# Hasura GraphQL Engine
[![Docs](https://img.shields.io/badge/docs-v1.0-brightgreen.svg?style=flat)](https://docs.hasura.io)
[![CircleCI](https://circleci.com/gh/hasura/graphql-engine.svg?style=shield)](https://circleci.com/gh/hasura/graphql-engine)
2018-07-12 16:31:46 +03:00
<a href="https://discord.gg/3FNQnWj"><img src="https://img.shields.io/badge/chat-discord-brightgreen.svg?logo=discord&style=flat"></a>
2018-07-12 16:40:15 +03:00
<a href="https://twitter.com/intent/follow?screen_name=HasuraHQ"><img src="https://img.shields.io/badge/Follow-HasuraHQ-blue.svg?style=flat&logo=twitter"></a>
2018-10-04 07:19:40 +03:00
<a href="https://eepurl.com/dBUfJ5"><img src="https://img.shields.io/badge/newsletter-subscribe-yellow.svg?style=flat"></a>
Hasura GraphQL Engine is a blazing-fast GraphQL server that gives you **instant, realtime GraphQL APIs over Postgres**, with [**webhook triggers**](event-triggers.md) on database events for asynchronous business logic.
Hasura helps you build GraphQL apps backed by Postgres or incrementally move to GraphQL for existing applications using Postgres.
2018-07-16 15:55:05 +03:00
Read more at [hasura.io](https://hasura.io) and the [docs](https://docs.hasura.io).
2018-07-16 13:52:27 +03:00
------------------
![Hasura GraphQL Engine Demo](assets/demo.gif)
------------------
![Hasura GraphQL Engine Realtime Demo](assets/realtime.gif)
2018-07-16 13:52:27 +03:00
-------------------
## Features
* **Make powerful queries**: Built-in filtering, pagination, pattern search, bulk insert, update, delete mutations
* **Realtime**: Convert any GraphQL query to a live query by using subscriptions
* **Trigger webhooks or serverless functions**: On Postgres insert/update/delete events ([read more](event-triggers.md))
2018-07-16 13:52:27 +03:00
* **Works with existing, live databases**: Point it to an existing Postgres database to instantly get a ready-to-use GraphQL API
* **Fine-grained access control**: Dynamic access control that integrates with your auth system (eg: auth0, firebase-auth)
* **High-performance & low-footprint**: ~15MB docker image; ~50MB RAM @ 1000 req/s; multi-core aware
* **Admin UI & Migrations**: Admin UI & Rails-inspired schema migrations
2018-10-02 07:55:31 +03:00
* **Postgres** ❤️: Supports Postgres types (PostGIS/geo-location, etc.), turns views to *graphs*, trigger stored functions or procedures with mutations
2018-10-11 09:07:05 +03:00
Read more at [https://hasura.io](https://hasura.io) and the [docs](https://docs.hasura.io).
2018-07-16 13:52:27 +03:00
## Table of contents
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Quickstart:](#quickstart)
- [One-click deployment on Heroku](#one-click-deployment-on-heroku)
- [Other deployment methods](#other-deployment-methods)
- [Architecture](#architecture)
- [Client-side tooling](#client-side-tooling)
- [Add business logic](#add-business-logic)
- [Custom resolvers](#custom-resolvers)
- [Trigger webhooks on database events](#trigger-webhooks-on-database-events)
- [Demos](#demos)
- [Realtime applications](#realtime-applications)
- [Videos](#videos)
- [Support & Troubleshooting](#support--troubleshooting)
- [Contributing](#contributing)
2018-09-27 14:14:50 +03:00
- [Brand assets](#brand-assets)
- [License](#license)
<!-- markdown-toc end -->
2018-07-16 13:52:27 +03:00
## Quickstart:
2018-07-16 13:52:27 +03:00
### One-click deployment on Heroku
2018-07-16 13:52:27 +03:00
The fastest way to try Hasura out is via Heroku.
2018-07-16 13:52:27 +03:00
1. Click on the following button to deploy GraphQL Engine on Heroku with the free Postgres add-on:
2018-07-16 13:52:27 +03:00
[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/hasura/graphql-engine-heroku)
2. Open the Hasura console
Visit `https://<app-name>.herokuapp.com` (*replace \<app-name\> with your app name*) to open the admin console.
3. Make your first GraphQL query
2018-07-16 13:52:27 +03:00
Create a table and instantly run your first query. Follow this [simple guide](https://docs.hasura.io/1.0/graphql/manual/getting-started/first-graphql-query.html).
### Other deployment methods
2018-09-13 12:33:13 +03:00
For Docker-based deployment and advanced configuration options, see [deployment
guides](https://docs.hasura.io/1.0/graphql/manual/getting-started/index.html) or
[install manifests](install-manifests).
## Architecture
2018-07-16 13:52:27 +03:00
The Hasura GraphQL Engine fronts a Postgres database instance and can accept GraphQL requests from your client apps. It can be configured to work with your existing auth system and can handle access control using field-level rules with dynamic variables from your auth system.
You can also place the engine behind a central GraphQL proxy that fronts multiple GraphQL APIs via schema stitching.
2018-07-16 13:52:27 +03:00
![Hasura GraphQL Engine architecture](assets/hasura-arch.svg)
## Client-side tooling
2018-07-16 13:52:27 +03:00
Hasura works with any GraphQL client. We recommend using [Apollo Client](https://github.com/apollographql/apollo-client). See [awesome-graphql](https://github.com/chentsulin/awesome-graphql) for a list of clients.
## Add business logic
### Custom resolvers
Add custom resolvers in addition to Hasura GraphQL engine. Ideal for delegating
to HTTP APIs, making direct calls to another data-source or writing business
logic in code - [read more](community/boilerplates/custom-resolvers).
### Trigger webhooks on database events
Add asynchronous business logic that is triggered based on database events.
Ideal for notifications, data-pipelines from Postgres or asynchronous
processing - [read more](event-triggers.md).
## Demos
Check out all the example applications in the
[community/examples](community/examples) directory.
### Realtime applications
- Group Chat application built with React, includes a typing indicator, online users & new
message notifications.
- [Try it out](https://chat-example-trial-roar.herokuapp.com/)
- [Tutorial](community/examples/realtime-chat)
- [Browse APIs](https://hasura-realtime-group-chat.herokuapp.com/)
- Live location tracking app that shows a running vehicle changing current GPS
coordinates moving on a map.
- [Try it out](https://hasura.github.io/realtime-location-app/)
- [Tutorial](community/examples/realtime-location-tracking)
- [Browse APIs](https://realtime-backend.herokuapp.com/)
- A realtime dashboard for data aggregations on continuously changing data.
- [Try it out](https://shahidh.in/hasura-realtime-poll/)
- [Tutorial](community/examples/realtime-poll)
- [Browse APIs](https://hasura-realtime-poll.herokuapp.com/)
### Videos
* [Add GraphQL to a self-hosted GitLab instance](https://www.youtube.com/watch?v=a2AhxKqd82Q) (*3:44 mins*)
* [Todo app with Auth0 and GraphQL backend](https://www.youtube.com/watch?v=15ITBYnccgc) (*4:00 mins*)
* [GraphQL on GitLab integrated with GitLab auth](https://www.youtube.com/watch?v=m1ChRhRLq7o) (*4:05 mins*)
* [Dashboard for 10million rides with geo-location (PostGIS, Timescale)](https://www.youtube.com/watch?v=tsY573yyGWA) (*3:06 mins*)
2018-07-11 16:42:49 +03:00
## Support & Troubleshooting
The documentation and community will help you troubleshoot most issues. If you have encountered a bug or need to get in touch with us, you can contact us using one of the following channels:
2018-07-11 16:42:49 +03:00
* Support & feedback: [Discord](https://discord.gg/3FNQnWj)
* Issue & bug tracking: [GitHub issues](https://github.com/hasura/graphql-engine/issues)
2018-07-16 13:52:27 +03:00
* Follow product updates: [@HasuraHQ](https://twitter.com/hasurahq)
* Talk to us on our [website chat](https://hasura.io)
2018-07-11 16:42:49 +03:00
We are committed to fostering an open and welcoming environment in the community. Please see the [Code of Conduct](code-of-conduct.md).
If you want to report a security issue, please [read this](SECURITY.md).
## Contributing
2018-07-11 16:42:49 +03:00
Check out our [contributing guide](CONTRIBUTING.md) for more details.
2018-09-27 14:14:50 +03:00
## Brand assets
Hasura brand assets (logos, the Hasura mascot, powered by badges etc.) can be
found in the [assets/brand](assets/brand) folder. Feel free to use them in your
application/website etc. We'd be thrilled if you add the "Powered by Hasura"
badge to your applications built using Hasura. ❤️
<div style="display: flex;">
<img src="assets/brand/powered_by_hasura_black.svg" width="150px"/>
<img src="assets/brand/powered_by_hasura_white.svg" width="150px"/>
</div>
```html
<!-- For light backgrounds -->
<a href="https://hasura.io">
<img width="150px" src="https://graphql-engine-cdn.hasura.io/img/powered_by_hasura_black.svg" />
</a>
<!-- For dark backgrounds -->
<a href="https://hasura.io">
<img width="150px" src="https://graphql-engine-cdn.hasura.io/img/powered_by_hasura_white.svg" />
</a>
```
## License
The core GraphQL Engine is available under the [GNU Affero General Public
License v3](https://www.gnu.org/licenses/agpl-3.0.en.html) (AGPL-3.0), the same
license as [MongoDB](https://www.mongodb.com/community/licensing). We have
written more about what you can and cannot do under AGPL
[here](https://github.com/hasura/graphql-engine/wiki/License-Explained).
2018-10-11 09:07:05 +03:00
**Commercial licenses** that bundle the Hasura GraphQL Engine with support and
SLAs are available on request. Please feel free to contact us at build@hasura.io
or on our [website chat](https://hasura.io).
2018-10-11 09:07:05 +03:00
All **other contents** (except those in [`server`](server), [`cli`](cli) and
[`console`](console) directories) are available under the [MIT License](LICENSE-community).
This includes everything in the [`docs`](docs) and [`community`](community)
directories.