VStream supports copying the current contents of a table — as you will often not
have the binary logs going back to the creation of the table — and then begin streaming
new changes to the table from that point on. It also supports resuming this initial copy
phase if it's interrupted for any reason.
In addition to the typical Context usage, it can contain a custom key-value pair where the key is 1 and the value is a
CallerID. This value is then passed along to
tablets to identify the originating client for the request. It is not meant to be secure, but
primarily informational. The client can provide whatever info they want in the
CallerID fields and they will be trusted by the servers
as this information is primarily used to aid in monitoring and debugging. The vtgate propagates
the value to the source vttablet processes and the tablets may use this information for various
monitoring, metrics, and logging purposes. It can, however, also be used for other purposes such as denying the client
access to tables during a migration (MoveTables or Reshard).
The keyspace, shard, and GTID position list to start streaming from. If no ShardGtid.Gtid value is provided
then a table copy phase will be initiated for the tables matched
by the provided filter on the given shard.
If the ShardGtid.Shard value is omitted, this means that all shards in the keyspace specified in the ShardGtid.Keyspace value are included.
Additionally, if the ShardGtid.Keyspace value has a / prefix, you can use regular expressions such as /.* to include all keyspaces.
The tables which you want to subscribe to change events from — in the given keyspace(s) and shard(s) contained
in the provided VGtid — and any query predicates to use when filtering the rows for which change
events will be generated.
When enabled the vtgate will keep the events in the stream roughly time aligned — it is aggregating streams coming
from each of the shards involved — using the event timestamps to ensure the maximum time skew between the source
tablet shard streams is kept under 10 minutes. When it detects skew between the source streams it will pause sending
the client more events and allow the lagging shard(s) to catch up.
There is no strict ordering of events across shards and the client will need to examine the event timestamps.
If specified, these cells (comma-separated list) are used
when selecting stream source tablets. When no value is specified the vtgate will
default to looking for source tablets within its own local cell.
If specified, this determines which cells to give preference to during tablet selection.
By default, preferlocalwithalias is used in order to give preference to the caller's local cell and then any alias its cell belongs to.
If onlyspecified is given, then only tablets within the specified Cells field value will be considered.
The VStream gRPC returns
a VStreamReader and a non-nil error if
the stream could not be initialized. You would call the Recv method on that
VStreamReader in a for loop and
responses will be sent when available. Each response consisting of the following two parameters:
An array of VEvent objects — the new messages to process in the stream
An error — an error that, if non-nil, indicates the stream has been closed (EOF) or an error occurred