Databases

Create PostgreSQL, Redis, and MongoDB databases from the Upvale dashboard and run them on the servers in your project's cluster. Choose a single server for a straightforward setup, or managed PostgreSQL high availability for automatic failover and optional replica reads.

Find your way around

Open Workloads, select the project and environment, then open the database. Its header shows the engine, image or managed release, runtime status, and available deployment actions.

Tabs and actions depend on your role and the engine. Missing engine-specific features are identified on the page.

Choose a database type

Single-node images remain under your control and are not upgraded automatically. You can use a compatible custom image for the selected engine; its image reference must contain postgres, redis, or mongo/mongodb, respectively. Managed HA uses Upvale's supplied PostgreSQL release and does not accept a custom image.

Redis has two single-node storage choices:

• Persistent creates a data volume on the selected Storage node. Backups require RDB snapshots to remain enabled in Configuration.
• Ephemeral creates no data volume and uses the selected Runtime node. Data can disappear after a restart or redeployment. Use it for disposable caches; backups are unavailable.

Create and deploy a database

Before you start, select a project environment assigned to a cluster with an online, active server. Creating a database requires Manage databases and Manage secrets permissions; deployment also requires Manage deployments.

1. Open your project and select the target environment. Choose Add Service → Database, or New database where shown.
2. Under Database type, choose Single Node or Managed High Availability.
3. Enter a Name and check Project. For Single Node, select Engine and Image. For Managed High Availability, select PostgreSQL version.
4. Under Credentials, enter Database user and review the generated Password. PostgreSQL and MongoDB also have an optional Database name; if empty, it defaults to the database slug. Use lowercase letters, digits, and underscores for the user name.
5. Choose Storage node for persistent single-node databases, or Runtime node for ephemeral Redis. For HA, choose Initial primary node, set Standby servers, and choose a different server in each Standby node field.
6. Optionally configure Reads from failover nodes for HA PostgreSQL, as described below.
7. Select Create database. This saves the database; it stays offline until deployed.
8. Open the new database and select Deploy as revision v1. Follow progress in Deployments. After deployment succeeds, open Connection for the application credentials.

For a custom PostgreSQL image, expand Advanced → Data volume path if Upvale cannot infer the storage path. Official PostgreSQL 18 and later use /var/lib/postgresql; official PostgreSQL 17 and earlier use /var/lib/postgresql/data. Vendor images may require a different path from their own documentation.

A simple first PostgreSQL database

Choose Single Node, keep the suggested PostgreSQL image, and enter a name such as app-db and user such as app_user. Keep the generated password and select an online storage node. Create, deploy, then copy the Internal connection URL from Connection into a secret used by your application.

For HA, use Managed High Availability, the recommended release, and three distinct nodes: one initial primary and two standbys. You do not need to configure replication manually. The cluster must have at least three online, active Swarm nodes; merely enrolled or drained nodes do not qualify.

Creation fields

Persistent storage

A persistent single-node database and its volume stay on the selected storage node. Restarting or redeploying the service reuses that volume. If the server is lost, the volume does not automatically move to another server; recovery requires the existing storage or a backup restored to a new database.

For HA, each primary or standby member has a separate local volume containing a full replica of the database data. Adding standbys provides redundancy and optional read capacity; it does not combine the servers' disks into a larger database or distribute writes across them.

Review data-retention choices when using Delete database. The deletion dialog lets you retain data or permanently delete the associated volumes. Keeping a volume is not a substitute for a backup.

Connect an application

Open the database's Connection tab. Internal credentials contains User, Password, Internal host, Internal port, and Internal connection URL. PostgreSQL and MongoDB also show Database name.

Use the internal connection URL from an application attached to the cluster's private service network. Default ports are PostgreSQL 5432, Redis 6379, and MongoDB 27017. Keep connection credentials in application secrets rather than source code.

