Difference between revisions of "User Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "syntaxhighlight" to "pre")
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] contains functions for creating and administering database users. The [[User Management]] article gives more information on database users and permissions.
+
This [[Module Library|XQuery Module]] contains functions for creating and administering database users. The [[User Management]] article provides more information on database users and permissions.
  
 
=Conventions=
 
=Conventions=
Line 10: Line 10:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:current||xs:string}}<br/>
+
|<pre>user:current() as xs:string</pre>
−
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the name of the currently logged in user.
+
|Returns the name of the currently logged-in user.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 25: Line 25:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:list||xs:string*}}<br/>
+
|<pre>user:list() as xs:string*</pre>
−
|-
+
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns the names of all registered users that are visible to the current user.
+
|Returns the names of all registered users who are visible to the current user.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 40: Line 40:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:list-details||element(user)*}}<br/>{{Func|user:list-details|$name as xs:string|element(user)*}}<br/>
+
|<pre>user:list-details(
−
|-
+
  $name as xs:string := ()
 +
) as element(user)*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an element sequence, containing all registered users that are visible to the current user.<br/>In addition to the [[Commands#SHOW_USERS|SHOW USERS]] command, encoded password strings and database permissions will be output. A user {{Code|$name}} can be specified to filter the results in advance.
+
|Returns an element sequence, containing all registered users who are visible to the current user.<br/>In addition to the {{Command|SHOW USERS}} command, encoded password strings and database permissions will be output. A user {{Code|$name}} can be specified to filter the results in advance.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* After a fresh installation, {{Code|user:list-details()}} returns output similar to the following one:
 
* After a fresh installation, {{Code|user:list-details()}} returns output similar to the following one:
−
<pre class="brush:xml">
+
<pre lang="xml">
 
<user name="admin" permission="admin">
 
<user name="admin" permission="admin">
 
   <password algorithm="digest">
 
   <password algorithm="digest">
Line 61: Line 63:
 
</user>
 
</user>
 
</pre>
 
</pre>
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|unknown|#Errors}} The specified user name is unknown.
+
|{{Error|unknown|#Errors}} The specified username is unknown.
 
|}
 
|}
  
Line 69: Line 71:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:exists|$name as xs:string|xs:boolean}}<br/>
+
|<pre>user:exists(
−
|-
+
  $name as xs:string
 +
) as xs:boolean</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Checks if a user with the specified {{Code|$name}} exists.
 
|Checks if a user with the specified {{Code|$name}} exists.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:exists('admin')}} will always yield true.
 
* {{Code|user:exists('admin')}} will always yield true.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|name|#Errors}} The specified user name is invalid.
+
|{{Error|name|#Errors}} The specified username is invalid.
 
|}
 
|}
  
Line 87: Line 91:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:check|$name as xs:string, $password as xs:string|empty-sequence()}}<br/>
+
|<pre>user:check(
−
|-
+
  $name     as xs:string,
 +
  $password as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Checks if the specified user and password is correct. Raises errors otherwise.
 
|Checks if the specified user and password is correct. Raises errors otherwise.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|user:check('admin', 'admin')}} will raise an error if the admin password was changed.
+
* {{Code|user:check('admin', '')}} will raise an error if the password of the admin user is a non-empty string.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|unknown|#Errors}} The specified user does not exist.<br/>{{Error|password|#Errors}} The specified password is wrong.<br/>
+
|{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|unknown|#Errors}} The specified user does not exist.<br/>{{Error|password|#Errors}} The specified password is wrong.<br/>
 
|}
 
|}
  
 
==user:info==
 
==user:info==
−
 
