feat: refine ISAC design and prepare production deployment
This commit is contained in:
@@ -144,60 +144,25 @@ Use `npm run db:restore -- <backup-file>` only with an empty, migrated target
|
||||
database. The restore script intentionally refuses to merge into a populated
|
||||
database.
|
||||
|
||||
## Low-downtime database migration windows
|
||||
## Development database maintenance
|
||||
|
||||
Friends and contributors may be actively entering game data in ISAC while
|
||||
development continues. Treat dev-server availability and unsaved contributor
|
||||
work as operational concerns whenever a schema change requires stopping the
|
||||
embedded database.
|
||||
The development server is no longer a shared contributor-facing service, so
|
||||
development database work does not need to optimize for minimum downtime.
|
||||
Database safety remains mandatory:
|
||||
|
||||
Use this sequence for every planned migration window:
|
||||
1. Prefer additive, repeatable migrations and finish the migration logic before
|
||||
operating on persistent data.
|
||||
2. Identify the exact environment and database path, then inspect running
|
||||
processes and stop only this project's development-server process tree.
|
||||
3. Run and verify `npm run db:backup` before migration, export, restore, or
|
||||
destructive schema work. Retain and report the backup path.
|
||||
4. Apply the migration or maintenance operation and verify schema state, record
|
||||
counts, and critical entities before restarting the server.
|
||||
5. If an operation fails, preserve logs and the verified backup rather than
|
||||
repeatedly improvising against the database.
|
||||
6. Restart the development server when maintenance and useful verification are
|
||||
complete, then confirm a basic health or page check.
|
||||
|
||||
### Prepare while the server remains online
|
||||
|
||||
1. Implement the application changes and the complete repeatable migration
|
||||
before stopping the server.
|
||||
2. Prefer additive, backward-compatible changes: new tables, new indexes, and
|
||||
nullable or safely defaulted columns. Avoid table copies, column removal,
|
||||
database recreation, or migrations that require the new application code to
|
||||
become active before the schema is ready.
|
||||
3. Make migrations idempotent by inspecting current schema state before each
|
||||
alteration. The migration must be safe to rerun after interruption.
|
||||
4. Batch related schema changes into one window instead of repeatedly stopping
|
||||
the server during the same task.
|
||||
5. Run `npm run check` and `npm run build` before the outage. Do not spend the
|
||||
offline interval editing code, resolving type errors, building assets, or
|
||||
performing ordinary UI review.
|
||||
6. Identify the exact environment, database path, migration steps, verification
|
||||
queries, and rollback/restore backup before stopping anything.
|
||||
|
||||
### Keep the offline window short
|
||||
|
||||
1. Do not start the window while a known contributor is in the middle of an
|
||||
unsaved form or submission. When contributor activity is known, allow them
|
||||
to finish or explicitly coordinate the interruption.
|
||||
2. Inspect processes and stop only this project's dev-server process tree.
|
||||
3. Run `npm run db:backup` immediately, verify that it completed, and retain the
|
||||
reported backup path.
|
||||
4. Run the already-prepared migration immediately after the backup.
|
||||
5. Perform only critical database checks while offline: migration success,
|
||||
expected columns/tables, record counts, and critical entity availability.
|
||||
6. Restart the dev server as soon as the database is safe for application use.
|
||||
Browser testing, extended regression checks, formatting, documentation
|
||||
review, and noncritical diagnostics happen after service is restored.
|
||||
|
||||
### Failure and high-risk handling
|
||||
|
||||
1. If backup, migration, or critical verification fails, do not repeatedly
|
||||
improvise against the live database. Preserve logs and the verified backup,
|
||||
determine whether the existing schema is still safe, and either restart the
|
||||
previous compatible application or follow the documented empty-database
|
||||
restore procedure.
|
||||
2. Separate destructive, data-rewriting, or predictably long migrations from
|
||||
routine additive windows. Report that a maintenance window is required
|
||||
before beginning one.
|
||||
3. Do not claim the service is available until the restarted dev server passes
|
||||
a basic health/page check.
|
||||
4. In the handoff, report the backup path, migration result, server restart,
|
||||
critical verification performed, and approximate offline interval when it
|
||||
can be determined.
|
||||
Production and staging remain persistent shared environments. Their deployment,
|
||||
backup, synchronization, and maintenance safeguards are defined separately in
|
||||
`docs/DEPLOYMENT.md`.
|
||||
|
||||
Reference in New Issue
Block a user