SchemaProbe Implementation

Relevant source files

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

• src/probe.rs
• sea-schema-sync/src/probe.rs
• src/lib.rs
• sea-schema-sync/src/lib.rs
• Cargo.toml
• CHANGELOG.md

Introduction

The SchemaProbe trait is a core component of the SeaSchema library designed to provide a unified interface for querying database metadata across different SQL backends. Its primary purpose is to generate sea-query ASTs (Abstract Syntax Trees) that verify the existence of specific database objects such as tables, columns, and indexes. This feature is essential for dynamic schema inspection and conditional migrations.
Sources: README.md, src/probe.rs:3-5, CHANGELOG.md:139-140

SchemaProbe replaces the legacy migration system in SeaSchema versions 0.8.0 and above, offering a more declarative approach to schema discovery. It integrates directly with the library's discovery and query modules to map live database states into Rust type definitions.
Sources: CHANGELOG.md:181, src/lib.rs:26-27

Architecture and Core Components

The SchemaProbe Trait

The SchemaProbe trait defines a set of methods that backends must implement to facilitate schema inspection. It leverages sea-query to build SelectStatement objects that can be executed against a database connection.
Sources: src/probe.rs:3-50

Key Methods

Method	Return Type	Description
get_current_schema()	SimpleExpr	Returns an expression representing the current active database schema.
query_tables()	SelectStatement	Generates a query to list all tables in the current schema.
has_table(table)	SelectStatement	Checks if a specific table exists.
has_column(table, column)	SelectStatement	Checks if a specific column exists within a given table.
has_index(table, index)	SelectStatement	Checks if a specific index exists on a given table.
Sources: src/probe.rs:4-48, CHANGELOG.md:94-101

Internal Identifiers

To construct database-agnostic queries, the module uses several internal enums that implement the Iden trait. These map Rust variants to the specific SQL identifiers required by information_schema.
Sources: src/probe.rs:52-73

The diagram above illustrates the relationship between the main trait and the supporting identifier enums used for query construction.
Sources: src/probe.rs:3-73

Query Logic and Data Flow

Table and Column Existence Checks

The default implementations for has_table and has_column use subqueries and joins against the information_schema.columns view. The logic follows a standard flow:

1. Selection: The query selects a boolean expression (e.g., COUNT(*) > 0).
2. Filtering: Conditions are added to match the table name, column name, and the current schema retrieved via get_current_schema().
3. Alias: The result is aliased using the Has enum (e.g., has_table or has_column).
   Sources: src/probe.rs:7-41

The flowchart describes the logical steps taken by the has_column implementation to build a valid SQL check.
Sources: src/probe.rs:26-41

Backend Specialization

While has_table and has_column have default implementations, has_index is frequently backend-specific because index metadata storage varies significantly between MySQL, PostgreSQL, and SQLite. These backends implement the SchemaProbe trait to provide the correct metadata queries for their respective engines.
Sources: src/probe.rs:44-48, src/lib.rs:4-14

Feature Integration

The SchemaProbe implementation is gated behind the probe feature. It is designed to work in both asynchronous (sqlx) and synchronous (rusqlite) environments, depending on the crate's configuration.
Sources: Cargo.toml:39, src/lib.rs:26-27, sea-schema-sync/src/lib.rs:29-30

Feature Dependencies

Feature	Dependency	Purpose
probe	query	Enables the SchemaProbe trait and AST construction.
query	def	Provides type definitions for database objects.
sqlx-dep	sqlx	Async database driver support for probing.
rusqlite	rusqlite	Synchronous SQLite driver support.
Sources: Cargo.toml:44-50, sea-schema-sync/Cargo.toml:41-43

Conclusion

The SchemaProbe implementation provides a robust mechanism for runtime database introspection. By abstracting the complexities of information_schema and backend-specific metadata tables into a unified trait, it allows the SeaSchema library to provide reliable schema discovery and conditional SQL generation. This implementation is a critical prerequisite for the library's ability to sync and write database schemas across different SQL dialects.
Sources: README.md, src/probe.rs, CHANGELOG.md:181