gitchegumi/GitchAlerts

Watch

Fork

You've already forked GitchAlerts

Code Issues 1 Pull requests 1 Releases 56 Packages 3 Activity Actions

Fix fresh PostgreSQL initialization without manual baselining #182

New issue

Open

opened 2026-09-13 21:20:05 -05:00 by kiyi · 0 comments

kiyi commented

2026-09-13 21:20:05 -05:00

Collaborator

Copy link

Goal and deployment hold

Make GitchAlerts usable by self-hosters who supply an empty PostgreSQL database: the documented normal startup must initialize the schema without manual Prisma baselining. Existing installations must continue to upgrade safely.

The owner requested that dev deployment testing remain paused until this fix is completed, released upstream, and incorporated into the Homelab/GitchAlerts deployment bundle. Implementation will be done by the owner in a separate project. This issue tracks the application fix and the downstream bundle follow-through; it does not authorize a production cutover or database reset.

Confirmed defect in v0.12.2

Upstream source: https://git.gitchegumi.com/gitchegumi/GitchAlerts

Prisma applies migration directories in name order. The earliest migration, 20250608000000_add_linked_accounts, creates linked_accounts and adds a foreign key referencing users(id). The initial migration directory is dated 20260531230000, so it runs later. A completely empty database does not have users when that foreign key is applied.

The bundle runs prisma migrate deploy before starting application services. Its current migration runbook works around this by creating the current schema with db push and marking historical migrations applied, only for a verified-empty dev database. Ordinary self-hosters should not need this procedure.

The ordering defect was verified from the v0.12.2 source. Audit and execute the entire migration sequence: do not assume fixing this first failure proves every later migration works. This issue does not claim a new live empty-database failure was reproduced during issue creation.

Scope

Reproduce the failure against a disposable empty PostgreSQL database using the released application's normal migration/startup path.
Audit migration ordering, table dependencies, duplicate objects and migration-history compatibility; select and document a safe fresh-install strategy.
Preserve existing installation histories. Do not simply rename, delete or rewrite migrations that deployed databases may already record without a tested compatibility plan.
Keep fresh initialization automatic and repeatable. Do not require operators to run db push, migrate resolve, reset, or hand-written schema SQL for a normal new installation.
Never infer that an existing database is disposable merely because _prisma_migrations is missing or empty. Unknown or partially initialized states must fail clearly rather than silently mark migrations applied.
Keep one migration owner per deployment. Web, ingress and worker must not independently race schema setup; dependent services must not start against an incomplete schema.
Log migration start, meaningful progress, success and actionable failures to normal container output. Propagate a nonzero exit on failure; do not print connection strings, passwords, tokens or stored data.

The solution should work for ordinary self-hosted/Compose installs as well as UDS. Avoid making this a Kubernetes-only workaround.

Acceptance tests

Empty database: normal documented startup creates the complete schema and migration history, creates expected bootstrap records, and reaches healthy application startup without manual commands beyond normal installation.
Verify first login/bootstrap, workspace creation, an overlay and a manual test alert on a fresh installation.
Repeat startup and migration execution: no duplicate bootstrap records, destructive operations or unintended migration replay.
Existing v0.12.2 database: upgrade preserves representative users, workspaces, linked accounts, encrypted integration credentials, display keys and asset references; retained keys can still decrypt existing values.
Database created using the currently documented db-push/migrate-resolve baseline: upgrade also succeeds. Test this separately if its recorded history differs from the existing-install fixture.
Partial/failed/unknown migration state: clear actionable error, no silent adoption or data deletion, and dependent services remain gated.
Supported PostgreSQL versions are documented and covered by automated tests. Homelab source was 17.11 and the shared destination is 18.6; exercise PostgreSQL 17 and 18 compatibility for this upgrade.
CI exercises both fresh installation and existing-database upgrade with disposable data. Test the packaged production image/startup path, not only source-level SQL.

Release and bundle follow-through

Link the upstream implementation PR and its passing test evidence here.
Publish an upstream release and immutable application images containing the fix; record release notes and any upgrade requirements.
Update Homelab/GitchAlerts's image lock/pins, package and bundle version, and startup commands if the supported entrypoint changes. Preserve the single-migrator gate and existing admission fixes.
Update upstream self-hosting documentation and the Homelab/GitchAlerts bundle runbook to remove the manual fresh-database baseline prerequisite once the new release supports normal initialization.
Run bundle validation/security checks and publish a new signed bundle. Record the exact release tag/digests here.
Only then resume dev deployment against its separate empty database and record acceptance results. Production cutover remains a separate decision.

