Class Postgresql.connection

Class of connections.

When conninfo is given, it will be used instead of all other optional arguments.

method finish : unit

#finish closes the connection.

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.

method reset : unit

#reset resets the connection.

Asynchronous Notification

method notifies : Notification.t option

#notifies

Control Functions

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

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

Accessors

method db : string

#db

method user : string

#user

method pass : string

#pass

method host : string

#host

method port : string

#port

method tty : string

#tty

method options : string

#options

method status : connection_status

#status

method error_message : string

#error_message

method backend_pid : int

#backend

method server_version : int * int * int

Commands and Queries

method empty_result : result_status ‑> result

empty_result stat

method exec : ?⁠expect:result_status list ‑> ?⁠params:string array ‑> ?⁠binary_params:bool array ‑> string ‑> result

exec ?expect ?params ?binary_params 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.

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

method prepare : string ‑> string ‑> result

prepare 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.

method send_query : ?⁠params:string array ‑> ?⁠binary_params:bool array ‑> string ‑> unit

send_query ?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.

method send_prepare : string ‑> string ‑> unit

#send_prepare 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.

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.

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.

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.

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

Low level

Copy operations

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.

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.

method putline : string ‑> unit

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

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).

method endcopy : unit

endcopy synchronizes with the backend.

High level

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

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

method copy_out_channel : Pervasives.out_channel ‑> unit

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

method copy_in_channel : Pervasives.in_channel ‑> unit

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

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.

method is_nonblocking : bool

is_nonblocking

method consume_input : unit

consume_input consume any available input from backend.

method is_busy : bool

is_busy

method flush : flush_status

flush attempts to flush any data queued to the backend.

method socket : int

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

method request_cancel : unit

request_cancel requests that PostgreSQL abandon processing of the current command.

Large objects

method lo_creat : oid

lo_creat creates a new large object and returns its oid.

method lo_import : string ‑> oid

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

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.

method lo_open : oid ‑> large_object

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

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.

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.

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).

method lo_tell : large_object ‑> int

lo_tell lo

method lo_close : large_object ‑> unit

lo_close lo closes large object lo.

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.

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.