Class Postgresql.connection
Class of connections.
When conninfo
is given, it will be used instead of all other optional arguments.
- parameter startonly
If true, initiate a non-blocking connect procedure, which involves cooperative calls to
connect_poll
before the connection is usable.
- raises Error
if there is a connection failure.
method try_reset : unit
#try_reset
tries to reset the connection if it is bad. If resetting fails, theerror
exception will be raised withConnection_failure
.- raises Error
if there is a connection error.
method notifies : Notification.t option
#notifies
- returns
Some notification
if available (None
otherwise).
- raises Error
if there is a connection error.
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.
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 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 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 commandquery
. The result status will be checked against all elements inexpect
. Ifexpect
is not empty and if there is no match, the exceptionUnexpected_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 inquery
as $1, $2, ... The valuenull
can be used in theparams
array to denote an SQL NULL. It is possible to specify that some of the query parameters are passed as binary strings using thebinary_params
array. By default, results are returned in text format, but will be returned in binary format ifbinary_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 namedstm_name
which will execute the query or commandquery
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 querystm_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. Thestm_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, aresult
with statusCommand_ok
is returned. The methodsresult.nparams
andresult.paramtype
of the classresult
can be used to obtain information about the parameters of the prepared statement, and the methodsresult.nfields
,result.fname
andresult.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 commandquery
.Additional query parameters can be passed in the
params
array. They must not be escaped and they can be referred to inquery
as $1, $2, ... The valuenull
can be used in theparams
array to denote an SQL NULL. It is possible to specify that some of the query parameters are passed as binary strings using thebinary_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 asprepare
except that the status is reported byget_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 ofquery_prepared
. The semantics is otherwise the same, and the result is reported byget_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 withget_result
when it becomes available. Otherwise it does the same asdescribe_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 withget_result
.- raises Error
if there is a connection error.
method set_single_row_mode : unit
#set_single_row_mode
called right aftersend_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 orNone
.
- raises Error
if there is a connection error.
method put_copy_data : ?pos:int -> ?len:int -> string -> put_copy_result
put_copy_data ?pos ?len buf
sendsbuf
of lengthlen
starting atpos
to the backend server, which must be in copy-in mode. In non-blocking mode, returnsPut_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 inCommand_ok
or failed state. In non-blocking mode, returnsPut_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 withGet_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 -> Stdlib.Bytes.t -> getline_result
getline ?pos ?len buf
reads a newline-terminated line of at mostlen
characters intobuf
starting at positionpos
.- 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 mostlen
characters intobuf
starting at positionpos
(asynchronously). No need to callendcopy
after receivingEndOfData
.- 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
sendsstr
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 ofbuf
of lengthlen
starting atpos
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.
method copy_out : (string -> unit) -> unit
copy_out f
appliesf
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 channelch
.- 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 channelch
to backend server.- raises Error
if there is a connection error.
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 primitivesreturn
and>>=
along with polling functionswait_for_read
andwait_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
. Usereset_poll
to finish re-establishing the connection.
method reset_poll : polling_status
Used analogously to
connect_poll
after callingreset_start
.
method set_nonblocking : bool -> unit
set_nonblocking b
sets state of the connection to nonblocking ifb
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.
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 byfilename
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 byoid
to an operating system file given byfilename
.- raises Error
if there is a connection error.
method lo_open : oid -> large_object
lo_open oid
opens the large object given byoid
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
writeslen
bytes of bufferbuf
starting at positionpos
to large objectlo
.- 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
readslen
bytes from large objectlo
to bufferbuf
starting at positionpos
.- 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 positionpos
in large objectlo
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 objectlo
.- raises Error
if there is a connection error.
method lo_unlink : oid -> unit
lo_unlink oid
removes the large object specified byoid
from the database.- raises Error
if there is a connection error.