Skip to main content
Newly supports manual database snapshots through the newly CLI. You can automate the same command with your own cron job, CI workflow or other scheduler. Each run creates one snapshot. Newly doesn’t configure a managed backup schedule or create a snapshot automatically before deployment. You control your automation, credentials, retention and monitoring, and decide when to change or restore your database.

​
Create a manual snapshot

Install the CLI and sign in using the steps in Get your code. Production database operations require the project owner’s account. Dev snapshots can also be created by a project Admin. Managed Newly agent credentials work on dev only. Run these commands with your project id, the last part of app.newly.app/projects/<id>:
Snapshot creation runs without an interactive confirmation. It reports success after the snapshot is ready. Creating a snapshot doesn’t apply migrations or change the live database. Snapshots expire after their retention period. Choose a frequency and retention that leave space for expiration cleanup and extra manual snapshots. For example, hourly snapshots kept for 24 hours would exceed the five-snapshot limit. Check backup status and backup list to see the current state.

​
Run snapshots from your own scheduler

Your scheduler invokes newly db backup create repeatedly. It doesn’t need database-provider credentials or a provider-managed scheduling feature. It does require Newly and the database provider to be available when the job runs.

​
Authenticate the job

On your own computer, create a separate CLI token and sign in as the project owner:
This prints a new token once and the matching API URL. It leaves your existing CLI login unchanged. Store the token in your scheduler’s secret store as NEWLY_API_TOKEN, and configure NEWLY_API_URL with the API URL printed by the command. Both values are required; the API URL is Newly’s API address, not your app’s backend address. The token carries your account’s CLI permissions. Keep it out of app code, chat messages and job logs. Monitor authentication failures and replace the job’s token when necessary.

​
Example: GitHub Actions

In a GitHub repository you control, add:
  • A repository secret named NEWLY_API_TOKEN containing the owner’s CLI token.
  • Repository variables named NEWLY_API_URL and NEWLY_PROJECT_ID containing the printed API URL and your project id.
Save this workflow as .github/workflows/newly-database-snapshot.yml on that repository’s default branch:
This example requests a snapshot daily at 03:17 UTC and keeps it for 48 hours. You can also start it with Run workflow. No project checkout or deployment is needed. GitHub runs scheduled workflows from the default branch and may delay or drop runs under load. Public repositories also have an inactivity timeout for schedules. See GitHub’s schedule documentation. Enable failure notifications and monitor the age of your latest successful snapshot; a schedule alone doesn’t confirm that backups are being created. For cron or another scheduler, install the CLI on the machine that runs the job, supply the same environment variables, and invoke the same snapshot command. Use a mechanism that prevents overlapping runs for the same database.

​
Handle failed or uncertain runs

Treat a nonzero exit code as a failed job. Investigate expired credentials, the snapshot limit and service availability. The CLI prints a backup operation id before submitting the request. If the command times out or loses its response, the snapshot operation can still be running. Inspect that operation and the snapshot list before retrying:
Repeating the create command starts a new operation, so avoid blind retries. Pause your scheduler while restoring the database, then check the restored app before resuming it.

​
Backups that can run while Newly is unavailable

CLI snapshot automation depends on Newly. For direct database access during a Newly outage, export and securely save the owner’s connection URL before the outage:
The URL contains a database password. Only the project owner can export it; managed agent credentials can’t. Store it in your own secret store and use it with Postgres tools, such as pg_dump, from infrastructure you control. A previously saved URL lets those tools connect without calling Newly, provided the database provider and network are available and the credentials remain valid. Production URL export, including read-only access, and owner export in either environment require an owner’s CLI key and a fresh verification code sent to the account’s verified email. The CLI prompts for this code; a web session or confirmation flag alone cannot authorize export. Each code expires after five minutes and authorizes one specific request. Never share it with an agent or in chat. An external pg_dump job produces a database export in your storage. It doesn’t create a snapshot listed by newly db backup list; you manage its storage, retention and restoration yourself. The connection URL grants database access, not a database-provider account or access to the provider’s snapshot API. Changing the owner’s database password also affects the deployed API and sign-in services.

​
Invalidate previously exported URLs

If a database URL leaks or someone who held it leaves, rotate the managed database passwords with this command:
This requires the current owner’s CLI key and a new email verification code. It resets the shared API/Auth owner password and the read-only password, updates their saved and deployed credentials, and invalidates both kinds of saved URLs. It closes existing connections using these roles. Export new URLs afterward and update your own backup jobs. Export and rotation events are recorded without storing the URLs in an operation result. A snapshot contains the database credentials from when it was created. Previews from before a password rotation may fail credential validation and cannot be applied through the CLI. Inspect the preview result and create a new snapshot after confirming the rotated application works. Rotating this password invalidates that credential; it does not remove additional database roles someone may have created with owner access.

​
Restore a snapshot

Prepare a separate restore preview and inspect its result before deciding to replace the live database:
Preparing a preview leaves the live database unchanged. Applying it requires the owner’s explicit confirmation:
Applying a restore replaces the whole database, including sign-in data and every app schema. Writes made after the snapshot can be lost, and database connections restart. Newly doesn’t pause app traffic or roll back deployed code, secrets, file storage or queues. Coordinate your app’s writes and automation, check compatibility, and validate the app after the restore.
Applying a production restore also requires the owner’s CLI key and a fresh email verification code. The CLI requests the code after checking the confirmation flags. These flags alone do not authorize a database switch. To remove an unapplied preview, run:
Discard also works for an older or failed preview after another restore has been applied. It cannot delete the live database. After a successful restore, Newly attempts to remove the previous branch. If the result reports cleanup_required: true, inspect the result, discard remaining unapplied previews, then remove the previous branch with:
Cleanup requires the owner’s CLI key and a fresh email code. One database operation can be queued or running per project. A busy response requires waiting for its result; avoid overlapping jobs. A snapshot doesn’t establish that a migration or catalog update is safe. Review and test your database changes before applying them. Restoring app code is a separate operation from restoring database data.