mysql - MySQL connector for Tarantool

Getting Started

Prerequisites

• Tarantool 1.6.5+ with header files (tarantool && tarantool-dev / tarantool-devel packages).
• MySQL 5.1 header files (libmysqlclient-dev package).
• OpenSSL development package.

If you prefer to install the connector using a system package manager you don't need to manually install dependencies.

Installation

Build from sources

Clone repository and then build it using CMake:

git clone https://github.com/tarantool/mysql.git tarantool-mysql
cd tarantool-mysql && cmake . -DCMAKE_BUILD_TYPE=RelWithDebInfo
make
make install

tarantoolctl rocks

You can also use tarantoolctl rocks:

tarantoolctl rocks install mysql

Install a package

Enable tarantool repository and install tarantool-mysql package:

apt-get install tarantool-mysql # Debian or Ubuntu
yum install tarantool-mysql     # CentOS
dnf install tarantool-mysql     # Fedora

Usage

local mysql = require('mysql')
local pool = mysql.pool_create({ host = '127.0.0.1', user = 'user', password = 'password', db = 'db', size = 5 })
local conn = pool:get()
local tuples, status  = conn:execute("SELECT ? AS a, 'xx' AS b, NULL as c", 42))
conn:begin()
conn:execute("INSERT INTO test VALUES(1, 2, 3)")
conn:commit()
pool:put(conn)

API Documentation

conn = mysql.connect(opts = {})

Connect to a database.

Options:

• host - hostname to connect to
• port - port number to connect to
• user - username
• password - password
• db - database name

Returns:

• connection ~= nil on success
• error(reason) on error

conn:execute(statement, ...)

Execute a statement with arguments in the current transaction.

Returns:

• { { { column1 = value, column2 = value }, ... }, { {column1 = value, ... }, ...}, ...}, true on success
• error(reason) on error

Example:

tarantool> conn:execute("SELECT ? AS a, 'xx' AS b", 42)
---
- - - a: 42
      b: xx
- true
...

conn:begin()

Begin a transaction.

Returns: true

conn:commit()

Commit current transaction.

Returns: true

conn:rollback()

Rollback current transaction.

Returns: true

conn:ping()

Execute a dummy statement to check that connection is alive.

Returns:

• true on success
• false on failure

conn:quote()

Quote a query string.

Returns:

• quoted_string on success
• error(reason) on error

pool = mysql.pool_create(opts = {})

Create a connection pool with count of size established connections.

Options:

• host - hostname to connect to
• port - port number to connect to
• user - username
• password - password
• db - database name
• size - count of connections in pool

Returns

• pool ~=nil on success
• error(reason) on error

conn = pool:get()

Get a connection from pool. Reset connection before returning it. If connection is broken then it will be reestablished. If there is no free connections then calling fiber will sleep until another fiber returns some connection to pool.

Returns:

• conn ~= nil

pool:put(conn)

Return a connection to connection pool.

Options

• conn - a connection

Comments

All calls to connections api will be serialized, so it should to be safe to use one connection from some count of fibers. But you should understand, that you can have some unwanted behavior across db calls, for example if another fiber 'injects' some sql between two your calls.

See Also

• Tests
• Tarantool
• Tarantool Rocks