unikernel/duniverse/ocaml-caqti/caqti/doc/dune

@@ -0,0 +1 @@
+(documentation (package caqti))

unikernel/duniverse/ocaml-caqti/caqti/doc/index.mld

@@ -0,0 +1,75 @@
+{0 caqti index}
+
+{1 Library caqti}
+
+This is classic API for Caqti, which mirrors the above libray and provides
+signatures, configurations, and a few other things for other Caqti packages.
+The plan in to uses wrapped module everywhere and to make some adjustments
+to the organization of modules.  You may continue to use this for now, as
+deprecation is posponed until the complete replacement is available.
+
+This library exposes the following toplevel modules:
+{!modules:
+    Caqti_connect_sig
+    Caqti_connection_sig
+    Caqti_driver_info
+    Caqti_error
+    Caqti_mult
+    Caqti_pool_config
+    Caqti_pool_sig
+    Caqti_query
+    Caqti_query_fmt
+    Caqti_request
+    Caqti_response_sig
+    Caqti_stream_sig
+    Caqti_switch_sig
+    Caqti_type
+    Caqti_type_sig
+}
+
+{1 Preview library caqti.template}
+
+For now, {b this library is provides as a preview only.  The interface will
+change in incompatible ways} before it's declared ready for usage in
+production code.
+
+This library provides the interface to create templates for requests to send
+to the database.  A request template essentially combines a parametrised
+query string with a parameter encoder and a row decoder, and can often be
+defined statically.  Execution of queries are handled by other packages,
+depending on your preferred concurrency and OS libraries.
+
+The entry point of this library is the module:
+{!module-Caqti_template}
+
+{1 Library caqti.blocking}
+
+This library implements the blocking (non-)concurrency using the unix library.
+Real concurrency support is provided by separate packages.
+
+The entry point of this library is the module:
+{!module-Caqti_blocking}.
+
+{1 Library caqti.plugin}
+
+This library registers a dynamic linker based on the dune-site.plugin
+library, which allows Caqti to automatically load driver libraries inferred
+from the URI when connecting to a new kind of database for the first time.
+It has entry point; linking aganist it provides all of its functionality.
+
+
+{1 Platform Libraries for Internal Use}
+
+The platform libraries are only meant for use in implementing drivers and
+concurrency support.  {b These APIs are unstable}, i.e. they can change between
+minor versions and without prior deprecation notices.
+
+{2 Library caqti.platform}
+
+The entry point of this library is the module:
+{!module-Caqti_platform}.
+
+{2 Library caqti.platform.unix}
+
+The entry point of this library is the module:
+{!module-Caqti_platform_unix}.

unikernel/duniverse/ocaml-caqti/caqti/doc/query_template.mld

