JSON Serialization

Relevant source files

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

• README.md
• Cargo.toml
• sea-schema-sync/Cargo.toml
• CHANGELOG.md
• tests/discovery/mysql/Cargo.toml
• tests/discovery/postgres/Cargo.toml
• tests/discovery/mysql/schema.rs

JSON serialization in SeaSchema provides the ability to convert complex database schema definitions—including tables, columns, indexes, and foreign keys—into a machine-readable JSON format. This feature is primarily used to facilitate schema snapshots, debugging, and interoperability between different modules of the SeaQL ecosystem.

The serialization capability is implemented as an optional feature, allowing users to minimize dependency overhead by only including serialization logic when necessary. It leverages the serde framework to provide consistent serialization and deserialization across various database backends including MySQL, PostgreSQL, and SQLite.

Sources: README.md:27-27, CHANGELOG.md:231-231

Feature Configuration

Serialization support is not enabled by default. It is gated behind the with-serde feature flag. When activated, this feature enables the serde dependency with its derive capabilities, applying them to the core type definitions in the def module.

Dependency Management

The project uses a modular approach to dependencies. The serde crate is marked as optional in the core package and the sync-specific package.

Feature Flag	Internal Dependency	Purpose
with-serde	serde (version 1)	Enables Serialize and Deserialize traits on schema definitions.
discovery	parser / query	Enables finding schema info to be serialized.

Sources: Cargo.toml:44-44, Cargo.toml:122-122, sea-schema-sync/Cargo.toml:46-46

Feature Flow

The following diagram illustrates how the with-serde feature enables the serialization path within the library architecture.

This diagram shows the relationship between the feature flag and the activation of JSON capabilities.
Sources: Cargo.toml:122-122, README.md:27-27

Serialized Data Structures

The core structures that are subject to JSON serialization reside in the definition modules. These structures represent a hierarchy from the entire database system down to individual column attributes.

Schema Hierarchy

A full database schema is represented by a Schema object, which serves as the root for serialization.

• SystemInfo: Contains database version and system details.
• TableDef: Encapsulates table metadata (TableInfo), columns, indexes, and foreign keys.
• ColumnInfo: Details the column name, type (e.g., SmallInt, Varchar), nullability, and default values.
• IndexInfo: Describes index types (BTree, FullText, Spatial) and the specific column parts involved.
• ForeignKeyInfo: Maps relationships between tables and defines referential integrity actions like Cascade or Restrict.

Sources: tests/discovery/mysql/schema.rs:1-1271

Data Relationship Diagram

The hierarchy of serialized objects follows a tree structure as seen in discovery results:

This diagram represents the logical structure of the schema data that SeaSchema produces and serializes.
Sources: README.md:43-143, tests/discovery/mysql/schema.rs:1-1271

Testing and Validation

The project extensively uses JSON serialization in its test suites, particularly within the discovery modules for MySQL, PostgreSQL, and SQLite.

• Discovery Verification: Tests often run discovery against a live database, serialize the resulting Schema object, and compare it against expected output to ensure accuracy.
• Integration with serde_json: Testing packages specifically include serde_json as a dependency to perform these validations.

Test Category	File Path	Usage
MySQL Discovery	tests/discovery/mysql/Cargo.toml	Uses with-serde and serde_json for discovery output validation.
Postgres Discovery	tests/discovery/postgres/Cargo.toml	Uses with-serde and serde_json for discovery output validation.
SQLite Discovery	tests/discovery/sqlite/Cargo.toml	Uses with-serde and serde_json for discovery output validation.

Sources: tests/discovery/mysql/Cargo.toml:12-13, tests/discovery/postgres/Cargo.toml:12-13, tests/discovery/sqlite/Cargo.toml:12-13

Historical Context

The capability for JSON serialization was introduced early in the project's development. According to the changelog, serde support was officially added to the type definitions in version 0.1.4. Since then, it has been maintained alongside the evolving database definitions for MySQL and PostgreSQL.

Sources: CHANGELOG.md:231-231

Conclusion

JSON Serialization in SeaSchema is a critical utility for schema management, enabled through the with-serde feature. By deriving Serialize and Deserialize on core schema definitions, SeaSchema allows developers to treat complex database structures as portable data. This facilitates advanced workflows like schema snapshotting, automated testing via JSON comparison, and simplified debugging across different database environments.