Team Adoption Guide

This guide is for teams adopting SQLQueryHelperjs as an operational schema-evolution layer, not only as a local developer convenience.

Who This Is For

Use this guide if your team needs to:

• evolve schema without handwritten migration files for every change
• review destructive changes before execution
• keep development, staging, and production behavior aligned
• bring existing databases under code-first control gradually

Recommended Adoption Path

Use this order instead of enabling every advanced feature on day one:

1. Start with schema inspection against the current database.
2. Generate entity classes and clean them up into a stable model layer.
3. Use planReflect(...) in review workflows before allowing reflect(...) in shared environments.
4. Enable destructive approvals and change-ticket requirements before production rollout.
5. Add object-level features such as views, triggers, and routines only after the table model is stable.

Team Operating Model

The safest team model is:

• developers change entities in code
• GitHub Actions or equivalent CI jobs run validation and planReflect(...)-style review steps
• reviewers inspect the plan for destructive or engine-specific behavior
• approved environments run reflect(...)
• audit history and benchmark snapshots are retained per release

That keeps schema intent in code while still giving the team an explicit review point.

For public repositories, GitHub-hosted Actions runners are enough to make these checks required for merge through branch protection or repository rulesets.

Engine Expectations

Do not assume every engine behaves identically.

• SQLite is the fastest local loop and simplest path for embedded workflows.
• PostgreSQL remains the broadest advanced-governance engine.
• MySQL now supports advanced runtime workflows, but some capabilities such as returning(...) are implemented with dialect-safe emulation instead of native behavior.

Use the engine guides and DATABASE_ENGINE.md as the source of truth before standardizing a production workflow.

When rollout policy depends on an exact capability boundary, use the compatibility matrix in DATABASE_ENGINE.md instead of relying on high-level wording from individual guides.

Suggested Documentation Sequence

For a new team rollout, read the guides in this order:

1. getting-started.md
2. api-map.md
3. production-workflows.md
4. legacy-onboarding.md
5. release-operations.md
6. plan-artifacts.md
7. observability.md
8. semantic-change-detection.md
9. advanced-object-coverage.md
10. engine-specific runtime guide for your target database
11. benchmarks.md
12. benchmark-history.md

What Good Looks Like

A mature team rollout usually has:

• a reviewed entity model checked into source control
• environment-specific reflector configuration
• destructive approvals enabled outside local development
• a plan review step before runtime synchronization
• benchmark and release snapshots captured per version

That is the point where SQLQueryHelperjs becomes an operational platform choice instead of just a local SQL helper.