Skip to content

docs: add PostgreSQL coverage to installation page #173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dimitri-yatsenko wants to merge 1 commit into
base: main
Choose a base branch
from
+28 −5
Open

docs: add PostgreSQL coverage to installation page #173

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions src/how-to/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ pip install datajoint[viz]
# For polars DataFrame support
pip install datajoint[polars]

# For the PostgreSQL backend (psycopg2-binary) — added in 2.1
pip install datajoint[postgres]

# For cloud storage backends
pip install datajoint[s3] # AWS S3
pip install datajoint[gcs] # Google Cloud Storage
Expand Down Expand Up @@ -51,27 +54,37 @@ print(dj.__version__)

## Database Server

DataJoint requires a MySQL-compatible database server:
DataJoint connects to either MySQL or PostgreSQL. MySQL has been supported since the original release; PostgreSQL support was added in **2.1**, and the `database.name` setting for selecting a non-default PostgreSQL database was added in **2.2.1**. See [Configure Database Connection](configure-database.md#postgresql-backend) for the full configuration reference.

### Local Development (Docker)

```bash
# MySQL
docker run -d \
--name datajoint-db \
-p 3306:3306 \
-e MYSQL_ROOT_PASSWORD=simple \
mysql:8.0
```

```bash
# PostgreSQL (added in 2.1)
docker run -d \
--name datajoint-db \
-p 5432:5432 \
-e POSTGRES_PASSWORD=simple \
postgres:15
```

### DataJoint.com (Recommended)

[DataJoint.com](https://datajoint.com) provides fully managed infrastructure for scientific data pipelines—cloud or on-premises—with comprehensive support, automatic backups, object storage, and team collaboration features.

### Self-Managed Cloud Databases

- **Amazon RDS** — MySQL or Aurora
- **Google Cloud SQL** — MySQL
- **Azure Database** — MySQL
- **Amazon RDS** — MySQL, Aurora MySQL, PostgreSQL, or Aurora PostgreSQL
- **Google Cloud SQL** — MySQL or PostgreSQL
- **Azure Database** — MySQL or PostgreSQL

See [Configure Database Connection](configure-database.md) for connection setup.

Expand All @@ -89,6 +102,14 @@ See [Configure Database Connection](configure-database.md) for connection setup.
pip install pymysql --force-reinstall
```

### `psycopg2` connection errors

```bash
pip install datajoint[postgres] --force-reinstall
```

The PostgreSQL backend (added in 2.1) requires the `postgres` extra, which installs `psycopg2-binary`.

### SSL/TLS connection issues

Set `use_tls=False` for local development:
Expand All @@ -99,8 +120,10 @@ dj.config['database.use_tls'] = False

### Permission denied

Ensure your database user has appropriate privileges:
Ensure your database user has appropriate privileges. MySQL example:

```sql
GRANT ALL PRIVILEGES ON `your_schema%`.* TO 'username'@'%';
```

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