Skip to content

docs: add PostgreSQL coverage to installation page#173

Open
dimitri-yatsenko wants to merge 1 commit into
mainfrom
docs/installation-postgres
Open

docs: add PostgreSQL coverage to installation page#173
dimitri-yatsenko wants to merge 1 commit into
mainfrom
docs/installation-postgres

Conversation

@dimitri-yatsenko
Copy link
Copy Markdown
Member

Summary

  • Documents the datajoint[postgres] extra and the PostgreSQL Docker setup so the Installation how-to matches multi-backend support, not just MySQL.
  • Reframes the page from "MySQL-compatible" to MySQL/PostgreSQL as peer backends, and expands the cloud-database list (RDS, Cloud SQL, Azure Database) to include PostgreSQL.
  • Adds version notes: PostgreSQL backend introduced in 2.1, database.name setting introduced in 2.2.1. Adds a psycopg2 troubleshooting subsection and a pointer to configure-database.md#postgresql-backend for the full reference.

Test plan

  • mkdocs serve and open /how-to/installation/ — confirm both Docker snippets render, the datajoint[postgres] extra is visible, cloud DB list shows PostgreSQL, and the psycopg2 troubleshooting subsection appears.
  • Click the configure-database.md#postgresql-backend link and confirm it lands on the right anchor.
  • Re-read for peer framing — PostgreSQL should never be described as an "alternative" backend.

Copy link
Copy Markdown
Collaborator

@MilagrosMarin MilagrosMarin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @dimitri-yatsenko! Verified the version claims and packaging end-to-end:

datajoint[postgres] extra exists in datajoint-python/pyproject.toml: postgres = ["psycopg2-binary>=2.9.0"]
✅ PostgreSQL in 2.1 — confirmed via git tag --contains on the PG-compat commits in datajoint-python (first land in v2.1.0).
database.name in 2.2.1 — confirmed: commit 58de0f32 feat: add dbname setting for PostgreSQL connections first appears in tag v2.2.1.
configure-database.md#postgresql-backend anchor exists (line 129).
✅ PostgreSQL 15+ / MySQL 8.0.13+ are consistent across CONTRIBUTING.md, src/about/whats-new-21.md, src/how-to/testing.md, src/how-to/configure-database.md, and the new installation page.
✅ Cloud DB expansion accurate — RDS Aurora MySQL/PostgreSQL, Cloud SQL, Azure Database all support PostgreSQL.

Two issues worth addressing — both small but visible to readers:

1. The linked target still uses the "alternative" framing this PR explicitly rejects. src/how-to/configure-database.md:131-132:

!!! version-added "New in 2.1"
    PostgreSQL is now supported as an alternative database backend.

A reader follows the new peer-framed link from installation.md (line 57) → configure-database.md#postgresql-backend → and lands on "alternative database backend" immediately. Suggest reframing the admonition body in the same PR, e.g.:

!!! version-added "New in 2.1"
    PostgreSQL is supported as a peer database backend alongside MySQL.

2. The new GRANT pointer is dangling. Line 129 of installation.md:

PostgreSQL uses a different `GRANT ... TO username` syntax — see [Configure Database Connection](configure-database.md#postgresql-backend) for backend-specific guidance.

The #postgresql-backend section (lines 129–220 of configure-database.md) covers configuration, env vars, programmatic config, docker-compose, and backend compatibility — but has no GRANT / permission content. A reader following this link will not find what they were promised.

Two reasonable fixes:

  • Drop the link and just inline a one-line PostgreSQL example, e.g. GRANT ALL PRIVILEGES ON DATABASE my_db TO username;
  • Or add a "Database permissions" subsection to configure-database.md and point there.

Optional nit: Worth noting briefly that pre-2.2.1 PostgreSQL connections were limited to the default postgres database — that's the context the database.name setting unlocked. Not load-bearing, just a sentence.

Otherwise this is a clean, well-scoped expansion. Happy to approve once the two pointer issues are sorted.

Bring the Installation how-to in line with multi-backend support:
- document the `datajoint[postgres]` extra (added in 2.1)
- replace "MySQL-compatible" with peer MySQL/PostgreSQL framing
- add a PostgreSQL Docker snippet beside the MySQL one
- list PostgreSQL options for RDS, Cloud SQL, and Azure Database
- add a psycopg2 troubleshooting subsection
- note PostgreSQL GRANT syntax differs, link to configure-database.md

Version notes call out 2.1 (initial PostgreSQL backend) and 2.2.1
(`database.name` setting for selecting a non-default PostgreSQL database).
@dimitri-yatsenko dimitri-yatsenko force-pushed the docs/installation-postgres branch from ff13547 to 550e053 Compare May 21, 2026 16:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants