Create and manage a database
Orchard runs managed Postgres databases in your cluster, next to the apps that use them. Each database belongs to a project and runs as a CloudNativePG cluster. CloudNativePG is the Kubernetes operator that handles failover, storage, and backups, so you do not run Postgres by hand.
Create a database
Section titled “Create a database”- Open a project.
- Select New app.
- In Start from scratch, select Postgres.
- In Start from, keep Empty. You can also select Import from URL or Copy of a database.
- In Database name, enter a name.
- In Postgres version, select a version.
- In Storage size, set the volume size. The default is 1 GiB.
- In Resources, set the CPU, memory, and Instances.
- Select Create database.
orchard db create --name appdb --pg-major 17 --storage 10Gi --waitTo seed the database from another Postgres server, add --restore-from postgres://....
Connect an app
Section titled “Connect an app”To connect an app in the same project, use a reference. A reference follows the database through a password rotation or a restore.
- Open the app.
- Go to Variables.
- Add a variable named
DATABASE_URL. - In the value field, select Use a resource.
- Select the database.
- Select Save.
orchard deploy bindings add <app-id> --database appdbGet a connection string
Section titled “Get a connection string”- Open the database.
- Select Connect.
- Select Private to connect from apps in this project, or Public to connect from anywhere.
- Select a format: URI, psql, .env, or JDBC.
- For a private connection, select the instances: Primary, Standbys, or Any.
The private host is a cluster-internal address, such as pg-<name>-rw.<namespace>.svc.cluster.local. Traffic to it stays inside the cluster. Apps in the same project use this address.
To print the connection details from the CLI, run orchard db connection <id>. To open a psql session, run orchard db psql <id>, or use the console on the database page. The session runs in a sandboxed client pod in your namespace as the app role, and ends when you quit psql.
Set CPU and memory
Section titled “Set CPU and memory”Set CPU and memory under Settings > Resources, or with orchard db resources set <id>. Changing them restarts the database.
Orchard sizes shared_buffers and backup compression from the memory limit, and recalculates them when the memory changes. To set shared_buffers yourself, refer to Change Postgres parameters.
Manage a database
Section titled “Manage a database”| Task | Location | Refer to |
|---|---|---|
| Read logs and open a shell | Overview | Logs and shell |
| Take and restore backups | Backups | Back up and restore a database |
| Read metrics and query performance | Observe | Monitor a database |
| Rename, stop, or delete the database | Settings > General and Danger zone | Delete a database |
| Grow storage | Settings > Resources | Grow database storage |
| Change protection settings | Settings > Protection | Protect a database |
| Upgrade Postgres | Security | Upgrade Postgres |
| Add standbys | Settings > High availability | Configure high availability |
| Turn on the pooler | Settings > Connection pooler | Use a connection pooler |
| Add users | Settings > Users | Add database users |
| Change parameters | Settings > Parameters | Change Postgres parameters |
| Install extensions | Settings > Extensions | Install Postgres extensions |
Public access
Section titled “Public access”By default, only apps in the project can connect. Public access assigns a port on the organization’s public IP address, so you can connect from your computer or a business intelligence tool.
Prerequisites
Section titled “Prerequisites”- A layer 4 (L4) load balancer in the cluster.
- A public IP address. To set one for your organization, go to Organization settings > Database defaults > Public database IP. Otherwise, the organization inherits the instance default.
Public access is not available in Cloudflare Tunnel mode, because tunnels carry HTTP only.
Turn on public access
Section titled “Turn on public access”- Open the database.
- Go to Settings > Public access.
- Turn on Reachable from the internet.
The connection string appears when the load balancer assigns the address. If the section shows an error, refer to Troubleshoot a public address.
orchard db public enable <id>Delete a database
Section titled “Delete a database”Deleting a database moves it to Recently deleted on the project for 30 days. You can bring it back only if it had at least one completed backup. For the steps, refer to Recover a deleted database.
- Open the database.
- Go to Settings > Danger zone.
- Select Delete database.
- Confirm the deletion.
orchard db delete <id>Related resources
Section titled “Related resources”- Read replicas - Send read-only traffic to standbys through a separate endpoint.
- Connect an app to a database or app - Learn how references keep connection strings current.
orchard dbreference - Review every database command and flag.