Postgresql.connection

# 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

- `Error` if there is a connection error.
- `Error` if there is an unexpected result status.

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

- `Invalid_argument` if the buffer parameters are invalid.
- `Error` if there is a connection error.

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

- `Invalid_argument` if the buffer parameters are invalid.
- `Error` if there is a connection error.

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

- `Invalid_argument` if the buffer parameters are invalid.
- `Error` if there is a connection error.

`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

- `Invalid_argument` if the buffer parameters are invalid.
- `Error` if `len` bytes could not be written.
- `Error` if there is a connection error.

`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

- `Invalid_argument` if the buffer parameters are invalid.
- `Error` if `len` bytes could not be read.
- `Error` if there is a connection error.

`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