5.1 KiB
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 proto3 service definition. Vitess supports gRPC, and you can use the proto compiler 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.
Core Principles
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
vtgateservice. 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
RPC system.
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.vtgateclienttestis a small server that simulates a realvtgateserver and returns specific responses to allow for full client feature coverage.
Language-specific considerations
- 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, though this support is not yet provided in some cases:
- Go: database/sql package (done)
- Java: JDBC compliance (in progress)
- PHP: PHP Data Objects
PDOcompliance (in progress) - Python: DB API compliance (done)
- 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.
Available libraries
Go
The Go client interface is in the "vtgateconn" package.
There are multiple implementations available. We recommend to use the "grpc" implementation. Load it by importing its package:
import "github.com/youtube/vitess/go/vt/vtgate/grpcvtgateconn"
When you connect to vtgate, use the
DialProtocol method
and specify "grpc" as protocol.
Alternatively, you can set the
command line flag "vtgate_protocol"
to "grpc".
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 ExecuteShards method and pass "0" as only shard.
For an example how to use the Go client, see the end-to-end test local_cluster_test.go. 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.