docs: add PostgreSQL coverage to installation page#173
Conversation
MilagrosMarin
left a comment
There was a problem hiding this comment.
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.mdand 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).
ff13547 to
550e053
Compare
Summary
datajoint[postgres]extra and the PostgreSQL Docker setup so the Installation how-to matches multi-backend support, not just MySQL.database.namesetting introduced in 2.2.1. Adds apsycopg2troubleshooting subsection and a pointer toconfigure-database.md#postgresql-backendfor the full reference.Test plan
mkdocs serveand open/how-to/installation/— confirm both Docker snippets render, thedatajoint[postgres]extra is visible, cloud DB list shows PostgreSQL, and thepsycopg2troubleshooting subsection appears.configure-database.md#postgresql-backendlink and confirm it lands on the right anchor.