package mysql_protocol

  1. Overview
  2. Docs

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

License:

External dependencies:

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 = {
  1. client_error_errno : int;
    (*

    error number

    *)
  2. client_error_sqlstate : string;
    (*

    state

    *)
  3. 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 = {
  1. sockaddr : Unix.sockaddr;
    (*

    socket

    *)
  2. capabilities : Mp_capabilities.capabilities list;
    (*

    capabilities

    *)
  3. max_packet_size : Stdlib.Int64.t;
    (*

    max packet size

    *)
  4. charset_number : int;
    (*

    charset

    *)
  5. user : string;
    (*

    login

    *)
  6. password : string;
    (*

    password

    *)
  7. databasename : string;
    (*

    database name (can be empty)

    *)
}

Client configuration.

type connection = {
  1. configuration : configuration;
    (*

    configuration

    *)
  2. mutable channel : (Stdlib.in_channel * Stdlib.out_channel) option;
    (*

    channel between client and server

    *)
  3. mutable handshake : Mp_handshake.handshake option;
    (*

    handshake answer from the server

    *)
}

Client connection.

type dml_dcl_result = {
  1. affected_rows : Stdlib.Int64.t;
    (*

    number of affected rows

    *)
  2. insert_id : Stdlib.Int64.t * Big_int.big_int;
    (*

    auto_increment id after an INSERT statement

    *)
  3. server_status : int;
    (*

    status

    *)
  4. warning_count : int;
    (*

    warning

    *)
  5. 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 = {
  1. prepare_handler : Stdlib.Int64.t;
  2. prepare_nb_columns : int;
  3. prepare_nb_parameters : int;
  4. prepare_warning_count : int;
  5. prepare_parameters_fields : Mp_field_packet.field_packet list;
  6. prepare_parameters_names : Mp_field.field_name list;
  7. prepare_columns_fields : Mp_field_packet.field_packet list;
  8. 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).

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.

OCaml

Innovation. Community. Security.