Adding a Database

Almost every app has to remember stuff. User accounts, posts, orders, settings. All of that data needs a safe place to live, even when your app restarts. That's the database's whole job.

In this lesson you'll add a database to your Railway project and hook it up to your app.

What is a Database?#

A database is organized storage for your app's data. Picture a super-powered spreadsheet that can do all this.

• Stores millions of rows without slowing down
• Lets you search and filter data instantly
• Keeps data safe even if the power goes out
• Allows multiple users to access data at the same time

PostgreSQL: The Database We'll Use#

There are a ton of database types out there. We're going with PostgreSQL (most people just say "Postgres"). Here's why.

• Free and open source. No licensing costs
• Reliable. Used by Instagram, Spotify, and thousands of companies
• Powerful. Handles everything from tiny apps to massive systems
• Well documented. Easy to find help and tutorials

Railway makes adding PostgreSQL ridiculously easy. A few clicks and you've got a running database.

Adding PostgreSQL to Your Project#

Let's add a database to the project you deployed last lesson.

Step 1. Open Your Project#

Go to your Railway dashboard and click the project you created.

Step 2. Add a New Service#

Click the "New" button inside your project, or right-click on the empty space. You'll see options for adding services.

Step 3. Choose Database#

Pick "Database" from the options. Railway shows you a few database types.

Step 4. Select PostgreSQL#

Click "PostgreSQL." Railway starts building your database right away.

Step 5. Wait for Provisioning#

Railway takes about 30 seconds to set things up. A new card pops up in your project for the PostgreSQL service.

Understanding Your Database#

Click the PostgreSQL service card to see more details. Here's what's in there.

Connection Info#

Railway shows you everything you need to connect.

• Host. The address of the database
• Port. The network port (usually 5432 for PostgreSQL)
• Database. The name of your database
• Username. Login name
• Password. Login password

Data Tab#

You can view and edit your data right inside Railway. It's a simple data browser that shows your tables.

Variables Tab#

The connection details also show up as environment variables. That's how your app is going to connect.

Connecting Your App to the Database#

Your database exists now, but your app has no clue about it yet. You have to hand your app the connection info.

Railway makes that easy with something called "Reference Variables."

Step 1. Click on Your App Service#

In your project, click the service running your web app (the app, NOT the PostgreSQL service).

Step 2. Go to Variables#

Click the "Variables" tab.

Step 3. Add a Reference Variable#

Click "New Variable" and look for the option to reference another service. You can also type it in by hand, using Railway's reference syntax with your database service's name.

DATABASE_URL=${{Postgres.DATABASE_URL}}

Step 4. Set DATABASE_URL#

Railway can fill in the connection string for you. Find the PostgreSQL service and pick its DATABASE_URL variable.

The DATABASE_URL squishes all the connection details into one string. It looks like this.

postgresql://username:password@host:port/database

Step 5. Deploy the Change#

Railway stages the new variable instead of applying it right away. Click "Deploy" on the banner at the top of your project, and Railway redeploys your app with the new settings.

Using the Database in Your Code#

Your app can now reach the database through the DATABASE_URL environment variable. How you use it depends on your language and framework.

For JavaScript/Node.js#

const connectionString = process.env.DATABASE_URL;

For Python#

import os
connection_string = os.environ.get('DATABASE_URL')

With Prisma (Common for Next.js)#

Prisma gets its connection string from DATABASE_URL too (the Prisma lesson in the Databases module walks through the setup). On Railway you don't need a .env file at all, because the variable you just added gets handed to your app at runtime. Your local .env file only holds the connection string for the database you use while developing.

Testing the Connection#

So how do you know your app is actually connected? Here are a few ways to check.

Check Your App's Logs#

Look for connection success or error messages when your app starts up.

Try a Feature That Uses Data#

If your app has a sign-up form or saves data somehow, give it a spin. If it works, your database is connected.

Use Railway's Data Browser#

Click your PostgreSQL service and go to the "Data" tab. After using your app a bit, you should see tables and data showing up here.

Database Best Practices#

A few tips for working with databases on Railway.

Back Up Important Data#

Railway has a Backups tab on your database service where you can make backups by hand or schedule them daily, weekly or monthly. It's on you to turn that on though, so do it before you have data you'd cry about losing.

Don't Share Credentials#

Keep your DATABASE_URL secret. Your password is sitting right inside it.

One Database Per Environment#

If you've got a testing environment and a production environment, give each one its own database.

Monitor Usage#

Databases eat memory and storage. Keep an eye on the Resources tab so you don't run out.

Viewing Your Data#

Railway includes a simple way to peek at what's in your database.

Step 1. Click on PostgreSQL Service#

Go to your PostgreSQL service in Railway.

Step 2. Open the Data Tab#

Click "Data" to open the data browser.

Step 3. Browse Tables#

If your app has created tables, you'll see them listed. Click a table to see what's inside.

You can also use outside tools like pgAdmin or TablePlus for fancier database management.

TL;DR#

• A database stores your app's data safely and permanently
• PostgreSQL is a powerful, free database used by tons of companies
• Adding PostgreSQL on Railway takes just a few clicks
• Use DATABASE_URL to connect your app to the database
• Never put database passwords directly in your code
• Railway's Data tab lets you browse what's in your database

What's Next?#

You've got an app with a database now. DATABASE_URL is just one example of an environment variable though. Next lesson, you'll dig into environment variables in more detail, including how to safely store secrets like API keys...