Realtime database

The realtime module is responsible to propagate database changes to the concerned clients in realtime. The clients execute a liveQuery which is similar to a normal query with a where clause. The realtime module makes sure that whenever there is any change in the result set (results get added, removed or updated), the client will be updated.

How it works?

The realtime module guarantees that all changes will propagate to the client irrespective of failures on the backend. To achieve these guarantees, Space Cloud uses Apache Kafka under the hood.

However, Space Cloud doesn't use Kafka by default. It uses Kafka ony when the PROD environment variable is set to true or when space-cloud is started with the --prod flag.

Note: The distributed mode of realtime module is not implemented yet.


There are a few limitations in the queries which can be used while using the realtime module.

  • The primary key must be _id in case of MongoDB and id for MySQL and Postgres and of type text, varchar or string.
  • All documents to be inserted must have the _id (for MongoDB) or id (for MySQL and Postgres) fields set.
  • The fields used in the where clause of liveQuery should not be updated by another request.
  • All updates and deletes can be made on a single document only using the _id or id field in the where clause.

Enable the realtime module

The configuration pertaining to the realtime module can be found under the realtime key under the modules object. Here's a snippet showing how to enable the realtime module. This 3 line snippet will set up all the necessary routines required by the realtime module.

    enabled: true     # Enable the realtime module globally
    kafka: localhost  # Connection string for kafka

# Config for other modules go here 

You also need to to enable the feature on the collections you want to sync. Here's a snippet which indicates that the collection todos is realtime.

      conn: mongodb://localhost:27017
      isPrimary: true
          isRealtimeEnabled: true   # This makes the todos collection realtime
              rule: allow
              rule: allow
              rule: allow
              rule: allow
    enabled: true     # Enable the realtime module globally
    kafka: localhost

  # Config for other modules go here 

Next steps

That's all you need to do to enable the realtime module. It's time to go ahead and how to use the realtime module on the frontend.

Have a technical question?

Edit docs!