Cygenix Help Guide

Cygenix is an AI-powered database migration platform. It connects to your source and target SQL Server databases, maps columns using Claude AI, applies value translations, validates results, and delivers professional reports — all from the browser.

Typical workflow

The recommended migration sequence in Cygenix:

Connection strings

Direct SQL Server connection string

Standard ADO.NET format — works on-premises and Azure SQL:

Azure Function (Managed Identity)

Recommended for Azure SQL — no passwords stored or transmitted:

Configure (live DB migration)

The legacy 5-step Configure wizard walks through source connection, target connection, column mapping, SQL preview and save. New migrations should use the Mapper directly, which provides a richer target-driven mapping experience.

Source database

Connect to the database you are migrating from. Use a direct connection string or Azure Function URL. Click 🔌 Connect source DB to test and load the schema.

Target database

Connect to the database you are migrating into. Same connection modes as source.

Select & Map

Choose source and target tables. Claude AI maps columns automatically. Override any row using the dropdowns. Load Was/Is rules from the panel on the right.

Preview SQL

Fetch live rows from the source and review the generated INSERT statements before executing. Download as .sql if preferred.

Save & finish

Enter a job name and save. The job appears in All Jobs and the Conversion Project job library.

Mapper

The Mapper is the primary tool for building migration jobs. It offers two modes toggled at the top: Simple Map and One-to-Many.

Simple map

Maps one source table to one target table. The mapping grid is target-driven — every non-identity target column appears as a fixed row. You choose the source column from a dropdown.

• AI map — Claude Haiku automatically maps all target columns. Retries automatically on overload (up to 3 attempts).
• Fixed value — type any SQL literal in the Fixed value column to override the source. Examples: N'Enterprise', NULL, GETDATE(), 0
• Truncation warning — if the source char type is wider than the target, a ⚠ LEFT(N) badge appears and LEFT() is auto-applied in the SQL
• 👁 Hide/Show Unmapped — toggle to show only columns that have a source or fixed value
• Filter bar — filter rows by text or match level (HIGH / MEDIUM / LOW / Unmapped / Fixed)
• Sort — click column headers to sort Source, Target or Match
• ✂ Remove unused — removes unmapped rows from the generated SQL (with ↩ undo)

One-to-many map

Maps one source table into multiple target tables in a single operation. Add as many target table cards as needed using + Add target table.

• Each card has its own target-driven mapping grid, AI map button, filter and 👁 Hide Unmapped toggle
• PK mode per card: Identity (auto-increment), GUID (NEWID()), or Natural key
• PK variable — name the variable (e.g. @ClientID) that captures the inserted PK for use in FK columns of child cards
• FK rows — add foreign key columns that reference the PK variable of a parent card
• Fixed value column per row — same as Simple map
• Cards can be reordered with ↑ ↓ buttons

Generated SQL

SQL is generated automatically as you edit. Click ⚡ Generate SQL to scroll to the SQL panel and refresh it explicitly.

• Three-part database names: [SourceDB].[dbo].[table] and [TargetDB].[dbo].[table]
• Bare column names in SELECT: [colName] (no schema prefix)
• No GO statements — compatible with direct execution and batch runners
• Was/Is rules appear as CASE WHEN blocks per column
• Fixed values replace the source column directly in SELECT
• LEFT(N) wrapping applied automatically for truncated char columns

SQL Editor

A full-featured SQL workspace for writing, running and managing scripts against source or target databases.

• Script library — left panel. Save any number of named scripts. Click to load. Scripts persist in localStorage.
• Connection selector — choose whether queries run against Source DB or Target DB
• Keyboard shortcuts — Ctrl+Enter run, Ctrl+F find, Ctrl+/ toggle comment, Tab indent
• Snippet toolbar — one-click SELECT, WHERE, INSERT, UPDATE, DELETE, BEGIN TRAN buttons
• Results grid — row view or pivot view. Export to Excel. Rows capped in browser but all rows execute on server.
• History — every executed query is stored with timestamp and result count. Click to reload.
• AI assistant — describe what you need. Claude writes or improves the SQL. Click Apply to load into the editor.
• Format SQL — uppercases all SQL keywords in the current script
• Word wrap / Line numbers toggles
• Fullscreen mode — hides the sidebar for maximum editor space
• Load from file — open any .sql file directly into the editor

Was/Is mapping

Was/Is mapping translates specific values during migration — for example converting status codes A → Active, or renaming department codes to match the target system.

Prepare a CSV or Excel file with columns: field name, old value (Was), new value (Is). Load it in the Mapper using the Was/Is panel. Columns with rules applied show a 🔄 N rules badge.

Data Validation

The Validation page runs SQL scripts to check data quality before and after migration. Unlike the old fixed-table approach, you can now add any table as a validation source.

Adding a validation table

Click + Add validation table. A modal walks through:

Running scripts

• ▶ Run all (topbar) — runs every script across all sources
• ▶ Run selected — runs only checked scripts
• ▶ Run (source card) — runs all scripts for that source only
• ▶ (row button) — runs a single script

