Skip to main content

Introduction: Why PostgreSQL in Frappe v15?

Frappe Framework v15 introduces experimental PostgreSQL support, enabling developers to run Frappe sites using PostgreSQL instead of MariaDB. This is particularly useful for organizations standardizing on PostgreSQL or evaluating alternative relational databases for ERPNext deployments.

However, PostgreSQL support in Frappe v15 is not yet production-recommended and comes with known limitations. This guide explains how PostgreSQL works in Frappe, how to configure it correctly, and when it should be used.

What Is PostgreSQL Support in Frappe?

PostgreSQL support allows Frappe to use PostgreSQL as the primary database backend instead of MariaDB. Frappe internally abstracts database operations through its ORM layer, making limited backend switching possible.

Key points:

  • PostgreSQL support is experimental
  • Some features behave differently compared to MariaDB
  • Not all ERPNext apps are fully PostgreSQL-compatible

Current Status of PostgreSQL Support (Important)

As per Frappe v15:

  • PostgreSQL is not the default database
  • MariaDB remains the recommended production database
  • PostgreSQL is suitable for:
    • Development
    • Testing
    • Proof-of-concept environments

ERPNext production deployments should continue using MariaDB unless explicitly tested with PostgreSQL.

Technical Prerequisites

Before starting PostgreSQL setup in Frappe v15, ensure:

  • Frappe Framework Version 15
  • PostgreSQL 12 or higher
  • Bench installed and working
  • PostgreSQL client libraries installed
  • Python dependencies for PostgreSQL available

Supported Frappe Modules with PostgreSQL

PostgreSQL works primarily with core Frappe modules, including:

  • Database
  • Desk
  • Website
  • REST API layer

Some advanced ERPNext modules may show inconsistent behavior.

Step-by-Step: PostgreSQL Setup in Frappe v15

Step 1: Install PostgreSQL

On Ubuntu/Debian systems:

sudo apt update
sudo apt install postgresql postgresql-contrib

Verify installation:

psql --version

Step 2: Create PostgreSQL User and Database

Switch to PostgreSQL shell:

sudo -u postgres psql

Create user:

CREATE USER frappe WITH PASSWORD 'strong_password';

Create database:

CREATE DATABASE frappe_site OWNER frappe;

Grant privileges:

GRANT ALL PRIVILEGES ON DATABASE frappe_site TO frappe;

Exit shell:

\q

Step 3: Install PostgreSQL Python Adapter

Frappe requires psycopg2:

pip install psycopg2-binary

This enables Python-to-PostgreSQL communication.

How Frappe Connects to PostgreSQL

Frappe uses database adapters internally to route ORM queries. When PostgreSQL is enabled:

  • SQL syntax is translated where possible
  • Schema definitions adapt automatically
  • Some MariaDB-specific queries are bypassed

Site Configuration for PostgreSQL

Update your site configuration:

{
"db_type": "postgres",
"db_name": "frappe_site",
"db_password": "strong_password",
"db_user": "frappe",
"db_host": "localhost",
"db_port": 5432
}

This configuration tells Frappe to use PostgreSQL instead of MariaDB.

Creating a Site with PostgreSQL

When creating a new site:

bench new-site site_name \
--db-type postgres \
--db-name frappe_site \
--db-password strong_password

Frappe will initialize schema using PostgreSQL-compatible migrations.

How Frappe Handles ORM Queries with PostgreSQL

Frappe ORM translates most operations transparently:

  • frappe.get_all() → PostgreSQL SELECT
  • frappe.insert() → PostgreSQL INSERT
  • frappe.db.sql() → Limited raw SQL support

However, custom SQL queries must be PostgreSQL-compatible.

Known Limitations of PostgreSQL in Frappe v15

PostgreSQL support has the following constraints:

  • Some ERPNext reports assume MariaDB functions
  • Full-text search behaves differently
  • JSON field handling varies
  • Certain index optimizations are unavailable
  • Migration tools are less mature

Best Practices for PostgreSQL Usage

  • Use PostgreSQL only for development/testing
  • Avoid raw SQL queries
  • Stick to Frappe ORM
  • Test all reports and workflows
  • Do not mix MariaDB and PostgreSQL in same environment

When Should You Use PostgreSQL with Frappe?

PostgreSQL is suitable when:

  • Evaluating database portability
  • Developing custom Frappe apps
  • Researching performance behavior
  • Aligning with PostgreSQL-first infrastructure

It is not recommended for large-scale ERPNext production yet.

Troubleshooting Common Issues

Database Connection Errors

Check:

  • PostgreSQL service status
  • Credentials in site_config.json
  • Port and host availability

Migration Failures

Ensure:

  • Correct database type specified
  • Latest Frappe v15 patches applied
  • No MariaDB-specific SQL exists

Industry Relevance

PostgreSQL support is relevant for:

  • SaaS product builders
  • Research teams
  • ERPNext contributors
  • Organizations exploring database flexibility

Target Audience

  • Frappe Developers
  • ERPNext Architects
  • DevOps Engineers
  • Open-source contributors

Related Topics

  • Frappe Database Architecture
  • MariaDB vs PostgreSQL in ERP Systems
  • Frappe ORM Internals
  • Database Migration in Frappe

Conclusion

PostgreSQL support in Frappe Framework v15 opens new possibilities for experimentation and future database flexibility. While MariaDB remains the production standard, PostgreSQL enables developers to explore alternative database backends within the Frappe ecosystem.
Used correctly, PostgreSQL can be a powerful development and research tool—but production ERPNext deployments should proceed cautiously until support matures.

Rating: 0 / 5 (0 votes)

© 2026 | goERPNext | All rights reserved