sql: support prepared statements

This patch adds the support of prepared statements.
Changed the interface of the method Execute for accepting the first
argument as a string (for sql queries) or uint64 (for statements id).
Added new methods for connector's interface in connector.go.
Added new IPROTO-constants for support of prepared statements
in const.go. Updated multi-package for corresponding it to connector's
interface.

Added a new function for checking the count of prepared statements in
config.lua in tests for Prepare and Unprepare.
Added benchmarks for SQL-select prepared statement.
Added examples of using Prepare in example_test.go.
Fixed some grammar inconsistencies for the method Execute.
Updated CHANGELOG.md.

Follows up #62
Closes #117

Author: vr009

CHANGELOG.md

@@ -18,6 +18,7 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 - queue-utube handling (#85)
 - Master discovery (#113)
 - SQL support (#62)
+- Prepared statements (#117)
 
 ### Fixed
 

config.lua

@@ -91,6 +91,7 @@ box.once("init", function()
     -- grants for sql tests
     box.schema.user.grant('test', 'create,read,write,drop,alter', 'space')
     box.schema.user.grant('test', 'create', 'sequence')
+    box.schema.user.grant('guest', 'super')
 end)
 
 local function func_name()
@@ -110,11 +111,15 @@ local function simple_incr(a)
 end
 rawset(_G, 'simple_incr', simple_incr)
 
+local function test_stmt_count_check()
+    return box.info().sql().cache.stmt_count
+end
+rawset(_G, 'test_stmt_count_check', test_stmt_count_check)
 box.space.test:truncate()
 
 --box.schema.user.revoke('guest', 'read,write,execute', 'universe')
 
 -- Set listen only when every other thing is configured.
 box.cfg{
-    listen = os.getenv("TEST_TNT_LISTEN"),
+    listen = 3013,
 }

connector.go

@@ -17,7 +17,9 @@ type Connector interface {
 	Call(functionName string, args interface{}) (resp *Response, err error)
 	Call17(functionName string, args interface{}) (resp *Response, err error)
 	Eval(expr string, args interface{}) (resp *Response, err error)
-	Execute(expr string, args interface{}) (resp *Response, err error)
+	Execute(expr interface{}, args interface{}) (resp *Response, err error)
+	Prepare(expr string) (resp *Response, err error)
+	Unprepare(stmt uint64) (resp *Response, err error)
 
 	GetTyped(space, index interface{}, key interface{}, result interface{}) (err error)
 	SelectTyped(space, index interface{}, offset, limit, iterator uint32, key interface{}, result interface{}) (err error)
@@ -28,6 +30,7 @@ type Connector interface {
 	CallTyped(functionName string, args interface{}, result interface{}) (err error)
 	Call17Typed(functionName string, args interface{}, result interface{}) (err error)
 	EvalTyped(expr string, args interface{}, result interface{}) (err error)
+	ExecuteTyped(expr interface{}, args interface{}, result interface{}) (SQLInfo, []ColumnMetaData, error)
 
 	SelectAsync(space, index interface{}, offset, limit, iterator uint32, key interface{}) *Future
 	InsertAsync(space interface{}, tuple interface{}) *Future
@@ -38,4 +41,7 @@ type Connector interface {
 	CallAsync(functionName string, args interface{}) *Future
 	Call17Async(functionName string, args interface{}) *Future
 	EvalAsync(expr string, args interface{}) *Future
+	ExecuteAsync(expr interface{}, args interface{}) *Future
+	PrepareAsync(expr string) *Future
+	UnprepareAsync(stmt uint64) *Future
 }

const.go

@@ -12,6 +12,7 @@ const (
 	UpsertRequest    = 9
 	Call17Request    = 10
 	ExecuteRequest   = 11
+	PrepareRequest   = 13
 	PingRequest      = 64
 	SubscribeRequest = 66
 
@@ -34,6 +35,7 @@ const (
 	KeySQLText      = 0x40
 	KeySQLBind      = 0x41
 	KeySQLInfo      = 0x42
+	KeyStmtID       = 0x43
 
 	KeyFieldName               = 0x00
 	KeyFieldType               = 0x01

example_test.go

@@ -499,3 +499,42 @@ func ExampleConnection_Execute() {
 	fmt.Println("MetaData", resp.MetaData)
 	fmt.Println("SQL Info", resp.SQLInfo)
 }
+
+// To use prepared statements to query a tarantool instance, call Prepare.
+func ExampleConnection_Prepare() {
+	// Tarantool supports SQL since version 2.0.0
+	isLess, _ := test_helpers.IsTarantoolVersionLess(2, 0, 0)
+	if isLess {
+		return
+	}
+	server := "127.0.0.1:3013"
+	opts := tarantool.Opts{
+		Timeout:       500 * time.Millisecond,
+		Reconnect:     1 * time.Second,
+		MaxReconnects: 3,
+		User:          "test",
+		Pass:          "test",
+	}
+	client, err := tarantool.Connect(server, opts)
+	if err != nil {
+		fmt.Printf("Failed to connect: %s", err.Error())
+	}
+
+	// pass a query to prepare
+	stmtResp, err := client.Prepare("SELECT id FROM SQL_TEST WHERE id=? AND name=?")
+	fmt.Println("Prepare")
+	fmt.Println("Error", err)
+	fmt.Println("Code", stmtResp.Code)
+	fmt.Println("Statement ID", stmtResp.StmtID)
+
+	stmtID := stmtResp.StmtID
+
+	// pass the id of the statement to Execute
+	resp, err := client.Execute(stmtID, []interface{}{2, "test"})
+	fmt.Println("Execute")
+	fmt.Println("Error", err)
+	fmt.Println("Code", resp.Code)
+	fmt.Println("Data", resp.Data)
+	fmt.Println("MetaData", resp.MetaData)
+	fmt.Println("SQL Info", resp.SQLInfo)
+}

multi/multi.go

@@ -340,13 +340,28 @@ func (connMulti *ConnectionMulti) Eval(expr string, args interface{}) (resp *tar
 	return connMulti.getCurrentConnection().Eval(expr, args)
 }
 
-// Execute passes sql expression to Tarantool for execution.
+// Execute passes a sql expression to Tarantool for execution.
 //
 // Since 1.6.0
-func (connMulti *ConnectionMulti) Execute(expr string, args interface{}) (resp *tarantool.Response, err error) {
+func (connMulti *ConnectionMulti) Execute(expr interface{}, args interface{}) (resp *tarantool.Response, err error) {
 	return connMulti.getCurrentConnection().Execute(expr, args)
 }
 
+// Prepare sends a sql statement to prepare.
+//
+// Since 1.6.0
+func (connMulti *ConnectionMulti) Prepare(expr string) (resp *tarantool.Response, err error) {
+	return connMulti.getCurrentConnection().Prepare(expr)
+}
+
+// Unprepare undo the result of Prepare request.
+//
+// It is equal to conn.UnprepareAsync(stmt).Get().
+// Since 1.6.0
+func (connMulti *ConnectionMulti) Unprepare(stmt uint64) (resp *tarantool.Response, err error) {
+	return connMulti.getCurrentConnection().Unprepare(stmt)
+}
+
 // GetTyped performs select (with limit = 1 and offset = 0) to box space and
 // fills typed result.
 func (connMulti *ConnectionMulti) GetTyped(space, index interface{}, key interface{}, result interface{}) (err error) {
@@ -401,6 +416,11 @@ func (connMulti *ConnectionMulti) EvalTyped(expr string, args interface{}, resul
 	return connMulti.getCurrentConnection().EvalTyped(expr, args, result)
 }
 
+// ExecuteTyped passes a sql expression for execution.
+func (connMulti *ConnectionMulti) ExecuteTyped(expr interface{}, args interface{}, result interface{}) (tarantool.SQLInfo, []tarantool.ColumnMetaData, error) {
+	return connMulti.getCurrentConnection().ExecuteTyped(expr, args, result)
+}
+
 // SelectAsync sends select request to Tarantool and returns Future.
 func (connMulti *ConnectionMulti) SelectAsync(space, index interface{}, offset, limit, iterator uint32, key interface{}) *tarantool.Future {
 	return connMulti.getCurrentConnection().SelectAsync(space, index, offset, limit, iterator, key)
@@ -454,3 +474,24 @@ func (connMulti *ConnectionMulti) Call17Async(functionName string, args interfac
 func (connMulti *ConnectionMulti) EvalAsync(expr string, args interface{}) *tarantool.Future {
 	return connMulti.getCurrentConnection().EvalAsync(expr, args)
 }
+
+// ExecuteAsync passes a sql expression for execution.
+//
+// Since 1.6.0
+func (connMulti *ConnectionMulti) ExecuteAsync(expr interface{}, args interface{}) *tarantool.Future {
+	return connMulti.getCurrentConnection().ExecuteAsync(expr, args)
+}
+
+// PrepareAsync passes a SQL statement to prepare.
+//
+// Since 1.6.0
+func (connMulti *ConnectionMulti) PrepareAsync(expr string) *tarantool.Future {
+	return connMulti.getCurrentConnection().PrepareAsync(expr)
+}
+
+// UnprepareAsync undo the result of Prepare request and returns Future.
+//
+// Since 1.6.0
+func (connMulti *ConnectionMulti) UnprepareAsync(stmt uint64) *tarantool.Future {
+	return connMulti.getCurrentConnection().UnprepareAsync(stmt)
+}

request.go

@@ -127,10 +127,26 @@ func (conn *Connection) Eval(expr string, args interface{}) (resp *Response, err
 //
 // It is equal to conn.ExecuteAsync(expr, args).Get().
 // Since 1.6.0
-func (conn *Connection) Execute(expr string, args interface{}) (resp *Response, err error) {
+func (conn *Connection) Execute(expr interface{}, args interface{}) (resp *Response, err error) {
 	return conn.ExecuteAsync(expr, args).Get()
 }
 
+// Prepare sends a sql statement to prepare.
+//
+// It is equal to conn.PrepareAsync(expr).Get().
+// Since 1.6.0
+func (conn *Connection) Prepare(expr string) (resp *Response, err error) {
+	return conn.PrepareAsync(expr).Get()
+}
+
+// Unprepare undo the result of Prepare request.
+//
+// It is equal to conn.UnprepareAsync(stmt).Get().
+// Since 1.6.0
+func (conn *Connection) Unprepare(stmt uint64) (resp *Response, err error) {
+	return conn.UnprepareAsync(stmt).Get()
+}
+
 // single used for conn.GetTyped for decode one tuple.
 type single struct {
 	res   interface{}
@@ -227,7 +243,7 @@ func (conn *Connection) EvalTyped(expr string, args interface{}, result interfac
 //
 // In addition to error returns sql info and columns meta data
 // Since 1.6.0
-func (conn *Connection) ExecuteTyped(expr string, args interface{}, result interface{}) (SQLInfo, []ColumnMetaData, error) {
+func (conn *Connection) ExecuteTyped(expr interface{}, args interface{}, result interface{}) (SQLInfo, []ColumnMetaData, error) {
 	fut := conn.ExecuteAsync(expr, args)
 	err := fut.GetTyped(&result)
 	return fut.resp.SQLInfo, fut.resp.MetaData, err
@@ -369,17 +385,57 @@ func (conn *Connection) EvalAsync(expr string, args interface{}) *Future {
 
 // ExecuteAsync sends a sql expression for execution and returns Future.
 // Since 1.6.0
-func (conn *Connection) ExecuteAsync(expr string, args interface{}) *Future {
+func (conn *Connection) ExecuteAsync(expr interface{}, args interface{}) *Future {
 	future := conn.newFuture(ExecuteRequest)
+	var stmtID uint64
+	exprStr, ok := expr.(string)
+	if !ok {
+		stmtID, ok = expr.(uint64)
+		if !ok {
+			err := errors.New("expr argument must be either string or uint64")
+			return NewErrorFuture(err)
+		}
+		return future.send(conn, func(enc *msgpack.Encoder) error {
+			enc.EncodeMapLen(2)
+			enc.EncodeUint64(KeyStmtID)
+			enc.EncodeUint64(stmtID)
+			enc.EncodeUint64(KeySQLBind)
+			return encodeSQLBind(enc, args)
+		})
+	}
 	return future.send(conn, func(enc *msgpack.Encoder) error {
 		enc.EncodeMapLen(2)
 		enc.EncodeUint64(KeySQLText)
-		enc.EncodeString(expr)
+		enc.EncodeString(exprStr)
 		enc.EncodeUint64(KeySQLBind)
 		return encodeSQLBind(enc, args)
 	})
 }
 
+// PrepareAsync sends a sql statement to prepare and returns Future.
+//
+// Since 1.6.0
+func (conn *Connection) PrepareAsync(expr string) *Future {
+	future := conn.newFuture(PrepareRequest)
+	return future.send(conn, func(enc *msgpack.Encoder) error {
+		enc.EncodeMapLen(1)
+		enc.EncodeUint64(KeySQLText)
+		return enc.EncodeString(expr)
+	})
+}
+
+// UnprepareAsync undo the result of Prepare request and returns Future.
+//
+// Since 1.6.0
+func (conn *Connection) UnprepareAsync(stmt uint64) *Future {
+	future := conn.newFuture(PrepareRequest)
+	return future.send(conn, func(enc *msgpack.Encoder) error {
+		enc.EncodeMapLen(1)
+		enc.EncodeUint64(KeyStmtID)
+		return enc.EncodeUint64(stmt)
+	})
+}
+
 // KeyValueBind is a type for encoding named SQL parameters
 type KeyValueBind struct {
 	Key   string

response.go

@@ -14,6 +14,7 @@ type Response struct {
 	Data     []interface{}
 	MetaData []ColumnMetaData
 	SQLInfo  SQLInfo
+	StmtID   uint64
 	buf      smallBuf
 }
 
@@ -178,6 +179,10 @@ func (resp *Response) decodeBody() (err error) {
 				if err = d.Decode(&resp.MetaData); err != nil {
 					return err
 				}
+			case KeyStmtID:
+				if resp.StmtID, err = d.DecodeUint64(); err != nil {
+					return err
+				}
 			default:
 				if err = d.Skip(); err != nil {
 					return err