Difference between revisions of "User Module"

From BaseX Documentation
Jump to navigation Jump to search
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the {{Code|http://basex.org/modules/user}} namespace, which is statically bound to the {{Code|user}} prefix.<br/>
+
All functions in this module and errors are assigned to the {{Code|http://basex.org/modules/user}} namespace, which is statically bound to the {{Code|user}} prefix.<br/>
−
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
 
=Functions=
 
=Functions=
Line 64: Line 63:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
−
|{{Error|BXUS0001|#Errors}} The specified user name is invalid.
+
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|}
 +
 
 +
==user:create==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{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, $permission as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Creates a new user with the specified {{Code|$name}} and {{Code|$password}}. The default permission {{Code|none}} can be overwritten with the {{Code|$permission}} argument. Existing users will be overwritten.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions.
 +
|-
 +
| '''Errors'''
 +
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|{{Error|permission|#Errors}} The specified permission is invalid.
 +
|{{Error|admin|#Errors}} The "admin" user cannot be modified.
 +
|{{Error|logged-in|#Errors}} The specified user is currently logged in.
 +
|{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 +
|}
 +
 
 +
==user:grant==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|user:grant|$name as xs:string, $permission as xs:string|empty-sequence()}}<br/>{{Func|user:grant|$name as xs:string, $permission as xs:string, $pattern as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Grants the specified {{Code|$permission}} to a user with the specified {{Code|$name}}. If a glob {{Code|$pattern}} is specified, the permission will only be applied to databases matching that pattern.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'.
 +
* {{Code|user:grant('John', 'write', 'unit*')}} allows John to write to all databases starting with the letters 'unit'.
 +
|-
 +
| '''Errors'''
 +
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|{{Error|pattern|#Errors}} The specified database pattern is invalid.
 +
|{{Error|permission|#Errors}} The specified permission is invalid.
 +
|{{Error|admin|#Errors}} The "admin" user cannot be modified.
 +
|{{Error|local|#Errors}} A local permission can only be 'none', 'read' or 'write'.
 +
|{{Error|logged-in|#Errors}} The specified user is currently logged in.
 +
|{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 +
|}
 +
 
 +
==user:drop==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|user:drop|$name as xs:string|empty-sequence()}}<br/>{{Func|user:drop|$name as xs:string, $pattern as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Drops a user with the specified {{Code|$name}}. If a glob {{Code|$pattern}} is specified, only the database pattern will be dropped.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{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.
 +
|-
 +
| '''Errors'''
 +
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|{{Error|pattern|#Errors}} The specified database pattern is invalid.
 +
|{{Error|admin|#Errors}} The "admin" user cannot be modified.
 +
|{{Error|logged-in|#Errors}} The specified user is currently logged in.
 +
|{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 +
|{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
 +
|}
 +
 
 +
==user:alter==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|user:alter|$name as xs:string, $newname as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Renames a user with the specified {{Code|$name}} to {{Code|$newname}}.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|user:rename('John', 'Jack')}} renames the user 'John' to 'Jack'.
 +
|-
 +
| '''Errors'''
 +
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|{{Error|admin|#Errors}} The "admin" user cannot be modified.
 +
|{{Error|logged-in|#Errors}} The specified user is currently logged in.
 +
|{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 +
|{{Error|conflict|#Errors}} A user cannot be both altered and dropped.
 +
|}
 +
 
 +
==user:password==
 +
 
 +
{| width='100%'
 +
|-
 +
| width='120' | '''Signatures'''
 +
|{{Func|user:password|$name as xs:string, $password as xs:string|empty-sequence()}}
 +
|-
 +
| '''Summary'''
 +
|Changes the {{Code|password}} of a user with the specified {{Code|$name}}.
 +
|-
 +
| '''Examples'''
 +
|
 +
* {{Code|user:password('John', '')}} assigns user 'John' an empty password string.
 +
|-
 +
| '''Errors'''
 +
|{{Error|name|#Errors}} The specified user name is invalid.
 +
|{{Error|update|#Errors}} The operation can only be performed once per user or database pattern.
 
|}
 
|}
  
Line 73: Line 184:
 
|Description
 
|Description
 
|-
 
|-
−
|{{Code|BXUS0001}}
+
|{{Code|name}}
 
|The specified user name is invalid.
 
|The specified user name is invalid.
 
|-
 
|-
−
|{{Code|BXUS0002}}
+
|{{Code|pattern}}
 
|The specified database name is invalid.
 
|The specified database name is invalid.
 
|-
 
|-
−
|{{Code|BXUS0003}}
+
|{{Code|permission}}
 
|The specified permission is invalid.
 
|The specified permission is invalid.
 
|-
 
|-
−
|{{Code|BXUS0004}}
+
|{{Code|unknown}}
 
|The specified user does not exist.
 
|The specified user does not exist.
 
|-
 
|-
−
|{{Code|BXUS0005}}
+
|{{Code|admin}}
 
|The "admin" user cannot be modified.
 
|The "admin" user cannot be modified.
 
|-
 
|-
−
|{{Code|BXUS0006}}
+
|{{Code|equal}}
 
|Name of old and new user is equal.
 
|Name of old and new user is equal.
 
|-
 
|-
−
|{{Code|BXUS0007}}
+
|{{Code|local}}
 
|A local permission can only be 'none', 'read' or 'write'.
 
|A local permission can only be 'none', 'read' or 'write'.
 
|-
 
|-
−
|{{Code|BXUS0008}}
+
|{{Code|logged-in}}
−
|A specified user is currently logged in.
+
|The specified user is currently logged in.
 
|-
 
|-
−
|{{Code|BXUS0009}}
+
|{{Code|update}}
−
|A user, or its associated permission, can only be created, modified or dropped once.
+
|The operation can only be performed once per user or database pattern.
 
|-
 
|-
−
|{{Code|BXUS0010}}
+
|{{Code|conflict}}
 
|A user cannot be both altered and dropped.
 
|A user cannot be both altered and dropped.
 
|}
 
|}

Revision as of 00:44, 11 December 2014

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

Conventions

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

Functions

user:list

Signatures user:list() as xs:string*
Summary Returns the names of all registered users.
Examples
  • user:list() returns all registered users.

user:list-details

Signatures user:list-details() as element(user)*
Summary Returns an element sequence, containing all registered users and their permissions.
In addition to the SHOW USERS, encoded password strings and database permissions will be output.
Examples
  • By default, user:list-details() returns the following output:
<user name="admin" permission="admin">
  <password algorithm="digest">
    <hash>304bdfb0383c16f070a897fc1eb25cb4</hash>
  </password>
  <password algorithm="salted-sha256">
    <salt>871602799292195</salt>
    <hash>a065ca66fa3d6da5762c227587f1c8258c6dc08ee867e44a605a72da115dcb41</hash>
  </password>
</user>

user:exists

Signatures 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 user name is invalid.

user:create

Signatures user:create($name as xs:string, $password as xs:string) as empty-sequence()
user:create($name as xs:string, $password as xs:string, $permission as xs:string) as empty-sequence()
Summary Creates a new user with the specified $name and $password. The default permission none can be overwritten with the $permission argument. Existing users will be overwritten.
Examples
  • user:create('John', '7e$j#!1', 'admin') creates a new user 'John' with admin permissions.
Errors name: The specified user name 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

Signatures user:grant($name as xs:string, $permission as xs:string) as empty-sequence()
user:grant($name as xs:string, $permission as xs:string, $pattern as xs:string) as empty-sequence()
Summary Grants the specified $permission to a user with the specified $name. If a glob $pattern is specified, the permission will only be applied to databases matching that pattern.
Examples
  • user:grant('John', 'create') grants create permissions to the user 'John'.
  • user:grant('John', 'write', 'unit*') allows John to write to all databases starting with the letters 'unit'.
Errors name: The specified user name 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

Signatures user:drop($name as xs:string) as empty-sequence()
user:drop($name as xs:string, $pattern as xs:string) as empty-sequence()
Summary Drops a user with the specified $name. If a glob $pattern is specified, only the database pattern will be dropped.
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 name: The specified user name 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

Signatures 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:rename('John', 'Jack') renames the user 'John' to 'Jack'.
Errors name: The specified user name 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

Signatures 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 name: The specified user name is invalid. update: The operation can only be performed once per user or database pattern.

Errors

Code Description
name The specified user name is invalid.
pattern The specified database name is invalid.
permission The specified permission is invalid.
unknown The specified user does not exist.
admin The "admin" user cannot be modified.
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.
update The operation can only be performed once per user or database pattern.
conflict A user cannot be both altered and dropped.

Changelog

The Module was introduced with Version 8.0.

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