A script ✓ Pass if it returns zero rows. It ✕ Fail if it returns any rows (those rows are the problem data). Click 👁 View on a failed script to see the rows inline, filtered to your chosen report columns.

Click 📊 Export to download an Excel file with a summary sheet and one sheet per failed script.

Data Insights

Connect to any database table and load column data into the browser for quick analysis — distinct values, value frequencies, null counts, date ranges. Useful for understanding source data before mapping.

Project Planner

A built-in project management tool for tracking your migration. Access it from Plan → Project Planner in the sidebar. The completion date is read from Project Settings → Target completion.

Calendar

Four views toggled at the top of the calendar panel:

• Year — 12 mini month grids. Days with events show a teal dot. Click any day to jump to Day view.
• Month — full month grid. Events shown as coloured pills (up to 3 per cell, +N more). Click a cell to drill into Day view.
• Week — 7-column hourly grid. All-day band at top. Click any hour slot to add an event pre-filled with that date and time.
• Day — single column hourly view. All-day events at top.

Use ‹ › to navigate and Today to jump back to now. Click + Event to add a calendar event manually.

The calendar automatically shows events generated from your tasks (due dates and start dates) and the project completion date from Project Settings. Clicking a task-generated event opens the task edit modal.

Event types and colours:

Tasks

Click + Add task to open the task modal (similar to an Outlook task). Fields include: name, description, phase, status, priority, start date, due date, owner/assignee and notes.

Task statuses: In progress To do Blocked Review Done

Overdue tasks (due date past, not done) are highlighted red. The tasks table can be filtered by status, phase and free text search.

The summary stats bar at the top shows: days remaining to completion, total tasks, completed, in progress, blocked, open blockers and overall % complete. Two progress bars show task completion and elapsed project time.

Blockers

Click + Add blocker to record anything blocking the migration. Fields: title, description, impact level (Low / Medium / High / Critical), raised by, owner, target resolution date and resolution notes.

Open blockers appear as red cards. Click ✓ Resolve to mark a blocker resolved (it turns green). The active blocker count is shown in the summary stats.

Execution phase tracker

A visual 7-stage pipeline: Planning → Analysis → Mapping → Development → UAT → Go-live → Post-migration. The current phase is highlighted in blue; completed stages in green. Click any stage to set it as the current phase — this saves back to Project Settings and is reflected across the dashboard.

Performance settings

Access from Configure → Performance. Settings are saved to localStorage (cygenix_performance) and applied across all migration operations.

Quick presets

Key settings:

• Fetch page size — rows fetched per round-trip from source. Reduce for wide tables with large text/blob columns.
• Insert batch size — rows per INSERT VALUES (max 1,000 for SQL Server). Reduce for tables approaching the 8,060 byte row size limit.
• Concurrent threads — parallel INSERT batches. Keep at 1–2 for Azure SQL Standard to avoid DTU spikes.
• NOLOCK — enables READ UNCOMMITTED on source reads. Reduces lock contention on live databases but allows dirty reads.
• Row verification — COUNT(*) check after each page insert to confirm rows were written.
• Index disable hint — adds ALTER INDEX DISABLE/REBUILD comments in generated SQL (you run manually in SSMS).

Use ⬇ Export to save settings as a JSON file. Use ⬆ Import to restore from a saved file. The Configuration summary panel shows warnings for conflicting settings (e.g. API timeout less than query timeout).

Project settings

Access from Configure → Project Settings (or the dashboard sidebar). Fields include: project name, type, reference number, description, analyst, PM, client, start date, target completion date, migration phase, source system, target system, estimated rows and notes.

Conversion Project

The Conversion Project Builder (Execute Jobs in the sidebar) sequences multiple migration jobs and custom SQL scripts into a single executable project.

Adding steps

• Select migration jobs from the job library on the left
• Add custom SQL steps — write any T-SQL to run on source or target
• Add stored procedure call steps with parameters
• Drag-and-drop to reorder steps

Running a project

Click ▶ Run project. Each step shows a live status: ⚪ pending → 🟡 running → 🟢 complete / 🔴 failed / 🟠 error. On failure you can Retry, Skip or Abort the run. A full execution log is captured and included in the Conversion Report.

Conversion Reports

Export a client-ready Excel report from Reports → Conversion Report in the dashboard. The report includes:

• Summary — project metadata, migration totals, row counts, error summary
• Migration results — one row per job: source table, target table, rows migrated, rows verified, status
• Column mapping — full mapping for each job including Was/Is rules applied
• Execution log — timestamped log of every step
• Was/Is rules — complete translation table used

Inventory

Store project documents, schema files, data dictionaries, mapping documents and Was/Is tables. Files can be uploaded, previewed (CSV, images) and downloaded. Client uploads appear in a separate 👤 Client submissions section.

Client Portal

Give clients a separate login that takes them to a simplified portal (/client.html) for uploading source data and notes.

Troubleshooting