Poem Integration
Relevant source files
The following files were used as context for generating this wiki page:
Poem integration in Seaography provides a streamlined way to deploy a GraphQL server using the Poem web framework. It bridges SeaORM entities with async-graphql through the async-graphql-poem crate, allowing developers to serve a fully-functional GraphQL API with minimal configuration. This integration includes support for GraphQL Playground, database connection management, and environment-based configuration for query limits.
The integration is primarily handled by the Seaography generator, which produces the necessary boilerplate code including main.rs, Cargo.toml, and environment files. This allows for rapid development of GraphQL backends that leverage Poem's routing and endpoint capabilities.
Sources: README.md, generator/src/templates/poem.rs:8-66, cli/src/main.rs:105-115
Architecture and Data Flow
The integration follows a standard web server pattern where Poem handles incoming HTTP requests and routes them to specific handlers. The GraphQL handler extracts the schema from the application data and executes the incoming request against the SeaORM-backed database.
Request Handling Flow
The following diagram illustrates how a request moves from the client through the Poem framework to the Seaography schema execution.
The server initialization involves connecting to the database, building the GraphQL schema using the generated query_root, and configuring the Poem Route with shared data.
Sources: examples/sqlite/src/main.rs:44-63, generator/src/templates/poem.rs:50-65
Server Configuration
Poem integration utilizes lazy_static for environment-driven configuration. This ensures that sensitive information like database URLs and performance limits like query depth are loaded once and available globally within the server module.
Environment Variables
| Variable | Description | Default Value |
|---|---|---|
URL | The host and port the server binds to | localhost:8000 |
ENDPOINT | The path for the GraphQL API and Playground | / |
DATABASE_URL | Connection string for the database | (Required) |
DEPTH_LIMIT | Maximum nesting depth allowed for queries | None |
COMPLEXITY_LIMIT | Maximum computational complexity for queries | None |
Sources: generator/src/templates/poem.rs:19-35, generator/src/writer.rs:163-181
Key Components and Handlers
The integration defines specific handlers to manage GraphQL interactions. These are generated as part of the main.rs template for Poem.
GraphQL Playground
The graphql_playground handler serves a web-based IDE for testing queries. It uses playground_source from async-graphql and returns a Poem Html response.
Sources: generator/src/templates/poem.rs:37-40, examples/sqlite/src/main.rs:35-38
GraphQL Execution Handler
The graphql_handler is an asynchronous function that takes the Schema (wrapped in Poem Data) and a GraphQLRequest. It executes the request and returns a GraphQLResponse.
Sources: generator/src/templates/poem.rs:42-46, examples/sqlite/src/main.rs:40-44
Dependencies
The integration requires specific dependencies in the generated Cargo.toml to function correctly.
[dependencies]
poem = { version = "3.0" }
async-graphql-poem = { version = "7.0" }
sea-orm = { version = "~2.0.0-rc", features = ["seaography", ...] }
seaography = { version = "~2.0.0-rc.8", features = ["graphql-playground"] }
Sources: generator/src/templates/poem_cargo.toml:8-20, examples/sqlite/Cargo.toml:7-22
Schema Construction
The schema is constructed via the query_root::schema function, which integrates the SeaORM database connection with the dynamic GraphQL types.
The writer.rs file manages the generation of the query_root.rs file, which is responsible for discovering entities in the provided directory and registering them with the Seaography builder.
Sources: generator/src/writer.rs:15-103, generator/src/writer.rs:105-113
Summary
Poem Integration serves as a robust foundation for building GraphQL APIs in the Seaography ecosystem. By automating the generation of framework-specific boilerplate and leveraging Poem's high-performance routing, it enables developers to move from a database schema to a live API in minutes. The use of environment variables for limits and connection strings ensures the generated project is production-ready and configurable across different environments.
Sources: README.md, generator/src/lib.rs:31-48