Deployment hold and downstream tracking

Dev deployment testing is paused at the owner’s request until the upstream fix is released and the deployment bundle consumes it. Dev is intended to start with an empty database; restoring production data is not a substitute for fresh-install coverage. End-to-end dev acceptance remains pending.

Originally filed in the bundle repository as Homelab/GitchAlerts#9; this source-repository issue supersedes it. Downstream migration tracking: Homelab/GitchAlerts#1 and Homelab/platform#28.

## Goal and deployment hold Make GitchAlerts usable by self-hosters who supply an empty PostgreSQL database: the documented normal startup must initialize the schema without manual Prisma baselining. Existing installations must continue to upgrade safely. The owner requested that **dev deployment testing remain paused until this fix is completed, released upstream, and incorporated into the Homelab/GitchAlerts deployment bundle**. Implementation will be done by the owner in a separate project. This issue tracks the application fix and the downstream bundle follow-through; it does not authorize a production cutover or database reset. ## Confirmed defect in v0.12.2 Upstream source: https://git.gitchegumi.com/gitchegumi/GitchAlerts Prisma applies migration directories in name order. The earliest migration, [20250608000000_add_linked_accounts](https://git.gitchegumi.com/gitchegumi/GitchAlerts/src/tag/v0.12.2/packages/database/prisma/migrations/20250608000000_add_linked_accounts/migration.sql), creates linked_accounts and adds a foreign key referencing users(id). The initial migration directory is dated 20260531230000, so it runs later. A completely empty database does not have users when that foreign key is applied. The bundle runs prisma migrate deploy before starting application services. Its [current migration runbook](https://git.gitchegumi.com/Homelab/GitchAlerts/src/branch/main/docs/migration.md) works around this by creating the current schema with db push and marking historical migrations applied, only for a verified-empty dev database. Ordinary self-hosters should not need this procedure. The ordering defect was verified from the v0.12.2 source. Audit and execute the entire migration sequence: do not assume fixing this first failure proves every later migration works. This issue does not claim a new live empty-database failure was reproduced during issue creation. ## Scope - Reproduce the failure against a disposable empty PostgreSQL database using the released application's normal migration/startup path. - Audit migration ordering, table dependencies, duplicate objects and migration-history compatibility; select and document a safe fresh-install strategy. - Preserve existing installation histories. Do not simply rename, delete or rewrite migrations that deployed databases may already record without a tested compatibility plan. - Keep fresh initialization automatic and repeatable. Do not require operators to run db push, migrate resolve, reset, or hand-written schema SQL for a normal new installation. - Never infer that an existing database is disposable merely because _prisma_migrations is missing or empty. Unknown or partially initialized states must fail clearly rather than silently mark migrations applied. - Keep one migration owner per deployment. Web, ingress and worker must not independently race schema setup; dependent services must not start against an incomplete schema. - Log migration start, meaningful progress, success and actionable failures to normal container output. Propagate a nonzero exit on failure; do not print connection strings, passwords, tokens or stored data. The solution should work for ordinary self-hosted/Compose installs as well as UDS. Avoid making this a Kubernetes-only workaround. ## Acceptance tests - [ ] Empty database: normal documented startup creates the complete schema and migration history, creates expected bootstrap records, and reaches healthy application startup without manual commands beyond normal installation. - [ ] Verify first login/bootstrap, workspace creation, an overlay and a manual test alert on a fresh installation. - [ ] Repeat startup and migration execution: no duplicate bootstrap records, destructive operations or unintended migration replay. - [ ] Existing v0.12.2 database: upgrade preserves representative users, workspaces, linked accounts, encrypted integration credentials, display keys and asset references; retained keys can still decrypt existing values. - [ ] Database created using the currently documented db-push/migrate-resolve baseline: upgrade also succeeds. Test this separately if its recorded history differs from the existing-install fixture. - [ ] Partial/failed/unknown migration state: clear actionable error, no silent adoption or data deletion, and dependent services remain gated. - [ ] Supported PostgreSQL versions are documented and covered by automated tests. Homelab source was 17.11 and the shared destination is 18.6; exercise PostgreSQL 17 and 18 compatibility for this upgrade. - [ ] CI exercises both fresh installation and existing-database upgrade with disposable data. Test the packaged production image/startup path, not only source-level SQL. ## Release and bundle follow-through - [ ] Link the upstream implementation PR and its passing test evidence here. - [ ] Publish an upstream release and immutable application images containing the fix; record release notes and any upgrade requirements. - [ ] Update Homelab/GitchAlerts's image lock/pins, package and bundle version, and startup commands if the supported entrypoint changes. Preserve the single-migrator gate and existing admission fixes. - [ ] Update upstream self-hosting documentation and the Homelab/GitchAlerts bundle runbook to remove the manual fresh-database baseline prerequisite once the new release supports normal initialization. - [ ] Run bundle validation/security checks and publish a new signed bundle. Record the exact release tag/digests here. - [ ] Only then resume dev deployment against its separate empty database and record acceptance results. Production cutover remains a separate decision. ## Deployment hold and downstream tracking Dev deployment testing is paused at the owner’s request until the upstream fix is released and the deployment bundle consumes it. Dev is intended to start with an empty database; restoring production data is not a substitute for fresh-install coverage. End-to-end dev acceptance remains pending. Originally filed in the bundle repository as [Homelab/GitchAlerts#9](https://git.gitchegumi.com/Homelab/GitchAlerts/issues/9); this source-repository issue supersedes it. Downstream migration tracking: [Homelab/GitchAlerts#1](https://git.gitchegumi.com/Homelab/GitchAlerts/issues/1) and [Homelab/platform#28](https://git.gitchegumi.com/Homelab/platform/issues/28).

