Identifiers (Iden)

Identifiers (Iden) are a fundamental abstraction in SeaQuery used to represent database objects such as table names, column names, and index names within SQL statements. The Iden trait provides a unified way to handle these identifiers across different database backends (MySQL, Postgres, and SQLite), ensuring they are correctly quoted and formatted based on the specific dialect being used.

Sources: README.md:213-214, src/lib.rs:374-375

The Iden Trait

The Iden trait is the core component for identifier representation. It typically requires the implementation of the unquoted method, which returns the raw string representation of the identifier. SeaQuery uses this to build the Abstract Syntax Tree (AST) for queries.

Implementation Methods

Identifiers are commonly implemented using Enums or Unit Structs. For Enums, each variant typically represents a specific column or the table itself.

pub trait Iden {
    fn unquoted(&self) -> &str;
    // ... other methods like quoted() which may return Cow<'static, str>
}

Sources: sea-query-derive/src/iden/mod.rs:56-118, src/tests_cfg.rs:30-41

Core Architecture Flow

The following diagram illustrates how an identifier moves from a Rust definition to a formatted SQL string via the Iden trait and a QueryBuilder.

The diagram shows the transformation of a Rust type into a backend-specific quoted identifier.
Sources: README.md:216-231, src/lib.rs:377-392

Iden Derivation and Macros

SeaQuery provides a powerful derive macro and the #[enum_def] attribute to automate the implementation of the Iden trait.

Derive Iden

The #[derive(Iden)] macro automatically converts variant names into snake_case strings by default. It supports customization via the #[iden = "custom_name"] attribute.

Sources: sea-query-derive/src/iden/mod.rs:164-172, tests/derive.rs:24-34

Enum Definition Utility

The #[enum_def] macro is used on structs to generate a corresponding Iden enum automatically. This is useful for maintaining a single source of truth for table schemas.

#[enum_def]
struct Character {
    pub foo: u64,
}
// Generates CharacterIden { Table, Foo }

Sources: sea-query-derive/src/enum_def.rs:7-89, src/lib.rs:396-411

Static Identifiers (IdenStatic)

For performance optimization, SeaQuery includes IdenStatic. This trait is used when identifiers are known at compile time and can be represented as 'static str. The derive macro automatically detects if an identifier is "static-friendly" (starting with [a-z_] and containing only alphanumeric characters or underscores).

The class diagram shows the relationship between standard identifiers and static identifiers.
Sources: sea-query-derive/src/iden/mod.rs:54-94, sea-query-derive/src/enum_def.rs:71-77

Iden in Query Building

Identifiers are utilized throughout the SeaQuery API in methods like .column(), .from_table(), and within Expr::col().

Sources: README.md:310-315, src/lib.rs:471-480, src/tests_cfg.rs:20-80

Example: Manual Implementation

impl Iden for Character {
    fn unquoted(&self) -> &str {
        match self {
            Self::Table => "character",
            Self::Id => "id",
            Self::FontSize => "font_size",
            // ...
        }
    }
}

Sources: src/tests_cfg.rs:30-45

Conclusion

Identifiers in SeaQuery provide a type-safe and backend-agnostic way to reference database entities. Through the use of the Iden trait and its associated derive macros, developers can represent complex database schemas in Rust code while ensuring that the resulting SQL is correctly formatted for MySQL, Postgres, or SQLite.

Sources: README.md:213-240, src/lib.rs:374-411