Skip to main content

Railway

Railway provides a useful feature known as templates to facilitate quick project setup. These templates allow users to package a service or a group of services into a format that can be easily reused and shared. We have two templates for Prisma Pulse that you can use:

Setup with template: "Prisma Pulse DB Only"

Overview

This section provides step-by-step instructions for setting up a Pulse-ready PostgreSQL database using the Railway template called: Prisma Pulse DB Only.

The template consists of two services:

  • Postgres: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions.
  • restart-and-delete-me: This service contains a script that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more.

Instructions

  1. Deploy the template on Railway.
  2. Once the deployment has finished, click on the service called restart-db-then-delete-me.
  3. You will see a list of deployments under the Deployments tab.
  4. Click the most recent deployment's View Logs button.
  5. Click on the Deploy Logs tab. If the service ran correctly, you should see a message in the logs that says:
    All done please restart the database and delete this service.
    Here is the DATABASE_URL
    postgresql://postgres:[email protected]:28606/railway

    Note: The DATABASE_URL can also be found by clicking on the Postgres Service and navigating to the Variables tab, then clicking the copy icon next to DATABASE_URL environment variable value.

  6. Copy the DATABASE_URL connection string and save it for later. Then restart your Railway database for the changes to be reflected:
    1. Click on the Postgres service that represents your deployed database.
    2. Navigate to the Deployments tab.
    3. Click on the three-dots menu on the latest deployment and click the Restart option.
  7. After restarting your database, click on the restart-db-then-delete-me service and navigate to the Settings tab.
  8. Scroll down to the bottom and click the red Delete service button.
  9. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the Getting started page.

Setup with template: "Prisma Pulse DB & App"

Overview

This section provides step-by-step instructions for setting up a Pulse starter project with a Pulse-ready PostgreSQL database using the Railway template called: Prisma Pulse DB & App. The template consists of three services:

  • Pulse-Starter: A Typescript app with a basic setup for using Prisma Pulse. You can find the repo for it on GitHub.
  • Postgres: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions.
  • restart-and-delete-me: This service contains a script that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more.

Instructions

  1. Deploy the template on Railway.
  2. You'll be navigated to a page prompting configuration for both the restart-db-then-delete-me and pulse-starter service: Configure Railway template
    1. For the restart-db-then-delete-me service, click on the Configure button and then save the configuration by clicking on Save Config.
    2. On the pulse-starter service, locate and click the Configure button. Within the Environment variables section, you'll find an option to include the PULSE_API_KEY environment variable. Keep the PULSE_API_KEY field blank for the time being. Once you've set up the database and obtained the database URL from the Prisma Data Platform, you can then add the PULSE_API_KEY to the pulse-starter service. With the empty field for the Pulse API key, click Save Config.
    3. Click on the Deploy button.
  3. To set up the database and make it Pulse-ready, complete the steps outlined in the previous section, starting from step 2. till step 8., then follow the instructions below.
  4. Go to the Platform Console and select the project in which you want to activate Pulse. If you don't have a project yet, create a new project via the New project button.
  5. Navigate to the project's environment in which Pulse should be activated. If you just created a new project, the only available environment is the Production environment.
  6. Click Enable Pulse on the environment's page.
  7. Paste the DATABASE_URL that you acquired before into the Database connection string field. Then, finish the process by clicking Enable Pulse.
  8. Pulse is now enabled in your project's environment. Click Generate API key to obtain the API key that you need in order to use Pulse in your TypeScript starter app.
  9. Save the PULSE_API_KEY for later and click I've securely stored my connection string.
  10. Back in the Railway UI, click on the pulse-starter service.

    Note: You'll likely find that the build failed for the pulse-starter service. This is because the Prisma Pulse API key wasn't provided. Do not worry, this is to be expected and not a problem for the next steps.

  11. Click on the Variables tab.
  12. Create your PULSE_API_KEY environment variable: Click the New Variable button, create the PULSE_API_KEY environment variable, and then paste the value of the PULSE_API_KEY that you obtained in the Platform Console. Then save the changes by clicking the Add button.
  13. With the PULSE_API_KEY environment variable in place, you need to rebuild the pulse-starter service for the environment variable to take effect:
  14. Click on the Deployments tab.
  15. Click on the three-dots menu on the deployment that failed. Then click Redeploy.
  16. When the deployment starts, click the View Logs button.
  17. Then click on the Deploy Logs tab to follow the deployment of the Pulse starter app.

Once the deployment is finished, your Pulse starter app should be running and any database events events will be logged under the Deploy Logs tab of the pulse-starter service.

To see an event in action, you need to make changes to the User table. You can follow the steps below to do that from the Railway UI:

  1. Click on the Postgres service on your Railway project.
  2. Click on the Data tab.
  3. Select the User table and click Add Row.
  4. Fill out an email and a name, then click Insert.
  5. Return to the Deploy Logs of your pulse-starter service.
  6. You should be able to see an output from Prisma Pulse for the user being created:
    just received an event: {
    action: "create",
    created: { id: 1, email: "test", name: "[email protected]" },
    id: 03/34334,
    modelName: "User"
    }

Setup without using a template

  1. Change the PostgreSQL database settings

    You can run these queries using a tool such as pgAdmin, dbeaver, or any other way you might run queries on your database.

    • Set the wal_level to logical:
      ALTER SYSTEM SET wal_level = logical;
    • Set the max_replication_slots to 20:
      ALTER SYSTEM SET max_replication_slots = 20;
    • Set the wal_keep_size to 2048:
      ALTER SYSTEM SET wal_keep_size = 2048;
    • Reload the PostgreSQL configuration:
      SELECT pg_reload_conf();
  2. You have to restart your database for the changes to be reflected. To restart your database using the Railway UI:

    1. Click on your database.
    2. Navigate to the Deployments tab.
    3. Click on the three-dots menu on the latest deployment and click the Restart option.
  3. After setting up your Railway database, you have to use the connection string provided by Railway that allows public access to your PostgreSQL database.

  4. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the Getting started page.