sihl 1.0.0 · OCaml Package

type 'a prepared_search_request

'a prepared_search_request is a prepared SQL statement that can be used to sort, filter and paginate (= search) a collection.

val prepare_requests : string -> string -> string -> string

deprecated Use prepare_search_request instead

val prepare_search_request : 
  search_query:string ->
  filter_fragment:string ->
  ?sort_by_field:string ->
  ?format_filter:(string -> string) ->
  'a Caqti_type.t ->
  'a prepared_search_request

prepare_search_request ~search_query ~count_query ~filter_fragment ?sort_by_field type returns a prepared SQL statement 'a prepared_search_request by assembling the SQL query from the provided fragments.

search_query is the SELECT ... FROM table part of the query.

count_query is a query that is executed by Sihl after the search in order to obtain the total number of items in the table. For example SELECT COUNT(\*\) FROM table.

filter_fragment is the fragment that is appended to search_query for filtering. Usually you want ot OR fields that are often searched for. For example WHERE table.field1 LIKE $1 OR table.field2 $1 OR table.field3 LIKE $1.

sort_by_field is an optional field name that is used for sorting. By default, the field "id" is used. Note that in order to prepare the requests, the sort field has to be known beforehand. If you want to dynamically set the field, you need to write your own query at runtime.

format_filter is a function applied to the filter keyword before it is passed to the database. By default, a keyword "keyword" is formatted to "%skeyword%s". This might not be what you want performance-wise. If you need full control, pass in the identity function and format the keyword yourself.

type is the caqti type of an item of the collection.

val run_request : 
  (module Caqti_lwt.CONNECTION) ->
  'a prepared_search_request ->
  [< `Asc | `Desc ] ->
  'c option ->
  'a ->
  ('b list * int) Lwt.t

deprecated Use run_search_request instead

val run_search_request : 
  'a prepared_search_request ->
  [ `Asc | `Desc ] ->
  string option ->
  limit:int ->
  offset:int ->
  ('a list * int) Lwt.t

run_search_request prepared_request sort filter ~limit ~offset runs the prepared_request and returns a partial result of the whole stored collection. The second element of the result tuple is the total amount of items in the whole collection.

prepared_request is the returned prepared request by prepare_search_request.

sort is the sort order. The field that is sorted by was set by prepare_search_request.

filter is an optional keyword that is used to filter the collection. If no filter is provided, the collection is not filtered.

offset is the number of items that the returned partial result is offset by.

limit is the number of items of the returned partial result.

offset and limit can be used together to implement pagination.

val raise_error : ('a, Caqti_error.t) Result.t -> 'a

raise_error err raises a printable caqti error err .

val fetch_pool : unit -> (Caqti_lwt.connection, Caqti_error.t) Caqti_lwt.Pool.t

fetch_pool () returns the connection pool that was set up. If there was no connection pool set up, setting it up now.

val find_opt : 
  ('a, 'b, [< `One | `Zero ]) Caqti_request.t ->
  'a ->
  'b option Lwt.t

find_opt request input runs a caqti request in the connection pool where input is the input of the caqti request and returns one row or None. Returns None if no rows are found.

Note that the caqti request is only allowed to return one or zero rows, not many.

val find : ('a, 'b, [< `One ]) Caqti_request.t -> 'a -> 'b Lwt.t

find request input runs a caqti request on the connection pool where input is the input of the caqti request and returns one row. Raises an exception if no row was found.

Note that the caqti request is only allowed to return one or zero rows, not many.

val collect : 
  ('a, 'b, [< `One | `Zero | `Many ]) Caqti_request.t ->
  'a ->
  'b list Lwt.t

collect request input runs a caqti request on the connection pool where input is the input of the caqti request and retuns a list of rows.

Note that the caqti request is allowed to return one, zero or many rows.

val exec : ('b, unit, [< `Zero ]) Caqti_request.t -> 'b -> unit Lwt.t

exec request input runs a caqti request on the connection pool.

Note that the caqti request is not allowed to return any rows.

Use exec to run mutations.

val query : (Caqti_lwt.connection -> 'a Lwt.t) -> 'a Lwt.t

query f runs the query f on the connection pool and returns the result. If the query fails the Lwt.t fails as well.

val query' : 
  (Caqti_lwt.connection -> ('a, Caqti_error.t) Result.t Lwt.t) ->
  'a Lwt.t

query' f runs the query f on the connection pool and returns the result. Use query' instead of query as a shorthand when you have a single caqti request to execute.

val transaction : (Caqti_lwt.connection -> 'a Lwt.t) -> 'a Lwt.t

transaction f runs the query f on the connection pool in a transaction and returns the result. If the query fails the Lwt.t fails as well and the transaction gets rolled back. If the database driver doesn't support transactions, transaction gracefully becomes query.

val transaction' : 
  (Caqti_lwt.connection -> ('a, Caqti_error.t) Result.t Lwt.t) ->
  'a Lwt.t

transaction' f runs the query f on the connection pool in a transaction and returns the result. If the query fails the Lwt.t fails as well and the transaction gets rolled back. If the database driver doesn't support transactions, transaction' gracefully becomes query'.

type database =

| MariaDb
| PostgreSql

val used_database : unit -> database option

used_database () returns the database that is defined in DATABASE_URL, None if an unsupported database is used.

val start : unit -> unit Lwt.t

val stop : unit -> unit Lwt.t

val lifecycle : Container.lifecycle

val register : unit -> Container.Service.t

module Migration : sig ... end

package sihl