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.
What is Changing?
Legacy Plugins
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.
Database Services
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.
Why Migrate?
There are several key reasons why this migration is beneficial -
- Data Security
- Modern Architecture
- Flexibility in configuration
Migration Process
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.
One-click Automated Migration
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
Other Options
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.
Switching Over Connections
After your database is migrated, you will need to update your services to use the new database's connection string and/or credentials.
If you are using Reference Variables, the migration process will switch them over for you automatically. If you are not, please update your services to use it - doing so will ensure the connection details are always in sync.
To retrieve the connection details of your new database, click into the migrated database service and navigate to the Variables tab:
If you are connecting to this database within Railway, it is highly recommended to use the Private URL of the new database to take advantage of our Private Networking features.
Re-initiating Migration
To re-initiate the migration process, click the Delete Previous Migration & Re-Migrate button in your legacy database:
Doing this will delete the previously-migrated database service, and re-migrate your legacy database to a new database service.
Please ensure that you switch over connections after the new migration is complete.
If you need further assistance on this, please reach out to us.
Migration Timeline
- On February 1st, 2024:
- We will begin a rolling shut down of all database plugins
- After your database plugin is shut down:
- You will not be able to connect to your database outside of the migration process
- Your database's data will remain intact
- You will receive an email with instructions on how to proceed
- We expect all database plugins to be shut down by February 9th, 2024
- Between February 1st, 2024 and February 23rd, 2024:
- You will be able to migrate your database plugin(s) to the new version by navigating to your projects in the Railway Dashboard
- On February 23rd, 2024:
- We will begin deleting all database plugins
- We will start archiving data of un-migrated database plugins (Data Archival)
- Archived data will be available for download upon request for up to 6 months
- Any database plugin that has not been migrated, or had its data archived by us, will be permanently lost
- On August 23rd, 2024:
- We will permanently delete all archived data
Data Archival
We will archive the data of un-migrated database plugins that were shut down as a result of this deprecation. Archived data will be available for download upon request for up to 6 months from February 23rd, 2024.
If your database plugin is locked, your data will not be archived, and it will be deleted on February 23rd, 2024. Please upgrade to a paying plan to unlock your database plugin and migrate.
On August 23rd, 2024, we will permanently deleted all archived data.
FAQ
What is the risk?
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.
Will there be downtime?
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.
Do I have to perform the migration for every environment?
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.
What is the deadline for migration?
While we encourage users to migrate as soon as possible to benefit from the enhanced features, you will have until February 23rd, 2024 to complete the migration.
What if something goes wrong?
The old plugin remains intact until you verify the migration. If you encounter any issues, please reach out on our Discord, Community Forum, or contact our support team at support@railway.app (for Pro users).
Conclusion
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.
Need Help?
If you run into any issues, or would like help with your migrations, we would be more than happy to answer your questions on our Discord, Community Forum, or over email at support@railway.app (for Pro users).
Edit this file on GitHub