When Connection displays PostgreSQL TLS details, use the generated URL with sslmode=require. It also provides the PostgreSQL public CA certificate for clients using sslmode=verify-ca. The certificate identifies the internal service name; an unrelated external hostname is not suitable for verify-full.

External access

To connect through a published TCP endpoint, use Connection → External access:

1. Set External port (Internet). Leave it empty to disable external access.
2. Set External host if needed. For Single Node, this can be a DNS name or floating IP; otherwise Upvale uses the detected public node address. HA requires a stable DNS name, floating IP, or load-balancer address that reaches the cluster.
3. Select Save changes, then deploy the saved revision. Allow the chosen port in the relevant firewall or cloud security group.
4. Use the displayed External connection URL when it is available.

A single-node endpoint is published on its storage or runtime node. For HA, point your stable external address at the cluster's replicated writer endpoint; one member's address alone is not a failover-safe endpoint. PostgreSQL external access uses its managed TLS endpoint. Publishing Redis or MongoDB does not add TLS to their database protocols.

Connect from your laptop

Use Developer VPN when your developer needs private database access without publishing a database port to the Internet. The cluster's Developer VPN configuration controls which networks, destinations, and ports that person can reach. They enroll a device through Profile → VPN access, download its WireGuard configuration, and connect their database client to an allowed database endpoint.

Use the host and access details shown for the granted network. A working tunnel does not make every cluster destination reachable: both the network route and the access rule must allow the connection. Ordinary service-network DNS names are not automatically your laptop's DNS names. See the Developer VPN guide for client configuration and destination selection.

The WireGuard configuration uses split routing for the granted networks. Other traffic keeps using the laptop's normal connection. Database authentication still applies; VPN access does not create a database login or grant database permissions.

Change a password

PostgreSQL and Redis expose Connection → Internal credentials → Change password. Enter a password of at least 16 characters and save it. A running database is redeployed to apply the password. Follow the operation and update clients after it succeeds. If no deployment is queued, the page tells you that the password will apply on the next deploy or start.

MongoDB does not currently offer password rotation through this screen. The HA reader password is a separate credential from the writer password.

PostgreSQL high availability

Managed HA requires at least three online, active servers in the cluster, even with one standby. The default is two standby servers. Choose 1–4 standby servers in addition to the initial primary, with each database member on a distinct server. The available count is limited by your eligible servers. Upvale manages the election service automatically.

HA is designed to tolerate one simultaneous server failure, with an eligible standby and election quorum available. More standbys do not increase the election quorum's failure tolerance. If the primary fails, an eligible standby can take over, and the writer endpoint follows the current primary. Applications must reconnect and retry interrupted operations as appropriate; active sessions are not transferred to the new primary.

Writes use one current primary. The application user owns its database without superuser access. Replication normally uses a synchronous standby, but writes remain available when no suitable synchronous standby is available. If the primary then fails, the latest acknowledged transactions may be lost.

Existing Single Node databases are not converted to HA in place. For compatible PostgreSQL backups, Restore can create a new managed HA database with fresh credentials. Test the restored database and update your application's connection when ready to switch.

Inspect the HA members

Open Deployments → High availability:

• Primary identifies the current writer.
• Election quorum shows whether the election service has enough members to make decisions.
• Quorum voters shows running voters and the number required.
• Further failures shows remaining election-service failure tolerance.
• Each Member shows its server, role, state, replication timeline, and replication lag.
• Refresh status requests a new observation.

A standby is another full PostgreSQL server following the primary. The election service decides which member may be primary. Upvale runs three voters, of which two are needed for quorum. This is separate from how many database standbys you selected.

Switch the primary deliberately

1. Open Deployments → High availability.
2. Under Planned primary, select an eligible synchronous standby.
3. Select Switchover primary and confirm.
4. Follow the operation and refresh the member status.

Use this for planned maintenance. The writer endpoint stays the same, but open client connections may need to reconnect. If no eligible synchronous standby is listed, restore the member's health before trying a planned switchover.

