ss-tools/specs/001-migration-ui-redesign/data-model.md

Data Model: Migration Process and UI Redesign

Entities

Environment

Represents a Superset instance.

Field	Type	Description
id	UUID	Primary Key
name	String	Display name (e.g., "Development", "Production")
url	String	Base URL of the Superset instance
credentials_id	String	Reference to encrypted credentials in the config manager

DatabaseMapping

Represents a mapping between a database in the source environment and a database in the target environment.

Field	Type	Description
id	UUID	Primary Key
source_env_id	UUID	Foreign Key to Environment (Source)
target_env_id	UUID	Foreign Key to Environment (Target)
source_db_uuid	String	UUID of the database in the source environment
target_db_uuid	String	UUID of the database in the target environment
source_db_name	String	Name of the database in the source environment (for UI)
target_db_name	String	Name of the database in the target environment (for UI)
engine	String	Database engine type (e.g., "clickhouse", "postgres")

MigrationJob

Represents a single migration execution.

Field	Type	Description
id	UUID	Primary Key
source_env_id	UUID	Foreign Key to Environment
target_env_id	UUID	Foreign Key to Environment
status	Enum	PENDING, RUNNING, COMPLETED, FAILED, AWAITING_MAPPING
replace_db	Boolean	Whether to apply database mappings
created_at	DateTime	Timestamp of creation

Relationships

• DatabaseMapping belongs to a pair of Environments.
• MigrationJob references two Environments.

Validation Rules

• source_env_id and target_env_id must be different.
• source_db_uuid and target_db_uuid must belong to databases with compatible engines (optional warning).
• Mappings must be unique for a given (source_env_id, target_env_id, source_db_uuid) triplet.