mysql_protocol 3.0.3 · OCaml Package

MySQL Protocol natively implements the MySQL client protocol (ie without any binding to C library).

License:

The MySQL Protocol library uses the LGPL license version 3.

External dependencies:

Bitstring.
Cryptokit.
optional: oUnit (to run the tests suite).

Tested configurations:

MySQL 5.1.69 server (64 bits) - FreeBSD -stable.
MySQL 5.5.31 server (64 bits) - FreeBSD -stable.
MySQL 5.6.26 server (64 bits) - FreeBSD -stable.
MariaDB 10.5.6 server (64 bits) - FreeBSD -stable.

The following functionalities are not implemented:

Master/slave.
Long data packet.
Compression.
Encryption.

Known limitations:

On 32 bits platforms, the data retrieved from the server cannot exceed 16777211 bytes (the OCaml Sys.max_string_length value). So, for instance, you cannot retrieve a column with a binary BLOB data greater than this max size. And if you have a TEXT column encoded in UTF-8, as a character will take 3 to 4 bytes, you will only be able to retrieve between 16777211/3=5592403 and 16777211/4=4194302 characters. On 64 bits platforms, the limit is so high that this limitation can be ignored.

Usage examples:

See "examples" directory.

type client_error = {

client_error_errno : int;
(*
error number
*)
client_error_sqlstate : string;
(*
state
*)
client_error_message : string;
(*
error message
*)

}

MySQL error.

exception Error of client_error

Raise if the MySQL server returns an error.

exception Fetch_no_more_rows

Raise if fetch is called and the server has no more rows to return.

type configuration = {

sockaddr : Unix.sockaddr;
(*
socket
*)
capabilities : Mp_capabilities.capabilities list;
(*
capabilities
*)
max_packet_size : Stdlib.Int64.t;
(*
max packet size
*)
charset_number : int;
(*
charset
*)
user : string;
(*
login
*)
password : string;
(*
password
*)
databasename : string;
(*
database name (can be empty)
*)

}

Client configuration.

type connection = {

configuration : configuration;
(*
configuration
*)
mutable channel : (Stdlib.in_channel * Stdlib.out_channel) option;
(*
channel between client and server
*)
mutable handshake : Mp_handshake.handshake option;
(*
handshake answer from the server
*)

}

Client connection.

type dml_dcl_result = {

affected_rows : Stdlib.Int64.t;
(*
number of affected rows
*)
insert_id : Stdlib.Int64.t * Big_int.big_int;
(*
auto_increment id after an INSERT statement
*)
server_status : int;
(*
status
*)
warning_count : int;
(*
warning
*)
message : string;
(*
warning message
*)

}

DML (Data Manipulation Language) and DCL (Data Control Language) result. Result of INSERT, UPDATE, GRANT... statements.

insert_id can be negative in two cases:

the auto_increment value is indeed negative (SIGNED field).
the returned value overflows Int64 maximum (BIGINT UNSIGNED field).

Unfortunately, the protocol gives no way to differentiate these two cases (see this bug report). So we return two values:

the first one is a Int64 and must be used when the auto_increment is _not_ a BIGINT UNSIGNED field.
the second one is a Big_int and must be used when the auto_increment is a BIGINT UNSIGNED field.

type prepare_result = {

prepare_handler : Stdlib.Int64.t;
prepare_nb_columns : int;
prepare_nb_parameters : int;
prepare_warning_count : int;
prepare_parameters_fields : Mp_field_packet.field_packet list;
prepare_parameters_names : Mp_field.field_name list;
prepare_columns_fields : Mp_field_packet.field_packet list;
prepare_columns_names : Mp_field.field_name list;

}

Result for a prepare command.

type executable_statement

type execute_result

type result

val error_exception_to_string : client_error -> string

Convert MySQL exception to string.

val dml_dcl_result_to_string : dml_dcl_result -> string

Convert DML (Data Manipulation Language) and DCL (Data Control Language) result to string.

val configuration : 
  user:string ->
  password:string ->
  sockaddr:Unix.sockaddr ->
  ?databasename:string ->
  ?max_packet_size:Stdlib.Int64.t ->
  ?charset:(Mp_charset.charset_name * Mp_charset.collation_name) ->
  ?capabilities:Mp_capabilities.capabilities list ->
  unit ->
  configuration

Build client configuration.

parameter user
Login.

parameter password
Password.

parameter sockaddr
Socket for the connection to the server.

parameter databasename
Database name.

parameter max_packet_size
Max client/server packet size.

parameter charset
Charset and collation name.

parameter capabilities
Client capabilities.

val connect : configuration:configuration -> ?force:bool -> unit -> connection

Connection to the server.

parameter configuration
Client configuration.

