Up  

Class Postgresql.connection

class connection : ?host:string -> ?hostaddr:string -> ?port:string -> ?dbname:string -> ?user:string -> ?password:string -> ?options:string -> ?tty:string -> ?requiressl:string -> ?conninfo:string -> ?startonly:bool -> unit -> object .. end
Class of connections.

When conninfo is given, it will be used instead of all other optional arguments.
Raises Error if there is a connection failure.

startonly : If true, initiate a non-blocking connect procedure, which involves cooperative calls to Postgresql.connection.connect_poll before the connection is usable.
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 : (string * int) option
#notifies
Raises Error if there is a connection error.
Returns Some (name, pid) if available (None otherwise), where name is the name the of relation containing data, pid the process id of the backend.

Control Functions

method set_notice_processor : (string -> unit) -> unit
#set_notice_processor controls reporting of notice and warning messages generated by a connection.
Raises Error if there is a connection error.

Accessors

method db : string
#db
Raises Error if there is a connection error.
Returns database name of the connection.
method user : string
#user
Raises Error if there is a connection error.
Returns user name of the connection.
method pass : string
#pass
Raises Error if there is a connection error.
Returns password of the connection.
method host : string
#host
Raises Error if there is a connection error.
Returns server host name of the connection.
method port : string
#port
Raises Error if there is a connection error.
Returns port of the connection.
method tty : string
#tty
Raises Error if there is a connection error.
Returns debug tty of the connection.
method options : string
#options
Raises Error if there is a connection error.
Returns backend options of the connection.
method status : connection_status
#status
Raises Error if there is a connection error.
Returns current connection status.
method error_message : string
#error_message
Raises Error if there is a connection error.
Returns most recent error message of the connection.
method backend_pid : int
#backend
Raises Error if there is a connection error.
Returns process id of the backend server of the connection.
method server_version : int * int * int

Commands and Queries

method empty_result : result_status -> result
empty_result stat
Raises Error if there is a connection error.
Returns dummy result with a given status 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.
Raises

Returns result of query.
expect : default = []
params : default = ||
binary_params : default = ||
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. Postgresql.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 Postgresql.result with status Command_ok is returned. The methods Postgresql.result.nparams and Postgresql.result.paramtype of the class result can be used to obtain information about the parameters of the prepared statement, and the methods Postgresql.result.nfields, Postgresql.result.fname and Postgresql.result.ftype provide information about the result columns (if any) of the statement.

To prepare a statement use the SQL command PREPARE.
Raises Error if there is a connection error.
See also PostgreSQL documentation about 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.
Raises Error if there is a connection error.

params : default = ||
binary_params : default = ||
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 Postgresql.connection.prepare except that the status is reported by Postgresql.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 query_prepared. The semantics is otherwise the same, and the result is reported by Postgresql.connection.get_result when available.
Raises Error if there is a connection error.
params : default = ||
binary_params : default = ||
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 Postgresql.connection.get_result when it becomes available. Otherwise it does the same as Postgresql.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 Postgresql.connection.get_result.
Raises Error if there is a connection error.
method set_single_row_mode : unit
#set_single_row_mode called right after Postgresql.connection.send_query or a sibling function causes the returned rows to be split into individual results.
method get_result : result option
get_result
Raises Error if there is a connection error.
Returns Some result of an asynchronous query if available or None.

Copy operations

Low level

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.
Raises Returns getline_result
pos : default = 0
len : default = Bytes.length buf - 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.
Raises Returns getline_async_result
pos : default = 0
len : default = Bytes.length buf - pos
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).
Raises
pos : default = 0
len : default = String.length buf - pos
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 : Pervasives.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 : Pervasives.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, Postgresql.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 Postgresql.connection.reset. Use Postgresql.connection.reset_poll to finish re-establishing the connection.
method reset_poll : polling_status
Used analogously to Postgresql.connection.connect_poll after calling Postgresql.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
Raises Error if there is a connection error.
Returns the blocking status of the connection.
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
Raises Error if there is a connection error.
Returns busy status of a query.
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.
Raises
pos : default = 0
len : default = String.length buf - pos
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.
Raises
pos : default = 0
len : default = Bytes.length buf - 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).
Raises Error if there is a connection error.
pos : default = 0
whence : default = SEEK_SET
method lo_tell : large_object -> int
lo_tell lo
Raises Error if there is a connection error.
Returns current read/write position of large object lo.
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.
pos : default = 0
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.
pos : default = 0
len : default = String.length str - pos