page_links FK on-delete behavior decision #21

New issue

Open

opened 2026-04-26 03:53:42 +02:00 by myrmidex · 0 comments

myrmidex commented

2026-04-26 03:53:42 +02:00

Owner

Context

The page_links table FKs (source_page_id, target_page_id) currently have no onDelete behavior. PostgreSQL defaults to NO ACTION, which means any page that participates in an edge cannot be deleted without first removing its edges.

For v0.1 this is a non-issue because we have no delete operations on pages. But the moment we add deletion (admin tooling, GDPR-style URL removal, instance withdrawal cascades), this constraint will bite.

Decision needed

Pick one:

cascadeOnDelete() — deleting a page also deletes its inbound and outbound edges. Lossy but simple. Right semantic if "page is gone, the citation graph forgets it."
nullOnDelete() — deleting a page leaves orphan edges with NULL endpoints. Requires nullable FK columns (currently NOT NULL). Enables "we know the edge existed but the page is gone" semantics. Almost certainly the wrong call for our citation graph.
Append-only — leave as-is, never delete pages. Document explicitly.

Recommended: cascadeOnDelete() on both columns. Edges follow page lifecycle.

Acceptance criteria

Migration adds the chosen behavior (likely a new migration since page_links already exists).
A test exercises the chosen semantic — e.g. delete a page, assert its edges are gone (or assert FK violation if append-only is the choice).

## Context The `page_links` table FKs (`source_page_id`, `target_page_id`) currently have no `onDelete` behavior. PostgreSQL defaults to `NO ACTION`, which means **any page that participates in an edge cannot be deleted** without first removing its edges. For v0.1 this is a non-issue because we have no delete operations on `pages`. But the moment we add deletion (admin tooling, GDPR-style URL removal, instance withdrawal cascades), this constraint will bite. ## Decision needed Pick one: - `cascadeOnDelete()` — deleting a page also deletes its inbound and outbound edges. Lossy but simple. Right semantic if "page is gone, the citation graph forgets it." - `nullOnDelete()` — deleting a page leaves orphan edges with NULL endpoints. Requires nullable FK columns (currently NOT NULL). Enables "we know the edge existed but the page is gone" semantics. Almost certainly the wrong call for our citation graph. - Append-only — leave as-is, never delete pages. Document explicitly. Recommended: `cascadeOnDelete()` on both columns. Edges follow page lifecycle. ## Acceptance criteria - Migration adds the chosen behavior (likely a new migration since `page_links` already exists). - A test exercises the chosen semantic — e.g. delete a page, assert its edges are gone (or assert FK violation if append-only is the choice).