postgresql

Bindings to the PostgreSQL library
IN THIS PACKAGE
Module Postgresql
method finish : unit

#finish closes the connection.

  • raises Error

    if there is a connection error.

method try_reset : unit

#try_reset tries to reset the connection if it is bad. If resetting fails, the error exception will be raised with Connection_failure.

  • raises Error

    if there is a connection error.

method reset : unit

#reset resets the connection.

  • raises Error

    if there is a connection error.

Asynchronous Notification

method notifies : Notification.t option

#notifies

  • returns

    Some notification if available (None otherwise).

  • raises Error

    if there is a connection error.

Control Functions

method set_notice_processor : ( string -> unit ) -> unit

#set_notice_processor controls reporting of notice and warning messages generated by a connection.

Warning: This function is unsafe in combination with a number of libpq entry points, and should not be used for now. As a workaround, #set_notice_processing can be used to silence notices, if this is more appropriate than the default behaviour of printing them to standard error.

  • raises Error

    if there is a connection error.

method set_notice_processing : [ `Stderr | `Quiet ] -> unit

#set_notice_processing controls reporting of notice and warning messages generated by a connection by providing predefined callbacks.

  • raises Error

    if there is a connection error.

Accessors

method db : string

#db

  • returns

    database name of the connection.

  • raises Error

    if there is a connection error.

method user : string

#user

  • returns

    user name of the connection.

  • raises Error

    if there is a connection error.

method pass : string

#pass

  • returns

    password of the connection.

  • raises Error

    if there is a connection error.

method host : string

#host

  • returns

    server host name of the connection.

  • raises Error

    if there is a connection error.

method port : string

#port

  • returns

    port of the connection.

  • raises Error

    if there is a connection error.

method tty : string

#tty

  • returns

    debug tty of the connection.

  • raises Error

    if there is a connection error.

method options : string

#options

  • returns

    backend options of the connection.

  • raises Error

    if there is a connection error.

method status : connection_status

#status

  • returns

    current connection status.

  • raises Error

    if there is a connection error.

method error_message : string

#error_message

  • returns

    most recent error message of the connection.

  • raises Error

    if there is a connection error.

method backend_pid : int

#backend

  • returns

    process id of the backend server of the connection.

  • raises Error

    if there is a connection error.

method server_version : int * int * int

Commands and Queries

method empty_result : result_status -> result

empty_result stat

  • returns

    dummy result with a given status stat.

  • raises Error

    if there is a connection error.

method exec : ?expect:result_status list -> ?param_types:oid array -> ?params:string array -> ?binary_params:bool array -> ?binary_result:bool -> string -> result

exec ?expect ?params ?param_types ?binary_params ?binary_result query synchronous execution of query or command query. The result status will be checked against all elements in expect. If expect is not empty and if there is no match, the exception Unexpected_status will be raised.

Additional query parameters can be passed in the params array. They must not be escaped and they can be referred to in query as $1, $2, ... The value null can be used in the params array to denote an SQL NULL. It is possible to specify that some of the query parameters are passed as binary strings using the binary_params array. By default, results are returned in text format, but will be returned in binary format if binary_result is true.

If no (or an empty) query parameter is passed, it is possible to emit several commands with a single call.

  • returns

    result of query.

  • parameter expect

    default =

  • parameter param_types

    default = ||

  • parameter params

    default = ||

  • parameter binary_params

    default = ||

  • parameter binary_result

    default = false

  • raises Error

    if there is a connection error.

  • raises Error

    if there is an unexpected result status.

method prepare : ?param_types:oid array -> string -> string -> result

prepare ?param_types stm_name query creates a prepared query named stm_name which will execute the query or command query when passed to #exec_prepared.

method exec_prepared : ?expect:result_status list -> ?params:string array -> ?binary_params:bool array -> string -> result

exec_prepared ?expect ?params ?binary_params stm_name acts as #exec, except executes the prepared query stm_name.

method describe_prepared : string -> result

#describe_prepared stm_name submits a request to obtain information about the specified prepared statement, and waits for completion. describe_prepared allows an application to obtain information about a previously prepared statement. The stm_name parameter can be the empty string ("") to reference the unnamed statement, otherwise it must be the name of an existing prepared statement. On success, a result with status Command_ok is returned. The methods result.nparams and result.paramtype of the class result can be used to obtain information about the parameters of the prepared statement, and the methods result.nfields, result.fname and result.ftype provide information about the result columns (if any) of the statement.

To prepare a statement use the SQL command PREPARE.

  • parameter stm_name

    The name of the previously prepared query

  • raises Error

    if there is a connection error.

method send_query : ?param_types:oid array -> ?params:string array -> ?binary_params:bool array -> string -> unit

send_query ?param_types ?params ?binary_params query asynchronous execution of query or command query.

