BaseX is a high-performance, open-source XML database and XQuery processor designed for storing, querying, and managing structured data efficiently. It provides a lightweight engine, powerful indexing features, and a rich set of tools for working with XML. With its built-in GUI, command-line client, and REST API, BaseX makes it easy for us to explore data, run complex queries and integrate XML processing into applications. In this article, we walk through the fundamentals of BaseX and demonstrate how to manage and interact with databases using both commands and the REST API.
1. What Is BaseX?
BaseX is an XML-native database built on W3C standards such as XQuery 3.1 for querying and XPath 3.1 for navigation. Its storage system is optimized for hierarchical documents, making tasks like indexing, slicing, and deep navigation very fast. BaseX also provides a lightweight server, a graphical user interface, and both a REST API and the RESTXQ framework for building web services.
1.1 Why Use BaseX?
- High Performance: BaseX uses compact data structures and advanced indexing strategies (text, attribute, full-text, and path indexes), making queries run significantly faster than traditional relational approaches for hierarchical data.
- Standards-Compliant: It follows W3C specifications for XQuery, which ensures portability and compatibility with existing XML technologies.
- Lightweight and Easy to Set Up: BaseX can be installed quickly and runs on all major platforms. The standalone server is small but powerful.
- Flexible APIs: Developers can work with BaseX using several options, including the Java API, REST and HTTP endpoints, RESTXQ annotations, the command-line client, WebSockets, and the XQJ driver.
2. Installing BaseX
You can download BaseX from the official website by choosing the ZIP file or installer for your operating system. The only requirement is Java 17 or later, preferably from Adoptium. If you download the ZIP version, the bin folder contains several startup scripts, and the one you choose depends on how you plan to use BaseX. All scripts require a working Java installation on your machine.
We can test BaseX on Windows by double-clicking the BaseX.jar file in the main folder, which starts the application right away. On a Mac, after installing BaseX, we can start the database server by running the following command in the terminal:
./bin/basex
Output:
/Path/to/Download/basex/.basex: writing new configuration file. BaseX 12.0 [Standalone] Try 'help' to get more information. >
3. Creating a Database
After installing BaseX, we can create and manage databases using the command-line client or the GUI. We will create a small library dataset for hands-on querying by adding a new file named library.xml.
<library>
<book id="b1" category="fiction">
<title>Poor Richard's Almanack</title>
<author>Benjamin Franklin</author>
<year>1732</year>
<price>39.95</price>
</book>
<book id="b2" category="technology">
<title>Mastering Jakarta Faces</title>
<author>Omos Aziegbe</author>
<year>2025</year>
<price>29.50</price>
</book>
<book id="b3" category="philosophy">
<title>The Age of Reason</title>
<author>Thomas Paine</author>
<year>1794</year>
<price>54.10</price>
</book>
</library>
Using Command Line
CREATE DATABASE LibraryDB /path/to/library.xml
Output:
> CREATE DATABASE LibraryDB /path/to/library.xml Database 'LibraryDB' created in 62.14 ms.
Below are essential commands commonly used when working with databases, collections, and files.
Listing Existing Databases (LIST)
The LIST command shows all databases that currently exist in your BaseX installation. This is useful for confirming that your database was created successfully or for checking the available databases before performing operations.
> LIST Name Resources Size Input Path -------------------------------------------------------------- LibraryDB 1 5974 /Users/omozegieaziegbe/library.xml 1 database(s).
The output displays a list of all databases along with basic information such as their size and input path.
Creating and Opening a Database (OPEN)
Once we have created a database (e.g., LibraryDB), we must open it before performing operations. The OPEN command loads the database into the current session.
> OPEN LibraryDB Database 'LibraryDB' was opened in 2.35 ms.
Checking Database Information (INFO)
After opening a database, we can inspect its structure and configuration using the INFO DATABASE command. This is useful for understanding how our data is stored and which indexes are active.
> INFO DATABASE Database Properties NAME: LibraryDB SIZE: 5974 b NODES: 54 DOCUMENTS: 1 BINARIES: 0 VALUES: 0 TIMESTAMP: 2025-11-16T14:26:35.764Z UPTODATE: true Resource Properties INPUTPATH: /Users/omozegieaziegbe/library.xml INPUTSIZE: 538 b INPUTDATE: 2025-11-16T14:25:57.949Z Indexes TEXTINDEX: true ATTRINDEX: true TOKENINDEX: false FTINDEX: false TEXTINCLUDE: ATTRINCLUDE: TOKENINCLUDE: FTINCLUDE: LANGUAGE: English STEMMING: false CASESENS: false DIACRITICS: false STOPWORDS: UPDINDEX: false AUTOOPTIMIZE: false MAXCATS: 100 MAXLEN: 96 SPLITSIZE: 0
The output displays metadata such as the number of documents, nodes, sizes, and available indexes, helping us understand the internal state of the database.
Adding Documents to the Database (ADD)
If our database is empty or we want to expand it, we can insert new XML files using ADD. This command loads one or more files into the active database.
> ADD /Users/omozegieaziegbe/authors.xml Resource(s) added in 86.19 ms.
After running this command, the authors.xml file is added to the active database as a separate document. It becomes available for queries, and we can now combine data from both library.xml and authors.xml in our XQuery expressions.
Viewing Files Inside the Database (DIR)
To inspect what documents or folders exist inside the database, use the DIR command.
> DIR Input Path Type Content-Type Size ---------------------------------------- authors.xml xml application/xml 33 books xml application/xml 33 library.xml xml application/xml 54 3 entries.
The output lists all documents and directories, giving us an overview of the database structure and confirming the placement of recently added files.
Deleting Files from the Database (DELETE)
If a document is no longer needed, we can remove it using the DELETE command.
> DELETE books 1 resource(s) deleted in 6.55 ms.
This permanently removes the specified file from the database storage.
Removing a Database (DROP DATABASE)
When a full database is no longer required, we can delete it entirely using DROP DATABASE.
> DROP DATABASE LibraryDB
Once executed, the database is completely removed and will no longer appear when we run LIST.
Running Queries from the Command Line (XQUERY)
We can run XQuery expressions directly in the terminal without opening the GUI. The XQUERY command is useful for quick checks and automation scripts.
> XQUERY //book/title <title>Poor Richard's Almanack</title> <title>Mastering Jakarta Faces</title> <title>The Age of Reason</title> Query "basex" executed in 2530.96 ms.
4. Working with the REST API in BaseX
The BaseX REST API allows us to interact with our databases over HTTP. This makes it possible to list databases, query data, create or modify content, and delete resources using standard HTTP verbs such as GET, PUT, and DELETE.
Starting the HTTP Server
The BaseX HTTP server enables REST-based interaction, exposing endpoints through which we can manage and query our databases. We must start this server before we can use any REST features.
./bin/basexhttp
After running this command, the HTTP server begins listening on port 8080, allowing clients and tools such as Curl, Postman, and browsers to access the REST interface.
Output:
BaseX 12.0 [HTTP Server]
[main] INFO org.eclipse.jetty.server.Server - jetty-12.0.22; built: 2025-06-02T15:25:31.946Z; git: 335c9ab44a5591f0ea941bf350e139b8c4f5537c; jvm 21.0.2+13-58
[main] INFO org.eclipse.jetty.ee9.webapp.StandardDescriptorProcessor - NO JSP Support for /, did not find org.eclipse.jetty.ee9.jsp.JettyJspServlet
[main] INFO org.eclipse.jetty.session.DefaultSessionIdManager - Session workerName=node0
Server was started (port: 1984).
[main] INFO org.eclipse.jetty.server.handler.ContextHandler - Started oeje9n.ContextHandler$CoreContextHandler@36b4091c{BaseX: The XML Database and XQuery Processor,/,b=file:///Users/pathto/Downloads/basex/webapp/,a=AVAILABLE,h=oeje9n.ContextHandler$CoreContextHandler$CoreToNestedHandler@4671115f{STARTED}}
[main] INFO org.eclipse.jetty.server.AbstractConnector - Started ServerConnector@21ba0741{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
[main] INFO org.eclipse.jetty.server.Server - Started oejs.Server@77fbd92c{STARTING}[12.0.22,sto=0] @6655ms
HTTP STOP Server was started (port: 8081).
HTTP Server was started (port: 8080).
Authentication and Password Management
The REST API uses HTTP Basic Authentication, requiring a username and password. BaseX ships with a default username admin. BaseX logs authentication details inside its internal log directory. We can inspect these logs to find the password that was generated.
If we need to recover the current password, we can locate it in the BaseX log files. Navigate to the data/.logs directory within your BaseX installation to find the appropriate log file for the date in question. From the BaseX installation or downloaded directory, execute a command like this:
cat data/.logs/2025-11-16.log
This displays the contents of the log file, where entries may include login information or previously set passwords.
17:11:04.100 SERVER admin OK Server was started (port: 1984). 17:11:04.253 SERVER admin INFO Initial admin password (change after first login): e3f8f14a-b4d2-49f6-9e65-162a4d90689e 17:11:04.495 SERVER admin OK HTTP Server was started (port: 8080).
After identifying the password, we can use it for REST API calls or update it with the PASSWORD command.
Command to Change the Password
PASSWORD newpassword
Running this command updates the password for the current user, and all REST calls must use this new value.
Listing Databases via the REST Endpoint
We can retrieve a list of all available databases through an HTTP GET request to the /rest endpoint. This is useful for verifying which databases exist on the server.
curl -u admin:e3f8f14a-b4d2-49f6-9e65-162a4d90689e http://localhost:8080/rest
This request returns an XML list of all databases stored on the server. The output is:
<databases xmlns="http://basex.org/rest"> <database resources="2" size="6190">LibraryDB</database> </databases>
Accessing a Specific Database
To view the contents of a particular database, include its name directly in the request URL. In our case, we will inspect the LibraryDB.
curl -u admin:e3f8f14a-b4d2-49f6-9e65-162a4d90689e http://localhost:8080/rest/LibraryDB
This returns the documents stored inside LibraryDB, such as library.xml and authors.xml.
<database xmlns="http://basex.org/rest" name="LibraryDB"> <resource type="xml" content-type="application/xml" size="33">authors.xml</resource> <resource type="xml" content-type="application/xml" size="54">library.xml</resource> </database>
Running Simple Queries Using URL Parameters
The REST API allows us to evaluate XQuery expressions directly by passing them through the query parameter. This makes it easy to test small expressions without writing full scripts.
curl -u admin:e3f8f14a-b4d2-49f6-9e65-162a4d90689e http://localhost:8080/rest/LibraryDB?query=//book/title
This returns the titles of all books in LibraryDB, demonstrating how quick inline queries can be executed via REST calls.
<title>Poor Richard's Almanack</title> <title>Mastering Jakarta Faces</title> <title>The Age of Reason</title>
Creating or Updating Resources
The REST API allows us to create or update documents by sending XML content to a specific resource path.
curl -u admin:newpassword -X PUT -H "Content-Type: application/xml" \
-d '<note><text>New resource created via REST</text></note>' \
http://localhost:8080/rest/LibraryDB/note.xml
After this request, a new file named note.xml is stored inside LibraryDB, or an existing one is updated.
Deleting Resources Using the DELETE Method
Deleting a resource is done by sending a DELETE request to its path.
curl -u admin:e3f8f14a-b4d2-49f6-9e65-162a4d90689e -X DELETE http://localhost:8080/rest/LibraryDB/note.xml
This removes note.xml from the LibraryDB database.
Beyond the basics covered here, you can explore more advanced BaseX topics such as indexing strategies for faster queries, writing modular XQuery applications and using RESTXQ for building full HTTP APIs.
5. Conclusion
In this article, we introduced BaseX, worked with XML data, explored essential database commands, and learned how to interact with databases through the REST API using GET, PUT and DELETE operations. We also covered how to start the HTTP server, manage authentication, recover passwords, run queries, and handle XML resources.
This article gave a basic introduction to BaseX and its use with XML.