−
{{Mark|Updated with Version 9.3:}} {{Code|$name}} parameter added.
 
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:info||element(info)}}<br/>{{Func|user:info|$name as xs:string|element(info)}}
+
|<pre>user:info(
−
|-
+
  $name as xs:string := ()
 +
) as element(info)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an <code>info</code> element, which may contain application-specific data. If a user {{Code|$name}} is supplied, a user-specific element is returned. By default, the returned element has no contents. It can be modified via [[#user:update-info|user:update-info]].
+
|Returns an <code>info</code> element, which may contain application-specific data. If a user {{Code|$name}} is supplied, a user-specific element is returned. By default, the returned element has no contents. It can be modified via {{Function||user:update-info}}.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
Line 121: Line 128:
 
=Updates=
 
=Updates=
  
−
'''Important note:''' All functions in this section are ''updating functions'': they will not be immediately executed, but queued on the [[XQuery Update#Pending Update List|Pending Update List]], which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query does usually not reflect the order in which the code will be evaluated.
+
'''Important note:''' All functions in this section are ''updating functions'': they will not be immediately executed, but queued on the [[XQuery Update#Pending Update List|Pending Update List]], which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query usually does not reflect the order in which the code will be evaluated.
  
 
==user:create==
 
==user:create==
−
 
−
{{Mark|Updated with Version 9.3:}} {{Code|$info}} parameter added.
 
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:create|$name as xs:string, $password as xs:string|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*, $info as element(info)|empty-sequence()}}
+
|<pre>user:create(
−
|-
+
  $name         as xs:string,
 +
  $password     as xs:string,
 +
  $permissions as xs:string*     := (),
 +
  $patterns    as xs:string*     := (),
 +
  $info         as element(info) := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Creates a new user with the specified {{Code|$name}}, {{Code|$password}}, and {{Code|$permissions}}:
 
|Creates a new user with the specified {{Code|$name}}, {{Code|$password}}, and {{Code|$permissions}}:
Line 138: Line 149:
 
* The default global permission (''none'') can be overwritten with an empty pattern or by omitting the last argument.
 
* The default global permission (''none'') can be overwritten with an empty pattern or by omitting the last argument.
 
* Existing users will be overwritten.
 
* Existing users will be overwritten.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions.
 
* {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions.
−
* {{Code|user:create('Jack', 'top!secret', 'read', 'index*')}} creates a new user 'Jack' with no permissions, but read permissions for databases starting with the letters 'index'.
+
* {{Code|user:create('Jack', 'top!secret', 'read', 'index*')}} creates a new user 'Jack' with read permissions for databases starting with the letters 'index'.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
+
|{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 
|}
 
|}
  
Line 151: Line 162:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:grant|$name as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:grant|$name as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}}
+
|<pre>user:grant(
−
|-
+
  $name         as xs:string,
 +
  $permissions as xs:string*,
 +
  $patterns     as xs:string* := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Grants global or local {{Code|$permissions}} to a user with the specified {{Code|$name}}. Local permissions are granted with non-empty glob {{Code|$patterns}}.
 
|Grants global or local {{Code|$permissions}} to a user with the specified {{Code|$name}}. Local permissions are granted with non-empty glob {{Code|$patterns}}.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'.
 
* {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'.
 
* {{Code|user:grant('John', ('read','write'), ('index*','unit*'))}} allows John to read all databases starting with the letters 'index', and to write to all databases starting with 'unit'.
 
* {{Code|user:grant('John', ('read','write'), ('index*','unit*'))}} allows John to read all databases starting with the letters 'index', and to write to all databases starting with 'unit'.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|local|#Errors}} A local permission can only be 'none', 'read' or 'write'.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
+
|{{Error|unknown|#Errors}} The specified username is unknown.<br/>{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|permission|#Errors}} The specified permission is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|local|#Errors}} A local permission can only be 'none', 'read' or 'write'.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 
|}
 
|}
  
Line 170: Line 185:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:drop|$name as xs:string|empty-sequence()}}<br/>{{Func|user:drop|$name as xs:string, $patterns as xs:string*|empty-sequence()}}
+
|<pre>user:drop(
−
|-
+
  $name     as xs:string,
 +
  $patterns as xs:string* := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Drops a user with the specified {{Code|$name}}. If non-empty glob {{Code|$patterns}} are specified, only the database patterns will be removed.
 
|Drops a user with the specified {{Code|$name}}. If non-empty glob {{Code|$patterns}} are specified, only the database patterns will be removed.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:drop('John')}} drops the user 'John'.
 
* {{Code|user:drop('John')}} drops the user 'John'.
 
* {{Code|user:grant('John', 'unit*')}} removes the 'unit*' database pattern. If John accesses any of these database, his global permission will be checked again.
 
* {{Code|user:grant('John', 'unit*')}} removes the 'unit*' database pattern. If John accesses any of these database, his global permission will be checked again.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
+
|{{Error|unknown|#Errors}} The specified username is unknown.<br/>{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|pattern|#Errors}} The specified database pattern is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
 
|}
 
|}
  
Line 189: Line 207:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:alter|$name as xs:string, $newname as xs:string|empty-sequence()}}
+
|<pre>user:alter(
−
|-
+
  $name     as xs:string,
 +
  $newname as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Renames a user with the specified {{Code|$name}} to {{Code|$newname}}.
 
|Renames a user with the specified {{Code|$name}} to {{Code|$newname}}.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:alter('John', 'Jack')}} renames the user 'John' to 'Jack'.
 
