yesodweb / yesodweb/persistent

Implement Postgresql `COMMENT` with documentation comments

Open
#1,364 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Postgres
Dominant language
Haskell
Stars
486
Forks
306
PR merge metrics
No merged PRs in 30d

Description

Doc comments would be neat and pretty easy to add in via migrations.

Adding them is easy. COMMENT ON COLUMN ${table}.${column} IS '${comment text goes here}' for columns and COMMENT ON TABLE $(table) IS '$(comment text)'.

Checking to see if we need to add them, though, is tricky. We need to provide the col_description(table_oid, column_number). This looks like col_description('foo'::regclass, 0) to get the first column. I don't think we can assume that the table has the same column ordering as the Persistent representation, so we'd want to associate the column names with their indices.

This StackOverflow question has some helpful info for retrieving the comments in SQL.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no files, tests, or entry points. Start by tracing the PostgreSQL migration path and how the Persistent representation maps column names, then consult PostgreSQL COMMENT and col_description behavior; done means adding and checking table and column documentation comments without relying on column order.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell, postgresql
Domain
databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.