Module PGOCaml

module Simple_thread : PGOCaml_generic.THREAD with type 'a t = 'a
include PGOCaml_generic.PGOCAML_GENERIC with type 'a monad = 'a
type 'a t

Database handle.

type 'a monad = 'a
type isolation = [
  1. | `Serializable
  2. | `Repeatable_read
  3. | `Read_committed
  4. | `Read_uncommitted
]
type access = [
  1. | `Read_write
  2. | `Read_only
]
exception Error of string

For library errors.

exception PostgreSQL_Error of string * (char * string) list

For errors generated by the PostgreSQL database back-end. The * first argument is a printable error message. The second argument * is the complete set of error fields returned from the back-end. * See http://www.postgresql.org/docs/8.1/static/protocol-error-fields.html

Connection management
val connect : ?host:string -> ?port:int -> ?user:string -> ?password:string -> ?database:string -> ?unix_domain_socket_dir:string -> unit -> 'a t monad

Connect to the database. The normal $PGDATABASE, etc. environment * variables are available.

val close : 'a t -> unit monad

Close the database handle. You must call this after you have * finished with the handle, or else you will get leaked file * descriptors.

val ping : 'a t -> unit monad

Ping the database. If the database is not available, some sort of * exception will be thrown.

val alive : 'a t -> bool monad

This function is a wrapper of ping that returns a boolean instead of * raising an exception.

Transactions
val begin_work : ?isolation:isolation -> ?access:access -> ?deferrable:bool -> 'a t -> unit monad

Start a transaction.

val commit : 'a t -> unit monad

Perform a COMMIT operation on the database.

val rollback : 'a t -> unit monad

Perform a ROLLBACK operation on the database.

val transact : 'a t -> ?isolation:isolation -> ?access:access -> ?deferrable:bool -> ('a t -> 'b monad) -> 'b monad

transact db ?isolation ?access ?deferrable f wraps your * function f inside a transactional block. * First it calls begin_work with isolation, access and deferrable, * then calls f and do rollback if f raises * an exception, commit otherwise.

Serial column
val serial : 'a t -> string -> int64 monad

This is a shorthand for SELECT CURRVAL(serial). For a table * called table with serial column id you would typically * call this as serial dbh "table_id_seq" after the previous INSERT * operation to get the serial number of the inserted row.

val serial4 : 'a t -> string -> int32 monad

As serial but assumes that the column is a SERIAL or * SERIAL4 type.

val serial8 : 'a t -> string -> int64 monad

Same as serial.

Miscellaneous
val max_message_length : int ref

Maximum message length accepted from the back-end. The default * is Sys.max_string_length, which means that we will try to read as * much data from the back-end as we can, and this may cause us to * run out of memory (particularly on 64 bit machines), causing a * possible denial of service. You may want to set this to a smaller * size to avoid this happening.

val verbose : int ref

Verbosity. 0 means don't print anything. 1 means print short * error messages as returned from the back-end. 2 means print all * messages as returned from the back-end. Messages are printed on stderr. * Default verbosity level is 1.

val set_private_data : 'a t -> 'a -> unit

Attach some private data to the database handle. * * NB. The pa_pgsql camlp4 extension uses this for its own purposes, which * means that in most programs you will not be able to attach private data * to the database handle.

val private_data : 'a t -> 'a

Retrieve some private data previously attached to the database handle. * If no data has been attached, raises Not_found. * * NB. The pa_pgsql camlp4 extension uses this for its own purposes, which * means that in most programs you will not be able to attach private data * to the database handle.

val uuid : 'a t -> string

Retrieve the unique identifier for this connection.

type pa_pg_data = (string, bool) Hashtbl.t

When using pa_pgsql, database handles have type * PGOCaml.pa_pg_data PGOCaml.t

Low level query interface - DO NOT USE DIRECTLY
type oid = int32
type param = string option

None is NULL.

type result = string option

None is NULL.

None is NULL.

type row = result list

None is NULL.

One row is a list of fields.

val prepare : 'a t -> query:string -> ?name:string -> ?types:oid list -> unit -> unit monad

prepare conn ~query ?name ?types () prepares the statement query * and optionally names it name and sets the parameter types to types. * If no name is given, then the "unnamed" statement is overwritten. If * no types are given, then the PostgreSQL engine infers types. * Synchronously checks for errors.

val execute_rev : 'a t -> ?name:string -> ?portal:string -> params:param list -> unit -> row list monad
val execute : 'a t -> ?name:string -> ?portal:string -> params:param list -> unit -> row list monad

execute conn ?name ~params () executes the named or unnamed * statement name, with the given parameters params, * returning the result rows (if any). * * There are several steps involved at the protocol layer: * (1) a "portal" is created from the statement, binding the * parameters in the statement (Bind). * (2) the portal is executed (Execute). * (3) we synchronise the connection (Sync). * * The optional ?portal parameter may be used to name the portal * created in step (1) above (otherwise the unnamed portal is used). * This is only important if you want to call describe_portal * to find out the result types.