@@ -0,0 +1,98 @@
+{1 The Syntax of Query Templates}
+
+In order to help even out common difference between database systems and
+provide additional features, Caqti uses a lightweight template syntax parsed
+into the internal form {!Caqti_query.t} by the
+{!Caqti_query.angstrom_parser} and related utility functions.  Query strings
+are written almost as you expect them to be sent to the database, but with
+some in-text special syntax.
+
+{2 Semicolon and End-of-Input}
+
+The {!Caqti_query.t} type represents a single statement. To allow reading
+statements from a script file and sending them to database one by one, the
+parser will stop at the first {{!quotes} unquoted} semicolon, as well as at
+the end of input.  The semicolon itself will not be parsed, but you can
+create your own parser from the {!Caqti_query.angstrom_parser} which does.
+
+{2 Parameter References}
+
+Parameters are specified as either
+
+  - ["?"] for linear substitutions (like Sqlite and MariaDB), or
+  - ["$1"], ["$2"], ... for non-linear substitutions (like PostgreSQL).
+
+Either case works independent of the style used by the database system; if
+non-linear substitutions are used with a database system which does not
+support it, the parameter values will be reorderd and duplicated as needed.
+Mixing the two styles in the same query string is not permitted.  Note that
+numbering of non-linear parameters is offset by one compared to
+{!Caqti_query.P}, in order to be consistent with PostgreSQL conventions.
+
+The following characters are not permitted immediately after a [?]
+reference:
+{[
+    'A'..'Z' | 'a'..'z' | '0'..'9' | '_'
+  | '!' | '"' | '#' | '$' | '%' | '&' | '\'' | '.' | ':'
+  | '<' | '=' | '>' | '?' | '@' | '^' | '`' | '|' | '~'
+]}
+
+{!quotes} are not scanned for parameter references, to avoid accidental
+transformation of string literals within query strings.
+
+{2 Environment References}
+
+Functions processing queries take an [?env] argument which provides
+substitutions for the references which can have one of the following
+syntaxes:
+
+  - ["$(<var>)"] is substituted by [env driver_info "<var>"].
+  - ["$(<var>.)"], if not found by the first rule, is substituted by
+    [env driver_info "<var>"] followed by a dot iff that result is nonempty.
+  - ["$<var>."] is a shortcut for ["$(<var>.)"].
+
+These aid in substituting configurable fragments into the queries, like
+database schemas or table names.  The forms involving a period are
+suggested for qualifying tables, sequences, and other database objects with
+the database schema.
+
+Environment references are not parsed inside quotes, except for one kind;
+see {!quotes} for details.
+
+{2:quotes Quotes}
+
+In order to avoid accidental conversion of parameter references or undesired
+expansion of environment lookups, the parser recognizes several kinds of
+quotations used by database systems.  The following common kinds of
+quotations are recognized:
+
+  - ['<text>'] where ['] may be escapes as ['']
+  - ["<text>"] where ["] may be escaped as [""]
+  - [`<text>`] with no escape mechanism
+
+In addition the parser recognizes PostgreSQL style tagged quotations:
+
+  - [$<tag>$<text>$<tag>$] where the tag has the form of an identifier
+  - [$$<text>$$] as above but with an emtpy tag
+
+The former is treated like the other quotations, i.e. the text inside is
+passed on as-is.  In the latter form, environment references are expanded,
+while parameter references are not recognized.
+
+The motivation for this exception is that dollar quotes are often used in
+PostgreSQL schemas to define saved procedures, where it is useful to
+substitute schema names and possibly other code fragments.  On the other
+hand, the dollar quotes are useful for other purposes, and when a tag is
+provided, whether it is around a saved procedure or elsewhere, it is
+typically to avoid a clashes with dollar signs in the text.  Therefore, the
+exception to expand environment references is only made for the tagless
+variant of the dollar quotes.
+
+Note that nested quotes are not recognized inside [$$<text>$$], so
+substitutions apply unconditionally.  That is, the [$(x)] substring will
+
+  - in [SELECT '$(x)'] be interpreted literally due to the single quotes,
+    and
+  - in [$q$SELECT '$(x)'$q$] be interpreted literally due to the tagged
+    quotes, but will
+  - in [$$SELECT '$(x)'$$] be expanded.

unikernel/duniverse/ocaml-caqti/caqti/doc/tweaks.mld

@@ -0,0 +1,37 @@
+{1:tweaks Database Tweaks}
+
+{2 TL;DR}
+
+The [?tweaks_version] parameter tells Caqti drivers to enable all tweaks
+introduced up to and including the given major and minor version of Caqti.
+
+{2 The Tweaks Parameter}
+
+Occasionally Caqti makes changes to the database session parameters or
+otherwise how it interacts with specific database systems.  This may be done
+to improve consistency across databases, to make it easier to detect
+mistakes, to avoid obsolete behaviour, etc.  However, this can break
+backwards compatibility with applications, sometimes in subtle ways, which
+is the motivation for the [?tweaks_version] parameter of the connecting
+functions.
+
+Passing [~tweaks_version:(major_version, minor_verson)] declares that the
+application is compatible with all tweaks introduced up to and including
+that version of Caqti.  The default is to omit all tweaks introduced since
+the last major version.  On each major release, all tweaks up to that point
+becomes permanent and requesting an earlier tweaks version will have no
+effect.
+
+Production code should either omit the parameter or pass the largest major
+and minor version pair for which the code has been tested.  This offers the
+choice of adapting only on major versions or incrementally.
+
+Code in development can declare a progressive value, like the next major
+version, in order to always use the latest set of tweaks.
+
+{2 Current Tweaks}
+
+{3 Introduced with [(1, 8)] and later}
+
+  - SQLite3: Checking of foreign key constraints has been enabled by issuing
+    a [PRAGMA foreign_keys = ON] for the session.