[jbylund]

Closes #127. Stacked on #137 (feat/declared-table-and-schema) — review that first; this PR targets its branch, so the diff here is only the primary-key work.

Table takes primary_key, one column or a tuple of them:

Table("commits", {"sha": "text", "author": "text"}, primary_key="sha")
Table("commit_files", {"sha": "text", "path": "text"}, primary_key=("sha", "path"))

Normalised to a tuple so nothing downstream branches on the spelling, and validated at construction against the table's own columns — a key naming a column the table does not have is knowable there, so it raises on the line that wrote it. A tuple rather than a set because a composite key's order is part of it: it is what conkey records and what psql prints.

What \d prints now

              Table "public.commit_files"
   Column   |  Type   | Collation | Nullable | Default
------------+---------+-----------+----------+---------
 sha        | text    |           | not null |
 path       | text    |           | not null |
 insertions | integer |           |          |
 deletions  | integer |           |          |
Indexes:
    "commit_files_pkey" PRIMARY KEY, btree (sha, path)

Byte-for-byte what PostgreSQL 18 prints for the same declaration — I diffed them against a real server rather than reconstructing the format.

Four things that are each invisible on their own

This is most of the work, and none of it is guessable from the outside:

• pg_class.relhasindex gates the entire footer. Left False, every row below is built and never asked for.
• The index needs its own pg_class row, relkind = 'i'. psql reads the index's name as c2.relname off a second pg_class in the same query, so without it the join drops every index it was told about.
• pg_get_indexdef cannot be the constant "" the other catalog functions are. psql echoes everything after " USING " straight into the footer, so that substring is where btree (sha) comes from. It is rewritten into a reference to a column carrying the rendered text — exactly as format_type already was — and pg_get_constraintdef gets the same treatment, which Declare foreign keys between Tables, resolved by name #129 will need.
• pg_index and pg_constraint leave _ALWAYS_EMPTY_TABLES. Safe because psql reads both in a JOIN, not in one of the correlated subqueries that substitution exists for; I checked every query \d sends.

Details worth a look in review

not null is written in two places on purpose. attnotnull and information_schema.columns.is_nullable answer one question and a client reads whichever it reads, so they must not disagree. There's a test asserting both.

Index and constraint OIDs come from their own ranges, not the continuation of the table numbering — declaring a key must not renumber a table, since table OIDs are positional and a client may have introspected them already. test_declaring_a_primary_key_does_not_renumber_the_tables pins that.

PostgreSQL 17 also records key columns as contype='n' rows in pg_constraint. pg_mimic reports server_version 16, so it deliberately does not.

Identifiers are quoted only when they have to be, which is what pg_get_constraintdef does — btree (sha) and btree ("userId"). Reserved words are not consulted; the comment says why.

Tests

20 new, at three levels:

• test_declared.py — normalisation, key order, and the two refusals.
• test_pg_catalog.py — psql's index-footer query verbatim, against one-column, composite and needs-quoting keys, plus a table with no key answering no rows. Also the OID-stability and conkey assertions.
• test_psql.py — the real psql binary, asserting the rendered footer string, that a keyless table has no Indexes: section, that \di lists the index, and that \dt does not — an index is a relation, so the pg_class row it needs must not leak into the table list.

Full suite: 928 passed, 32 xfailed (up from 908). ruff check and ruff format --check clean.

Also here

examples/git_sql.py declares the four keys that are actually sound for git data: commits.sha, files.path, branches.name and commit_files (sha, path). Verified live.

Not in scope

Unique constraints (#128), foreign keys (#129), declaring a constraint after construction (#130). pg_get_constraintdef is made row-dependent here but no non-primary constraint exists to render yet.