ss-tools/specs/001-migration-ui-redesign/quickstart.md

Quickstart: Migration Process and UI Redesign

Setup

1. Install Dependencies:

   pip install rapidfuzz sqlalchemy
   cd frontend && npm install
   

2. Configure Environments: Ensure you have at least two Superset environments configured in the application settings.

3. Initialize Database: The system will automatically create the mappings.db SQLite file on the first run.

Usage

1. Define Mappings

1. Navigate to the Database Mapping tab.
2. Select your Source and Target environments.
3. Click Fetch Databases.
4. Review the Suggested Mappings (highlighted in green).
5. Manually adjust any mappings using the dropdowns.
6. Click Save Mappings.

2. Run Migration

1. Go to the Migration dashboard.
2. Select the Source and Target environments.
3. Select the assets (Dashboards/Datasets) you want to migrate.
4. Enable the Replace Database toggle.
5. Click Start Migration.
6. If a database is missing a mapping, a modal will appear prompting you to select a target database.

Troubleshooting

• Connection Error: Ensure the backend can reach both Superset instances. Check credentials in settings.
• Mapping Not Applied: Verify that the "Replace Database" toggle was enabled and that the mapping exists for the specific environment pair.
• Fuzzy Match Failure: If names are too different, manual mapping is required. The system learns from manual overrides.