pgocaml 2.3 · OCaml Package

type 'a t

Database handle.

type 'a monad

type isolation = [

| `Serializable
| `Repeatable_read
| `Read_committed
| `Read_uncommitted

]

type access = [

| `Read_write
| `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.

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 = {

name : string;
(*
Field name.
*)
table : oid option;
(*
OID of table.
*)
column : int option;
(*
Column number of field in table.
*)
field_type : oid;
(*
The type of the field.
*)
length : int;
(*
Length of the field.
*)
modifier : int32;
(*
Type modifier.
*)

}

type params_description = param_description list

and param_description = {

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 timestamptz = CalendarLib.Calendar.t * CalendarLib.Time_Zone.t

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

package pgocaml

Connection management

Transactions

Serial column

Miscellaneous

Low level query interface - DO NOT USE DIRECTLY

Low level type conversion functions - DO NOT USE DIRECTLY