Introduction and Quick Start

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/lib.rs
• cli/src/main.rs
• generator/src/writer.rs
• CHANGELOG.md
• generator/src/templates/axum.rs
• generator/src/templates/poem.rs
• generator/src/templates/actix.rs

Seaography is a powerful and extensible GraphQL framework for Rust that bridges SeaORM and async-graphql. It facilitates the transformation of database schemas into fully-typed GraphQL APIs with minimal boilerplate by leveraging a dynamic schema engine. This approach avoids heavy code generation, leading to faster compile times while allowing the generated schema to remain in sync with SeaORM entities.

Sources: README.md:16-21, src/lib.rs:16-21

The framework supports multiple database backends including MySQL, PostgreSQL, SQLite, and SQL Server. It also integrates seamlessly with popular Rust web frameworks such as Actix, Axum, and Poem. Seaography provides features like rich type support, relational queries (1-to-1, 1-to-N, M-to-N), diverse pagination methods, and advanced filtering capabilities.

Sources: README.md:29-45, src/lib.rs:29-45

Core Architecture and Data Flow

Seaography functions as a middleware layer between the database ORM (SeaORM) and the GraphQL engine (async-graphql). It utilizes a Builder pattern to construct the GraphQL schema dynamically based on SeaORM entities.

System Integration Flow

The following diagram illustrates how Seaography integrates with the underlying database and the web framework to serve GraphQL requests.

Key Components

Component	Description	Location
Builder	The main engine responsible for creating the dynamic GraphQL schema.	src/lib.rs:271
BuilderContext	Holds configuration and lifecycle hooks for the schema building process.	src/lib.rs:268
seaography-cli	Command-line tool to generate entity-based projects.	cli/src/main.rs:4-70
query_root	The entry point for GraphQL queries, generated per project.	generator/src/writer.rs:11-96

Quick Start Guide

Getting a Seaography project running involves three primary steps: installing dependencies, generating entities from a database, and running the generated GraphQL server.

1. Installation

Install the necessary CLI tools via Cargo:

cargo install sea-orm-cli@^2.0.0-rc
cargo install seaography-cli@^2.0.0-rc

Sources: README.md:73-77, src/lib.rs:73-77

2. Project Generation

The project generation flow involves using sea-orm-cli to inspect the database and seaography-cli to build the GraphQL wrapper.

3. Command Line Interface (CLI) Options

The seaography-cli provides several arguments to customize the generated project:

Argument	Short	Description	Default
--output-dir	-o	Project output directory	./
--entities	-e	Path to the generated SeaORM entities	(Required)
--database-url	-u	Database connection string	(Required)
--framework	-f	Web framework (Actix, Axum, Poem)	Poem
--depth-limit		GraphQL query depth limit	None
--complexity-limit		GraphQL complexity limit	None

Sources: cli/src/main.rs:7-38

Project Structure and Templates

When generating a project, Seaography creates several key files based on the chosen web framework.

Query Root Generation

The query_root.rs file is generated by scanning the entities directory. It registers entities and enumerations into the GraphQL schema.

pub fn schema(
    database: DatabaseConnection,
    depth: Option<usize>,
    complexity: Option<usize>,
) -> Result<Schema, SchemaError> {
    schema_builder(&CONTEXT, database, depth, complexity).finish()
}

Sources: generator/src/writer.rs:77-83

Web Framework Integration

Seaography supports multiple frameworks with specific entry point templates:

• Axum: Uses async_graphql_axum and axum::Router.
• Poem: Uses async_graphql_poem and poem::Route.
• Actix: Uses async_graphql_actix_web and actix_web::App.

Sources: generator/src/templates/axum.rs:11-64, generator/src/templates/poem.rs:11-64, generator/src/templates/actix.rs:11-68

Summary

Seaography enables rapid development of GraphQL APIs by automating the mapping between database entities and GraphQL types. By providing a CLI tool and supporting major Rust web frameworks, it reduces the time to launch a backend to minutes. The framework's architecture ensures that developers can still extend the schema with custom logic, guards, and hooks while benefiting from the speed of dynamic schema generation.

Sources: README.md:16-28, CHANGELOG.md:43-125