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 150 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
dbasubdirectory can simply be copied and moved to any other place. 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
adminuser, 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
On the welcome page, you need to authenticate yourself by entering the name and password of a user with admin permissions; other users are rejected. Logins and logouts are written to the database logs.
Two keyboard shortcuts are available on all pages: / jumps to the search field of the current panel, Esc clears the status message.
All views are split into panels. A panel can be collapsed to a narrow strip by clicking the arrow in its upper right corner, and a panel that has nothing to show is hidden.
Logs
All database logs are listed, ordered by creation time in descending order. For each day, a new log file is created. Old log files can be selected, 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; the Ignore field hides entries that match the supplied expression (e.g. /dba for the requests caused by the DBA itself).
If Live is ticked, the entries are reloaded repeatedly. As a search may take longer than the interval, the next one is started one second after the last result was received.
Databases
Updated: The Databases view shows databases, resources, backups and properties side by side; the former Database page has been dropped.
The first panel lists all databases. They can be created, optimized, dropped, backed up and restored; the options that are assigned when a database is created or optimized are edited in a dialog.
If a database is selected, it can be renamed and copied, and its resources are listed in the next panel. Resources can be added, renamed, downloaded, replaced by an upload and deleted.
If a single resource is selected, its contents are displayed:
- XML documents can be edited and saved back to the database.
- Queries can be run on the resource, which is bound to the query context.
- Documents that exceed the maximum output size (see Settings) are truncated and read-only; the full contents can be downloaded.
The Backups panel offers the backups of all databases, including those of databases that no longer exist, and, if a database is selected, its own backups. Backups can be created, restored, uploaded and dropped, and they are downloaded by clicking their name. A backup that is uploaded for a single database must be named after it.
The Information panel lists the properties and the index structures of the selected database.
The selection is part of the address, so a database and a resource can be bookmarked and linked to. The panels themselves are refreshed via WebSockets, and an edited document survives a new selection.
Files
Added: The Files view combines the former Editor and Files pages.
The Files 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. The panels can be resized by dragging the space in between; their sizes are remembered by the browser.
Queries are run as jobs: Run starts the evaluation, Stop terminates it, and the result is pushed to the browser via WebSockets as soon as it is available. Evaluation is also stopped if it takes too long or consumes too much memory (see Settings). Inside the editor area, Ctrl-Enter (Cmd-Enter on macOS) runs the query as well. Job opens the running query in the Activity view; if Ctrl is pressed, it is opened in a new browser tab. 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.
Files are opened by clicking their name. The directory of the opened file becomes the static base URI of the query. Unsaved changes are preserved in the browser and restored when the file is opened again.
Several files can be open at the same time, each with its own tab, directory and undo history. New adds an empty tab. A dot marks unsaved changes; closing such a tab asks whether they are to be saved or discarded. Save writes the file back, Save as stores it under another name. The open files are remembered by the browser and restored on the next visit.
The file list can be sorted by name, date and size. Files can be downloaded, deleted and uploaded, and new directories can be created. If more than one file is selected, the files are downloaded as a ZIP archive that is named after the current directory.
The directory can be chosen from a list of relevant locations: the DBA directory, the webapp, RESTXQ and repository directories, the BaseX home, working and temporary directory, and the file system roots.
You can edit your RESTXQ code in real time by switching to the RESTXQ or repository directory and opening the corresponding modules.
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 every second via WebSockets. 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. The job that prepares your own HTTP response is not listed.
New… starts a job: the query is evaluated at once, or at the times that are supplied as start, end, interval or cron expression. Its result can be cached, and its ID can be assigned. Relative paths in the query are resolved against the current file directory, as they are in the Files view. A job of the DBA is bound by the permission, timeout and memory limit of the Settings.
Register as service additionally persists the job as service. A service requires an ID, which is the handle for addressing it later, and it is not restricted by the settings: it outlives the session that registered it. The Service column marks the jobs that belong to a service. A service that has no job is dormant; it is listed as registered and will be scheduled again when the server is restarted.
If a job is selected, its properties, its query bindings and its job string are shown. The result of a cached job can be viewed and downloaded; as a result is dropped once it is fetched, the job is closed by the download. The details of a running job are updated as long as it runs. Remove gives up a registered job, Unregister deletes the definition of a service.
The query of a service is shown as it was stored, and can be edited and stored back with Replace, which keeps the schedule. The query is parsed before the service is registered anew, so a typo will not cost the registration.
The Web Sessions table lists all users that are currently registered in an application or the DBA. Single sessions can be killed. See the DBA RESTXQ code for information about how clients can be registered and logged out.
The Database Sessions table 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 and how often they were of use. Single caches can be deleted, and all of them cleared.
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.
The first panel lists all stores with the number of entries they hold, their size, and the time they were last written to disk. The store that is addressed by no name is listed as (default). As a store that holds nothing does not exist, New asks for a name and the first entry right away. Delete removes the checked stores, Clear All removes all of them.
If a store is selected, its entries are listed with their key, a preview of their value, and the type of the value. Add stores a new entry: its key and its value are XQuery expressions, evaluated with the permission, timeout and memory limit of the Settings. A map is keyed by any atomic value, so 1 yields the integer and "1" the string; an entry of a store is named by a string. An entry that already exists is never replaced; a value is overwritten in the value panel. Remove deletes the checked entries. Write persists the store to disk, Read restores it from there, and Close drops it from memory.
A value that holds further values can be opened with the marker next to it: its children become the level that is listed, and the path that leads there is shown below the table. The children of a map are its keys, those of an array or a sequence their positions. A new child of an array or a sequence is appended, so no position is asked for.
The value of the selected entry is shown as the expression that yields it again, so that it can be edited and stored back with Replace. Values that exceed the maximum output size (see Settings) are truncated and read-only, and so are values whose path does not consist of strings and integers alone: a key of another type can only be addressed by its position, which no update can rely on.
The selection is part of the address, so a store, a level and an entry can be bookmarked and linked to. The panels are refreshed via WebSockets.
Users
Updated: The Users view shows users and their permissions side by side; the former User page has been dropped.
The first panel lists all users; they can be created and dropped. If a user is selected, its password and its global permission can be changed, and the local permissions that overwrite the global one for single databases are listed in a panel of their own.
Extra information can be attached to all users and to a single user (see User Management for more information).
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. |
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, Files, Activity, CodeMirror 6, use of WebSockets.
- Updated: Queries panel replaced with the Editor panel, which can edit arbitrary files.
- Updated: Logging was improved for millions of log entries
- Updated: Always accessible, even if job queue is full
- Removed: Remote connections (to allow for better optimizations and less locking)
- Added: Editor: Key combination 'Shift-Ctrl-Enter', real time mode removed.
- Added: Web-based Database Administration added.