Axum Integration

Relevant source files

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

• generator/src/templates/axum.rs
• generator/src/templates/axum_cargo.toml
• examples/postgres/Cargo.toml
• examples/sea-draw/src/schema.rs
• cli/src/main.rs
• generator/src/writer.rs
• src/lib.rs

Seaography provides native support for the Axum web framework, allowing developers to quickly deploy GraphQL backends built on top of SeaORM. This integration is facilitated through the seaography-cli, which can generate a complete Axum project structure, and the async-graphql-axum bridge, which handles the communication between Axum's routing and the dynamic GraphQL schema engine.

Sources: src/lib.rs:43-46, cli/src/main.rs:136-138

System Architecture

The Axum integration functions as a delivery layer for the Seaography engine. The architecture follows a standard web-server pattern where Axum routes incoming HTTP requests to specific handlers that interact with the generated GraphQL schema.

Data Flow Overview

When an Axum-based Seaography server receives a request, it follows this processing path:

1. Axum Router: Receives the HTTP POST/GET request.
2. State Extraction: Extracts the async_graphql::dynamic::Schema from the application state.
3. GraphQL Handler: Converts the Axum request into a GraphQLRequest and executes it against the schema.
4. Database Interaction: The schema resolvers use the DatabaseConnection (provided during schema initialization) to query the underlying database.

The diagram shows the request-response lifecycle within an Axum-integrated Seaography application.
Sources: generator/src/templates/axum.rs:41-68, examples/sea-draw/src/schema.rs:356-373

Core Components

The Axum integration consists of several key functional parts defined in the project templates and examples.

1. GraphQL Handlers

Axum utilizes specific asynchronous functions to process GraphQL queries and the interactive playground.

• graphql_handler: Accepts State<Schema> and GraphQLRequest, executes the query, and returns a GraphQLResponse.
• graphql_playground: Returns an HTML response containing the GraphQL Playground UI configured to point to the server's endpoint.

Sources: generator/src/templates/axum.rs:41-48

2. Project Configuration

Projects using Axum integration require specific dependencies in their Cargo.toml.

Dependency	Purpose
axum	The core web framework (version 0.8)
async-graphql-axum	The bridge between Axum and async-graphql
tokio	The async runtime for Axum
sea-orm	Database ORM with seaography feature enabled

Sources: generator/src/templates/axum_cargo.toml:7-17, examples/postgres/Cargo.toml:7-17

Server Configuration and Startup

The generated Axum server uses environment variables for runtime configuration, typically managed via a .env file.

Environment Variables

Axum-based projects look for the following variables during the main function execution:

Variable	Default Value	Description
URL	localhost:8000	The host and port the server binds to
ENDPOINT	/	The URL path for the GraphQL API and Playground
DATABASE_URL	(Required)	The connection string for the database
DEPTH_LIMIT	None	Optional limit on GraphQL query depth
COMPLEXITY_LIMIT	None	Optional limit on GraphQL query complexity

Sources: generator/src/templates/axum.rs:27-39, generator/src/writer.rs:163-172

Initialization Logic

The server initialization involves connecting to the database and creating the shared schema state.

#[tokio::main]
async fn main() {
    dotenv().ok();
    let db = Database::connect(&*DATABASE_URL).await.expect("Fail to initialize database connection");
    let schema = crate_name::query_root::schema(db, *DEPTH_LIMIT, *COMPLEXITY_LIMIT).unwrap();
    let app = Router::new()
        .route(&*ENDPOINT, get(graphql_playground).post(graphql_handler))
        .with_state(schema);
    axum::serve(TcpListener::bind(&*URL).await.unwrap(), app).await.unwrap();
}

Sources: generator/src/templates/axum.rs:51-68

Advanced Usage: Header and Metadata Extraction

In complex scenarios, such as the sea-draw example, Axum's HeaderMap and Extension layers are used to extract authentication tokens or shared application backends before executing the GraphQL query. This allows for implementing Row-Level Security (RLS) or RBAC by inserting custom data into the GraphQLRequest context.

This sequence illustrates how Axum-specific types (HeaderMap) are used to enrich the GraphQL context for authorization.
Sources: examples/sea-draw/src/schema.rs:344-373

Conclusion

Axum integration provides a robust, production-ready environment for Seaography applications. By combining Axum's performant routing with Seaography's dynamic schema generation, developers can move from database schema to a served GraphQL API with minimal boilerplate, while retaining the ability to customize the server's behavior through Axum's middleware and state management systems.