You can access your Vitess cluster using a variety of clients and
programming languages. Vitess client libraries help your client
application to more easily talk to your storage system to query data.
Vitess' service is exposed through a
service definition. Vitess supports gRPC,
and you can use the
to generate stubs that can call the API in any language that the
gRPC framework supports.
This document explains the client library strategy for Vitess.
Vitess client libraries follow these core principles:
- Libraries fully implement the server API and provide access to all
API methods, which support the following types of functions:
- Transactions (begin, commit, rollback)
- Queries targeted to a specific shards or groups of shards
- Queries targeted based on sharding key values
- Queries that monitor sharding configurations
- MapReduce operations
- Libraries expose an identical set of well-documented error codes.
- Libraries provide a single-connection abstraction to the
vtgate service. The connection object should be
thread-safe, if applicable, and should support multiplexing for
streaming queries, transactions, and other operations that rely
on multiple queries.
- A low-level plug-in abstraction enables the transport to be plugged
in so that the application can use different RPC frameworks. For
instance, within Google, we use proto2 objects with an internal
Note: If the proto3 library is available in
your language, we recommend that your API calls use the data types
generated from our .proto files.
- A high-level object abstraction allows the user to execute transactions
without having to keep track of the database session.
- Libraries support
vtgateclienttest, enabling you to
fully unit-test all API calls.
a small server that simulates a real
and returns specific responses to allow for full client feature
- Each client library should support language-specific, idiomatic
constructs to simplify application development in that language.
- Client libraries should integrate with the following language-specific
database drivers. For example, current languages implement the following:
- Libraries provide a thin wrapper around the proto3 service definitions.
Those wrappers could be extended with adapters to higher level libraries
like SQLAlchemy (Python) or JDBC (Java), with other object-based helper
classes in the relevant language, or both.
- If a well-known MapReduce framework exists for the language, the client
library should provide a data source and a data sink. For example, you
can read data from Vitess inside a Hadoop MapReduce job and save the
output into Vitess.
The Go client interface is in the
There are multiple implementations available. We recommend to use the
Load it by importing its package:
When you connect to vtgate, use the
and specify "grpc" as protocol.
Alternatively, you can set the
command line flag "vtgate_protocol"
The Go client interface has multiple
Execute*() methods for different use-cases
and sharding configurations. When you start off with an unsharded database, we
recommend to use the
and pass "0" as only shard.
For an example how to use the Go client, see the end-to-end test
From this test file, you can also reuse the "LaunchVitess" call to
instantiate a minimal Vitess setup (including a MySQL server). This way you can
test your application against an actual instance.