Getting Started

Relevant source files

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

• README.md
• Cargo.toml
• CHANGELOG.md
• src/lib.rs
• tests/live/mysql/src/main.rs
• sea-schema-sync/Cargo.toml

SeaSchema is a comprehensive library designed to manage database schemas for MySQL, Postgres, and SQLite within the Rust ecosystem. It serves two primary purposes: providing detailed type definitions that map closely to database-specific structures and offering robust utilities to discover existing schemas from live database connections.

The library is built to integrate seamlessly with the SeaQL ecosystem, particularly sea-query, allowing developers to transition from raw database inspection to programmatic SQL manipulation. It supports both asynchronous operations (default) and synchronous operations via the sea-schema-sync crate.

Sources: README.md:16-20, Cargo.toml:1-40, src/lib.rs:1-35

Installation and Configuration

To begin using SeaSchema, add it to your Cargo.toml. The crate is highly modular, allowing you to enable only the database backends and features necessary for your project.

Dependency Setup

[dependencies]
sea-schema = { version = "0.18.0", features = ["mysql", "discovery", "writer"] }

Sources: Cargo.toml:15-25, CHANGELOG.md:7-12

Feature Flags

SeaSchema uses features to manage dependencies like sqlx and specific database drivers.

Feature	Description
mysql	Enables MySQL database support and types.
postgres	Enables PostgreSQL database support and types.
sqlite	Enables SQLite database support and types.
discovery	Enables tools to inspect a live database and generate a Schema.
writer	Enables exporting discovered schemas into SeaQuery statements.
sqlx-mysql	Bundles sqlx with MySQL driver for discovery.
runtime-tokio	Uses the Tokio runtime for asynchronous operations.

Sources: Cargo.toml:35-95, sea-schema-sync/Cargo.toml:40-60

Architecture Overview

The project is structured into distinct modules that handle different stages of the schema management lifecycle.

Module Structure

• def: Contains the core type definitions (e.g., TableDef, ColumnInfo, IndexInfo) that represent the database schema.
• query / parser: Internal logic used to query and interpret the information_schema of the target database.
• discovery: The entry point for connecting to a live database and generating a Schema object.
• writer: Logic for converting a Schema or TableDef back into SQL via sea-query.
• probe: A utility for checking database capabilities or existence of specific objects (e.g., has_table, has_index).

Sources: README.md:25-31, src/lib.rs:1-35, CHANGELOG.md:130-140

System Workflow

The following diagram illustrates the flow from a live database to generated SQL statements using SeaSchema.

This diagram shows how SeaSchema acts as a bridge between a running database instance and programmatic schema definitions.
Sources: README.md:25-31, tests/live/mysql/src/main.rs:48-75

Schema Discovery

Schema discovery is the process of inspecting an existing database to create a Rust representation of its structure.

Discovery Process

To discover a schema, you typically initialize a SchemaDiscovery object for your specific database backend, providing a database connection.

// Example for MySQL Discovery
let schema_discovery = SchemaDiscovery::new(connection, "my_database");
let schema = schema_discovery.discover().await.expect("Discovery failed");

Sequence of Discovery

This sequence represents the communication between the library and the database engine to reconstruct the schema.
Sources: tests/live/mysql/src/main.rs:48-54, README.md:33-40

Writing and Exporting Schemas

Once a schema is discovered or manually defined using def types, the writer module can convert these structures into sea-query statements or raw SQL.

Example: Discovery to SQL

The library allows for a full round-trip: discovering a table, and then writing it back to a SQL string.

// Discover the table
let table = schema.tables.iter().find(|t| t.info.name == "my_table").unwrap();

// Convert back to SeaQuery statement
let create_stmt = table.write();

// Convert to SQL string for a specific backend
let sql = create_stmt.to_string(MysqlQueryBuilder);

Sources: tests/live/mysql/src/main.rs:65-72, README.md:110-150

Data Mapping

SeaSchema maps database-specific types to high-level Rust enums. Below is a summary of how complex types are handled across backends.

Component	Description	Sources
NumericAttr	Handles maximum, decimal precision, and unsigned attributes.	README.md:65-75
ColumnExtra	Captures auto-increment, generated, and "on update current timestamp" flags.	README.md:76-85
IndexInfo	Represents unique constraints, index types (BTree, Spatial), and index parts.	README.md:120-140
ForeignKeyInfo	Maps relationships including on_update and on_delete actions.	README.md:145-155

Summary

SeaSchema provides a structured way to handle SQL schemas by mirroring database internals in Rust types. By utilizing the discovery and writer modules, developers can automate schema migrations, generate documentation, or build dynamic database tools while supporting MySQL, Postgres, and SQLite backends.

Sources: README.md:16-31, CHANGELOG.md:7-15