Database service backups in NEXUS AI

Database service backups in NEXUS AI: backup, in-place restore, and cross-service restore

Published: May 9, 2026

Category: Databases · DevOps

Reading time: 10 minutes

Author: NEXUS AI Team

Database backups should be boring. You should be able to create one, download it, restore it into the same service, or restore it into a replacement deployment without rebuilding the whole application stack by hand.

NEXUS AI database services now support that full lifecycle for deployment-attached database services. You can back up PostgreSQL, MySQL, MongoDB, and Redis services, restore a backup back into the original service, or restore it into another compatible database service in a different deployment under the same organization.

This post walks through the complete workflow using the dashboard, REST API, CLI, and MCP tools.

What database backups cover

NEXUS AI backups are created from database services attached to a deployment through Additional Services.

Supported engines:

Service	Backup format	Restore behavior
PostgreSQL	pg_dump custom dump	Restores database objects with clean/replace behavior
MySQL	SQL dump	Imports the dump into the target database
MongoDB	compressed mongodump archive	Restores collections with drop behavior
Redis	RDB snapshot	Replaces the target Redis dataset

Backups are organization-scoped. A backup created in one organization cannot be restored into another organization. Cross-service restore is allowed only when the target service belongs to the same organization and uses a compatible database engine.

Backups do not include application code, container images, secrets, deployment configuration, or filesystem volumes. They cover the database service data only.

Create a database backup

First, find the database service you want to back up.

nexus db services
nexus db services <deployment-name-or-id>

Create the backup:

nexus db backup <service-id>

List backups for that service:

nexus db backups <service-id>
nexus db backups <service-id> --json

You can also create a backup through the REST API:

export NEXUS_API_BASE="https://nexusai.run/api"
export NEXUS_JWT="YOUR_JWT_FROM_LOGIN"

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/backup" \
  -H "Authorization: Bearer $NEXUS_JWT"

NEXUS AI runs the native database backup tool inside the running database container and stores the backup record for later download or restore.

Download a backup

For local retention, migration testing, or compliance workflows, download the backup file:

nexus db backup-download <service-id> <backup-id>
nexus db backup-download <service-id> <backup-id> --out ./backups/prod-postgres.dump

To create a short-lived signed download URL:

nexus db backup-download <service-id> <backup-id> --share
nexus db backup-download <service-id> <backup-id> --share --ttl 900

The REST API supports both direct downloads and signed URLs:

curl -L -o backup.dump \
  "$NEXUS_API_BASE/deployment-services/<serviceId>/backups/<backupId>/download" \
  -H "Authorization: Bearer $NEXUS_JWT"

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/backups/<backupId>/download-url" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":900}'

Treat downloaded backup files as sensitive. They may contain production user data, application data, credentials stored in tables, or regulated records.

Restore into the same service

Use in-place restore when you want to roll a database service back to a known backup.

CLI:

nexus db restore <service-id> <backup-id>
nexus db restore <service-id> <backup-id> --yes

REST:

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<serviceId>/restore" \
  -H "Authorization: Bearer $NEXUS_JWT" \
  -H "Content-Type: application/json" \
  -d '{"backupId":"<backupId>"}'

Use in-place restore carefully. Restore can overwrite, clean, drop, or replace data depending on the database engine. Before restoring, create a fresh backup of the current state if you may need to roll forward again.

Recommended in-place restore workflow:

1. Put the app into maintenance mode or stop write-heavy workers.
2. Create a fresh backup of the current service.
3. Restore the selected backup.
4. Restart or redeploy application containers if they cache connections or schema metadata.
5. Validate critical flows before sending normal traffic back to the deployment.

Restore into another deployment service

Cross-service restore is useful when you want to restore production data into a staging deployment, migrate data to a replacement deployment, test a backup without touching the source service, or recover into a newly created database service.

The target service must be:

• In the same organization as the backup.
• A compatible database engine.
• Running and reachable by NEXUS AI.
• Safe to overwrite.

CLI:

nexus db restore-to <target-service-id> <backup-id>
nexus db restore-to <target-service-id> <backup-id> --yes
nexus db restore-to <target-service-id> <backup-id> --json

REST:

curl -s -X POST "$NEXUS_API_BASE/deployment-services/<targetServiceId>/restore-from/<backupId>" \
  -H "Authorization: Bearer $NEXUS_JWT"

MCP:

nexusai_db_restore_to

The MCP tool requires deployments:create scope. When using an AI client, include the backup ID and target service ID explicitly, then confirm the destructive operation before the tool call.

Backend integrations can call:

await backupService.restoreBackup(backupId, { targetServiceId });

The targetServiceId option is optional. Existing in-place restore calls continue to work:

await backupService.restoreBackup(backupId);

Example: restore production data into staging

This workflow copies a production database backup into a staging database service under the same organization.

# 1. Find production database service
nexus db services prod-api

# 2. Create a production backup
nexus db backup <prod-service-id>

# 3. List backups and copy the backup id
nexus db backups <prod-service-id>

# 4. Find the staging database service
nexus db services staging-api

# 5. Restore the production backup into staging
nexus db restore-to <staging-service-id> <backup-id> --yes

After restore, restart or redeploy the staging app if it caches database connections, schema state, or application-level lookup data.

nexus deploy redeploy <staging-deployment-id> --wait

Example: recover into a replacement deployment

If a deployment is being replaced, create the new deployment with the same database service type, then restore the backup into the new database service.

# Create or identify the replacement deployment
nexus deploy source \
  --repo https://github.com/your-org/your-app \
  --name api-replacement \
  --provider docker \
  --services postgresql \
  --wait

# Find the replacement PostgreSQL service
nexus db services api-replacement

# Restore the backup into the replacement service
nexus db restore-to <replacement-postgres-service-id> <backup-id> --yes

This lets you validate the replacement deployment before cutting traffic over.

Safety checklist before restore

Before any restore, confirm:

• The backup ID is correct.
• The target service ID is correct.
• The target service belongs to the same organization.
• The target service uses the same database engine.
• You understand that target data may be overwritten.
• You have a fresh backup of the target service if rollback matters.
• Application workers are paused if they may write during restore.

For production services, schedule a maintenance window. Database restore is a data-changing operation, not a harmless read.

Common questions

Can I restore a backup into a different deployment?

Yes. Use nexus db restore-to <target-service-id> <backup-id> or POST /api/deployment-services/:targetServiceId/restore-from/:backupId. The target service must be in the same organization and compatible with the backup engine.

Can I restore across organizations?

No. Cross-organization restore is blocked. Backups and database services are organization-scoped to prevent cross-tenant data access.

Does restore overwrite existing data?

Yes. Restore can overwrite, clean, drop, or replace existing data depending on the engine. Treat every restore as destructive unless you have verified otherwise for your specific database and backup.

Does the old in-place restore endpoint still work?

Yes. Existing restore flows still work:

nexus db restore <service-id> <backup-id>

POST /api/deployment-services/:serviceId/restore

The new cross-service restore path adds a target-service restore option without removing the old behavior.

Should I use download-and-manual-restore instead?

Use built-in restore for same-org NEXUS AI database services. Use manual restore when moving data outside NEXUS AI, restoring into an external managed database, or performing a custom migration that needs database-native flags not exposed by the platform.

Final takeaway

NEXUS AI database backups are designed for the actual recovery workflows teams need:

• Back up a running database service.
• Download the backup for retention or audit.
• Restore in place when you need rollback.
• Restore into another same-org service when you need staging refreshes, migration testing, or deployment replacement.

The important rule is simple: choose the target service carefully. Restore is powerful because it changes real data.