Skip to main content
Railway is a managed cloud platform (PaaS) for deploying and scaling applications, services, and databases via containers.

​
Step 1: Deploy on Railway

Find the “PowerSync Starter (Postgres)” template on the Railway Marketplace, or click the button below to get started: Deploy on Railway The starter template will deploy and boot with a default configuration for all of the services. You can always add more services to your project as you need them and update the configuration as you go. Once you’ve opened the deployed project in Railway, you’ll see the following services:
  • PowerSync Service: The PowerSync service is responsible for syncing data between the Postgres database and your client applications.
  • Postgres Source Data: The Postgres source data is the database that contains your application data.
  • Postgres (PowerSync Bucket Storage): The Postgres (PowerSync Bucket Storage) is the database that contains your PowerSync bucket data.
  • Demo Node.js Backend: The Node.js backend is the backend for your application and is responsible for generating JWT tokens and API requests that handle upload events from a connected client. Note that this backend is not secured at all, and is intended to be used for demo purposes only.
  • Sync Diagnostics Client: The Sync Diagnostics Client is a web app that implements the PowerSync Web SDK and allows you to test your PowerSync connection and see the data that is being synced.
  • Execute Scripts: The Execute Scripts service is used to apply schema changes to your PowerSync Postgres instance.
This template automatically creates lists and todos tables in your Postgres database. The default Sync Rules are configured to sync these tables to your clients.The Execute Scripts service creates the powersync publication for these tables. We recommend limiting the publication to only the tables you want clients to download.
Once you’re up and running with the default lists and todos tables, you can add more tables at any time using either of these approaches:Option 1: Use your existing Postgres toolsManage your database schema as you normally would. For example, using psql:
psql $POSTGRES_URL <<'SQL'

CREATE TABLE notes (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  list_id UUID REFERENCES lists(id) ON DELETE CASCADE,
  content TEXT,
  created_at TIMESTAMP DEFAULT now()
);

CREATE PUBLICATION powersync FOR TABLE notes;

SQL
Option 2: Use the Execute Scripts serviceThe Execute Scripts service can also be used as a general-purpose tool to apply schema changes to your PowerSync Postgres instance:
  1. Add your new table creation statements and publication updates to the Execute Scripts code
  2. Redeploy the Execute Scripts service
After adding tables with either option:
  1. Update the Sync Rules to include the new tables in the sync_rules section of your YAML config.
  2. Re-encode the YAML config to base64 and update the POWERSYNC_CONFIG_B64 environment variable. See Understanding the PowerSync Service Configuration for more details.

​
Step 2: Test with the Sync Diagnostics Client

  1. Generate a development token
    • The Demo Node.js Backend service has a /api/auth/token endpoint you can hit to get a development JWT token. You can use this endpoint to generate a development token.
    • You can also generate a development token by following the Generate development token tutorial.
  2. Open the Sync Diagnostics Client service in the browser.
  3. Paste your token to test your connection and Sync Rules

​
Step 3: Connect Your Client

Client-Side Setup

Follow our guide to connect your app to your backend and PowerSync instance. See our guide to learn more about how to implement your client-side application.

​
Step 4: Implement your Backend

Backend Application Setup

PowerSync is designed to integrate with your existing backend infrastructure for persisting client mutations to your backend database. See our guide to learn more about how to implement your backend application.

​
Understanding the PowerSync Service Configuration

The PowerSync Service configuration is written in YAML and converted to base64 to be used as an environment variable. If you need to make changes to the configuration, you can copy and edit the example YAML file below, base64 encode it, and update the POWERSYNC_CONFIG_B64 environment variable in the PowerSync Service service. This will be required if you need to update the Sync Rules of your project.
config.yaml
replication:
  connections:
    - type: postgresql
      uri: !env PS_POSTGRES_SOURCE_URL
      sslmode: disable

storage:
  type: postgresql
  uri: !env PS_POSTGRES_BUCKET_URL
  sslmode: disable

port: 80

sync_rules:
  content: |
    bucket_definitions:
      global:
        data:
          - SELECT * FROM lists
          - SELECT * FROM todos

client_auth:
  jwks_uri: !env PS_AUTH_JWKS
  audience:
    - !env PS_AUTH_AUD