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:

• Prisma Pulse DB Only: Provides a fresh, pre-configured PostgreSQL database which you can use with Prisma Pulse.
• Prisma Pulse DB & App: Provides a pre-configured PostgreSQL database and a Prisma Pulse starter app.

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.
   Use the following DATABASE_URL to enable Prisma Pulse:
   
   postgresql://postgres:password@roundhouse.proxy.rlwy.net:28606/railway?sslmode=disable
   warning

   The sslmode=disable parameter is required when enabling Pulse, as Pulse defaults to sslmode=require. We recommend setting up TLS for your database, which will allow you to use the DATABASE_URL without the need for the sslmode=disable parameter.

   note

   The DATABASE_URL environment variable 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.

   1. There should be a toast asking whether you want to apply the change. Click the Deploy + ⇧Enter button.
   2. There should be a pop-up prompting you to type apply destructive changes to confirm that you want to proceed with deleting the service.
   3. Click the Commit button to confirm and apply the deletion.

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 the restart-db-then-delete-me and pulse-starter service:
   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. 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 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.

warning

Make sure to append ?sslmode=disable to the database connection string if TLS is not set up for your database.

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 notice that the pulse-starter service logs a message stating "Please ensure that PULSE_API_KEY environment variable is set". 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 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 latest deployment. 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: "test@test.io" },
     id: 03/34334
   }

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.