User Functions
This module contains functions for creating and administering database users. The User Management article provides more information on database users and permissions.
All functions and errors are in the http://basex.org/modules/user namespace, to which the user prefix is statically bound.
| Signature | user:current() as xs:string |
|---|
| Summary | Returns the name of the currently logged-in user. |
|---|
| Examples | user:current()
Always returns admin if the standalone mode or the GUI is used. |
|---|
| Signature | user:list() as xs:string* |
|---|
| Summary | Returns the names of all registered users who are visible to the current user, sorted by name. |
|---|
| Examples | user:list()
Only returns admin after a fresh installation. |
|---|
| Signature | user:list-details( $name as xs:string := ()) as element(user)*admin |
|---|
| Summary | Returns an element sequence, containing all registered users who are visible to the current user, sorted by name. 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. admin permissions are required, unless the addressed user is the current one. |
|---|
| Errors | unknown | The specified user does not exist. |
|
|---|
| Examples | user:list-details()
Returns output similar to this one after a fresh installation. The result:<user name="admin" permission="admin">
<password algorithm="salted-sha256">
<salt>***</salt>
<hash>***</hash>
</password>
</user>
|
|---|
| Signature | user:exists( $name as xs:string) as xs:booleanadmin |
|---|
| Summary | Checks if a user with the specified $name exists. |
|---|
| Errors | name | The specified username is invalid. |
|
|---|
| Examples | user:exists('admin')
Always yields true. |
|---|
| Signature | user:check( $name as xs:string, $password as xs:string) as empty-sequence()admin |
|---|
| Summary | Checks if the specified user and password are correct. Raises errors otherwise. admin permissions are required, unless the addressed user is the current one. |
|---|
| Errors | name | The specified username is invalid. | password | The specified password is wrong. | unknown | The specified user does not exist. |
|
|---|
| Examples | user:check('admin', '')
Raises an error if the password of the admin user is a non-empty string. |
|---|
| Signature | user:info( $name as xs:string := ()) as element(info)admin |
|---|
| 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. admin permissions are required, unless the addressed user is the current one. |
|---|
| Examples | user:info()
Returns <info/> after a fresh installation. |
|---|
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.
| 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()admin |
|---|
| 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 overridden with an empty pattern or by omitting the
$patterns argument. - Existing users will be overwritten.
|
|---|
| Errors | admin | The "admin" user cannot be modified. | logged-in | The specified user is currently logged in. | name | The specified username is invalid. | permission | The specified permission is invalid. | update | The operation can only be performed once per user or database pattern. |
|
|---|
| Examples | user:create('John', '7e$j#!187?aZX81', 'admin')
Creates a new user John with admin permissions.
user:create('Jack', 'top!secret', ('read', 'write'), ('data*', 'index*'))
Creates a new user Jack with read permissions for databases starting with the letters data, and write permissions for databases starting with index. |
|---|
| Signature | user:grant( $name as xs:string, $permissions as xs:string*, $patterns as xs:string* := ()) as empty-sequence()admin |
|---|
| Summary | Grants global or local $permissions to a user with the specified $name. Local permissions are granted with non-empty glob $patterns. |
|---|
| Errors | 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. | name | The specified username is invalid. | 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. |
|
|---|
| 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'. |
|---|
| Signature | user:drop( $name as xs:string, $patterns as xs:string* := ()) as empty-sequence()admin |
|---|
| Summary | Drops a user with the specified $name. If non-empty glob $patterns are specified, only the database patterns will be removed. admin permissions are required, unless the addressed user is the current one. |
|---|
| Errors | admin | The "admin" user cannot be modified. | conflict | A user cannot be both altered and dropped. | logged-in | The specified user is currently logged in. | name | The specified username is invalid. | pattern | The specified database name is invalid. | unknown | The specified user does not exist. | update | The operation can only be performed once per user or database pattern. |
|
|---|
| Examples | user:drop('John')
Drops the user 'John'.
user:drop('John', 'unit*')
Removes the unit* database pattern. If John accesses any of these databases, their global permission will be checked again. |
|---|
| Signature | user:alter( $name as xs:string, $newname as xs:string) as empty-sequence()admin |
|---|
| Summary | Renames a user with the specified $name to $newname. |
|---|
| Errors | admin | The "admin" user cannot be modified. | conflict | A user cannot be both altered and dropped. | logged-in | The specified user is currently logged in. | name | The specified username is invalid. | unknown | The specified user does not exist. | update | The operation can only be performed once per user or database pattern. |
|
|---|
| Examples | user:alter('John', 'Jack')
Renames the user 'John' to 'Jack'. |
|---|
| Signature | user:password( $name as xs:string, $password as xs:string) as empty-sequence()admin |
|---|
| Summary | Changes the password of a user with the specified $name. admin permissions are required, unless the addressed user is the current one. |
|---|
| Errors | name | The specified username is invalid. | unknown | The specified user does not exist. | update | The operation can only be performed once per user or database pattern. |
|
|---|
| Examples | user:password('John', '')
Assigns user 'John' an empty password string. |
|---|
| Signature | user:update-info( $info as element(info), $name as xs:string := ()) as empty-sequence()admin |
|---|
| 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.). admin permissions are required, unless the addressed user is the current one. |
|---|
| Errors | info | The global info element can only be updated once. | name | The specified username is invalid. | unknown | The specified user does not exist. | update | The operation can only be performed once per user or database pattern. |
|
|---|
| Examples | user:update-info(element info {
for $group in ('editor', 'author', 'writer')
return element group { $group }
})
Stores initial groups information.
user:update-info(<info group='editor'/>, 'john')
Adds a group to a specific user. |
|---|
| Code | Description |
|---|
admin | The "admin" user cannot be modified. |
conflict | A user cannot be both altered and dropped. |
info | The global info element can only be updated once. |
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. |
Version 8.6Version 8.4Version 8.1Version 8.0
⚡Generated with XQuery
