Difference between revisions of "Admin Module"

From BaseX Documentation
Jump to navigation Jump to search
(Created page with "This XQuery Module contains functions for performing operations that are restricted to users with |Admin Permissions. Existing users can be...")
 
 
(71 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
This [[Module Library|XQuery Module]] contains functions for performing operations that are restricted to users with [[User Management||Admin Permissions]]. Existing users can be listed, and soon more.
+
This [[Module Library|XQuery Module]] contains functions for performing admin-centric operations such as managing database users and log data.
  
 
=Conventions=
 
=Conventions=
  
−
All functions in this module are assigned to the {{Code|http://basex.org/modules/admin}} namespace, which is statically bound to the {{Code|admin}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/admin</nowiki></code> namespace, which is statically bound to the {{Code|admin}} prefix.<br/>
−
All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.
 
  
−
=Functions=
+
=Database Logs=
  
−
==admin:users==
+
==admin:logs==
−
{|
+
 
−
|-
+
{| width='100%'
−
| width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Func|admin:users||element(user)*}}<br/>{{Func|admin:users|$db as item()|element(user)*}}<br/>
+
| width='120' | '''Signature'''
−
|-
+
|<pre>admin:logs(
 +
  $date  as xs:string    := (),
 +
  $merge  as xs:boolean?  := false()
 +
) as element()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
|Returns an {{Code|element}} sequence, containing all registered users along with their access permissions.<br/>If a [[Database Module#Database Nodes|database node]] {{Code|$db}} is specified, users registered for a particular database will be returned.
+
|Returns [[Logging]] data compiled by the database or HTTP server:
−
|-
+
* If no argument is specified, a list of all log files will be returned, including the file size and date.
 +
* If a {{Code|$date}} is specified, the contents of a single log file will be returned.
 +
* If {{Code|$merge}} is set to true, related log entries will be merged. The merged representation may not be 100% correct, as log entries can be ambiguous.
 +
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
−
* {{Code|admin:users("factbook")}} returns all users that have particularly registered for the specified database.
+
* {{Code|admin:logs()}} may return <code><file size="834367"/>2015-01-23</file></code> if a single log file exists.
 +
* {{Code|admin:logs() ! admin:logs(.)}} lists the contents of all log files.
 
|}
 
|}
 +
 +
==admin:write-log==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>admin:write-log(
 +
  $message  as xs:string,
 +
  $type    as xs:string  := ()
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Writes a log {{Code|$message}} to the database logs, along with current user data (timestamp, username). An optional log {{Code|$type}} can be specified. If omitted, the log type is {{Code|INFO}}.<br/>If the function is called from a database client, the IP will be logged. Otherwise, the string {{Code|SERVER}} will be logged.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|type|#Errors}} Type string contains whitespaces.
 +
|}
 +
 +
==admin:delete-logs==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>admin:delete-logs(
 +
  $date  as xs:string
 +
) as empty-sequence()</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Deletes the log entries from the specified <code>$date</code>
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|today|#Errors}} Today's log file cannot be deleted.<br/>{{Error|delete|#Errors}} An error occurred while deleting a log file.
 +
|}
 +
 +
=Database Sessions=
 +
 +
==admin:sessions==
 +
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>admin:sessions() as element(session)*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
|Returns an element sequence with all currently opened database sessions, including the username, address (IP:port) and an optionally opened database.<br/>The output of this function and the {{Command|SHOW SESSIONS}} command is similar.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* {{Code|admin:sessions()}} may e.g. return <code><session user="admin" address="127.0.0.1:6286" database="factbook"/></code>
 +
|}
 +
 +
=Errors=
 +
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|- valign="top"
 +
|{{Code|delete}}
 +
|An error occurred while deleting a log file.
 +
|- valign="top"
 +
|{{Code|today}}
 +
|Today's log file cannot be deleted.
 +
|- valign="top"
 +
|{{Code|type}}
 +
|Type string contains whitespaces.
 +
|}
 +
 +
=Changelog=
 +
 +
;Version 9.2
 +
 +
* Updated: {{Function||admin:write-log}}: type string may contain more characters
 +
 +
;Version 9.0
 +
 +
* Updated: error codes updated; errors now use the module namespace
 +
 +
;Version 8.3
 +
 +
* Updated: {{Function||admin:write-log}}: optional log type added
 +
 +
;Version 8.2
 +
 +
* Added: {{Function||admin:delete-logs}}
 +
 +
;Version 8.0
 +
 +
* Added: {{Function||admin:write-log}}
 +
* Deleted: admin:users (renamed to {{Function|User|user:list-details}}).
 +
 +
;Version 7.8.2
 +
 +
* Updated: {{Function||admin:users}}: md5-encoded password added to output.
 +
* Updated: {{Function||admin:logs}}: represent name of log files as string value; {{Code|$merge}} argument added.
 +
 +
The Module was introduced with Version 7.5.

Latest revision as of 14:58, 18 September 2023

This XQuery Module contains functions for performing admin-centric operations such as managing database users and log data.

Conventions[edit]

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

Database Logs[edit]

admin:logs[edit]

Signature 
admin:logs(
  $date   as xs:string    := (),
  $merge  as xs:boolean?  := false()
) as element()*
Summary Returns Logging data compiled by the database or HTTP server:
  • If no argument is specified, a list of all log files will be returned, including the file size and date.
  • If a $date is specified, the contents of a single log file will be returned.
  • If $merge is set to true, related log entries will be merged. The merged representation may not be 100% correct, as log entries can be ambiguous.
Examples
  • admin:logs() may return <file size="834367"/>2015-01-23</file> if a single log file exists.
  • admin:logs() ! admin:logs(.) lists the contents of all log files.

admin:write-log[edit]

Signature 
admin:write-log(
  $message  as xs:string,
  $type     as xs:string  := ()
) as empty-sequence()
Summary Writes a log $message to the database logs, along with current user data (timestamp, username). An optional log $type can be specified. If omitted, the log type is INFO.
If the function is called from a database client, the IP will be logged. Otherwise, the string SERVER will be logged.
Errors type: Type string contains whitespaces.

admin:delete-logs[edit]

Signature 
admin:delete-logs(
  $date  as xs:string
) as empty-sequence()
Summary Deletes the log entries from the specified $date
Errors today: Today's log file cannot be deleted.
delete: An error occurred while deleting a log file.

Database Sessions[edit]

admin:sessions[edit]

Signature 
admin:sessions() as element(session)*
Summary Returns an element sequence with all currently opened database sessions, including the username, address (IP:port) and an optionally opened database.
The output of this function and the SHOW SESSIONS command is similar.
Examples
  • admin:sessions() may e.g. return <session user="admin" address="127.0.0.1:6286" database="factbook"/>

Errors[edit]

Code Description
delete An error occurred while deleting a log file.
today Today's log file cannot be deleted.
type Type string contains whitespaces.

Changelog[edit]

Version 9.2
Version 9.0
  • Updated: error codes updated; errors now use the module namespace
Version 8.3
Version 8.2
Version 8.0
Version 7.8.2
  • Updated: admin:users: md5-encoded password added to output.
  • Updated: admin:logs: represent name of log files as string value; $merge argument added.

The Module was introduced with Version 7.5.

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