Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 9.0}}:
{{Mark|Updated with Version 9.0}}: Return update count for updating statements.
{{Mark|Updated with Version 9.0}}: Return update count for updating statements.
{{Mark|Updated with Version 9.0}}:
no edit summary
=Conventions=
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/sql</nowiki></code> namespace, which is statically bound to the {{Code|sql}} prefix.<br/>
|-
| '''Errors'''
|{{Error|init|XQuery Errors#SQL Functions Errors}} the specified driver is not found.
|}
|-
| width='120' | '''Signatures'''
|{{Func|sql:connect|$url as xs:string|xs:anyURI}}<br/ >{{Func|sql:connect|$url as xs:string, $user as xs:string, $password as xs:string|xs:anyURI}}<br/ >{{Func|sql:connect|$url as xs:string, $user as xs:string, $password as xs:string, $options as map(xs:string, item()*)?|xs:anyURI}}<br/ >
|-
| '''Summary'''
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an SQL exception occurs, e.g. missing JDBC driver or not existing relationoccurred when connecting to the database.
|-
| '''Examples'''
==sql:execute==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|sql:execute|$id as xs:anyURI, $statement as xs:string|item()*}}<br/>{{Func|sql:execute|$id as xs:anyURI, $statement as xs:string, $options as map(*)?|item()*}}
|-
| '''Summary'''
* If an update statement was executed, the number of updated rows will be returned as integer.
* Otherwise, an XML representation of all results will be returned.
With {{Code|$options}}, the following parameter can be set:
* {{Code|timeout}}: query execution will be interrupted after the specified number of seconds.
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an error occurred while executing SQL exception occurs, e.g. not existing relation is retrieved.<br/ >{{Error|id|XQuery Errors#SQL Functions Errors}} the specified connection does not exist.<br/>{{Error|timeout|#Errors}} query execution exceeded timeout.<br/ >
|}
==sql:execute-prepared==
{| width='100%'
|-
| width='120' | '''Signatures'''
|{{Func|sql:execute-prepared|$id as xs:anyURI, $params as element(sql:parameters)|item()*}}<br/>{{Func|sql:execute-prepared|$id as xs:anyURI, $params as element(sql:parameters), $options as map(*)?|item()*}}
|-
| '''Summary'''
| This function executes a prepared statement:* with the specified {{Code|$id}}. The output format is identical to [[#sql:execute|sql:execute]].* The parameter {{Code|$id}} refers to the prepared statement.* The optional parameter {{Code|$params}} is an element {{Code|<sql:parameters/>}} representing the parameters for a prepared statement along with their types and values. The following schema shall be used:<br/ >
<pre class="brush:xquery">
element sql:parameters {
}?
</pre>
With {{Code|$options}}, the following parameter can be set:
* {{Code|timeout}}: query execution will be interrupted after the specified number of seconds.
|-
| '''Errors'''
|{{Error|errorattribute|XQuery Errors#SQL Functions Errors}} an SQL exception occurs, e.g. not existing relation is retrieved.<br/ >attribute different from {{ErrorCode|id|XQuery Errors#SQL Functions Errorstype}} the specified connection does not exist.<br/ >and {{ErrorCode|parameters|XQuery Errors#SQL Functions Errorsnull}} the number of is set for a {{Code|<sql:parameter/>}} elements in element.<br/ >{{CodeError|error|<sql:parameters/>#Errors}} differs from the number of placeholders in the prepared statementan error occurred while executing SQL.<br/ >{{Error|BXSQ0004id|XQuery Errors#SQL Functions Errors}} the type of a parameter for a prepared statement is specified connection does not specifiedexist.<br/ >{{Error|attributeparameters|XQuery Errors#SQL Functions Errors}} an attribute different from {{Code|no parameter type}} and specified.<br/>{{CodeError|null}} is set for a {{Codetimeout|<sql:parameter/>#Errors}} elementquery execution exceeded timeout.<br/ >{{Error|type|XQuery Errors#SQL Functions Errors}} the value of a parameter is from type date, time or timestamp and its value is in an invalid cannot be converted to the specified format.<br/ >
|}
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an error occurred while executing SQL exception occurs.<br/ >{{Error|id|XQuery Errors#SQL Functions Errors}} the specified connection does not exist.<br/ >
|}
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an error occurred while executing SQL exception occurs.<br/ >{{Error|id|XQuery Errors#SQL Functions Errors}} the specified connection does not exist.<br/ >
|}
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an error occurred while executing SQL exception occurs.<br/ >{{Error|id|XQuery Errors#SQL Functions Errors}} the specified connection does not exist.<br/ >
|}
|-
| '''Errors'''
|{{Error|error|XQuery Errors#SQL Functions Errors}} an error occurred while executing SQL exception occurs.<br/ >{{Error|id|XQuery Errors#SQL Functions Errors}} the specified connection does not exist.<br/ >
|}
=Errors=
{| class="wikitable" width="100%"
|{{Code|error}}
|An SQL exception occurred.
|-
|{{Code|id}}
|A connection does not exist.
|-
|{{Code|init}}
|A database driver is not found.
|-
|{{Code|idparameters}}|A connection does not existNo parameter type specified.
|-
|{{Code|parameterstimeout}}|Wrong number of {{Code|<sql:parameter/>}} elements, or parameter type is not specifiedQuery execution exceeded timeout.
|-
|{{Code|type}}
|A The value of a parameter is from type date, time or timestamp and its value is in an invalid cannot be converted to the specified format.
|}
;Version 9.0
* Updated: [[#sql:execute|sql:execute]], [[#sql:execute-prepared|sql:execute-prepared]]: Return update count for updating statements. {{Code|$options}} argument added.
* Updated: Connection ids are URIs now.
* Updated: error codes updatesupdated; errors now use the module namespace
;Version 7.5
* Updated: prepared statements are now executed via [[#sql:execute-prepared|sql:execute-prepared]]
The module was introduced with Version 7.0.