kiyi referenced this issue from a commit

2026-09-13 22:43:06 -05:00

fix(database): initialize fresh PostgreSQL with a migration gate

kiyi referenced this issue

2026-09-13 22:43:28 -05:00

fix(database): initialize fresh PostgreSQL safely #183

portegumi referenced this issue

2026-09-14 09:18:37 -05:00

fix(database): initialize fresh PostgreSQL safely #183

kiyi referenced this issue from a commit

2026-09-14 09:50:58 -05:00

fix(database): reject false-positive readiness states

No Branch/Tag specified

main

build/patch-image-dependencies

fix/fresh-postgres-initialization

build/targeted-container-copy

alerts-worker-v0.2.3

v0.12.4

alerts-ingress-v0.2.3

alerts-web-v0.3.4

alerts-worker-v0.2.2

alerts-ingress-v0.2.2

alerts-web-v0.3.3

v0.12.3

alerts-worker-v0.2.1

alerts-ingress-v0.2.1

alerts-web-v0.3.2

v0.12.2

alerts-web-v0.3.1

v0.12.1

alerts-worker-v0.2.0

v0.12.0

alerts-ingress-v0.2.0

alerts-web-v0.3.0

alerts-web-v0.2.0

v0.11.0

alerts-web-v0.1.22

v0.10.13

alerts-web-v0.1.21

v0.10.12

alerts-web-v0.1.20

v0.10.11

alerts-web-v0.1.19

v0.10.10

alerts-ingress-v0.1.3

alerts-web-v0.1.18

alerts-worker-v0.1.2

v0.10.9

alerts-web-v0.1.17

v0.10.8

alerts-web-v0.1.16

v0.10.7

alerts-web-v0.1.15

v0.10.6

alerts-web-v0.1.14

v0.10.5

alerts-web-v0.1.13

v0.10.4

alerts-web-v0.1.12

v0.10.3

alerts-ingress-v0.1.2

alerts-web-v0.1.11

v0.10.2

alerts-web-v0.1.10

alerts-web-v0.1.9

v0.10.1

alerts-web-v0.1.8

alerts-web-v0.1.7

v0.1.10

v0.1.9

v0.1.8

alerts-web-v0.1.6

v0.1.7

alerts-web-v0.1.5

v0.1.6

alerts-web-v0.1.4

v0.1.5

alerts-web-v0.1.3

v0.1.4

alerts-web-v0.1.2

v0.1.3

v0.1.2

alerts-ingress-v0.1.1

alerts-web-v0.1.1

alerts-worker-v0.1.1

v0.1.1

Labels

Clear labels

Something isn't working

dependencies

Pull requests that update a dependency file

devops

docker

Pull requests that update docker code

documentation

Improvements or additions to documentation

duplicate

This issue or pull request already exists

enhancement

New feature or request

github_actions

Pull requests that update GitHub Actions code

good first issue

Good for newcomers

help wanted

Extra attention is needed

invalid

This doesn't seem right

javascript

Pull requests that update javascript code

maintenance

question

Further information is requested

refactor

wontfix

This will not be worked on

No labels

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gitchegumi/GitchAlerts#182

Reference in a new issue

Repository

gitchegumi/GitchAlerts

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns