# Hasura — Instant GraphQL & REST APIs on Your Database

> Hasura generates instant, real-time GraphQL and REST APIs on PostgreSQL, MySQL, SQL Server, and MongoDB with fine-grained access control, event triggers, and remote schemas.

## Install

Save in your project root:

## Quick Use

```bash
docker run -d --name hasura -p 8080:8080 
  -e HASURA_GRAPHQL_DATABASE_URL=postgres://user:pass@host:5432/db 
  -e HASURA_GRAPHQL_ENABLE_CONSOLE=true 
  -e HASURA_GRAPHQL_ADMIN_SECRET=myadminsecret 
  hasura/graphql-engine:latest
```

Open `http://localhost:8080/console` — your database tables are instantly available as GraphQL API.

## Intro

**Hasura** is an open-source engine that connects to your databases and microservices to provide instant, real-time GraphQL and REST APIs. Point Hasura at your PostgreSQL, MySQL, SQL Server, or MongoDB database, and it automatically generates a full CRUD API with subscriptions, relationships, access control, and event triggers — no backend code required.

With 31.9K+ GitHub stars and Apache-2.0 license, Hasura has become the standard for instantly API-ifying databases, used by thousands of companies from startups to enterprises.

## What Hasura Does

- **Instant APIs**: Auto-generate GraphQL and REST APIs from any database table
- **Real-time Subscriptions**: Live query subscriptions for real-time data updates
- **Access Control**: Row-level and column-level permissions with session variables
- **Relationships**: Define relationships between tables for nested queries
- **Event Triggers**: Fire webhooks on database insert/update/delete events
- **Remote Schemas**: Stitch multiple GraphQL services into one unified API
- **Actions**: Extend GraphQL schema with custom business logic via webhooks
- **Migrations**: Version-controlled schema and metadata migrations
- **Caching**: Query response caching with configurable TTL

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Frontend    │────▶│  Hasura      │────▶│  PostgreSQL /│
│  (Any)       │     │  Engine      │     │  MySQL /     │
│  GraphQL     │     │  (Haskell)   │     │  SQL Server /│
│  Queries     │     └──────┬───────┘     │  MongoDB     │
└──────────────┘            │             └──────────────┘
                     ┌──────┴───────┐
                     │ Remote       │
                     │ Services     │
                     │ (Custom API) │
                     └──────────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  hasura:
    image: hasura/graphql-engine:latest
    ports:
      - "8080:8080"
    environment:
      HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://hasura:hasura@postgres:5432/hasura
      HASURA_GRAPHQL_DATABASE_URL: postgres://hasura:hasura@postgres:5432/myapp
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_ADMIN_SECRET: your-admin-secret
      HASURA_GRAPHQL_UNAUTHORIZED_ROLE: anonymous
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: hasura
      POSTGRES_PASSWORD: hasura
      POSTGRES_DB: myapp
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data:
```

## How It Works

### 1. Connect Database

Point Hasura at your existing PostgreSQL:
```
Database URL: postgres://user:password@host:5432/mydb
```

Hasura reads your schema and instantly generates GraphQL types for every table.

### 2. Query via GraphQL

```graphql
# Auto-generated queries
query {
  users(where: {active: {_eq: true}}, order_by: {created_at: desc}, limit: 10) {
    id
    name
    email
    orders(order_by: {created_at: desc}) {
      id
      total
      status
      items {
        product { name price }
        quantity
      }
    }
  }
}

# Mutations
mutation {
  insert_users_one(object: {name: "John", email: "john@example.com"}) {
    id
  }
}

# Real-time subscription
subscription {
  orders(where: {status: {_eq: "pending"}}) {
    id
    total
    customer { name }
  }
}
```

### 3. Access Control

```yaml
# Role-based permissions
- role: user
  table: orders
  permission:
    filter:
      customer_id: X-Hasura-User-Id    # Users can only see their own orders
    columns: [id, total, status, created_at]  # Can't see internal fields

- role: admin
  table: orders
  permission:
    filter: {}                          # Admins see all orders
    columns: "*"                        # All columns
```

### 4. Event Triggers

```
Table: orders
Event: INSERT
Webhook: https://api.example.com/new-order-handler

Payload:
{
  "event": {
    "data": {
      "new": { "id": 123, "total": 99.99, "customer_id": 456 }
    }
  }
}
```

Use cases: Send emails, update inventory, sync CRM, trigger notifications.

### 5. Actions (Custom Logic)

```graphql
# Extend schema with custom mutations
type Mutation {
  processPayment(orderId: Int!, paymentMethod: String!): PaymentResult
}

# Hasura forwards to your webhook
# POST https://api.example.com/process-payment
# Your code handles the business logic
```

## Hasura vs Alternatives

| Feature | Hasura | PostgREST | Supabase | Directus |
|---------|--------|-----------|----------|----------|
| API Type | GraphQL + REST | REST | REST + Realtime | REST + GraphQL |
| Subscriptions | Real-time | No | Real-time | No |
| Access control | Row/Column level | Row level | Row level | Role level |
| Event triggers | Yes | No | Edge Functions | Flows |
| Remote schemas | Yes | No | No | No |
| Multi-database | PG, MySQL, MSSQL, MongoDB | PostgreSQL only | PostgreSQL only | Any SQL |
| Language | Haskell | Haskell | TypeScript | JavaScript |

## 常见问题

**Q: Hasura 需要写后端代码吗？**
A: 简单 CRUD 操作完全不需要——Hasura 自动生成。复杂业务逻辑通过 Actions（webhook）实现，你只需要写处理函数。适合 80% 不需要后端的场景 + 20% 自定义逻辑。

**Q: 性能如何？能应对高并发吗？**
A: Hasura 用 Haskell 编写，性能极高。单实例可以处理每秒数千个 GraphQL 请求。支持查询缓存和水平扩展。在生产环境中已被验证处理每秒数万请求。

**Q: 已有数据库可以直接用吗？**
A: 完全可以。Hasura 不修改你的数据库 schema，只读取 schema 信息并生成 API。这是 Hasura 最大的优势——给已有项目加 API 只需要几分钟。

## 来源与致谢

- GitHub: [hasura/graphql-engine](https://github.com/hasura/graphql-engine) — 31.9K+ ⭐ | Apache-2.0
- 官网: [hasura.io](https://hasura.io)

---
Source: https://tokrepo.com/en/workflows/caafaa4a-34bf-11f1-9bc6-00163e2b0d79
Author: AI Open Source