parameter force
If true, the connection is immediately opened. Otherwise, the connection is opened only the first time it is needed.

val change_user : 
  connection:connection ->
  user:string ->
  password:string ->
  ?databasename:string ->
  ?charset:(Mp_charset.charset_name * Mp_charset.collation_name) ->
  unit ->
  configuration

Change user / databasename / charset

parameter connection
Connection.

parameter user
Login.

parameter password
Password.

parameter databasename
Database name.

parameter charset
Charset and collation name.

val reset_session : connection:connection -> unit

Reset the session : equivalent to a disconnect/reconnect with the same configuration.

parameter connection
Connection.

val reset_connection : connection:connection -> unit

Reset the connection without re-authentication. From documentation), this will:

rollback any open transaction
reset transaction isolation level
reset session variables
delete user variables
remove temporary tables
remove all PREPARE statement

Database will NOT be reset to initial value.

parameter connection
Connection.

val use_database : connection:connection -> databasename:string -> unit

Change current database.

parameter connection
Connection.

parameter databasename
Database name.

val ping : connection:connection -> unit

Send a PING to the server.

parameter connection
Connection.

val create_statement_from_string : string -> executable_statement

Create a new statement from a SQL string.

val prepare : 
  connection:connection ->
  statement:executable_statement ->
  executable_statement

Prepare a statement.

parameter connection
Connection.

parameter statement
Executable statement.

val get_created_statement : executable_statement -> string

Extract the statement from an executable statement.

val get_prepared_statement : executable_statement -> string * prepare_result

Extract the prepared statement from an executable statement.

val execute : 
  connection:connection ->
  statement:executable_statement ->
  ?filter:((string * int) list -> Mp_data.t list -> bool) option ->
  ?iter:((string * int) list -> Mp_data.t list -> unit) option ->
  ?return_all_raw_mysql_data:bool ->
  ?params:Mp_data.t list ->
  ?bind:Mp_execute.bind ->
  ?flag:Mp_execute.flag ->
  unit ->
  execute_result

Execute a statement (prepared or not prepared) and return the result.

parameter connection
Client connection.

parameter statement
Executable statement.

parameter filter
Optional function applied to each row of the result. If it returns true, the row is kept in the return result. Otherwise, the row is discarded from the result.

parameter iter
Optional function applied to each row of the result. If there is also a filter function, this filter is applied _before_ the iter function. So a row will be processed by the iter function only if this row has passed the filter function.

parameter return_all_raw_mysql_data
If true, the returned result will include MySQL raw data. It's useful if you need for instance to get the MySQL columns types and options. The default is false.

parameter params
List of params for prepared statement. Must be in the same order than in the prepared statement.

parameter bind
Specify if the params must be bound into the prepared statement. The default is to bind. A statement must be at least executed once with bind. After that, if you need to execute again the same statement with the same params, you can use No_bind.

parameter flag
Cursor options. To use fetch to get the statement results, you must specify the Cursor_type_read_only option.

val get_result : execute_result -> result

Extract the result part from an executed result.

val get_result_multiple : execute_result -> result list

Extract the multiple part from an executed result (for CALL result).

val get_result_set : result -> Mp_result_set_packet.result_select

Extract the set part from a result (for SELECT result).

val get_result_ok : result -> dml_dcl_result

Extract the ok part from a result (for INSERT, UPDATE, GRANT... result).

val fetch : 
  connection:connection ->
  statement:execute_result ->
  ?nb_rows:int64 ->
  ?filter:((string * int) list -> Mp_data.t list -> bool) option ->
  ?iter:((string * int) list -> Mp_data.t list -> unit) option ->
  ?return_all_raw_mysql_data:bool ->
  unit ->
  result

Fetch row(s) from an executed result. It must be a prepared statement executed with a cursor.

parameter connection
Client connection.

parameter statement
Executable statement.

parameter nb_rows
Number of row(s) to fetch. Default is 1.

parameter filter
Optional function applied to each fetched rows. If it returns true, the row is kept. Otherwise, the row is discarded.

parameter iter
Optional function applied to each fetched rows. If there is also a filter function, this filter is applied _before_ the iter function. So a row will be processed by the iter function only if this row has passed the filter function.

parameter return_all_raw_mysql_data
If true, the fetch will include MySQL raw data. It's useful if you need for instance to get the MySQL columns types and options. The default is false.

val get_fetch_result_set : result -> Mp_result_set_packet.result_select

Extract the set part from a fetch.

val close_statement : 
  connection:connection ->
  statement:executable_statement ->
  unit

Close and destroy the prepared statement. It will be unusable.

parameter connection
Client connection.

parameter statement
Executable statement.

val disconnect : connection:connection -> unit

Close the connection to the server.

parameter connection
Client connection.

package mysql_protocol