Upgrading to BaseX 13

This article summarizes the changes that may require adjustments when migrating existing projects from BaseX 12. Details are given in the linked articles, the highlights of the release are presented in BaseX 13, and all additions and updates are listed in the Changelog.

Critical Changes

The following changes can prevent BaseX from starting or clients from connecting, or change results without raising an error. Most other changes raise errors that point to the required adjustment.

• Java: Java 21 or later is required (see Startup).
• Configuration: Existing .basex files are no longer rewritten: old values of PARALLEL and HTTPLOCAL remain effective (see Configuration).
• Server: basexhttp no longer starts a database server on port 1984 (see Server and Clients).
• Clients: Clients of BaseX 8 to 12 cannot connect, and users with digest hashes can no longer log in (see Server and Clients).
• Web application: A Jakarta EE 10 servlet container is required, and RESTXQ results other than a single element are sent as text/plain (see Server and Clients).
• Downgrades: Databases written by BaseX 13 may be rejected by BaseX 12 (see Compatibility).
• Databases: STRIPWS preserves whitespace in mixed content, and db:create and related functions ignore options assigned with SET or in .basex (see Databases).
• Options: Boolean options must be booleans: fn:serialize($data, { 'indent': 'no' }) raises an error (see Functions).
• External resources: DTDs, entities, XInclude documents and schemas are only fetched if TRUSTEXTERNAL is enabled (see Functions).
• Results: http:send-request returns lower-case header names, the XHTML method serializes HTML5, and dates without timezone may shift by an hour (see Functions, Serialization and Language).

Configuration

• Entries of an existing .basex file take precedence over the new defaults: remove them, or delete the file to have a new one created. Removed local options (e.g. SPLITSIZE) are reported on every start until they are removed.
• A .basex or .basexhome file in an ancestor of the user directory may now determine the home directory (see Configuration).

Databases

Compatibility

Databases created with BaseX 12 can be opened with BaseX 13, including their index structures, and vice versa. BaseX 12 rejects a database in the following cases:

• Updated indexes: With UPDINDEX, which is now enabled by default, larger updates of indexed databases (beyond 100,000 nodes) are stored in a new index format. Optimize the database with OPTIMIZE or db:optimize to make it readable again, or disable the option (see Updates).
• Mixed content: The new FTMIXED option is enabled and a full-text index exists. Drop the index, or disable the option and optimize the database.
• Namespaces: The namespace structure has more than 4,096 entries. Such structures are stored in a compact format.

Changes

• db:create, db:add, db:put, db:optimize, fetch:doc: Options are taken from $options, option declarations and pragmas, but no longer from SET or .basex (see Create Options).
• STRIPWS preserves whitespace in mixed content, UPDINDEX is enabled by default, and PARALLEL defaults to 32.
• Various options were removed, e.g. MIXUPDATES, ADDCACHE, FORCECREATE and CHECKSTRINGS (see Options).
• db:put and related functions only replace the resource at the specified path.
• Full-text terms with characters such as ß or æ are only found after the index has been rebuilt (see Full-Text Index).

Server and Clients

• Server: Start basexhttp with -L or disable HTTPLOCAL if Clients need to connect on port 1984. Servers can only be stopped from the same host, with the binaries of the same version.
• Authentication: The Server Protocol uses salted authentication: third-party bindings must be updated, and clients of version 13 cannot connect to older servers. HTTP Digest authentication, the XML:DB API and the outdated clients were removed (see User Management).
• Permissions: CREATE was merged into ADMIN, and more functions and options require ADMIN (see User Management).
• Web Server: Jakarta EE 10 containers are supported, such as Tomcat 10.1, Jetty 12 or WildFly 27. Compare a custom web.xml with the one of the distribution; jetty.xml is optional, and the port is specified with HTTPPORT. Session cookies are sent with SameSite=Lax (see Web Application).
• RESTXQ: Results without media-type and method are only sent as application/xml if they are a single element; add %output:media-type to keep the old type. Server-side forwarding was dropped, and unmatched requests and permission errors are answered with specific status codes (see RESTXQ).
• WebSockets: %ws:header-param was removed, error messages are only sent by %ws:error functions, and connections are closed with their HTTP session (see WebSockets).

Language

The implementation follows the latest drafts of XQuery 4.0:

• Records have a fixed set of fields (no field? or *), declared record types are nominative, and built-in record types have no constructor functions.
• gnode() was removed: node() matches XML nodes and JNodes, and xnode() XML nodes only. Values with multiple items are represented by a separate JNode.
• The %method annotation was replaced by =?>, and the map and array filter, the nondeterministic prefix and the regular expression flags j, ! and ; were removed.
• Dates and times without timezone are adjusted with the implicit timezone: results may shift by an hour.

Functions

• Boolean options must be booleans: use { 'indent': false() } instead of { 'indent': 'no' }.
• External DTDs, entities, XInclude documents and schemas are only fetched if the trust-external option or TRUSTEXTERNAL is enabled, and modules loaded with fn:load-xquery-module are untrusted by default.
• Renamed or removed: fn:sequence-join → fn:insert-separator, fn:csv-to-arrays → fn:parse-csv, map:pairs → map:entries, map:of-pairs → map:build, hof:scan-left → fn:scan, convert:dayTime-to-integer → fn:duration-to-seconds, convert:binary-to-string → Binary Functions, string:format → fn:pad-string, and more. The Higher-Order Functions Module and web:forward were removed (see Changelog).
• Options and parameters of various functions were renamed or removed, e.g. in the CSV Functions, JSON Functions and File Functions.
• Results change for http:send-request (lower-case header names, fewer redirects), ft:thesaurus (one level), using fuzzy 0 errors (exact matching), fn:decode-from-uri (plus signs), file:delete (missing paths), CSV parsing (quotes in unquoted fields) and Cache Functions (expiry after 24 hours).
• job:execute: Jobs may only read databases that are read-locked by the calling query.

Serialization

• The xhtml method serializes HTML5 by default; specify html-version to get the old output.
• The custom parameters indents, newline and tabulator were removed: use indent-unit and line-ending.
• The adaptive method outputs doubles as JSON numbers, and the output of fn:trace is dropped for users without ADMIN permission.

Graphical User Interface

Only a single GUI instance is opened per project directory, the fullscreen mode and the editing of nodes in the visualizations were removed, and the Map view is disabled by default (see Graphical User Interface).