/ src /
/src/sql.mli
1 (* macaque : sql.mli
2 MaCaQue : Macros for Caml Queries
3 Copyright (C) 2009 Gabriel Scherer, Jérôme Vouillon
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this library; see the file LICENSE. If not, write to
17 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19 *)
20
21 open Sql_base
22
23 type untyped
24
25 type 'a writable
26 type non_writable
27
28 type nullable
29 type non_nullable
30
31
32 type 'n nul_witness
33 val nullable_witness : nullable nul_witness
34 val non_nullable_witness : non_nullable nul_witness
35
36 class type ['t] type_info = object method typ : 't end
37 class type numeric_t = object method numeric : unit end
38
39 class type bool_t = object inherit [bool] type_info end
40 class type int16_t = object inherit [int16] type_info inherit numeric_t end
41 class type int32_t = object inherit [int32] type_info inherit numeric_t end
42 class type int64_t = object inherit [int64] type_info inherit numeric_t end
43 class type float_t = object inherit [float] type_info inherit numeric_t end
44 class type string_t = object inherit [string] type_info end
45 class type bytea_t = object inherit [bytea] type_info end
46 class type time_t = object inherit [time] type_info end
47 class type date_t = object inherit [date] type_info end
48 class type timestamp_t = object inherit [timestamp] type_info end
49 class type timestamptz_t = object inherit [timestamptz] type_info end
50 class type interval_t = object inherit [interval] type_info end
51 class type int32_array_t = object inherit [int32 array] type_info end
52
53 class type ['row] row_t = object inherit ['row] type_info end
54
55 (* used in some coercicions scenario, eg. update *)
56 type 't type_info_only = < t : 't type_info >
57
58 (** values *)
59 type +'a t
60 val untyped_t : 'a t -> untyped t
61
62 type 'phant binary_op = 'a t -> 'b t -> 'c t
63 constraint 'a = < t : 'in_t; nul : 'n; .. >
64 constraint 'b = < t : 'in_t; nul : 'n; .. >
65 constraint 'c = < t : 'out_t; nul : 'n >
66 constraint 'phant =
67 < in_t : 'in_t; out_t : 'out_t; nul : 'n; a : 'a; b : 'b >
68
69 (** unsafe *)
70 type +'a unsafe
71 val unsafe : 'a -> 'a unsafe
72
73 (** types *)
74 type +'a sql_type
75 val untyped_type : 'a sql_type -> untyped sql_type
76 val recover_type : 'a sql_type -> untyped sql_type unsafe -> 'a sql_type
77
78 (* It is this [get_type] function that is used in the parser for SQL
79 rows, that, from a typing point of view, gives the `get` predicate
80 back to the row values even if they didn't have one initially --
81 see the type below. *)
82 val get_type :
83 < t : 't; nul : 'nul; .. > t ->
84 < t : 't; nul : 'nul; get : unit > sql_type
85
86 (** parsers *)
87 type 'a result_parser = string array * int ref -> 'a
88 type 'a record_parser = untyped sql_type tuple -> 'a result_parser
89
90 (** access functions *)
91 val get : < get : _; nul : non_nullable; t : 't #type_info > t -> 't
92 val getn : < get : _; nul : nullable; t : 't #type_info > t -> 't option
93
94 (** parse function *)
95 val parse : 'a sql_type -> 'a t result_parser
96
97 (** views *)
98 type (+'a, 'w) view
99 val untyped_view : (_, 'w) view -> (untyped, untyped) view
100
101 val field :
102 < t : 'a #row_t; nul : non_nullable; .. > t ->
103 string list unsafe ->
104 (row:'a -> < t : 't; nul : 'n; ..> t) unsafe ->
105 <t : 't; nul : 'n> t
106 (* The 'row' label is there to clarify error reporting: it
107 makes the purpose of this argument clear. Note that this is only
108 useful betcause there is an unification between two parts of the
109 parameters type -- shared by the variable 'def -- so there may be
110 a type conflict detected here.
111 *)
112
113 val default :
114 (_, 'def writable) view ->
115 string unsafe ->
116 (default_fields:'def -> < t : 't; nul : 'n; .. > t) unsafe ->
117 < t : 't; nul : 'n > t
118
119 val row :
120 string unsafe -> ('a, _) view -> < t : < typ : 'a >; nul : non_nullable > t
121 (* < typ : 'a > instead of 'a row_t to lighten error reporting *)
122
123 val tuple :
124 untyped t tuple unsafe ->
125 (tuple:'tup -> untyped t tuple) unsafe ->
126 'tup record_parser unsafe ->
127 < t : < typ : 'tup >; nul : non_nullable > t
128 (* < typ : 'a > instead of 'a row_t to lighten error reporting *)
129
130 val if_then_else : < t : #bool_t; .. > t -> < in_t : 't; out_t : 't; .. > binary_op
131
132 val match_null :
133 < t : 't; nul : nullable; .. > t -> < t : 'res_t; nul : 'res_n; .. > t ->
134 (< t :'t; nul : non_nullable; ..> t -> < t : 'res_t; nul : 'res_n; .. > t) ->
135 < t : 'res_t; nul : 'res_n > t
136
137 (** select and view building *)
138 type +'a result
139 constraint 'a = < .. >
140
141 val simple_select : < t : 'a #row_t; .. > t -> 'a result
142
143 type from = (untyped, untyped) view tuple
144 type where = < t : bool_t > t list
145 type order = Asc | Desc
146
147 val view : 'a result ->
148 ?order_by: (untyped t * order) list ->
149 ?limit: < t : #numeric_t; .. > t ->
150 ?offset: < t : #numeric_t; .. > t ->
151 from -> where -> ('a, non_writable) view
152
153 (** group by and accumulators *)
154 type grouped_row
155 val grouped_row : grouped_row
156
157 type +'a group
158 type +'a accum
159 val accum : 'a t -> 'a accum
160 val group_of_accum : 'a accum -> 'a group
161
162 val group :
163 < t : 'const #row_t; .. > t -> < t : 'res #row_t; .. > t -> 'res result
164
165
166 (** tables *)
167 val table :
168 untyped sql_type tuple ->
169 (row:'row -> untyped t tuple) unsafe ->
170 ('row record_parser) ->
171 (string option * string) ->
172 'def * untyped t tuple -> ('row, 'def writable) view
173
174 (** standard SQL field types
175 (in pa_descr, ie. <:table< .. >>) *)
176 module Table_type : sig
177 val boolean : 'nul nul_witness ->
178 < get : unit; nul : 'nul; t : bool_t > sql_type
179 val smallint : 'nul nul_witness ->
180 < get : unit; nul : 'nul; t : int16_t > sql_type
181 val integer : 'nul nul_witness ->
182 < get : unit; nul : 'nul; t : int32_t > sql_type
183 val bigint : 'nul nul_witness ->
184 < get : unit; nul : 'nul; t : int64_t > sql_type
185 val double : 'nul nul_witness ->
186 < get : unit; nul : 'nul; t : float_t > sql_type
187 val text : 'nul nul_witness ->
188 < get : unit; nul : 'nul; t : string_t > sql_type
189 val bytea : 'nul nul_witness ->
190 < get : unit; nul : 'nul; t : bytea_t > sql_type
191 val time : 'nul nul_witness ->
192 < get : unit; nul : 'nul; t : time_t > sql_type
193 val date : 'nul nul_witness ->
194 < get : unit; nul : 'nul; t : date_t > sql_type
195 val timestamp : 'nul nul_witness ->
196 < get : unit; nul : 'nul; t : timestamp_t > sql_type
197 val timestamptz : 'nul nul_witness ->
198 < get : unit; nul : 'nul; t : timestamptz_t > sql_type
199 val interval : 'nul nul_witness ->
200 < get : unit; nul : 'nul; t : interval_t > sql_type
201 val int32_array : 'nul nul_witness ->
202 < get : unit; nul : 'nul; t : int32_array_t > sql_type
203 end
204
205 (** final query building *)
206 type +'a query
207
208 val select : ('a, _) view -> 'a list query
209 val insert : ('a, _ writable) view -> ('a, _) view -> unit query
210 val delete :
211 ('a, _ writable) view -> string unsafe -> from -> where -> unit query
212 val update :
213 ('a, _ writable) view -> string unsafe ->
214 'b t -> bool unsafe ->
215 from -> where -> unit query
216
217 (* notice how the type for [value] below reinstates the [get] property,
218 just as [get_type] does for parsed row types. *)
219 val value : < t : 't; nul : 'nul; .. > t ->
220 < t : 't; nul : 'nul; get : unit > t query
221
222 (** query printing *)
223 val sql_of_query : _ query -> string
224 val sql_of_view : (_, _) view -> string
225
226 (** handle result from PGOCaml call *)
227 val handle_query_results : 'a query -> string array list unsafe -> 'a
228
229 (** standard SQL value types
230 (usable from user code, in pa_macaque value antiquotations) *)
231 module Value : sig
232 val bool : bool -> < t : bool_t; nul : _ > t
233 val int16 : int16 -> < t : int16_t; nul : _ > t
234 val int32 : int32 -> < t : int32_t; nul : _ > t
235 val int64 : int64 -> < t : int64_t; nul : _ > t
236 val float : float -> < t : float_t; nul : _ > t
237 val string : string -> < t : string_t; nul : _ > t
238 val bytea : bytea -> < t : bytea_t; nul : _ > t
239 val time : time -> < t : time_t; nul : _ > t
240 val date : date -> < t : date_t; nul : _ > t
241 val timestamp : timestamp -> < t : timestamp_t; nul : _ > t
242 val timestamptz : timestamptz -> < t : timestamptz_t; nul : _ > t
243 val interval : interval -> < t : interval_t; nul : _ > t
244 val int32_array : int32 array -> < t : int32_array_t; nul : _ > t
245 end
246
247
248 (** sequence creation operators
249 (usable from user code, in pa_descr sequence expressions) *)
250 type 'a sequence
251 module Sequence : sig
252 val serial : string -> int32_t sequence
253 val bigserial : string -> int64_t sequence
254 val sequence : string -> int64_t sequence
255 end
256
257 (** standard SQL operators
258 (usable from user code, in pa_comp expressions) *)
259 module Op : sig
260 val null :
261 < t : < .. >; nul : nullable; get : unit > t
262 val nullable :
263 < t : 't; nul : non_nullable; .. > t -> < t : 't; nul : nullable > t
264 val is_null :
265 < nul : nullable; .. > t -> < t : bool_t; nul : non_nullable > t
266 val is_not_null :
267 < nul : nullable; .. > t -> < t : bool_t; nul : non_nullable > t
268
269 val of_option : < t : 't; nul : non_nullable; .. > t option -> < t : 't; nul : nullable > t
270
271 type 'phant arith_op = 'phant binary_op
272 constraint 'phant = < in_t : #numeric_t as 't; out_t : 't; .. >
273
274 val (+) : _ arith_op
275 val (-) : _ arith_op
276 val (/) : _ arith_op
277 val ( * ) : _ arith_op
278
279 type 'phant comp_op = 'phant binary_op
280 constraint 'phant = < out_t : bool_t; .. >
281
282 val (<) : _ comp_op
283 val (<=) : _ comp_op
284 val (=) : _ comp_op
285 val (<>) : _ comp_op
286 val (>=) : _ comp_op
287 val (>) : _ comp_op
288 val is_distinct_from :
289 < nul : 'n; t : 't; .. > t ->
290 < nul : 'n; t : 't; .. > t ->
291 < nul : non_nullable; t : bool_t > t
292 val is_not_distinct_from :
293 < nul : 'n; t : 't; .. > t ->
294 < nul : 'n; t : 't; .. > t ->
295 < nul : non_nullable; t : bool_t > t
296
297 type 'phant logic_op = 'phant binary_op
298 constraint 'phant = < in_t : #bool_t as 't; out_t : 't; .. >
299
300 val (&&) : _ logic_op
301 val (||) : _ logic_op
302 val not :
303 < t : #bool_t; nul : 'n; .. > t -> < t : bool_t; nul : 'n; > t
304
305 (** aggregate functions *)
306 val count :
307 _ group -> < t : int64_t; nul : non_nullable > t
308 val min :
309 < t : #numeric_t as 't; nul : 'n; .. > group -> < t : 't; nul : nullable > t
310 val max :
311 < t : #numeric_t as 't; nul : 'n; .. > group -> < t : 't; nul : nullable > t
312 val sum :
313 < t : #numeric_t as 't; nul : 'n; .. > group -> < t : 't; nul : nullable > t
314
315 (** sequence functions *)
316 val nextval : 'a sequence -> < t : 'a; nul : non_nullable > t
317 val currval : 'a sequence -> < t : 'a; nul : non_nullable > t
318
319 (** timestamp *)
320 val current_timestamp : < t : timestamp_t; nul : _ > t
321 end
322
323 (** standard view operators
324 (in pa_comp, view antiquotations) *)
325 module View : sig
326 val one : < t : 'a #row_t; nul : non_nullable; .. > t -> ('a, non_writable) view
327 end
328
329 val break : _ t -> Sql_internals.value
330 val break_view : (_, _) view -> Sql_internals.view