remote library

Library support for accessing remote databases.

This library provides support for database servers and remote clients. It makes few assumptions over the underlying two-way communication channel, except that it must adhere to the StreamChannel guarantees.

This allows you to use a drift database (including stream queries) over a remote connection as it were a local database. For instance, this api could be used for

• accessing databases on a remote isolate: The package:drift/isolate.dart library is implemented on top of this library.
• running databases in web workers
• synchronizing stream queries and data across multiple tabs with shared web workers
• accessing databases over TCP or WebSockets.

Drift uses an internal protocol to serialize database requests over stream channels. To make the implementation of channels easier, drift guarantees that nothing but the following messages will be sent:

• primitive values (null, int, bool, double, String)
• lists

Lists are allowed to nest, but drift will never send messages with cyclic references. Implementations are not required to reserve the type argument of lists when serializing them. However, note that drift might encode a List<int> as Uint8List. For performance reasons, channel implementations should preserve this.

Drift assumes full control over the StreamChannels it manages. For this reason, do not send your own messages over them or close them prematurely. If you need further channels over the same underlying connection, consider a MultiChannel instead.

The public apis of this libraries are stable. The present experimental annotation refers to the underlying protocol implementation. As long as this library is marked as experimental, the communication protocol can change in every version. For this reason, please make sure that all channel participants are using the exact same drift version. For local communication across isolates or web workers, this is usually not an issue.

For an example of a channel implementation, you could study the implementation of the package:drift/isolate.dart library, which uses this library to implement its apis. The web documentation on the website contains another implementation based on web workers that might be of interest.

Classes

DriftServer

Serves a drift database connection over any two-way communication channel.

Functions

connectToRemoteAndInitialize(StreamChannel<Object?> channel, {bool debugLog = false, bool serialize = true, bool singleClientMode = false}) → Future<DatabaseConnection>

Connects to a remote server over a two-way communication channel.

remote(StreamChannel<Object?> channel, {bool debugLog = false, bool serialize = true, bool singleClientMode = false}) → DatabaseConnection

Connects to a remote server over a two-way communication channel.

shutdown(StreamChannel<Object?> channel, {bool serialize = true}) → Future<void>

Sends a shutdown request over a channel.

Exceptions / Errors

DriftRemoteException

An exception reported on the other end of a drift remote protocol.