busya
2ffc3cc68f
- Add SQLite database integration for environments and mappings - Update TaskManager to support pausing tasks (AWAITING_MAPPING) - Modify MigrationPlugin to detect missing mappings and wait for resolution - Add frontend UI for handling missing mappings interactively - Create dedicated migration routes and API endpoints - Update .gitignore and project documentation
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# Database Mapping in Migration
|
|
|
|
This document describes how to use the database mapping feature during Superset dashboard migrations.
|
|
|
|
## Overview
|
|
|
|
When migrating dashboards between different Superset environments (e.g., from Dev to Prod), the underlying databases often have different UUIDs even if they represent the same data source. The Database Mapping feature allows you to define these relationships so that migrated assets automatically point to the correct database in the target environment.
|
|
|
|
## How it Works
|
|
|
|
1. **Fuzzy Matching**: The system automatically suggests mappings by comparing database names between environments using the RapidFuzz library.
|
|
2. **Persistence**: Mappings are stored in a local SQLite database (`mappings.db`) and are reused for future migrations between the same environment pair.
|
|
3. **Asset Interception**: During migration, the system intercepts the Superset export ZIP archive, modifies the `database_uuid` in the dataset YAML files, and re-packages the archive before importing it to the target.
|
|
|
|
## Usage Instructions
|
|
|
|
### 1. Define Mappings
|
|
|
|
1. Navigate to the **Database Mapping** tab in the application.
|
|
2. Select your **Source** and **Target** environments.
|
|
3. Click **Fetch Databases & Suggestions**.
|
|
4. Review the suggested mappings (highlighted in green).
|
|
5. If a suggestion is incorrect or missing, use the dropdown in the "Target Database" column to select the correct one.
|
|
6. Mappings are saved automatically when you select a target database.
|
|
|
|
### 2. Run Migration with Database Replacement
|
|
|
|
1. Go to the **Migration** dashboard.
|
|
2. Select the **Source** and **Target** environments.
|
|
3. Select the dashboards or datasets you want to migrate.
|
|
4. Enable the **Replace Database (Apply Mappings)** toggle.
|
|
5. Click **Start Migration**.
|
|
|
|
### 3. Handling Missing Mappings
|
|
|
|
If the migration engine encounters a database that has no defined mapping, the process will pause, and a modal will appear prompting you to select a target database on-the-fly. Once selected, the mapping is saved, and the migration continues.
|
|
|
|
## Troubleshooting
|
|
|
|
- **Mapping not applied**: Ensure the "Replace Database" toggle is enabled.
|
|
- **Wrong database in target**: Check the mapping table for the specific environment pair and correct any errors.
|
|
- **Connection errors**: Ensure both Superset environments are reachable and credentials are correct in Settings.
|