Legacy Database Onboarding Guide

This guide is for teams that already have a live database and want to bring it under SQLQueryHelperjs control gradually.

Recommended Sequence

Start from inspection, not from reflect(...).

1. inspect the existing schema
2. generate entity classes
3. normalize names, keys, nullability, and table ownership in code
4. re-run inspection until the generated model and the reviewed model are aligned
5. only then start using planReflect(...) and reflect(...)

That sequence avoids turning unknown drift into accidental destructive changes.

Why Inspection Comes First

Legacy systems often contain:

• naming inconsistencies
• nullable columns that are treated as required in application code
• indexes nobody remembers creating
• triggers or routines with hidden dependencies
• manual hotfixes applied directly in production

Inspection makes that visible before code-first synchronization begins.

First Pass Goals

The first pass should not try to redesign the entire schema.

• capture the current structure faithfully
• identify risky tables and objects
• document engine-specific objects the code model must preserve
• decide which tables are safe for early synchronization and which need manual review

Advanced index fidelity is one of the review points that should be checked explicitly.

• SQLite generated output now preserves expression and partial indexes
• PostgreSQL generated output now preserves expression indexes and partial predicates
• MySQL generated output now preserves functional indexes on servers that expose expression metadata, but still needs manual review for some engine-specific index attributes

Safe Rollout Pattern

For a legacy database, the safe rollout pattern is:

1. inspect and generate
2. commit the reviewed model
3. run planReflect(...) against a staging copy
4. resolve unexpected diffs
5. enable reflect(...) on low-risk tables first
6. expand to more sensitive tables and advanced objects later

Handling Drift

Assume drift exists until proven otherwise.

• compare inspection output across environments
• do not trust production and staging to match automatically
• treat missing indexes, renamed columns, and altered defaults as review items
• use destructive approvals conservatively until the model has stabilized

Advanced Objects In Legacy Systems

Legacy databases often hide logic in:

• views
• triggers
• procedures and functions
• foreign-key chains across tables not owned by one team

Those objects should be inventoried early, even if table synchronization is your first target.

Practical Team Boundary

Do not try to claim the whole database at once.

• start with the subset your team owns
• document external dependencies clearly
• expand ownership only after the first synchronized slice proves stable

That keeps onboarding realistic and reduces the chance of breaking unrelated systems.