macaque 0.7.1 · 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

type connection_desc = {

user : string;
port : int;
password : string;
host : [ `Hostname of string | `Unix_domain_socket_dir of string ];
database : string;

}

val describe_connection : 
  ?host:string ->
  ?port:int ->
  ?user:string ->
  ?password:string ->
  ?database:string ->
  ?unix_domain_socket_dir:string ->
  unit ->
  connection_desc

Produce the actual, concrete connection parameters based on the values and * availability of the various configuration variables.

val connection_desc_to_string : connection_desc -> string

Produce a human-readable textual representation of a concrete connection * descriptor (the password is NOT included in the output of this function) * for logging and error reporting purposes.

val connect : 
  ?host:string ->
  ?port:int ->
  ?user:string ->
  ?password:string ->
  ?database:string ->
  ?unix_domain_socket_dir:string ->
  ?desc:connection_desc ->
  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 Pervasives.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 Pervasives.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

type timestamp_array = CalendarLib.Calendar.t 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_bytea_array : string_array -> string

val string_of_float_array : float_array -> string

val string_of_timestamp_array : timestamp_array -> string

val comment_src_loc : unit -> bool

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 timestamp_array_of_string : string -> timestamp_array

val bind : 'a monad -> ('a -> 'b monad) -> 'b monad

val return : 'a -> 'a monad

package macaque

Connection management

Transactions

Serial column

Miscellaneous

Low level query interface - DO NOT USE DIRECTLY

Low level type conversion functions - DO NOT USE DIRECTLY