DBA

The full distributions of BaseX are equipped with a browser-based database administration interface, the DBA. It allows you to create and administrate databases, run queries, view log files, monitor jobs and sessions, inspect stores, manage users, and more. The server-side code is completely written in XQuery and RESTXQ.

Updated: Queries are evaluated as jobs that can be stopped at any time, and the editor is based on CodeMirror 6.

These were our design goals:

• The code base is supposed to inspire and motivate you to develop your own RESTXQ web applications.
• The XQuery DBA code is very lean; it consumes less than 250 KB. Apart from the CodeMirror component that powers the editor, it uses plain and simple JavaScript and no framework.
• We tried to make the DBA features as self-explanatory as possible. All functionalities are also available via Commands, XQuery Functions or the Graphical User Interface.
• The DBA is shipped as dba.zip Web Archive, which can simply be copied and moved to any other place. It can be unpacked to a dba directory if you want to adapt the code. All URL paths point to the same directory; it should be straightforward to adjust the RESTXQ path.

If you put DBA online along with your web page, please ensure at the very least…

• that you have chosen a strong password for your admin user, and
• that the BaseX process has not been started with admin privileges.

Startup

• Download the ZIP Archive or the Windows Installer from the download page
• Start the BaseX HTTP Server
• Open a browser and visit the URL http://localhost:8080/dba

You need to authenticate yourself with a user that has admin permissions; other users are rejected, and logins and logouts are written to the database logs.

All views are split into panels, which can be collapsed and resized; the layout is remembered by the browser. Two keyboard shortcuts are available on all pages: / jumps to the search field of the current panel, Esc clears the status message.

Workspace

Added: The Workspace view combines the former Editor and Files pages.

The Workspace view is where files are managed and queries are written and evaluated. It shows the files of the current directory, the editor and the query result side by side:

• Queries are run as jobs and can be stopped at any time, or automatically if they take too long or consume too much memory (see Settings). Results are pushed to the browser via WebSockets.
• A query is not stopped if the browser is closed: it keeps running, and its result can be viewed and downloaded in the Activity view.
• The information of the last query (see job:info) can be displayed below the result. It is also available for a query that failed, which is where it is often most helpful.
• Several files can be open at the same time, each with its own tab, directory and undo history. Unsaved changes are preserved in the browser and restored on the next visit.
• Files can be sorted, uploaded, downloaded (several ones as a ZIP archive) and deleted, and new directories can be created.
• The directory can be chosen from a list of relevant locations, including the DBA, webapp, RESTXQ and repository directories. RESTXQ code can thus be edited in real time.

Databases

Updated: The Databases view shows databases, resources, backups and properties side by side; the former Database page has been dropped.

The Databases view lists all databases, the resources of the selected database, its backups, and its properties and index structures:

• Databases can be created, optimized, renamed, copied, dropped, backed up and restored. The options that are assigned when a database is created or optimized are edited in a dialog.
• A new database can be filled at once with a file, directory, archive or URL that is read by the server.
• Resources are listed one directory level at a time. They can be added, renamed, downloaded, replaced and deleted; uploads are stored as XML documents or as binary resources.
• The contents of a single resource are displayed in the last panel: XML documents can be edited and saved back to the database, and queries can be run on the resource, which is bound to the query context.
• Backups of all databases are offered, including those of databases that no longer exist. They can be created, restored, uploaded, downloaded and dropped.
• The selection is part of the address, so a database, a directory level and a resource can be bookmarked and linked to.

Stores

Added: The Stores view was added.

The Stores view shows the stores of the server: the stores themselves, the entries of the selected one, and the value that is looked at.

• Stores can be created and deleted, persisted to disk, restored from there, and dropped from memory.
• Entries are listed with their key, a preview of their value and its type. Keys and values are supplied as XQuery expressions, evaluated with the permission, timeout and memory limit of the Settings.
• A value that holds further values can be opened: the children of a map are its keys, those of an array or a sequence their positions.
• The selected value is shown as the expression that yields it again, so that it can be edited and stored back.
• The selection is part of the address, so a store, a level and an entry can be bookmarked and linked to.

Users

Updated: The Users view shows users and their permissions side by side; the former User page has been dropped.

Users can be created and dropped, their password and their global permission can be changed, and local permissions can be assigned that overwrite the global one for single databases. Extra information can be attached to all users and to a single user (see User Management for more information).

Logs

All database logs are listed, ordered by creation time in descending order. For each day, a new log file is created; old files can be downloaded and deleted.

The entries of the selected file are listed with time, address, user, type, runtime and text. Two filters are available: the search field matches users and texts via regular expressions and highlights the found substrings, and the Ignore field hides matching entries (e.g. /dba for the requests caused by the DBA itself). If Live is ticked, the entries are reloaded repeatedly.

Activity

Added: The Activity view combines the former Jobs and Sessions pages.

The Activity view shows what the server is currently doing, and for whom. If Live is ticked, its panels are refreshed via WebSockets (by default, every second; see Settings); as no HTTP requests are sent, the refresh causes no log entries.

• The Jobs panel lists all jobs that are currently running, queued or cached. You can view details on particular jobs, spot potential bottlenecks, or spot and terminate malicious requests.
• New jobs can be started at once or scheduled with start, end, interval or cron expressions, and their result can be cached, viewed and downloaded.
• A job can additionally be persisted as a service, which outlives the current session and is scheduled again when the server is restarted. The query of a service can be edited and stored back, keeping the schedule.
• The Web Sessions panel lists the attributes of all sessions that are currently registered in an application or the DBA. Attributes can be added, edited as XQuery expressions and deleted, and entire sessions can be invalidated.
• The WebSockets panel lists the attributes of all open connections, which can be edited in the same way; single connections can be closed.
• The Database Sessions panel shows clients that are connected via the client/server architecture.
• The Caches panel lists the caches of the server with the number of entries they hold, their limits and how often they were of use. Single caches can be deleted, and all of them cleared.

Settings

The following DBA options can be assigned. They are stored in a .dba.xml file in the .dba directory of the DBPATH directory:

Option	Description
Timeout	Maximum runtime of a query, in seconds (0 = disabled).
Memory limit	Maximum memory a query may consume, in MB (0 = disabled).
Maximum output size	Number of characters after which results and resources are truncated.
Permission	Permission with which queries are run.
Displayed table rows	Number of entries per page in the tables of the DBA.
Delay between requests	Refresh interval of live panels, in seconds (1–10).

In addition, all global and local database options, environment variables and Java system properties are listed, and a garbage collection can be enforced.

Changelog

Version 13.0

• Added: Stores view; Caches panel of the Activity view.
• Updated: Full redesign: side-by-side panels, Workspace, Activity, CodeMirror 6, use of WebSockets.

Version 11.0

• Updated: Queries panel replaced with the Editor panel, which can edit arbitrary files.

Version 9.4

• Updated: Logging was improved for millions of log entries

Version 8.6

• Updated: Always accessible, even if job queue is full
• Removed: Remote connections (to allow for better optimizations and less locking)

Version 8.4

• Added: Editor: Key combination 'Shift-Ctrl-Enter', real time mode removed.

Version 8.0

• Added: Web-based Database Administration added.