Production Workflows Guide

This guide describes how to operate SQLQueryHelperjs across development, staging, and production environments.

Default Recommendation

Use different reflector policies by environment.

• development: fast iteration, broad visibility, low ceremony
• staging: plan-first validation and approval rehearsal
• production: explicit approvals, change-ticket enforcement, audit logging, and conservative destructive policy

Development

In development, optimize for fast feedback.

• allow planReflect(...) and reflect(...) frequently
• inspect generated plans when changing keys, nullability, or indexes
• keep local benchmark runs available for regressions on hot paths
• use SQLite for fast local iteration when your deployment model allows it

Development is where you want change detection to feel cheap.

Staging

Staging should behave like production, but with room to rehearse.

• require teams to review planReflect(...) output before execution
• persist a reviewable plan artifact when rollout approval depends on destructive or engine-specific behavior
• inspect rename hints separately from confirmed destructive removals
• test routines, views, triggers, and dependency-aware rebuilds against the real engine
• validate history entries and audit hooks
• confirm engine-specific behavior such as MySQL returning(...) semantics before release

Staging is the place to catch cross-engine surprises, not production.

Production

Production should be treated as a governed runtime.

• require destructive approvals
• require change-ticket identifiers
• block destructive changes by default when policy demands it
• keep onSchemaChange hooks enabled for audit pipelines
• preserve schema change history for post-release review

Production rollout should prefer planReflect(...) first and reflect(...) second, never the other way around.

Destructive Change Approval Model

A workable approval model is:

1. engineer changes entity definitions
2. CI or release tooling captures planReflect(...)
3. reviewers check destructive reasons, dependency impact, rename hints, and the persisted plan artifact when available
4. approved table list and change ticket are attached for the execution window
5. reflect(...) runs with audit and history enabled

This keeps destructive rebuilds intentional and reviewable.

Environment Separation

Avoid reusing one reflector policy everywhere.

• local development can be permissive
• shared development and staging should look closer to production
• production should have the strictest approval and audit rules

The goal is not only safety. It is predictability.

Operational Checklist

Before a production schema rollout, verify:

• target engine and version are known
• entity model is committed and reviewed
• planReflect(...) output was reviewed recently
• persisted plan artifact exists when the rollout needs formal approval evidence
• rename hints were explicitly reviewed when present
• change ticket and approvals are present when destructive changes exist
• routines, triggers, and views were validated in staging if used
• benchmark or smoke-test data exists for performance-sensitive releases

When To Stop An Automated Rollout

Pause automation when:

• the plan shows destructive rebuilds you did not expect
• engine-specific emulation behavior changes the risk profile
• dependencies are deeper than the current review can justify
• the target schema was modified out of band and no longer matches the expected baseline

When that happens, treat the plan as an investigation artifact instead of blindly applying it.