What Database Does Plane Use? PostgreSQL 15.7 Configuration and Setup

Plane uses PostgreSQL 15.7 (Alpine Linux variant) as its primary relational database, configured through Django’s django.db.backends.postgresql engine.

The open-source project management platform Plane persists all application data in PostgreSQL. According to the makeplane/plane source code, the backend Django application explicitly declares django.db.backends.postgresql as its database engine and ships with Docker Compose configurations that pin the official postgres:15.7-alpine image. This setup ensures identical database behavior across local development, continuous integration, and production deployments.

PostgreSQL Version and Docker Configuration

Plane standardizes on PostgreSQL 15.7 using the lightweight Alpine Linux variant. The repository’s orchestration files hardcode this version to prevent drift between environments.

In docker-compose.yml (alongside docker-compose-local.yml and docker-compose-test.yml), the database service definition specifies:

services:
  db:
    image: postgres:15.7-alpine
    command: postgres -c 'max_connections=1000'
    environment:
      POSTGRES_DB: plane
      POSTGRES_USER: plane
      POSTGRES_PASSWORD: plane
    volumes:
      - pgdata:/var/lib/postgresql/data

The command override adjusts max_connections to 1000, accommodating Plane’s concurrency requirements. Using the same 15.7-alpine tag across all compose files guarantees that developers and CI pipelines run the identical minor version as production systems.

Django Database Engine Configuration

The Plane backend—implemented in Django—configures its database connection in apps/api/plane/settings/common.py. This file defines the DATABASES dictionary that instructs Django to use the PostgreSQL backend.

Primary Database Engine

The configuration explicitly sets the engine to PostgreSQL:

# Located in apps/api/plane/settings/common.py

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        # ... additional connection parameters

    }
}

This hardcoded engine string prevents runtime database swapping and ensures Plane utilizes PostgreSQL-specific features.

Connection Parameters

Plane supports two methods for supplying connection details: a unified URL string or discrete environment variables. The logic in apps/api/plane/settings/common.py checks for DATABASE_URL first, falling back to individual parameters if the URL is absent:

import os
import dj_database_url

if os.getenv("DATABASE_URL"):
    DATABASES = {"default": dj_database_url.config()}
else:
    DATABASES = {
        "default": {
            "ENGINE": "django.db.backends.postgresql",
            "NAME": os.getenv("POSTGRES_DB"),
            "USER": os.getenv("POSTGRES_USER"),
            "PASSWORD": os.getenv("POSTGRES_PASSWORD"),
            "HOST": os.getenv("POSTGRES_HOST"),
            "PORT": os.getenv("POSTGRES_PORT", "5432"),
        }
    }

The dj_database_url library parses DATABASE_URL (e.g., postgres://user:pass@host:5432/dbname) into Django’s expected format. When the URL variable is missing, Plane reads POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST, and POSTGRES_PORT directly.

Environment Variables and Connection Setup

Database credentials are externalized via environment variables, with templates provided in .env.example. Key variables include:

• DATABASE_URL – A RFC 1738-compliant connection URL that supersedes individual variables.
• POSTGRES_DB – The target database name (default: plane).
• POSTGRES_USER – The PostgreSQL role for authentication.
• POSTGRES_PASSWORD – The corresponding password.
• POSTGRES_HOST – The hostname or IP of the PostgreSQL server.
• POSTGRES_PORT – The TCP port (defaults to 5432).

This dual-configuration approach allows Plane to deploy seamlessly on managed database services (using DATABASE_URL) or traditional VM-based PostgreSQL instances (using discrete variables).

Summary

• Plane uses PostgreSQL 15.7 (Alpine variant) as specified in docker-compose.yml and sibling files.
• Django configuration in apps/api/plane/settings/common.py hardcodes django.db.backends.postgresql as the engine.
• Connection flexibility is achieved through DATABASE_URL (preferred) or individual POSTGRES_* environment variables.
• Consistency is enforced by pinning postgres:15.7-alpine across development, test, and production environments.

Frequently Asked Questions

What specific PostgreSQL version does Plane require?

Plane officially targets PostgreSQL 15.7 via the postgres:15.7-alpine Docker image. While the Django backend may function with other PostgreSQL versions, the 15.7 Alpine build is the only version validated in the official Docker Compose files and CI pipelines.

Can I use MySQL or another database instead of PostgreSQL with Plane?

No. The ENGINE parameter in apps/api/plane/settings/common.py is hardcoded to django.db.backends.postgresql. Changing this value would break application functionality, as Plane relies on PostgreSQL-specific SQL extensions and data types.

Where is the database connection configured in Plane's codebase?

The primary configuration resides in apps/api/plane/settings/common.py. This file contains the DATABASES dictionary that defines the PostgreSQL engine and logic for parsing DATABASE_URL or individual POSTGRES_* environment variables.

How does Plane handle database connection strings?

Plane uses the dj_database_url library to parse DATABASE_URL when present. If DATABASE_URL is unset, it constructs the connection dictionary from separate environment variables (POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_PORT), defaulting the port to 5432.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}