Database Support and Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Database Support and Configuration in SeaORM Pro encompasses the multi-backend driver management, environment-based connection strings, and the structured configuration of admin panel interfaces. The system leverages SeaORM's asynchronous capabilities to support MySQL, PostgreSQL, and SQLite, while providing a specialized helper library (sea-orm-pro) to map database entities to administrative views.
The configuration flow begins with environment variables defining the DATABASE_URL, followed by feature-flagged backend selection in Cargo.toml, and finally detailed UI-level table configurations defined in TOML files. This ensures a decoupling between the physical database layer and the logical administrative representation.
Sources: README.md:1-20, sea-orm-pro/Cargo.toml:1-25, Cargo.toml:50-55
Backend Driver Support
SeaORM Pro supports multiple relational database backends through Cargo features. These features enable the specific SQLx drivers required for connection and query execution.
Supported Database Engines
The project provides built-in support for the following database engines:
| Engine | Cargo Feature | Description |
|---|---|---|
| SQLite | sqlx-sqlite | Default database engine for development and demos. |
| MySQL | sqlx-mysql | Support for MySQL backends via SeaORM. |
| PostgreSQL | sqlx-postgres | Support for PostgreSQL backends via SeaORM. |
Sources: README.md:11-17, Cargo.toml:50-55
Connection Lifecycle
The application initializes database connections during the server startup phase, typically utilizing an asynchronous Database::connect call with a URI retrieved from environment variables.
The diagram shows the initialization flow from environment variables through the selected SQLx driver to server startup.
Sources: examples/axum_example/api/src/lib.rs:40-50, README.md:6-10
Connection Configuration
Database connections are managed via YAML configuration files (for Loco-rs based setups) and .env files.
Database Settings (Loco-rs)
The framework provides granular control over connection pooling and timeouts within the database block of configuration files.
| Option | Type | Description |
|---|---|---|
uri | String | Connection string (e.g., sqlite://db.sqlite). |
max_connections | Integer | Maximum number of connections in the pool. |
min_connections | Integer | Minimum number of connections for the pool. |
connect_timeout | Integer | Timeout for acquiring a connection (ms). |
auto_migrate | Boolean | Automatically run migrations on startup. |
Sources: config/development.yaml:94-115
Environment Variables
The DATABASE_URL is the primary mechanism for switching between database types without modifying code.
# Examples of connection strings supported
DATABASE_URL="mysql://root:root@localhost/db_name"
DATABASE_URL="postgres://root:root@localhost/db_name"
DATABASE_URL="sqlite://db.sqlite?mode=rwc"
Sources: README.md:6-10
Admin Panel Schema Mapping
The sea-orm-pro crate introduces a specialized configuration layer to map database tables to administrative interfaces. This configuration is split into "Raw Tables" (direct entity mapping) and "Composite Tables" (complex relational views).
Data Structure Architecture
The configuration is parsed into a JsonCfg structure which defines how the UI interacts with the underlying database schema.
The class diagram represents the hierarchical structure of the admin panel configuration used to define table behaviors.
Sources: sea-orm-pro/src/config.rs:6-20, sea-orm-pro/src/config.rs:136-150
Table Behavior Configuration
For every database entity, the system allows configuring CRUD permissions and visibility:
- Visibility:
hidden_columnsinTableCfgallows excluding sensitive fields from the list view. - Editing:
EditorCfgandUpdateCfgdefine which fields are editable or read-only. - Actions:
CreateCfgandDeleteCfgenable or disable specific database operations for the table.
Sources: sea-orm-pro/src/config.rs:156-160, sea-orm-pro/src/config.rs:250-280
Data Initialization and Seeding
SeaORM Pro includes a dedicated task system for seeding the database with initial data, particularly useful for development environments.
The Seed Task
The SeedData task implements logic to read data from external files (e.g., .tsv or .csv) and perform batch inserts into the database.
- Migration: Runs migrations before seeding to ensure the schema is current.
- Transcoding: Supports multiple encodings (UTF-16LE, Windows-1252) for legacy data files.
- Chunked Insertion: Inserts data in chunks (e.g., 100 records) to optimize database performance.
The sequence diagram illustrates the automated data seeding process triggered via the CLI.
Sources: src/tasks/seed.rs:45-80
Summary
Database support in SeaORM Pro is designed for flexibility and ease of administrative setup. By combining SeaORM's robust ORM capabilities with a custom configuration parser, the system allows developers to define a database connection via environment variables, enable the appropriate backend drivers through features, and fine-tune the administrative UI's interaction with the schema using structured TOML configuration. This architecture facilitates rapid development while maintaining strict control over database operations.