connection (postgresql.Postgresql.connection)

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, connection.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. connection.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.

see http://www.postgresql.org/docs/8.3/interactive/sql-prepare.html
PostgreSQL documentation about PREPARE

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.

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 connection.prepare except that the status is reported by connection.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 connection.exec_prepared. The semantics is otherwise the same, and the result is reported by connection.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 connection.get_result when it becomes available. Otherwise it does the same as connection.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 connection.get_result.

raises Error
if there is a connection error.

method set_single_row_mode : unit

#set_single_row_mode called right after connection.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 connection.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 connection.consume_input before retrying.

parameter async
default = false

method getline : ?pos:int -> ?len:int -> Stdlib.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 ->
  Stdlib.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 : Stdlib.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 : Stdlib.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, connection.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 connection.reset. Use connection.reset_poll to finish re-establishing the connection.

method reset_poll : polling_status

Used analogously to connection.connect_poll after calling connection.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, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout)
    Stdlib.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 -> Stdlib.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, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout)
    Stdlib.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.

method lo_unlink : oid -> unit

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