New Database Reference Variables
📣 Today we’re deprecating auto-injection of plugin variables in favor of explicit Database Reference Variables. We’ve backfilled these references to all existing services so no migration step is required.
Since the beginning, Railway has auto-injected database variables into every deployment. This made sense when a project could only contain a single service and database, but this behavior actually blocked some key items that users have wanted like multiple databases in a project.
Starting today, we’re replacing this implicit auto-injection behavior with explicit Database Reference Variables. Reference Variables, which can be added from the Variables page in Service Settings, enable the following benefits:
- 💾 Multiple Databases → Multiple Postgres/Mongo/etc can now co-exist in one project
- 🔐 Enhanced Security → DB credentials can be restricted to services that require them
Here’s a quick screencast that covers the changes.
As part of this change, a service will no longer receive plugin variables unless a reference is explicitly added. We’ve already created these references for all existing services so no migration steps are required.
We launched Shared Variables late last year to help simplify configuration within large multi-service projects. Shared Variables enables variables to be defined at the project environment level and referenced using a templated value like ${{shared.SECRET}}.
Database variables leverage the exact same system. Here are some examples of things you can do with them:
DATABASE_URL=${{Postgres.DATABASE_URL}}
PRISMA_URL=${{MySQL.DATABASE_URL}}?connection_limit=100For each of these variables, we’ve interpolated a reference to a database variable — but don’t worry about remembering this syntax because in the UI the new autocomplete component does the work for you!
Adding a database reference variable to a service using autocomplete
Also, these references are dynamic under the hood, so renaming a database won’t break any existing references.
Let’s get into some of the features that Reference Variables unlocks.
We like to provide simple and secure defaults out of the box that you can eject from if needed. Reference Variables adheres to this by allowing the restriction of credential sharing to only the services that require access.
In other words, you can now explicitly define the services that receive variables from your database(s). This means that if you ever deploy bad code to your frontend service (which doesn’t need database access) you don’t have to worry about database credentials accidentally being leaked.
Since user data is the most valuable part of any business, we think it’s a helpful step forward to limit credential distribution as much as possible.
Database Reference Variables also unlocks the ability to have multiple databases of the same type in a single project! Our internal infrastructure has technically supported this for a while, but the auto-injection behavior prevented us from enabling it because multiple of the same database would have previously resulted in variable namespace collisions.
It took many iterations to figure out the best way around this, but Reference Variables ended up being the simplest and most flexible solution.
There are also some smaller unexpected benefits:
- It’s no longer possible to add a variable that overwrites a database variable
- Database variables can be provided under any name
- Re-deploys happen automatically when reference variables are added/removed
- Shared and DB variables leverage the same autocompletion component
Example of a project with multiple databases
Even though this change is relatively minor, it affects a foundational part of Railway and unlocks some important features to allow you to deepen your use on the platform.
Variables are the glue that tie a project together, so it’s paramount that they remain easy to use and understand. Please send us your questions, opinions, or concerns via Discord and we’ll be happy to chat! 👋
