Module type PGOCaml_generic.PGOCAML_GENERIC

module type PGOCAML_GENERIC = sig .. end

type 'a t

Database handle.

type 'a monad

type isolation = [ `Read_committed | `Read_uncommitted | `Repeatable_read | `Serializable ]

type access = [ `Read_only | `Read_write ]

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 PGOCaml_generic.PGOCAML_GENERIC.serial but assumes that the column is a SERIAL or * SERIAL4 type.

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

Same as PGOCaml_generic.PGOCAML_GENERIC.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

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 PGOCaml_generic.PGOCAML_GENERIC.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

type 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

type 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 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_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 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