βRequests
A request is a JSON structure that is passed via a POST HTTP call to sqliterg
, using the port specified when running the server application.
First and foremost, the database we connect to is specified in the URL of the POST call. It is something like this:
That db2
part is the database ID, and must match the id
of a database, defined in the commandline.
This is a JSON that exemplifies all possible elements of a request.
Let's go through it.
credentials
: Authentication Credentials
credentials
: Authentication CredentialsLines 2-5; object
If authentication is enabled in INLINE
mode, this object describes the credentials.
See the detailed docs.
transaction
: List of Queries/Statements
transaction
: List of Queries/StatementsLines 6-29; list of objects; mandatory
The list of the queries or statements that will actually be performed on the database, with their own parameters.
They will be run in a transaction, and the transaction will be committed only if all the queries that are not marked as noFail
(see the relevant section) do successfully complete.
The transaction can be empty, in that case the database will be locked and unlocked but nothing else will be done.
SQL Statements to Execute
Lines 8, 11, 15, 19; string; mandatory one of query
or statement
The actual SQL to execute.
Specifying it as query
means that a result set is expected (typically, SELECT
queries or queries with a RETURNING
clause).
Specifying a statement
will not return a result set, but a count of affected records.
Stored Query Reference
Line 23; string; mandatory as the above
A query
or a statement
(see above) can consist of a reference to a Stored Query. They are prepended by a ^
. An error will occour if the S.Q. with an ID equal to the part after the ^
was not defined for this database.
See the relevant section.
(Named) Parameter Values for the Query/Statement
Lines 12, 20; object
If the query needs to be parametrized, named parameters can be defined in the statement using colon-prefixed syntax (e.g. :id
), and the proper values for them must be specified here. You can specify values that do not match a parameter; they'll be ignored.
What happens if some parameter values aren't defined in the values
object? If there are less parameter values than expected, it will give an error. If they are correct in number, but some parameter names don't match, the missing parameters will be assigned a value of null
.
(Positional) Parameter Values for the Query/Statement
Lines 31; array
Parameters can also be positional, i.e. specified in order. In this case the placeholder is a simple ?
and the values are given as an array.
Batch Parameter Values for a Statement
Lines 24..27; list of objects
Only for statement
s, more than one set of parameter values can be specified; the statement will be applied to them in a batch (by preparing the statement).
It's not possible to specify both values
and valuesBatch
.
noFail
: don't Fail when Errors Occour
noFail
: don't Fail when Errors OccourLine 18; Boolean
When a query/statement fails, by default the whole transaction is rolled back and a response with a single error is returned (the first one for the whole transaction). Specifying this flag, the error will be reported for that statement, but the execution will continue and eventually be committed. See the relevant page for more details.
Last updated