Using Appwrite Realtime Subscriptions for Live Document Updates

Problem: Avoiding Polling for Live Data

Many applications need to show the latest data as soon as it changes—think chat messages, dashboard metrics, or collaborative editors. Polling the database every few seconds creates unnecessary network traffic and adds latency, especially when updates are infrequent.

How Appwrite Realtime Works

Appwrite’s Realtime feature exposes a WebSocket‑based publish/subscribe channel. When you enable Realtime for a collection, the server pushes a message to every subscribed client the instant a document is created, updated, or deleted. This eliminates client‑side polling and delivers updates with near‑zero delay.

Enabling Realtime on a Collection

1. Open the Appwrite console (or use the SDK/CLI) and create a collection if you don’t already have one.
2. In the collection settings, toggle the Realtime switch to ON. Note the Collection ID displayed—this identifier is used in the subscription URL.
3. Make sure your project has the Realtime feature enabled (it is on by default for new projects).

Worked Example: Subscribing to Document Changes

The following JavaScript snippet can be run in a browser console or a Node.js environment after installing the Appwrite SDK (npm install appwrite). Replace the placeholders with your actual project and collection IDs.

// Initialize the Appwrite client
const client = new Appwrite.Client();
client
  .setEndpoint('https://cloud.appwrite.io/v1')   // Adjust if self‑hosted
  .setProject('YOUR_PROJECT_ID');                // <-- replace

// Optional: authenticate if your collection requires permissions
// const account = new Appwrite.Account(client);
// await account.createEmailPasswordSession('user@example.com', 'password');

const databases = new Appwrite.Databases(client);

// Build the Realtime topic for the collection
const COLLECTION_ID = 'YOUR_COLLECTION_ID';      // <-- replace
const topic = `collections.${COLLECTION_ID}.documents`;

// Open the WebSocket subscription
const subscription = client.subscribe(topic);

subscription.on('event', (payload) => {
  // payload contains the full document and event type
  console.log('Realtime event:', payload);
  // Example: update UI based on payload.payload.data
});

// To stop listening later:
// subscription.unsubscribe();

When a document is inserted, updated, or removed in the specified collection from any client (or server‑side code), the callback logs the event instantly. You can verify this by opening two browser tabs: one runs the snippet above, the other inserts a document via the SDK; the first tab should log the event without any manual refresh.

Trade‑offs and Limitations

• Free‑tier connection limit: The hosted free plan allows at most 100 concurrent Realtime connections per project. Exceeding this causes new sockets to be disconnected until existing ones close.
• Message ordering under load: While Appwrite strives for in‑order delivery, bursts of updates can cause slight reordering; clients should be tolerant or implement their own sequencing if strict order is required.
• Bandwidth considerations: Each event includes the full document payload. Large documents or high‑frequency updates increase data transfer; consider projecting only needed fields or using a change‑data‑capture pattern on the client side.
• Client‑side reconciliation: Network interruptions may cause missed events. Applications should implement reconnection logic and, if necessary, refetch missed data after a disconnect.

Actionable Next Steps

To test the feature in a controlled environment:

1. Run a local Appwrite instance with Docker: docker run -p 80:80 appwrite/appwrite:1.5.
2. Create a test collection via the console and enable Realtime.
3. Open two browser tabs; in the first tab paste the subscription snippet (adjusting endpoint to http://localhost/v1 and your local project ID).
4. In the second tab, use the SDK to insert a document into the same collection.
5. Observe the first tab’s console for the Realtime event.
6. Check the Appwrite console’s Realtime metrics to ensure the concurrent connection count stays below the free‑tier limit while testing.

If you anticipate needing more than 100 simultaneous sockets, plan to upgrade to a paid Appwrite plan or self‑host a higher‑capacity deployment. Monitoring connection counts and message sizes early helps avoid surprises as your application scales.