Rebuild a replica

Reinitialize rebuilds a reachable replica from the primary. It is for a replica that needs a fresh copy, not for the current writer. Confirm Reinitialize replica and wait for replication to catch up.

Reinitialization replaces that replica's local database contents. Do not use it if the member holds the only copy of data you need to recover.

Replace a dead member

Use Replace dead member for a permanently unavailable non-primary member. This requires database and infrastructure management permissions.

1. Power off the old server or block it from starting at the provider or hypervisor. Confirm that its disks will be wiped before reuse. Disconnecting its network or agent alone is not enough.
2. Select a Replacement server with capacity for a full copy.
3. If the old server was selected for reads, explicitly choose whether to use the replacement for reads, remove the old reader selection, or disable replica reads when it was the only selected reader.
4. Confirm Replace and rebuild.
5. Follow the operation until the new replica is healthy. Use Resume replacement if a partially completed replacement needs to continue.

The replacement receives a new volume and copies data from the primary. The old volume is retained and is not automatically reused. Large databases can take time to copy; the new member is not redundant protection until it has caught up.

Read from PostgreSQL failover nodes

Managed HA PostgreSQL can also serve application reads from selected standby members. Enable this during creation, or open the database's Database tab and find Reads from failover nodes.

1. Set Reads from failover nodes to On.
2. Select the standby servers under Eligible replica nodes.
3. Choose how Current primary should participate, using the modes below.
4. Select Save changes when editing an existing database, then deploy the saved revision.
5. Open Connection → Read-only connection and use its Read-only connection URL in a separate application connection pool for reads.

The reader has its own Read-only user and Read-only password. It uses the same internal hostname on port 5433. Reader access is internal only; publishing the writer's external port does not publish the reader endpoint.

Always use selected replicas

Leave Current primary unchecked. New reader connections are balanced across selected healthy replicas. If none are available, the reader endpoint cannot serve connections until a selected replica recovers; it does not fall back to the primary.

Offload reads when the primary is busy

Select Current primary to serve reads from the primary normally. Set CPU threshold (%) and For (minutes) to move new reader connections to selected replicas after sustained load. The default is above 80% for one minute; the supported range is 1–99% for 1–60 minutes.

The threshold measures CPU across the current primary's host, including other workloads. It is not PostgreSQL-only CPU. Reads return to the primary after CPU stays below 75% of your configured threshold for five minutes: with an 80% threshold, that means below 60%. Missing fresh metrics or unavailable selected replicas cause this mode to use the primary when available.

Selection and connection behavior

Current primary follows the primary role after failover. Standby selections follow physical nodes and apply only while those nodes are replicas. Review the selection after replacing a member; its replacement is not automatically selected.

Upvale filters out unhealthy or excessively lagging replicas. Eligible replicas need a fresh running observation and replication lag no greater than 16 MiB. Replica reads can still lag behind the primary. Send writes and reads that must immediately reflect a preceding write to the writer connection.

Upvale routes connections, not individual SQL statements. It does not inspect SQL or split reads and writes automatically. Existing connections stay with their assigned member; failover or reader-proxy updates can require pooled connections to reconnect. Configure your application pool to recover from disconnected connections and retry reads where appropriate.

The routing status shows whether it is waiting, using the primary, balancing replicas, or unavailable. Saved changes remain pending until deployed. A primary change starts a new CPU measurement window; stale metrics cannot satisfy the sustained-load threshold.

Back up and restore a database

Database backups support PostgreSQL, persistent Redis with RDB enabled, and MongoDB. They protect the customer database selected in your project. HA replication does not replace backups: an accidental data change can reach the replicas too.