Additional query parameters can be passed in the params array. They must not be escaped and they can be referred to in query as $1, $2, ... The value null can be used in the params array to denote an SQL NULL. It is possible to specify that some of the query parameters are passed as binary strings using the binary_params array.

If no (or an empty) query parameter is passed, it is possible to emit several commands with a single call.

  • parameter param_types

    default = ||

  • parameter params

    default = ||

  • parameter binary_params

    default = ||

  • raises Error

    if there is a connection error.

method send_prepare : ?param_types:oid array -> string -> string -> unit

#send_prepare ?param_types stm_name query sends a query preparation without waiting for the result. This does the same as prepare except that the status is reported by get_result when available.

  • raises Error

    if there is a connection error.

method send_query_prepared : ?params:string array -> ?binary_params:bool array -> string -> unit

#send_query_prepared ?params ?binary_params stm_name is an asynchronous version of query_prepared. The semantics is otherwise the same, and the result is reported by get_result when available.

  • parameter params

    default = ||

  • parameter binary_params

    default = ||

  • raises Error

    if there is a connection error.

method send_describe_prepared : string -> unit

#send_describe_prepared stm_name sends a request for a description of a prepared query without waiting for the result. The result must be fetched with get_result when it becomes available. Otherwise it does the same as describe_prepared.

  • raises Error

    if there is a connection error.

method send_describe_portal : string -> unit

#send_describe_portal portal_name sends a request for a description of the named portal. The result must be fetched with get_result.

  • raises Error

    if there is a connection error.

method set_single_row_mode : unit

#set_single_row_mode called right after send_query or a sibling function causes the returned rows to be split into individual results.

method get_result : result option

get_result

  • returns

    Some result of an asynchronous query if available or None.

  • raises Error

    if there is a connection error.

Copy operations

Low level

method put_copy_data : ?pos:int -> ?len:int -> string -> put_copy_result

put_copy_data ?pos ?len buf sends buf of length len starting at pos to the backend server, which must be in copy-in mode. In non-blocking mode, returns Put_copy_not_queued if the data was not queued due to full buffers.

  • parameter pos

    default = 0

  • parameter len

    default = String.length - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

method put_copy_end : ?error_msg:string -> unit -> put_copy_result

put_copy_end ?error_msg () terminates the copy-in mode, leaving the connection in Command_ok or failed state. In non-blocking mode, returns Put_copy_not_queued if the termination message was not queued due to full buffers. Also, to ensure delivery of data in non-blocking mode, repeatedly wait for write-ready an call #flush.

  • parameter error_msg

    if set, force the copy operation to fail with the given message.

method get_copy_data : ?async:bool -> unit -> get_copy_result

get_copy_data ?async () retrieves the next row of data if available. Only single complete rows are returned. In synchronous mode, the call will wait for completion of the next row. In asynchronous mode it will return immediately with Get_copy_wait if the row transfer is incomplete. In that case, wait for read-ready and call #consume_input before retrying.

  • parameter async

    default = false

method getline : ?pos:int -> ?len:int -> Bytes.t -> getline_result

getline ?pos ?len buf reads a newline-terminated line of at most len characters into buf starting at position pos.

  • returns

    getline_result

  • parameter pos

    default = 0

  • parameter len

    default = Bytes.length buf - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

  • raises Error

    if there is a connection error.

method getline_async : ?pos:int -> ?len:int -> Bytes.t -> getline_async_result

getline_async ?pos ?len buf reads a newline-terminated line of at most len characters into buf starting at position pos (asynchronously). No need to call endcopy after receiving EndOfData.

  • returns

    getline_async_result

  • parameter pos

    default = 0

  • parameter len

    default = Bytes.length buf - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

  • raises Error

    if there is a connection error.

method putline : string -> unit

putline str sends str to backend server. Don't use this method for binary data, use putnbytes instead!

  • raises Error

    if there is a connection error.

method putnbytes : ?pos:int -> ?len:int -> string -> unit

putnbytes ?pos ?len buf sends the substring of buf of length len starting at pos to backend server (use this method for binary data).

  • parameter pos

    default = 0

  • parameter len

    default = String.length buf - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

  • raises Error

    if there is a connection error.

method endcopy : unit

endcopy synchronizes with the backend.

  • raises Error

    if there is a connection error.

High level

method copy_out : ( string -> unit ) -> unit

copy_out f applies f to each line returned by backend server.

  • raises Error

    if there is a connection error.

method copy_out_channel : out_channel -> unit

copy_out_channel ch sends each line returned by backend server to output channel ch.

  • raises Error

    if there is a connection error.

method copy_in_channel : in_channel -> unit

copy_in_channel ch sends each line in input channel ch to backend server.

  • raises Error

    if there is a connection error.

Asynchronous operations and non blocking mode

method connect_poll : polling_status

