docs(#1512): specify FK-column indexing on PostgreSQL - #244
Merged
Conversation
- table-declaration spec §2.6 (new): DataJoint guarantees FK columns are indexed on both backends — implicit on MySQL/InnoDB, emitted (coverage-aware) on PostgreSQL; skipped when already a left-prefix of the PK or a declared index. - database-backends spec: add the FK-index row to Backend-Specific Behavior with a pointer to the declaration spec. - referential-integrity explanation §5: flip the now-obsolete guidance to declare an explicit index on PostgreSQL; the database indexes FK columns on both backends. Pairs with datajoint-python #1526.
MilagrosMarin
approved these changes
Aug 5, 2026
dimitri-yatsenko
added
the
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the behavior added in datajoint/datajoint-python#1526 (closes #1512), and flips the now-obsolete guidance from #227.
Changes
reference/specs/table-declaration.md§2.6 (new) — Foreign-Key Indexes. Normative statement of the guarantee: FK columns are indexed on both backends — implicit on MySQL/InnoDB, emitted by DataJoint on PostgreSQL — and the emitted index is coverage-aware (skipped when the columns are already a left-prefix of the PK, a declared index, or a wider FK index). Notes that lifecycle on FK drop /alter()is out of declaration scope.reference/specs/database-backends.md§Backend-Specific Behavior. Adds a "Foreign-key column index" row (Implicit / Emitted by DataJoint) with a pointer to the declaration spec — the difference is only who creates the index.explanation/referential-integrity.md§5. Flips the guidance added in docs: add Data Integrity, Referential Integrity, and Transactions explanation pages #227: it previously told users to declare an explicitindex(...)on PostgreSQL; that index is now created by the framework, so the mental model "the database indexes foreign-key columns" holds on both backends.Why now (not the spec-reshape)
§5's old text becomes actively wrong the moment #1526 merges (it tells users to hand-declare an index the framework now creates), so this shouldn't wait for the larger diagram-operations spec reshape.