1. Configure an organization destination in S3 Destinations, following Storage and backup destinations.
2. Open your deployed database's Backups tab.
3. In Backup policy, select one or more Destinations, set Schedule (cron) and Timezone, and optionally set Retention (count). Check Enabled for scheduled backups, then select Save changes.
4. Select Back up now for an immediate run. Inspect Backup history, including the result for each destination. An encrypted backup is saved to each selected destination.

For example, the five-field cron expression 0 3 * * * runs daily at 03:00 in the selected time zone. PostgreSQL backups are logical dumps; Redis uses RDB snapshots; MongoDB uses compressed database archives. PostgreSQL point-in-time recovery and continuous WAL archiving are not currently available.

To restore, select Restore beside a successful backup. In Restore to a new database, enter New database name and choose Restore target. PostgreSQL offers New single-node database or New managed HA PostgreSQL; HA additionally requires a managed release and distinct primary and standby nodes. Select Restore and follow the operation's progress.

A restore creates a new database with fresh credentials and leaves the source database unchanged. The Database credentials dialog shows the new login; you can also find it later in the new database's Connection tab. Check the restored result before updating your application connection. A newly restored HA database starts with replica reads disabled; enable them and select reader nodes after deployment if needed. In-place restore is not supported.

Backup policy options

Backup history shows each run's status, size, checksum, and destination results. Check each destination: one successful copy does not mean every destination upload succeeded. Restore requires a usable completed copy and working access to its destination. Keep the destination available for as long as you need its backups, and update its stored credentials when they change.

Restoring a backup is separate from comparing a database revision. A revision records configuration; it does not contain the database's data.

Apply later changes

Use the Database tab for the database image or managed release information, storage, resource settings, and HA reader settings. PostgreSQL and Redis expose engine settings in Configuration; PostgreSQL also provides Extensions. MongoDB does not currently have integrated engine-configuration or live database-statistics controls, although container metrics and logs remain available.

Select Save changes, then Deploy as revision v… to apply saved runtime settings. Review Deployments, Logs, and Monitoring if deployment or application connectivity needs attention. Controls and credential details are shown according to your organization permissions.

Database tab options

For a single-node database, Image changes the image used on the next deployment. Review engine compatibility before changing a major version: changing an image tag is not a data migration.

For custom single-node PostgreSQL, Advanced contains:

Do not put credentials in a preparation script: it is stored in revision history. Runtime extension-package installation and this pre-start script cannot be used together.

Storage displays the volume, container path, server, and observed host path. The host path can remain pending until the agent reports it. HA lists these details for each member. Storage placement does not move existing data automatically.

Resources sets CPU, memory, shared memory, and process limits. These have the same meanings as application resource settings. For HA, size every node for the database member it will run.

Change Redis storage mode

In Database → Redis storage, choose Persistent or Ephemeral, select the available node, acknowledge data loss, save, and deploy.

Changing storage mode discards the running instance's in-memory data. Switching to ephemeral keeps any existing persistent volume for later reattachment. Switching back uses that retained volume on its original node, rather than copying the current cache into it. If no retained volume exists, Upvale creates a new persistent instance. Moving an ephemeral instance to another node also discards its current memory contents.

Managed PostgreSQL updates

The PostgreSQL updates section lists supported updates for the selected managed release. Each row shows the target release, update strategy, whether a backup is required, and its available action. Deploy the selected release before requesting another update. For an incomplete release transition, retry the upgrade operation shown on the page.

The release catalog determines which upgrades are supported. The ordinary deployment button is not a substitute for an offered upgrade operation.

Engine configuration

Use Configuration for PostgreSQL and Redis. Enter one setting=value per line; blank lines and lines starting with # are ignored. PostgreSQL values can have outer quotes. Save, then deploy. Invalid engine settings can fail during deployment, and some changes restart PostgreSQL.

For PostgreSQL, common settings include:

These are engine settings, not the container's resource limits. For example, shared_buffers=256MB still needs room within the container's memory limit for connections, query work, and the rest of PostgreSQL.