val cursor : 'a t -> ?name:string -> ?portal:string -> params:param list -> (row -> unit monad) -> unit monad
val close_statement : 'a t -> ?name:string -> unit -> unit monad

close_statement conn ?name () closes a prepared statement and frees * up any resources.

val close_portal : 'a t -> ?portal:string -> unit -> unit monad

close_portal conn ?portal () closes a portal and frees up any resources.

val inject : 'a t -> ?name:string -> string -> row list monad

inject conn ?name query executes the statement query * and optionally names it name and gives the result.

val alter : 'a t -> ?name:string -> string -> unit monad

alter conn ?name query executes the statement query * and optionally names it name. Same as inject but ignoring the result.

type row_description = result_description list
and result_description = {
  1. name : string;
    (*

    Field name.

    *)
  2. table : oid option;
    (*

    OID of table.

    *)
  3. column : int option;
    (*

    Column number of field in table.

    *)
  4. field_type : oid;
    (*

    The type of the field.

    *)
  5. length : int;
    (*

    Length of the field.

    *)
  6. modifier : int32;
    (*

    Type modifier.

    *)
}
type params_description = param_description list
and param_description = {
  1. param_type : oid;
    (*

    The type of the parameter.

    *)
}
val describe_statement : 'a t -> ?name:string -> unit -> (params_description * row_description option) monad

describe_statement conn ?name () describes the named or unnamed * statement's parameter types and result types.

val describe_portal : 'a t -> ?portal:string -> unit -> row_description option monad

describe_portal conn ?portal () describes the named or unnamed * portal's result types.

Low level type conversion functions - DO NOT USE DIRECTLY
val name_of_type : ?modifier:int32 -> oid -> string

Returns the OCaml equivalent type name to the PostgreSQL type oid. * For instance, name_of_type (Int32.of_int 23) returns "int32" because * the OID for PostgreSQL's internal int4 type is 23. As another * example, name_of_type (Int32.of_int 25) returns "string".

type inet = Unix.inet_addr * int
type int16 = int
type bytea = string
type point = float * float
type hstore = (string * string option) list
type numeric = string
type uuid = string
type jsonb = string
type bool_array = bool option list
type int32_array = int32 option list
type int64_array = int64 option list
type string_array = string option list
type float_array = float option list

The following conversion functions are used by pa_pgsql to convert * values in and out of the database.

val string_of_oid : oid -> string
val string_of_bool : bool -> string
val string_of_int : int -> string
val string_of_int16 : int16 -> string
val string_of_int32 : int32 -> string
val string_of_int64 : int64 -> string
val string_of_float : float -> string
val string_of_point : point -> string
val string_of_hstore : hstore -> string
val string_of_numeric : numeric -> string
val string_of_uuid : uuid -> string
val string_of_jsonb : jsonb -> string
val string_of_inet : inet -> string
val string_of_timestamp : CalendarLib.Calendar.t -> string
val string_of_timestamptz : timestamptz -> string
val string_of_date : CalendarLib.Date.t -> string
val string_of_time : CalendarLib.Time.t -> string
val string_of_interval : CalendarLib.Calendar.Period.t -> string
val string_of_bytea : bytea -> string
val string_of_string : string -> string
val string_of_unit : unit -> string
val string_of_bool_array : bool_array -> string
val string_of_int32_array : int32_array -> string
val string_of_int64_array : int64_array -> string
val string_of_string_array : string_array -> string
val string_of_float_array : float_array -> string
val oid_of_string : string -> oid
val bool_of_string : string -> bool
val int_of_string : string -> int
val int16_of_string : string -> int16
val int32_of_string : string -> int32
val int64_of_string : string -> int64
val float_of_string : string -> float
val point_of_string : string -> point
val hstore_of_string : string -> hstore
val numeric_of_string : string -> numeric
val uuid_of_string : string -> uuid
val jsonb_of_string : string -> jsonb
val inet_of_string : string -> inet
val timestamp_of_string : string -> CalendarLib.Calendar.t
val timestamptz_of_string : string -> timestamptz
val date_of_string : string -> CalendarLib.Date.t
val time_of_string : string -> CalendarLib.Time.t
val interval_of_string : string -> CalendarLib.Calendar.Period.t
val bytea_of_string : string -> bytea
val unit_of_string : string -> unit
val bool_array_of_string : string -> bool_array
val int32_array_of_string : string -> int32_array
val int64_array_of_string : string -> int64_array
val string_array_of_string : string -> string_array
val float_array_of_string : string -> float_array
val bind : 'a monad -> ('a -> 'b monad) -> 'b monad
val return : 'a -> 'a monad