Migration · By Rivtor · Updated
Move a Next.js, API and PostgreSQL app from Railway
Migrate a Railway application by inventorying services and reference variables, rehearsing the destination with disposable data and planning a controlled database cutover. Translate each capability explicitly; copying source code alone does not move databases, jobs or files.
Compare Rivtor plans for your workload →
Inventory services and references
Export a list of service roots, build/start commands and environment variable names without exposing secret values. Record Railway reference variables, private service addresses, database extensions, storage, queues and scheduled work. A reference expression belonging to Railway must become the destination’s supported configuration rather than being copied as a literal string.
Use a representative Next.js/API/PostgreSQL application for rehearsal. Check which requests originate in the browser and which originate on the server. A private Railway hostname will not remain a valid destination after moving the service.
Rehearse on isolated destination resources
| Component | Destination verification |
|---|---|
| Next.js | Production output and build-time public API URL |
| API | Runtime, listener and required secrets |
| Postgres | Version, extensions, privileges and restore path |
| Worker | Queue identity, retry behaviour and output ownership |
| Files | Object keys, access policy and download URLs |
On Rivtor, inspect the source-detection plan and data interfaces. Confirm a supported way to import into the destination database before scheduling a production move. Do not assume a private connection URL is directly reachable from your laptop.
Plan a database-consistent cutover
Rehearse a logical export and restore into a disposable database. Verify row counts, critical relationships, sequences and representative queries. Record the PostgreSQL tool versions and extension requirements. A dump file’s existence is not proof that it restores correctly.
For the real cutover, define when writes stop, when the final export is taken and who verifies the restored data. Include queue producers and workers in the write-freeze plan so background work cannot continue writing to the old database unnoticed.
Make rollback a data decision
Keep the source environment available until acceptance checks pass. Once users write to the destination, switching traffic back requires a reconciliation decision; DNS rollback alone does not merge new records. Document that boundary before changing the public hostname.
After cutover, test a synthetic create/read operation, a job and a file download. Check the running source revision and retain sanitized migration evidence. Retire the old services only after the agreed retention period and a verified recovery plan.