Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Outgrow Starter without rebuilding your app or re-pointing every connection by hand.

​
Prerequisites

  • A running Starter PostgreSQL database on StackShift’s servers
  • Dedicated switched on for your account
  • A wallet balance or a saved card for the new database

​
Workflow

1
Check the move first: stackshift database move-preflight DATABASE --query instance_class=s-2vcpu-4gb --query storage_gb=50 --query billing=monthly (GET /api/v1/databases/{id}/move-to-dedicated/preflight). With instance_class and storage_gb it also returns a price quote. eligible must be true.
2
Fix anything under blockers, and read the warnings in findings. On PostgreSQL 14 or older, choose the new version (15 or newer) with version.
3
Start the move with stackshift database move-to-dedicated DATABASE --file move.json (POST /api/v1/databases/{id}/move-to-dedicated), giving instance_class, storage_gb, billing (monthly, yearly or hourly) and confirm_charge_minor set to the quoted charge. Add name, version, standby, on_standby_loss or maintenance_window if you want them.
4
Save the new database’s password from the response: it is shown only once.
5
If the answer is 402 payment_required, open checkout_url and pay. The new database starts, and the move begins, once the payment clears.
6
Follow the move with stackshift database move-status DATABASE (GET /api/v1/databases/{id}/move-to-dedicated) until state is completed.
7
Check your apps. They are already using the new database.

​
Preflight

  • The result gives the database size, the copy method, the estimated pause in seconds, the smallest storage that fits, the version choices and the services that use the database.
  • PostgreSQL 14 or older can’t move as it is. Choose a version from 15 up with version.
  • Blockers stop the move. They include: the database isn’t running; it is on your own servers; read-only connection addresses are still in use (switch those apps to the main connection first); services run on servers that can’t reach Dedicated databases yet; and objects Dedicated doesn’t support, for example event triggers, functions written in C or languages other than SQL and PL/pgSQL, foreign data wrappers other than postgres_fdw, and extensions that Dedicated doesn’t offer.
  • Warnings don’t stop the move. They cover things like server-wide settings set with ALTER SYSTEM, objects owned by other roles, and tables without a primary key.
  • The new database keeps your username and database name when Dedicated allows them. The password is new.

​
What the move costs

The new database is a normal Dedicated database, paid for like any other. A paid move always needs you to confirm the quote: the first request answers 409 price_confirmation_required with the quote, and you send it again with confirm_charge_minor. See https://stackshift.cloud/pricing and Dedicated billing.

​
How long writes pause

  • Reads keep working the whole time. Writes to the original database pause only while the final copy runs, then your apps switch to the new database.
  • Up to 5 GB, the data is copied in one go and the pause lasts for the copy. estimated_pause_seconds in the preflight is your estimate.
  • Over 5 GB, the data is copied while your database keeps running and the pause is about a minute. The original database restarts once to allow this. The preflight’s source_restart says whether that is needed and when your maintenance window is. Send "source_restart": "now" or "window" when starting the move.
  • Large objects can’t be copied this way and block the move. Tables without a primary key are copied, but don’t change your table structure while the move runs.

​
Progress

  • state goes provisioning, preparing, replicating (large databases), cutting_over, transferring, repointing and completed, or failed.
  • The status also shows the percent done, bytes copied, the pause so far, and the checks run on your data: tables, row counts and sequences must match.
  • The new database’s events feed shows move_started, move_cutover, move_completed and move_failed.

​
After the move

  • Service bindings, access grants, the application link and stored connection variables follow the new database, and the apps that use it are redeployed.
  • The original is stopped, so its billing stops, and it is read-only. It is deleted 7 days later through the normal delete path. Anything you still need from it must be copied before then.
  • Data written to the new database after the switch is not in the original.

​
If the move fails

  • A failure before the switch makes the original database writable again. You keep the new, paid database.
  • Retry with stackshift database move-retry DATABASE (POST /api/v1/databases/{id}/move-to-dedicated/retry) once retry_available is true. There is no second charge. A retry waits until the original is writable again and any cleanup from the failed attempt has finished.
  • If the new database was removed, start the move again. If you don’t want it, delete the new database.
  • Start-up work done for the copy on the original database, such as the temporary copy connection and replication settings, is removed for you.

​
Availability

Dedicated databases are rolling out. If Create doesn’t offer Dedicated, it isn’t switched on for your account yet, and the API answers 403. “Moving a database to Dedicated is not available yet” means the move isn’t switched on for your account. MySQL on Dedicated isn’t available yet, so only PostgreSQL databases should be moved.

​
Expected result

Your data, apps and connection variables are on the new Dedicated database, and the Starter database is read-only and stopped.

​
Common failures

  • 409 move_blocked: the response lists blockers. Fix them and start again.
  • 409 “This database is already on Dedicated.”: the move only starts from a Starter database.
  • 409 “This database is already being moved.”: wait for the current move to finish.
  • 409 price_confirmation_required: resend with confirm_charge_minor at or above the quoted charge.
  • 409 “We’re adding capacity…”: try again shortly; nothing was charged.
  • 402 payment_required: open checkout_url and pay. The move starts once the new database is running.
  • 400 for "source_restart": "window": the original database has no maintenance window. Use now.

Starter or Dedicated

Starter databases share a server with other databases. A Dedicated database is its own virtual machine with a standby, read replicas and restore to any second.

Dedicated databases

Create a Dedicated PostgreSQL database, connect to it, resize it and manage its lifecycle.

Dedicated billing

Pay for a Dedicated database monthly, yearly or by the hour, from your wallet or card.

Performance Insights and events

See what a Dedicated database spends its time on, find its slowest queries, and read a feed of failovers, backups and maintenance.