Issue Reporting

Relevant source files

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

• README.md
• CHANGELOG.md
• Cargo.toml
• src/mysql/def/system.rs
• tests/live/mysql/src/main.rs

Issue reporting is a critical component of the SeaSchema project, facilitating continuous improvement and maintenance across various SQL dialects including MySQL, MariaDB, PostgreSQL, and SQLite. As a community-driven project, SeaSchema utilizes GitHub for formal tracking of bugs, feature requests, and technical enhancements.

The reporting process ensures that discrepancies in schema discovery or writing are identified, reproduced through live tests, and eventually resolved through public pull requests. Users are encouraged to contribute by reporting issues found during schema mapping or discovery tasks. Formal reports are often supplemented by informal discussions on the community Discord server.

Sources: README.md:16-25, README.md:111-118

Categories of Reports

Issues within SeaSchema are generally classified into four primary categories based on the nature of the feedback or the required development effort.

Bug Reports

These involve correcting erroneous behavior where the library fails to accurately map or discover a database schema. Common examples include failures in discovering unique constraints, incorrect enum ordering, or version-specific discovery issues.

Feature Requests

Requests for new functionality, such as support for specialized data types (e.g., PostgreSQL vector extensions) or new index types.

Enhancements

Improvements to existing logic that do not necessarily fix a "broken" feature but make it more robust or efficient. Examples include improving column default parsing logic for specific engines like MariaDB or SQLite.

Upgrades and Maintenance

Tracking updates for core dependencies like sea-query, sqlx, or the Rust edition itself.

Category	Typical Focus Areas	Documentation Reference
Bug Fixes	Schema discovery, Foreign key ordering, Partitioned table parsing	CHANGELOG.md:12-23
Features	New data types (Vector, JSONB), New Index types	CHANGELOG.md:30-34
Enhancements	Non-TLS runtimes, Improved parsing logic	CHANGELOG.md:52-53
Upgrades	sea-query, sqlx, syn	CHANGELOG.md:37-43

Sources: CHANGELOG.md:12-60

Reporting Workflow

The lifecycle of an issue from discovery to resolution follows a structured path involving reproduction and documentation.

This diagram illustrates the standard flow for reporting and resolving issues within the SeaSchema ecosystem.

Sources: README.md:20-25, CHANGELOG.md:5-10

Technical Requirements for Reports

When reporting issues related to schema discovery, specific technical details regarding the database system are required to ensure accuracy, as different engines (like MySQL vs. MariaDB) require different handling logic.

System Information

Reports should include the target database version and system string. SeaSchema uses a internal SystemInfo structure to manage these details during discovery.

pub struct SystemInfo {
    pub version: u32,
    pub system: String,
    pub suffix: Vec<String>,
}

Sources: src/mysql/def/system.rs:5-12

Reproduction Environment

Reliable reports typically include a reproduction script or a SQL schema snippet. The project uses "live" tests to verify discovery against actual database instances. A standard reproduction environment involves:

1. Schema Definition: A CREATE TABLE statement representing the problematic structure.
2. Discovery Call: Executing SchemaDiscovery::new(connection).discover().
3. Expected vs Actual: Comparing the generated TableDef against the expected output.

Sources: tests/live/mysql/src/main.rs:24-55

Resolution Tracking

Once an issue is reported and a fix is implemented, the resolution is documented in the project's changelog, citing the specific Pull Request (PR) or issue number. This provides a transparent history of community-driven improvements.

Examples of Tracked Resolutions

• Version Specifics: Backward compatible discovery for MySQL 5.6. Sources: CHANGELOG.md:88
• Dialect Differences: Discovering SYSTEM VERSIONED tables for MariaDB. Sources: CHANGELOG.md:96
• Type Mapping: Parsing PostgreSQL citext or array datatypes. Sources: CHANGELOG.md:81-86

The sequence shows how user reports directly influence the changelog through numbered pull requests.

Sources: CHANGELOG.md:10-50

Conclusion

Issue reporting is the primary mechanism for evolving SeaSchema's support for complex SQL schemas. By providing detailed system information and reproduction cases, contributors help maintain high fidelity between live database states and the library's internal definitions. All resolved issues are transparently tracked in the project's history, ensuring that the community remains informed of fixes and new capabilities.

Sources: README.md:111-118, CHANGELOG.md:5-8