After creating a connection with ~startonly:true, connect_poll must be called a number of times before the connection can be used. The precise procedure is described in the libpq manual, but the following code should capture the idea, assuming monadic concurrency primitives return and >>= along with polling functions wait_for_read and wait_for_write:

let my_async_connect () =
  let c = new connection () in
  let rec establish_connection = function
    | Polling_failed | Polling_ok -> return c
    | Polling_reading -> wait_for_read c#socket >>= fun () ->
                         establish_connection c#connect_poll
    | Polling_writing -> wait_for_write c#socket >>= fun () ->
                         establish_connection c#connect_poll in
  establish_connection Polling_writing

See also examples/async.ml.

method reset_start : bool

An asynchronous variant of reset. Use reset_poll to finish re-establishing the connection.

method reset_poll : polling_status

Used analogously to connect_poll after calling reset_start.

method set_nonblocking : bool -> unit

set_nonblocking b sets state of the connection to nonblocking if b is true and to blocking otherwise.

  • raises Error

    if there is a connection error.

method is_nonblocking : bool

is_nonblocking

  • returns

    the blocking status of the connection.

  • raises Error

    if there is a connection error.

method consume_input : unit

consume_input consume any available input from backend.

  • raises Error

    if there is a connection error.

method is_busy : bool

is_busy

  • returns

    busy status of a query.

  • raises Error

    if there is a connection error.

method flush : flush_status

flush attempts to flush any data queued to the backend.

  • raises Error

    if there is a connection error.

method socket : int

socket obtains the file descriptor for the backend connection socket as an integer.

  • raises Error

    if there is a connection error.

method request_cancel : unit

request_cancel requests that PostgreSQL abandon processing of the current command.

  • raises Error

    if there is a connection or cancel error.

Large objects

method lo_creat : oid

lo_creat creates a new large object and returns its oid.

  • raises Error

    if there is a connection error.

method lo_import : string -> oid

lo_import filename imports an operating system file given by filename as a large object.

  • raises Error

    if there is a connection error.

method lo_export : oid -> string -> unit

lo_export oid filename exports the large object given by oid to an operating system file given by filename.

  • raises Error

    if there is a connection error.

method lo_open : oid -> large_object

lo_open oid opens the large object given by oid for reading and writing.

  • raises Error

    if there is a connection error.

method lo_write : ?pos:int -> ?len:int -> string -> large_object -> unit

lo_write ?pos ?len buf lo writes len bytes of buffer buf starting at position pos to large object lo.

  • parameter pos

    default = 0

  • parameter len

    default = String.length buf - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

  • raises Error

    if len bytes could not be written.

  • raises Error

    if there is a connection error.

method lo_write_ba : ?pos:int -> ?len:int -> ( char, Bigarray.int8_unsigned_elt, Bigarray.c_layout ) Bigarray.Array1.t -> large_object -> unit

As lo_write, but performs a zero-copy write from the given Bigarray.

method lo_read : large_object -> ?pos:int -> ?len:int -> Bytes.t -> int

lo_read lo ?pos ?len buf reads len bytes from large object lo to buffer buf starting at position pos.

  • parameter pos

    default = 0

  • parameter len

    default = Bytes.length buf - pos

  • raises Invalid_argument

    if the buffer parameters are invalid.

  • raises Error

    if len bytes could not be read.

  • raises Error

    if there is a connection error.

method lo_read_ba : large_object -> ?pos:int -> ?len:int -> ( char, Bigarray.int8_unsigned_elt, Bigarray.c_layout ) Bigarray.Array1.t -> int

As lo_read, but performs a zero-copy read into the given Bigarray.

method lo_seek : ?pos:int -> ?whence:seek_cmd -> large_object -> unit

lo_seek ?pos ?whence lo seeks read/write position pos in large object lo relative to the start, current read/write position, or end of the object (whence is SEEK_SET, SEEK_CUR, SEEK_END respectively).

  • parameter pos

    default = 0

  • parameter whence

    default = SEEK_SET

  • raises Error

    if there is a connection error.

method lo_tell : large_object -> int

lo_tell lo

  • returns

    current read/write position of large object lo.

  • raises Error

    if there is a connection error.

method lo_close : large_object -> unit

lo_close lo closes large object lo.

  • raises Error

    if there is a connection error.

lo_unlink oid removes the large object specified by oid from the database.

  • raises Error

    if there is a connection error.

Escaping

method escape_string : ?pos:int -> ?len:int -> string -> string

escape_string ?pos ?len str escapes ASCII-substring str of length len starting at position pos for use within SQL.

  • parameter pos

    default = 0

  • parameter len

    default = String.length str - pos

method escape_bytea : ?pos:int -> ?len:int -> string -> string

escape_bytea ?pos ?len str escapes binary substring str of length len starting at position pos for use within SQL.

  • parameter pos

    default = 0

  • parameter len

    default = String.length str - pos