# Database planning

The PostgreSQL database is a critical, client-provided component. It serves as the central source of truth for the platform. Ensuring correct configuration, resilience, and accessibility is a primary client responsibility.

## Core requirements

Before installation, you must provision a PostgreSQL database instance that meets the following requirements:

* **Minimum version:** The platform requires PostgreSQL v14+ or higher.
* **Required plugins:** You **must** install, enable, and make accessible to the application user the following plugins:
  * `hstore`
  * `uuid-ossp`
  * `plpgsql`
* **Schema management:** You are responsible for creating the initial database and the user credentials. The Ripple Custody application manages its own schema within that database upon successful connection.


## High availability (HA) and management

As this is a client-managed component, you are fully responsible for the end-to-end lifecycle of the database. This includes:

* **Deployment and lifecycle:** Initial deployment, version upgrades, and decommissioning.
* **High Availability (HA):** Ensuring the database is highly available. We strongly recommend a production-grade 3-node cluster with synchronous replication and automated failover. Use Patroni or a managed cloud service.
* **Backup and disaster recovery (DR):** You are responsible for all database backup, replication, and DR procedures. Database backups must be time-synced with backups of the notary's anti-rewind file (ARF).


## Network connectivity

Enterprise network environments typically use a "default-deny" security posture. Your internal network and firewall teams must explicitly enable all required communication paths.

Verify that nodes in the OpenShift/Kubernetes cluster have network access to the database instance/cluster endpoint.

**Critical network consideration:**

In on-premises environments, the application cluster, the database, and the HSM may not be on the same network segment. They are often on different logical or even physical networks.

Assume that a connection from the application to the HSM spans two separate internal networks. This connection will fail unless you open a specific route. Also validate any required connections from your internal network to external services, such as Ripple or blockchain node providers.

## Checklist: Before you proceed

### Decisions made

- [ ] **Deployment model**: Self-managed PostgreSQL cluster OR managed cloud service.
- [ ] **HA topology**: 3-node cluster with synchronous replication planned.
- [ ] **Backup strategy**: Backup frequency, retention, and time-sync with ARF backups defined.


### Artifacts ready

- [ ] PostgreSQL cluster provisioned (v14 or higher)
- [ ] Required plugins enabled: `hstore`, `uuid-ossp`, `plpgsql`
- [ ] Database created with application user credentials
- [ ] Connection string documented: `host`, `port`, `database`, `username`
- [ ] Firewall rules updated: Kubernetes cluster to PostgreSQL endpoint
- [ ] SSL/TLS configuration documented (certificate, CA, mode)


### Configuration reference

For Helm values, SSL modes, schema isolation, and cloud database examples, see [PostgreSQL configuration](/products/custody/deployment/reference/postgresql).

### Next step

**Next:** [Message queue planning](/products/custody/deployment/planning/messaging).