Seaography

Introduction

Seaography is a powerful and extensible GraphQL framework for Rust that bridges SeaORM and async-graphql, turning your database schema into a fully-typed GraphQL API with minimal effort. By leveraging async-graphql's dynamic schema engine, Seaography avoids the heavy code generation of static approaches, resulting in faster compile times. The generated schema stays in sync with your SeaORM entities, while still giving you full control to extend and customize it.

With Seaography you can focus on application logic instead of boilerplate. It enables you to:

• Expose a complete GraphQL schema directly from your SeaORM entities, including filters, pagination, and nested relations
• Use derive macros to define custom input/output objects, queries, and mutations, and seamlessly mix them with SeaORM models
• Generate ready-to-run GraphQL servers via the included CLI, supporting different web frameworks out of the box
• Use RBAC, guards, and lifecycle hooks to implement authorization and custom business logic

Supported technologies

Databases

Seaography is built on top of SeaORM, so it supports:

• MySQL, PostgreSQL and SQLite
• SQL Server (via SeaORM X)

Web framework

It's easy to integrate Seaography with any web framework, and we ship with the following examples out-of-the-box:

• Actix, Axum, Poem
• Loco (SeaORM), Loco (SeaORM Pro)

SeaORM Version Compatibility

Seaography	SeaORM
2.0	2.0
1.1	1.1

Features

• Rich types support (e.g. DateTime, Decimal)
• Relational query (1-to-1, 1-to-N, M-to-N)
• Offset-based and cursor-based pagination
• Filtering with operators (e.g. gt, lt, eq)
• Filter by related entities
• Order by any column
• Mutations (create, update, delete)
• Guards and Filters on entity to restrict access
• Choose between camel or snake case field names

Extensible

Seaography is also completely extensible. It offers:

• Extensive configuration options in schema builder
• Lifecycle hooks for custom resolver logic
• Add custom queries & mutations with derive macros

Quick start - ready to serve in 3 minutes!

Install

cargo install sea-orm-cli@^2.0.0-rc # used to generate entities
cargo install seaography-cli@^2.0.0-rc

MySQL

Setup the sakila sample database. Then regenerate example project like below, or simply do cargo run.

cd examples/mysql
sea-orm-cli generate entity -o src/entities -u mysql://user:[email protected]/sakila --seaography
seaography-cli -o ./ -e src/entities -u mysql://user:[email protected]/sakila seaography-mysql-example
cargo run

Postgres

Setup the sakila sample database. Then regenerate example project like below, or simply do cargo run.

cd examples/postgres
sea-orm-cli generate entity -o src/entities -u postgres://user:pw@localhost/sakila --seaography
seaography-cli -o ./ -e src/entities -u postgres://user:pw@localhost/sakila seaography-postgres-example
cargo run

SQLite

sakila.db is shipped with this repository. You don't have to setup anything, simply do cargo run.

cd examples/sqlite
sea-orm-cli generate entity -o src/entities -u sqlite://sakila.db --seaography
seaography-cli -o ./ -e src/entities -u sqlite://sakila.db seaography-sqlite-example
cargo run

Quick Demo

Go to http://localhost:8000/ and try out the following queries:

Fetch films and their actors

{
  film(pagination: { page: { limit: 10, page: 0 } }, orderBy: { title: ASC }) {
    nodes {
      title
      description
      releaseYear
      actor {
        nodes {
          firstName
          lastName
        }
      }
    }
  }
}

Fetch store and its employee

{
  store(filters: { storeId: { eq: 1 } }) {
    nodes {
      storeId
      address {
        address
        address2
      }
      staff {
        firstName
        lastName
      }
    }
  }
}

Fetch inactive customers with pagination

{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { page: { page: 2, limit: 3 } }
  ) {
    nodes {
      customerId
      lastName
      email
    }
    paginationInfo {
      pages
      current
    }
  }
}

The query above using cursor pagination

{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { cursor: { limit: 3, cursor: "Int[3]:271" } }
  ) {
    nodes {
      customerId
      lastName
      email
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      endCursor
    }
  }
}

Complex query with filters on relations

Find all inactive customers, include their address, and their payments with amount greater than 7 ordered by amount the second result

{
  customer(
    filters: { active: { eq: 0 } }
    pagination: { cursor: { limit: 3, cursor: "Int[3]:271" } }
  ) {
    nodes {
      customerId
      lastName
      email
      address {
        address
      }
      payment(
        filters: { amount: { gt: "7" } }
        orderBy: { amount: ASC }
        pagination: { page: { limit: 1, page: 1 } }
      ) {
        nodes {
          paymentId
          amount
        }
        paginationInfo {
          pages
          current
        }
        pageInfo {
          hasPreviousPage
          hasNextPage
        }
      }
    }
    pageInfo {
      hasPreviousPage
      hasNextPage
      endCursor
    }
  }
}

Filter using MySQL / Postgres enum

{
  film(
    filters: { rating: { eq: NC17 } }
    pagination: { page: { page: 1, limit: 5 } }
  ) {
    nodes {
      filmId
      title
      rating
    }
  }
}

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

We invite you to participate, contribute and together help build Rust's future.

Mascot

A friend of Ferris, Terres the hermit crab is the official mascot of SeaORM. His hobby is collecting shells.