Seaography CLI

Relevant source files

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

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

Introduction

Seaography CLI is a command-line utility designed to scaffold ready-to-run GraphQL servers in Rust. It serves as a bridge between database entities (generated by SeaORM) and a functional GraphQL backend, automating the creation of project structures, configuration files, and boilerplate code for various web frameworks.

The CLI works in tandem with the seaography-generator crate to parse existing SeaORM entities and generate a GraphQL schema root, environmental configurations, and the entry point for the chosen web framework. By using this tool, developers can transform a database schema into a fully typed GraphQL API with features like filtering, pagination, and nested relations in minutes.

Sources: README.md:12-25, cli/src/main.rs:114-131

CLI Configuration and Arguments

The CLI utilizes the clap crate to handle command-line arguments and environment variables. It requires specific inputs to locate source entities, define the target output, and configure database connection details.

Command Line Arguments

Argument	Short	Long	Default	Description
output_dir	-o	--output-dir	./	The directory where the new project will be generated.
entities	-e	--entities	N/A	Path to the directory containing SeaORM entity files.
database_url	-u	--database-url	N/A	The connection string for the database (can be set via DATABASE_URL).
crate_name	N/A	N/A	N/A	The name of the generated Rust crate.
framework	-f	--framework	Poem	The web framework to use (Actix, Poem, or Axum).
depth_limit	N/A	--depth-limit	None	Optional limit for GraphQL query depth.
complexity_limit	N/A	--complexity-limit	None	Optional limit for GraphQL query complexity.

Sources: cli/src/main.rs:6-42

Core Architecture and Execution Flow

The CLI acts as a controller that validates user input and invokes the project generator. The process begins with parsing the provided Database URL to determine the appropriate SQL library and validating the existence of mandatory components like hostnames and database names.

Database URL Validation

The parse_database_url function ensures that the provided URL is valid for the supported database types (MySQL, PostgreSQL, and SQLite). For non-SQLite databases, it strictly enforces the presence of a username, host, and database name.

The CLI maps database schemes to specific sqlx libraries: mysql maps to sqlx-mysql, sqlite to sqlx-sqlite, and postgres/postgresql to sqlx-postgres.

Sources: cli/src/main.rs:48-93, cli/src/main.rs:136-143

Project Generation System

The generation logic is primarily located in generator/src/writer.rs. It handles the physical creation of files based on the parsed entities and selected framework.

Query Root Generation

The CLI scans the entities directory to identify SeaORM models. It filters out internal files like mod.rs, prelude.rs, and sea_orm_active_enums.rs to build a clean list of entities for the GraphQL schema. It also detects if active enums are present and automatically includes logic to register them in the schema builder.

Sources: generator/src/writer.rs:13-68

Framework Templates

Seaography CLI supports three primary web frameworks. Each framework has a specific template for the main.rs file:

• Poem: Uses async-graphql-poem for handlers.
• Axum: Uses async-graphql-axum and Axum's state management.
• Actix: Uses async-graphql-actix-web with Actix web resources.

These templates include lazy_static blocks to load configuration from environment variables such as DATABASE_URL, DEPTH_LIMIT, and COMPLEXITY_LIMIT.

Sources: generator/src/templates/poem.rs:13-40, generator/src/templates/axum.rs:13-40, generator/src/templates/actix.rs:14-41

File Writing Components

Component	Responsibility	Relevant Function
Cargo.toml	Generates the manifest with correct dependencies for the framework and SQL driver.	write_cargo_toml
lib.rs	Defines the module structure (entities and query_root).	write_lib
.env	Stores the database URL and commented-out limit configurations.	write_env
query_root.rs	Bridges SeaORM entities with the Seaography Builder.	write_query_root

Sources: generator/src/writer.rs:109-178

Conclusion

Seaography CLI provides an automated workflow for bootstrapping Rust GraphQL servers. By abstracting the complexities of schema registration and framework-specific boilerplate, it allows developers to focus on the data model and business logic while maintaining compatibility with the major asynchronous web frameworks in the Rust ecosystem.

Sources: README.md:12-25, cli/src/main.rs:114-131