Live settings (pg_settings) reads the running server. Select Load from instance, then filter to find a setting. It shows the actual value, units, change context, description, and whether a restart is pending. Hide closes the table. Saved configuration and live values can differ until deployment finishes.

For Redis, common settings include:

Disabling persistence can discard data on restart. MongoDB does not have an integrated configuration editor in the current UI.

PostgreSQL extensions

The Extensions tab separates what you want installed from what the running server reports.

Plan an extension

Extension plans are available for custom single-node PostgreSQL. Managed HA shows its runtime capabilities but does not accept these custom installation plans.

1. Open Extensions.
2. Choose a common suggestion, or enter Extension name and select Add extension.
3. Leave Runtime Debian packages blank if the image already contains the extension. Otherwise enter compatible package names, one per line or separated by commas.
4. Enter any required Preload libraries, also one per line or comma-separated.
5. Check PostgreSQL entrypoint path for the image.
6. Save and deploy.
7. Check Observed and the Live extension catalog for the installed version.

Runtime Debian packages are operating-system packages providing extension files. Preload libraries are libraries PostgreSQL must load when it starts. Extension name is the SQL extension to enable. These names are related but are not necessarily identical.

Package installation requires Manage secrets, a compatible Debian-based runtime, and access to the package repository. Packages install as root when a container is replaced. A missing package or library can prevent startup. Using an image that already contains the required extension avoids that installation dependency.

Read the live catalog

The catalog comes from PostgreSQL's available extensions. Available means the server has its files; Installed means it is enabled in the database. Add to plan adds an available extension to the desired configuration. A missing observation after a deployment needs investigation; it does not prove the extension is installed.

You can remove an unapplied plan. Installed extensions cannot be uninstalled through this screen, because dependent database objects may use them.

Deployments and runtime actions

Deployments compares Desired configuration with Last successful deployment. Running replicas lists active containers; Starting and previous replicas helps diagnose starts and replacements. Revision history → Compare revisions shows configuration differences using From and To selectors.

Database revision history does not provide the application's one-click rollback action. Use a compatible configuration change or restore a backup to a new database when data recovery is needed.

Open Terminal beside a running single-node container when your role allows it. Interactive terminals are not available for managed HA database members. Use the regular database connection for SQL access.

Compose-owned databases show their ownership on the detail page. Edit their imported configuration through the project's Compose workflow.

Monitoring and logs

Logs provides task selection, tail length, stdout/stderr filtering, search, and download of the displayed lines. Use it for startup errors, failed authentication, or engine messages.

Monitoring → Live instance metrics refreshes every 15 seconds:

• PostgreSQL shows connection usage, database size, cache-hit ratio, commits, rollbacks, locks, deadlocks, and user-table count.
• Redis shows keys, current and peak memory, connected clients, operations per second, hits and misses, evictions, and uptime.
• MongoDB has historical container metrics, but no integrated live engine-statistics view.

Historical metrics shows resource trends over your chosen period. Missing live engine statistics do not necessarily mean the database is down; check the displayed query error and container state.

Recovery and deletion

A working backup restored into a new database is the usual recovery path. Test it before changing application credentials or removing the original database.

If Upvale offers Repair database for a damaged PostgreSQL instance, it is a last-resort operation. Snapshot and repair stops the database, snapshots its volume, and runs pg_resetwal. It can lose committed data or leave inconsistencies. Read and type the required acknowledgement. After repair, immediately make a logical dump and restore it to a fresh database, even if the server appears healthy.

To delete a database, open Database → Danger zone → Delete database. Review Delete data volumes carefully: checked permanently deletes the stored data; unchecked retains the volumes. Type the exact database name and follow the cleanup operation. HA deletion includes the proxy, member services, secrets, and the selected handling of all member volumes.

When no manager is online, Remove database record only cannot clean up servers. It leaves services, secrets, and data on those servers and requires explicit acknowledgement.

Common problems