Live queries

Live queries allow your application to receive real-time notifications whenever records in a table are created, updated, or deleted. The Go SDK delivers notifications through Go channels, making it easy to integrate with goroutines and concurrent patterns.

Live queries require a WebSocket connection (ws:// or wss://). They are available on *DB and *Session but not on *Transaction.

API references

Starting a live query

Use the Live function to subscribe to changes on a table. It returns a UUID that identifies the live query.

liveID, err := surrealdb.Live(ctx, db, models.Table("persons"), false)
if err != nil {
	log.Fatal(err)
}

The diff parameter controls notification format. When false, notifications contain the full record. When true, they contain JSON Patch diffs instead.

Receiving notifications

After starting a live query, call .LiveNotifications() on the *DB or *Session to get a channel that receives Notification values.

ch, err := db.LiveNotifications(liveID.String())
if err != nil {
	log.Fatal(err)
}

for notification := range ch {
	fmt.Printf("Action: %s, Result: %v\n", notification.Action, notification.Result)
}

Each notification includes:

Processing notifications in a goroutine

A common pattern is to process live query notifications in a separate goroutine while the main goroutine continues other work.

liveID, err := surrealdb.Live(ctx, db, models.Table("persons"), false)
if err != nil {
	log.Fatal(err)
}

ch, err := db.LiveNotifications(liveID.String())
if err != nil {
	log.Fatal(err)
}

go func() {
	for n := range ch {
		switch n.Action {
		case "CREATE":
			fmt.Println("New record:", n.Result)
		case "UPDATE":
			fmt.Println("Updated record:", n.Result)
		case "DELETE":
			fmt.Println("Deleted record:", n.Result)
		}
	}
}()

Stopping a live query

Use the Kill function to terminate a live query on the server and close its notification channel.

if err := surrealdb.Kill(ctx, db, liveID.String()); err != nil {
	log.Fatal(err)
}

Kill both sends the kill RPC to the server and closes the local notification channel. If you only want to close the channel without killing the server-side query, use .CloseLiveNotifications() instead.

Learn more

• •

  DB API reference for complete function signatures and parameters

• •

  Connecting to SurrealDB for WebSocket connection requirements

• •

  Multiple sessions for session-scoped live queries

• •

  Reliable connections for live queries that persist across reconnections

• •

  SurrealQL LIVE statement for the underlying query language syntax