* {{Code|user:alter('John', 'Jack')}} renames the user 'John' to 'Jack'.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
+
|{{Error|unknown|#Errors}} The specified username is unknown.<br/>{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|admin|#Errors}} The "admin" user cannot be modified.<br/>{{Error|logged-in|#Errors}} The specified user is currently logged in.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.<br/>{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
 
|}
 
|}
  
Line 207: Line 228:
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:password|$name as xs:string, $password as xs:string|empty-sequence()}}
+
|<pre>user:password(
−
|-
+
  $name     as xs:string,
 +
  $password as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Changes the {{Code|password}} of a user with the specified {{Code|$name}}.
 
|Changes the {{Code|password}} of a user with the specified {{Code|$name}}.
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* {{Code|user:password('John', '')}} assigns user 'John' an empty password string.
 
* {{Code|user:password('John', '')}} assigns user 'John' an empty password string.
−
|-
+
|- valign="top"
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
+
|{{Error|unknown|#Errors}} The specified username is unknown.<br/>{{Error|name|#Errors}} The specified username is invalid.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 
|}
 
|}
  
 
==user:update-info==
 
==user:update-info==
−
 
−
{{Mark|Updated with Version 9.3:}} {{Code|$name}} parameter added.
 
  
 
{| width='100%'
 
{| width='100%'
−
|-
+
|- valign="top"
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|user:update-info|$info as element(info)|empty-sequence()}}<br/>{{Func|user:update-info|$info as element(info), $name as xs:string|empty-sequence()}}
+
|<pre>user:update-info(
−
|-
+
  $info as element(info),
 +
  $name as xs:string     := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
 
|Assigns the specified {{Code|$info}} element to the user management or, if {{Code|$name}} is supplied, to a specific user. This function can be used to manage application-specific data (groups, enhanced user info, etc.).
 
|Assigns the specified {{Code|$info}} element to the user management or, if {{Code|$name}} is supplied, to a specific user. This function can be used to manage application-specific data (groups, enhanced user info, etc.).
−
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
 
* Store initial groups information:
 
* Store initial groups information:
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
user:update-info(element info {
 
user:update-info(element info {
 
   for $group in ('editor', 'author', 'writer')
 
   for $group in ('editor', 'author', 'writer')
Line 244: Line 269:
 
</pre>
 
</pre>
 
* Add a group to a specific user:
 
* Add a group to a specific user:
−
<pre class="brush:xquery">
+
<pre lang='xquery'>
 
user:update-info(<info group='editor'/>, 'john')
 
user:update-info(<info group='editor'/>, 'john')
 
</pre>
 
</pre>
Line 254: Line 279:
 
! width="110"|Code
 
! width="110"|Code
 
|Description
 
|Description
−
|-
+
|- valign="top"
 
|{{Code|admin}}
 
|{{Code|admin}}
 
|The "admin" user cannot be modified.
 
|The "admin" user cannot be modified.
−
|-
+
|- valign="top"
 
|{{Code|conflict}}
 
|{{Code|conflict}}
 
|A user cannot be both altered and dropped.
 
|A user cannot be both altered and dropped.
−
|-
+
|- valign="top"
 
|{{Code|equal}}
 
|{{Code|equal}}
 
|Name of old and new user is equal.
 
|Name of old and new user is equal.
−
|-
+
|- valign="top"
 
|{{Code|local}}
 
|{{Code|local}}
 
|A local permission can only be 'none', 'read' or 'write'.
 
|A local permission can only be 'none', 'read' or 'write'.
−
|-
+
|- valign="top"
 
|{{Code|logged-in}}
 
|{{Code|logged-in}}
 
|The specified user is currently logged in.
 
|The specified user is currently logged in.
−
|-
+
|- valign="top"
 
|{{Code|name}}
 
|{{Code|name}}
−
|The specified user name is invalid.
+
|The specified username is invalid.
−
|-
+
|- valign="top"
 
|{{Code|password}}
 
|{{Code|password}}
 
|The specified password is wrong.
 
|The specified password is wrong.
−
|-
+
|- valign="top"
 
|{{Code|pattern}}
 
|{{Code|pattern}}
 
|The specified database name is invalid.
 
|The specified database name is invalid.
−
|-
+
|- valign="top"
 
|{{Code|permission}}
 
|{{Code|permission}}
 
|The specified permission is invalid.
 
|The specified permission is invalid.
−
|-
+
|- valign="top"
 
|{{Code|unknown}}
 
|{{Code|unknown}}
 
|The specified user does not exist.
 
|The specified user does not exist.
−
|-
+
|- valign="top"
 
|{{Code|update}}
 
|{{Code|update}}
 
|The operation can only be performed once per user or database pattern.
 
|The operation can only be performed once per user or database pattern.
Line 292: Line 317:
  
 
;Version 8.6
 
;Version 8.6
−
* Updated: [[#user:create|user:create]], [[#user:info|user:info]], [[#user:update-info|user:update-info]]: {{Code|$name}} parameter added.
+
* Updated: {{Function||user:create}}, {{Function||user:info}}, {{Function||user:update-info}}: {{Code|$name}} parameter added.
  
 
;Version 8.6
 
;Version 8.6
−
* Added: [[#user:check|user:check]], [[#user:info|user:info]], [[#user:update-info|user:update-info]].
+
* Added: {{Function||user:check}}, {{Function||user:info}}, {{Function||user:update-info}}.
−
* Updated: [[#user:list|user:list]], [[#user:list-details|user:list-details]]: If called by non-admins, will only return the current user.
+
* Updated: {{Function||user:list}}, {{Function||user:list-details}}: If called by non-admins, will only return the current user.
  
 
;Version 8.4
 
;Version 8.4
−
* Updated: [[#user:create|user:create]], [[#user:grant|user:grant]], [[#user:drop|user:drop]]: extended support for database patterns.
+
* Updated: {{Function||user:create}}, {{Function||user:grant}}, {{Function||user:drop}}: extended support for database patterns.
  
 
;Version 8.1
 
;Version 8.1
−
* Added: [[#user:current|user:current]].
+
* Added: {{Function||user:current}}.
  
 
The Module was introduced with Version 8.0.
 
The Module was introduced with Version 8.0.

Latest revision as of 18:39, 1 December 2023

This XQuery Module contains functions for creating and administering database users. The User Management article provides more information on database users and permissions.

Conventions[edit]

All functions and errors in this module are assigned to the http://basex.org/modules/user namespace, which is statically bound to the user prefix.

Read Operations[edit]

user:current[edit]

Signature 
user:current() as xs:string
Summary Returns the name of the currently logged-in user.
Examples
  • If the GUI or the standalone mode is used, user:current() always returns admin.

user:list[edit]

Signature 
user:list() as xs:string*
Summary Returns the names of all registered users who are visible to the current user.
Examples
  • After a fresh installation, user:list() will only return admin.

user:list-details[edit]

Signature 
user:list-details(
  $name  as xs:string  := ()
) as element(user)*
Summary Returns an element sequence, containing all registered users who are visible to the current user.
In addition to the SHOW USERS command, encoded password strings and database permissions will be output. A user $name can be specified to filter the results in advance.
Examples
  • After a fresh installation, user:list-details() returns output similar to the following one:
<user name="admin" permission="admin">
  <password algorithm="digest">
    <hash>304bdfb0383c16f070a897fc1eb25cb4</hash>
  </password>
  <password algorithm="salted-sha256">
    <salt>871602799292195</salt>
    <hash>a065ca66fa3d6da5762c227587f1c8258c6dc08ee867e44a605a72da115dcb41</hash>
  </password>
</user>
Errors unknown: The specified username is unknown.

user:exists[edit]

Signature 
user:exists(
  $name  as xs:string
) as xs:boolean
Summary Checks if a user with the specified $name exists.
Examples
  • user:exists('admin') will always yield true.
Errors name: The specified username is invalid.

user:check[edit]

Signature 
user:check(
  $name      as xs:string,
  $password  as xs:string
) as empty-sequence()
Summary Checks if the specified user and password is correct. Raises errors otherwise.
Examples
  • user:check('admin', ) will raise an error if the password of the admin user is a non-empty string.
Errors name: The specified username is invalid.
unknown: The specified user does not exist.
password: The specified password is wrong.

user:info[edit]

Signature 
user:info(
  $name  as xs:string  := ()
) as element(info)
Summary Returns an info element, which may contain application-specific data. If a user $name is supplied, a user-specific element is returned. By default, the returned element has no contents. It can be modified via user:update-info.
Examples
  • After a fresh installation, user:info() returns <info/>.

Updates[edit]

Important note: All functions in this section are updating functions: they will not be immediately executed, but queued on the Pending Update List, which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query usually does not reflect the order in which the code will be evaluated.

user:create[edit]

Signature 
user:create(
  $name         as xs:string,
  $password     as xs:string,
  $permissions  as xs:string*     := (),
  $patterns     as xs:string*     := (),
  $info         as element(info)  := ()
) as empty-sequence()
Summary Creates a new user with the specified $name, $password, and $permissions:
  • Local permissions are granted with non-empty glob $patterns.
  • An $info element with application-specific information can be supplied.
  • The default global permission (none) can be overwritten with an empty pattern or by omitting the last argument.
  • Existing users will be overwritten.
Examples
  • user:create('John', '7e$j#!1', 'admin') creates a new user 'John' with admin permissions.
  • user:create('Jack', 'top!secret', 'read', 'index*') creates a new user 'Jack' with read permissions for databases starting with the letters 'index'.
Errors name: The specified username is invalid.
permission: The specified permission is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.

user:grant[edit]

Signature 
user:grant(
  $name         as xs:string,
  $permissions  as xs:string*,
  $patterns     as xs:string*  := ()
) as empty-sequence()
Summary Grants global or local $permissions to a user with the specified $name. Local permissions are granted with non-empty glob $patterns.
Examples
  • user:grant('John', 'create') grants create permissions to the user 'John'.
  • user:grant('John', ('read','write'), ('index*','unit*')) allows John to read all databases starting with the letters 'index', and to write to all databases starting with 'unit'.
Errors unknown: The specified username is unknown.
name: The specified username is invalid.
pattern: The specified database pattern is invalid.
permission: The specified permission is invalid.
admin: The "admin" user cannot be modified.
local: A local permission can only be 'none', 'read' or 'write'.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.

user:drop[edit]

Signature 
user:drop(
  $name      as xs:string,
  $patterns  as xs:string*  := ()
) as empty-sequence()
Summary Drops a user with the specified $name. If non-empty glob $patterns are specified, only the database patterns will be removed.
Examples
  • user:drop('John') drops the user 'John'.
  • user:grant('John', 'unit*') removes the 'unit*' database pattern. If John accesses any of these database, his global permission will be checked again.
Errors unknown: The specified username is unknown.
name: The specified username is invalid.
pattern: The specified database pattern is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.
conflict: A user cannot be both altered and dropped.

user:alter[edit]

Signature 
user:alter(
  $name     as xs:string,
  $newname  as xs:string
) as empty-sequence()
Summary Renames a user with the specified $name to $newname.
Examples
  • user:alter('John', 'Jack') renames the user 'John' to 'Jack'.
Errors unknown: The specified username is unknown.
name: The specified username is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.
conflict: A user cannot be both altered and dropped.

user:password[edit]

Signature 
user:password(
  $name      as xs:string,
  $password  as xs:string
) as empty-sequence()
Summary Changes the password of a user with the specified $name.
Examples
  • user:password('John', ) assigns user 'John' an empty password string.
Errors unknown: The specified username is unknown.
name: The specified username is invalid.
update: The operation can only be performed once per user or database pattern.

user:update-info[edit]

Signature 
user:update-info(
  $info  as element(info),
  $name  as xs:string      := ()
) as empty-sequence()
Summary Assigns the specified $info element to the user management or, if $name is supplied, to a specific user. This function can be used to manage application-specific data (groups, enhanced user info, etc.).
Examples
  • Store initial groups information:
user:update-info(element info {
  for $group in ('editor', 'author', 'writer')
  return element group { $group }
})
  • Add a group to a specific user:
user:update-info(<info group='editor'/>, 'john')

Errors[edit]

Code Description
admin The "admin" user cannot be modified.
conflict A user cannot be both altered and dropped.
equal Name of old and new user is equal.
local A local permission can only be 'none', 'read' or 'write'.
logged-in The specified user is currently logged in.
name The specified username is invalid.
password The specified password is wrong.
pattern The specified database name is invalid.
permission The specified permission is invalid.
unknown The specified user does not exist.
update The operation can only be performed once per user or database pattern.

Changelog[edit]

Version 8.6
Version 8.6
Version 8.4
Version 8.1

The Module was introduced with Version 8.0.

Retrieved from "http://docs.basex.org/index.php?title=User_Module&oldid=16896"