Difference between revisions of "User Module"
m (Text replacement - "'''Signatures'''" to "'''Signature'''") |
|||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions for creating and administering database users. The [[User Management]] article | + | 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 15: | Line 15: | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the name of the currently logged in user. | + | |Returns the name of the currently logged-in user. |
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
Line 30: | Line 30: | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the names of all registered users | + | |Returns the names of all registered users who are visible to the current user. |
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
Line 47: | Line 47: | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns an element sequence, containing all registered users | + | |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" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
Line 94: | Line 94: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:check( | |<pre>user:check( | ||
− | $name as xs:string | + | $name as xs:string, |
$password as xs:string | $password as xs:string | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 128: | 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 | + | '''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== | ||
Line 136: | Line 136: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:create( | |<pre>user:create( | ||
− | $name as xs:string | + | $name as xs:string, |
− | $password as xs:string | + | $password as xs:string, |
− | $permissions as xs:string* := () | + | $permissions as xs:string* := (), |
− | $patterns as xs:string* := () | + | $patterns as xs:string* := (), |
$info as element(info) := () | $info as element(info) := () | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 165: | Line 165: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:grant( | |<pre>user:grant( | ||
− | $name as xs:string | + | $name as xs:string, |
− | $permissions as xs:string* | + | $permissions as xs:string*, |
$patterns as xs:string* := () | $patterns as xs:string* := () | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 188: | Line 188: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:drop( | |<pre>user:drop( | ||
− | $name as xs:string | + | $name as xs:string, |
$patterns as xs:string* := () | $patterns as xs:string* := () | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 210: | Line 210: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:alter( | |<pre>user:alter( | ||
− | $name as xs:string | + | $name as xs:string, |
$newname as xs:string | $newname as xs:string | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 231: | Line 231: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:password( | |<pre>user:password( | ||
− | $name as xs:string | + | $name as xs:string, |
$password as xs:string | $password as xs:string | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> | ||
Line 252: | Line 252: | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
|<pre>user:update-info( | |<pre>user:update-info( | ||
− | $info as element(info) | + | $info as element(info), |
$name as xs:string := () | $name as xs:string := () | ||
) as empty-sequence()</pre> | ) as empty-sequence()</pre> |
Revision as of 16:18, 9 March 2023
This XQuery Module contains functions for creating and administering database users. The User Management article provides more information on database users and permissions.
Contents
Conventions
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
user:current
Signature | user:current() as xs:string |
Summary | Returns the name of the currently logged-in user. |
Examples |
|
user:list
Signature | user:list() as xs:string* |
Summary | Returns the names of all registered users who are visible to the current user. |
Examples |
|
user:list-details
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 |
<syntaxhighlight lang="xml"> <user name="admin" permission="admin"> <password algorithm="digest"> <hash>304bdfb0383c16f070a897fc1eb25cb4</hash> </password> <password algorithm="salted-sha256"> <salt>871602799292195</salt> <hash>a065ca66fa3d6da5762c227587f1c8258c6dc08ee867e44a605a72da115dcb41</hash> </password> </user> </syntaxhighlight> |
Errors | unknown : The specified username is unknown.
|
user:exists
Signature | user:exists( $name as xs:string ) as xs:boolean |
Summary | Checks if a user with the specified $name exists.
|
Examples |
|
Errors | name : The specified username is invalid.
|
user:check
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 |
|
Errors | name : The specified username is invalid.unknown : The specified user does not exist.password : The specified password is wrong. |
user:info
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 |
|
Updates
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
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 :
|
Examples |
|
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
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 |
|
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
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 |
|
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
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 |
|
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
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 |
|
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
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 |
<syntaxhighlight lang="xquery"> user:update-info(element info { for $group in ('editor', 'author', 'writer') return element group { $group } }) </syntaxhighlight>
<syntaxhighlight lang="xquery"> user:update-info(<info group='editor'/>, 'john') </syntaxhighlight> |
Errors
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
- Version 8.6
- Updated:
user:create
,user:info
,user:update-info
:$name
parameter added.
- Version 8.6
- Added:
user:check
,user:info
,user:update-info
. - Updated:
user:list
,user:list-details
: If called by non-admins, will only return the current user.
- Version 8.4
- Updated:
user:create
,user:grant
,user:drop
: extended support for database patterns.
- Version 8.1
- Added:
user:current
.
The Module was introduced with Version 8.0.