A pure php implementation of the PDO interface for Vitess (vitess.io)
PHP Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Vitess PDO driver

This library provides a PDO driver for Vitess. It is not a driver for the PDO PHP extension, it's just a pure PHP implementation of the PDO interface. It is interchangeable with the original PDO class, if no instanceof \PDO checks are present in the application code.

Current state

Currently the code is beta quality, not all PDO methods and classes are implemented, but it already has been tested in our application and it works properly. Everybody is welcome to create pull requests to implement some of the missing things.

Also, the unit tests are currently bound to our Vitess dev instance, there is a plan to change this. There's also not much documentation yet, but people requested the driver, so we decided to go open source.

This driver isn't compatible with any official MySql/MariaDB management tools, but we created an Adminer fork, which you can use to have some insight about the data in your Vitess cluster.


The Vitess PHP client, which is used in the PDO implementation has a dependency on the PHP GRPC extension, which has to be installed together with GRPC and Protobuf.

To install the composer package, run the following command:

composer require pixelfederation/vitess-php-pdo

After the installation of the dependencies, the PDO class should be instantiated this way:

$pdo = new \VitessPdo\PDO("keyspace={$keyspace};host={$host};port={$port}");
  • $keyspace: vitess keyspace (alternative to database name)
  • $host: IP or hostname of Vtgate
  • $port: Vtgate port

If you want to use some limited DDL support, you have to instantiate the PDO instance this way:

$pdo = new \VitessPdo\PDO("vitess:cell={$cell};keyspace={$keyspace};host={$host};port={$port};vtctld_host={vtcrld_host};vtctld_port={vtctld_port}");
  • $cell: name of the Vitess cell
  • $vtctld_host: IP or hostname of Vtctld
  • $vtctld_port: Vtctld port

Only a limited subset of DDL queries is supported (the goal of the implementation was to get the PDO driver work with Adminer.


If you'd like to contribtue, we strongly recommend to run


from the project directory. This script will set up a commit hook, which checks the PSR/2 coding standards using PHPCS and also runs PHP linter and PHP Mess Detector PHPMD

To be able to run the unit tests, you need to have installed Vitess locally for now (there is a guide for Ubuntu and OS X).

The tests need to be run from a shell which has set all the environment variables from the guide, to be ready to run vitess instances. After setting the enviroment variables, just got to the library root folder and run the following command:


If there is a need to perform any sql queries in the newly written unit tests, there is a database schema provided in the tests/vitess/schema folder. The schema contains two shards - lookup and user.

Known issues

On OS X there is was "sometimes" a problem with the current GRPC version (0.13) and PHP GRPC extension (0.8) (both of the versions are mandatory for the PDO driver and Vitess), meaning that the GRPC requests to Vitess are a little bit slower for an unknown reason. Linux is unaffected.

Also, there is no PHP 7 GRPC extension yet.

Both issues were resolved in grpc 1.0.0RC1 and 1.0.0RC2, the extension should be stable now.