Database Enums Integration

Relevant source files

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

• src/builder.rs
• generator/src/writer.rs
• macros/src/custom_output_type.rs
• examples/sea-draw/src/schema.rs
• CHANGELOG.md
• src/lib.rs

Introduction

Database Enums Integration in Seaography provides a seamless bridge between SeaORM ActiveEnum types and async-graphql dynamic enumerations. This system allows developers to expose native database enums (such as those in MySQL or PostgreSQL) directly through a GraphQL API, complete with type safety and filtering capabilities. By automating the registration and mapping of these types, Seaography ensures that the GraphQL schema accurately reflects the allowed values defined in the underlying database.

The integration supports both standard SeaORM active enums and custom enumeration types defined within the application logic. It handles the complexities of converting database values into GraphQL enum symbols and provides specialized input objects for filtering queries based on these enum values.

Sources: src/builder.rs:218-240, README.md:144-155

Architecture and Components

The integration is primarily managed through the Builder and several specialized helper macros and structs. The architecture is designed to recursively register enums found in the entity definitions.

Key Components

Component	Description
ActiveEnumBuilder	Responsible for converting a SeaORM ActiveEnum into an async-graphql Enum object.
ActiveEnumFilterInputBuilder	Generates the InputObject used for filtering columns that use enums (e.g., eq, ne, in, not_in).
register_active_enums!	A macro used in the generated query_root.rs to batch register all active enums in a project.
impl_custom_type_for_enum!	A macro that implements both CustomOutputType and CustomInputType for a given enum.

Sources: src/builder.rs:218-240, src/builder.rs:509-515, src/builder.rs:438-472

Registration Workflow

The following diagram illustrates the process of registering an enum within the Seaography Builder:

The registration process ensures that for every enum, both its output representation and its filtering input representation are added to the schema.
Sources: src/builder.rs:218-240

Implementation Details

Enum Registration in the Schema Builder

The Builder::register_enumeration method is the core entry point for integrating SeaORM enums. It utilizes the ActiveEnum trait to inspect variants and metadata.

pub fn register_enumeration<A>(&mut self)
where
    A: ActiveEnum,
{
    let active_enum_builder = ActiveEnumBuilder {
        context: self.context,
    };
    let active_enum_filter_input_builder = ActiveEnumFilterInputBuilder {
        context: self.context,
    };
    let filter_types_map_helper = FilterTypesMapHelper {
        context: self.context,
    };

    let enumeration = active_enum_builder.enumeration::<A>();
    self.enumerations.push(enumeration);

    let filter_info = active_enum_filter_input_builder.filter_info::<A>();
    self.inputs
        .push(filter_types_map_helper.generate_filter_input(&filter_info));
}

Sources: src/builder.rs:218-240

Custom Enum Support

Beyond standard database enums, Seaography supports CustomEnum types which can be registered manually or via macros. This is useful for application-level enums that are not necessarily tied to a SeaORM active enum but need to be exposed in the GraphQL schema.

Automated Generation

The Seaography generator automatically detects enums by looking for a specific file named sea_orm_active_enums.rs within the entities directory. If found, it inserts the register_active_enums call into the generated schema_builder.

let enumerations = std::fs::read_dir(entities_path)
    .unwrap()
    .filter(|r| r.is_ok())
    .map(|r| r.unwrap().path())
    .find(|r| {
        let name = r.file_stem();
        if let Some(v) = name {
            v.eq(std::ffi::OsStr::new("sea_orm_active_enums"))
        } else {
            false
        }
    });

let enumerations = if enumerations.is_some() {
    quote!(builder = register_active_enums(builder);)
} else {
    quote!()
};

Sources: generator/src/writer.rs:56-85

Filtering and Operations

Enum columns support a specific set of filtering operations. When an enum is registered, Seaography creates a filter input that allows users to query entities based on these types.

Operation	Description
eq	Matches the exact enum variant.
ne	Matches any variant except the one provided.
in	Matches any variant within a provided list.
not_in	Matches any variant not within a provided list.

In the GraphQL schema, these appear as valid symbols rather than strings, ensuring that only valid variants defined in the database/model can be passed as arguments.
Sources: CHANGELOG.md:144-155, src/builder.rs:238-240

Summary

The Database Enums Integration is a critical component of Seaography that ensures strict type safety between the database and the GraphQL layer. By leveraging SeaORM's ActiveEnum trait and the Builder's dynamic registration system, the framework automates the creation of GraphQL Enum types and their corresponding filter inputs. This allows for complex queries, such as filtering films by rating (NC17, PG13, etc.), to be handled natively and efficiently.

Sources: src/builder.rs:218-240, src/lib.rs:210-222