How to synchronize your Liveblocks Yjs document data to a Vercel Postgres database
Liveblocks allows you to build collaborative applications with Yjs, which is tightly integrated into our infrastructure. Using our Webhooks and REST API, you can then retrieve the Yjs document data as it changes, and store it in your database.
In this guide we’ll be linking a Yjs application up to a Vercel Postgres database so that Yjs document data is automatically synchronized. This is enabled through the following:
Note that the YDocUpdated webhook event is throttled at a rate of once every 5 minutes. This is because Yjs can update up to 60 times per second, and it would be impractical to run the webhook this frequently.
When a webhook event is triggered, it can send POST request to the back end in your project, and from within there we can update the database. In this guide, we’ll be using a Next.js route handler (API endpoint) as an example, but other frameworks work similarly.
In order to use webhooks, we’ll need to retrieve the
the request. Here’s the basic endpoint we’ll be starting from:
Create this endpoint in your project, and make it available on
the following URL:
If your project is running on
localhost:3000, you can run the following
command to generate a temporary URL that’s available while your localhost server
If you correctly input your IP address, the URL
localtunnel generates can be
placed into the Liveblocks webhooks dashboard for quick testing.
To use webhooks, you need to your endpoint URL to the webhooks dashboard inside our Liveblocks project, and tell the webhook to trigger when Yjs document data has changed.
Webhooks dashboard is set up!
Note that you filter specifically for
ydocUpdatedevents, but we’re ignoring this for now so we can test more easily. Let’s go back to the code.
The dashboard’s now set up! Note that you filter specifically for
events, but we’re ignoring this for now so we can test more easily. Let’s go
back to the endpoint.
@liveblocks/node package provides
you with a function that verifies whether the current request is a real webhook
request from your Liveblocks. You can set this up by setting up a
Make sure to add your “Signing Secret” from the Liveblocks dashboard—in a real project we’d recommend using an environment variable for this.
We can then check we’re receiving the correct type of event, get the updated
roomId, and handle updating the database inside there.
Before updating our database, we need to get the current room’s data. We can do this through the Get Yjs Document REST API. You use the REST API, you need to add your secret key from your project page.
We’re ready to set up our database! This is how to get started with Vercel Postgres:
Follow the getting started guide to connect the database to your Vercel project, link your environment variables, and install the packages.
And finally, we can add the Yjs JSON data to our database. Here we’re creating a
documents table that contains the following fields:
|The stringified JSON Yjs data.|
This is how to implement it in your endpoint:
To check if your database synchronization is working, you can replay a
yDocUpdated event from the Liveblocks dashboard.
Then go to the Data page on your Vercel Postgres dashboard, find your table in the dropdown, and check the entries. You should now see your Yjs document—we’ve successfully set up data synchronization!
When a user edits Yjs data in your app, this function will be called, and your database will be updated. You can rely on this to stay up to date, within the throttle limit.
Note that the
YDocUpdated event is
throttled, and only runs once every 5 minutes. When building with webhooks, it
can sometimes be helpful to temporarily listen for
UserEntered instead, a
non-throttled event, and then refresh the page to trigger it.
Make sure to change your code back to the correct event type when you’re done.