[!WARNING] This code is in active development and is not yet production-ready.

If you're excited by what we're building, we're looking for design partners - contact us if you want early access to Solarflare.

Join our waitlist to be notified when we launch for production use.

Introduction

solarflared is a server-side daemon process that sits alongside your existing Postgres database. It listens for changes to your 'live' tables and broadcasts them via WebSockets to connected clients (see the Solarflare Typescript Client).

Packaged with solarflared is a CLI tool for managing your installation.

Features

• [x] Postgres logical replication
• [x] WebSocket server
• [x] JWT-based auth for partial replication
• [x] CLI
• [x] Typescript codegen

Getting started

1. Install the Solarflare CLI:

   npm install -g @solarflare/solarflared

2. Initialize Solarflare in your backend project:

   solarflared init

   This command will interactively allow you to configure which tables you want to expose to your frontend, and ensures that your Postgres installation works with Solarflare. In particular, you need to have logical replication enabled with wal_level = logical in your postgresql.conf file (this requires a Postgres restart).

   Each table can have row-level security configured. Currently, this works by nominating a column as the rls column and a JWT claim to use for filtering. When a user on your frontend loads a table from Solarflare, they will only see rows where the rls column matches the claim in their JWT.

   The command generates a solarflare.json file in your project root, which you can commit to your version control system.

3. Run the Solarflare server:

   solarflared start

   This will start the Solarflare server on http://localhost:54321. It reads the solarflare.json configuration file.

4. Install the Solarflare client in your frontend project:

    npm install @solarflare/client

5. Generate types for your tables:

   solarflared codegen

6. Setup a SolarflareProvider in your React app.

   This needs to be somewhere high up in your component tree, so that all components that use Solarflare are descendants of it. If your project is a Next.js app, you could put it in _app.tsx, or layout.tsx.

   import { SolarflareProvider } from "@solarflare/client";
   
   const App = ({ Component, pageProps }) => {
     const usersJwt = "...";
   
     return (
       <SolarflareProvider
         jwt={usersJwt}
         solarflareUrl="http://localhost:54321"
       >
         <Component {...pageProps} />
       </SolarflareProvider>
     );
   };

   The jwt prop is the JWT that Solarflare will use to filter rows in your tables.

7. Use the useTable hook in your components to get live data from your Postgres tables.

   import { createSolarflare, type DB } from '@solarflare/client'
   
   const { useTable } = createSolarflare<DB>()
   
   const Todos = () => {
       const { data, isLoading } = useTable("todos");
   
       if (isLoading) return <div>Loading...</div>
   
       return (
           <div>
               {data.map(todo => <Todo key={todo.id} todo={todo}>)}
           </div>
       )
   }

Optimistic updates

Solarflare supports optimistic updates. Our philosophy is one of pragmatism. We don't attempt to solve the general case of conflict resolution, or be a full-blown ORM where you just edit the values of object fields and expect everything to happen by magic.

Instead, for live changing data, the model we encourage is:

• You have a server which performs writes
• The server exposes an API which you can call to perform writes (e.g. REST, GraphQL, tRPC)
• When you render the page, you fetch the data via Solarflare and get a declarative view to render in a natural way
• When a user does an action, you call your (non-Solarflare) API to request the change
• Your server performs whatever complex validation, authorization or conflict resolution logic is necessary
• Your server writes the change to the database
• The database, being the source of truth for the state of your data, pushes changes out via Solarflare to everybody who needs to know
• Meanwhile, your frontend client can optimistically render the updated value with a couple of lines of Javascript. When the ratified change comes back via Solarflare, the optimistic update is replaced with the real data

Here's how you do an optimistic update with Solarflare:

const Todos = () => {
  const { data, optimistic } = useTable("todos");

  const updateTodo = async (id: number, text: string) => {
    // Perhaps do some client-side validation here...

    // Optimistically update the UI
    const { rollback } = optimistic({
      action: "update",
      id,
      data: { text },
    });

    const res = /* call your normal API here */;

    // If the server responds with an error, roll back the optimistic update
    if (res.error) {
      rollback();
    }
  };

  return (
    <div>
      {data.map((todo) => (
        <Todo key={todo.id} todo={todo} updateTodo={updateTodo} />
      ))}
    </div>
  );
};