Sync Metadata
A beginner-friendly guide to keeping your database metadata up-to-date inside Anansi — without starting from scratch.
What Is Metadata Sync?
Once you've imported your database metadata into Anansi for the first time, your database will keep changing over time — new tables get added, columns get renamed, schemas get updated. Metadata Sync keeps Anansi in step with those changes.
Think of it this way:
Import = First time you bring your database structure into Anansi
Sync = Keeping that structure up-to-date as your database evolves
When you sync, Anansi connects to your database again and updates the existing metadata inside a catalog you've already set up — without creating a new catalog or losing your existing lineage configurations.
Video Walkthrough
Watch the full walkthrough on YouTube: https://youtu.be/jdh_hyiWckY
Architectural Flow Diagram
Image shows the architecture of the Database Sync process.
Import vs. Sync: What's the Difference?
| Import | Sync | |
|---|---|---|
| When to use | First-time database onboarding | Database structure has changed |
| Catalog | Can create a new catalog or use an existing one | Must use an existing catalog |
| Node Names | You define or select node type names | You select from existing node types |
| Existing data | Populates a fresh catalog | Updates data inside an existing catalog |
Getting Started
How to Access the Sync Metadata Page
From the Dashboard, look for the Data Integration card. Click the dropdown button and select "Sync Metadata".
You will be taken to a 3-step wizard that guides you through the process.
The Three-Step Wizard
The Sync flow is split into three steps:
| Step | Name | What You Do |
|---|---|---|
| 1 | Setup Connection | Tell Anansi which database to connect to and how to reach it. |
| 2 | Sync Metadata | Choose the existing catalog and node types to sync into. |
| 3 | Sync Result | View a detailed report of all tables, columns, and keys inserted, updated, or deleted during the sync. |
A visual step indicator at the top of the page always shows you where you are.
Step 1: Setup Connection
Please refer to the Setup Connection guide to configure your database credentials and verify connectivity.
Step 2: Sync Metadata
Specify which existing catalog in Anansi should be updated with the latest structure from your database.
- Source Identifier (Required): Automatically pre-filled from your Schema Name.
- Select a Catalog (Required): Choose the existing catalog you want to update.
- Note: In Sync mode, the option to create a new catalog is hidden because sync only applies to existing catalogs.
- Node Names (Required): Select the matching node types representing your schema, tables, and columns in that catalog.
Click "Sync" to start the sync task. Anansi will scan for changes and advance you to Step 3.
Step 3: Sync Result
Once the sync task completes, you will automatically be redirected to the Sync Result report page.
1. Stats Summary
The summary card displays color-coded badges indicating exactly what has changed:
- Added: Items added to the database since the last sync (e.g.
+2 added). - Updated: Items modified or renamed since the last sync (e.g.
~1 updated). - Removed: Items deleted from the database since the last sync (e.g.
−1 removed). - Unchanged: Items skipped because no changes were detected (e.g.
14 unchanged). - Keys: Displays primary keys (
PKadded/removed) and foreign keys (FKadded/removed).
2. Side-by-Side Detailed Change Columns
Under Change Details, changes are split into a clean, two-column layout:
- Tables Column: Lists all added, updated, or removed table structures (e.g.
LoyaltyProgramunder Added,AuditLogunder Removed). - Columns Column: Lists all added, updated, or removed column structures (e.g.
LoyaltyProgram.LoyaltyIDunder Added,Customers.LoyaltyTierunder Updated).
3. Download Plaintext Report (.txt)
Click "Download Result" to save a plaintext report of this run.
- File Name: Saved as
sync-report-[CatalogName]-[Timestamp].txt - Content: Includes a timestamped summary header, detailed summary tables of changes, and lists of all additions, removals, and modifications.
Click "OK" to return to your main Dashboard.
When Should I Sync?
| Situation | Should You Sync? |
|---|---|
| A new table or view was added to your database | Yes |
| A column was renamed, added, or deleted | Yes |
| You want to connect a completely new database | No (use Database Import instead) |
Common Issues & Fixes
| Problem | Likely Cause | Fix |
|---|---|---|
| "401 Unauthorized" error | Expired session or token | Log out and log back in to renew your security access token. |
| Catalog dropdown is empty | No catalogs exist yet | You must Import metadata first to create a catalog before you can run a sync. |
| Sync runs but no stats change | No schema changes in database | If the database schema has not changed, the sync will show 0 changes. |