Migrating from Legacy Plugins to Database Services
We've introduced a more secure and flexible way to deploy databases on Railway. The purpose of this guide is to provide an overview of why we are making these changes, what they mean for you, and how you can migrate.
In the early stages of Railway, we introduced "Plugins", a foundational part of our offering. They were databases deployed from Docker images with a fixed version, no data persistence, and no way to customize the database to your needs.
Some of our newest features - Volumes, Docker Image Deployments, TCP Proxy - open the door for deploying databases as services, complete with data persistence, flexible configuration and management, and connectivity over the public Internet or private network.
In fact, we have updated our official databases to deploy from templates, built as database services using all of the features above, utilizing the
latest image versions available in Docker Hub.
There are several key reasons why this migration is beneficial -
- Data Security
- Modern Architecture
- Flexibility in configuration
You have some options when it comes to migrating from a database plugin to a database service.
We wanted to make the process as easy as possible, so we built an automated process to migrate the data for you. However, there are other options in case you would like a bit more control over the process.
When you access the plugin panel from within your project canvas, you will see a prompt to migrate.
Once you click the
Migrate button, a modal will appear, detailing the steps that will be taken on your behalf, to migrate your data. After acknowledgment, the data migration will begin -
Deploy Database Service - A new database service with an attached volume will be deployed.
Stop Connected Services - Any service within your project that is connected to the plugin via a variable reference will be stopped, for the duration of the migration, to prevent data loss or corruption.
Note: You should ensure that any service(s) external to Railway which is writing to, or reading from, the database plugin is also stopped, or otherwise prevented from performing operations against the database, for the duration of the migration.
Data Transfer - A migration service will be deployed that will execute a migration script. The script will connect to your database plugin, create a dump of the data, and then transfer it to the new database service. The scripts are open-source and can be reviewed here:
Once the migration is complete, the migration service will be deleted.
Update Service Variables - Variable references within services that point to the database plugin will be updated to the new database service
Redeploy Connected Services - Services previously connected to the database plugin will be redployed to apply the updated connection string and connect to the new database service.
NOTE: The legacy plugin will NOT be deleted automatically.
Once you have performed the necessary actions to ensure data consistency between the database plugin and the new database service, you should delete the database plugin from your project.
If you have hard-coded the plugin
DATABASE_URL anywhere, make sure to update it to point to the new database
If you would prefer not to go through the migration flow as outlined above, there are other options for your migration path -
- Template - The template which is used in the automation can be deployed at-will. Deploy this manually in your project if you prefer this method.
- DIY - If our tools don't align with your needs, or you have a unique migration process in mind, you're welcome to execute your own strategy. We always recommend ensuring you have a backup and a process for testing.
The migration process has been designed to minimize risks. By temporarily stopping services that reference the old plugin, we prevent data corruption. Also, we don't immediately delete the old plugin, allowing you to verify the migration.
Yes, there will be a brief downtime for services that reference the old plugin. However, this is essential to ensure a seamless and error-free migration.
If you follow the one-click automated process, each environment will be handled for you. If you perform the migration via another process, you will need to perform the migration within each environment.
While we encourage users to migrate as soon as possible to benefit from the enhanced features, you will have until January 31st, 2024 to complete the migration.
We're committed to providing the best solutions for your needs, and the new database services are a big step in that direction. We're excited about the possibilities that this transition brings to your experience on Railway.
Edit this file on GitHub