Client Libraries

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 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 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. vtgateclienttest is a small server that simulates a real vtgate server 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. 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.

Available libraries


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 ""

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.