Main Page » Developer Section » Clients

Clients

This page describes how to communicate with BaseX from other programming languages.

To address a server from within XQuery, use the Client Module instead.

You can use the following light-weight language bindings to connect to a running BaseX server instance, execute database commands and evaluate XQuery expressions (see Usage below). The underlying protocol is described in the Server Protocol.

Available Bindings

  • Java: The default implementation
  • C++: contributed by Karim Salama (based on SDL2_net)
  • C++: contributed by Jean-Marc Mercier (based on libboost)
  • C++: contributed by Ben Engbers (built with CMake)
  • C#, contributed by the BaseX Team and Martín Ferrari
  • C, contributed by the BaseX Team
  • Golang: contributed by Christian Baune
  • Erlang: contributed by Zachary Dean
  • node.js: contributed by Andy Bunce
  • Perl, contributed by the BaseX Team
  • PHP: updated by James Ball
  • Python: contributed by Hiroaki Itoh
  • Python, using BaseX REST services: contributed by Luca Lianas
  • R: contributed by Ben Engbers
  • R: package by Ben Engbers
  • Raku: contributed by Wayland
  • Rust
  • Ruby, contributed by the BaseX Team
  • V, contributed by Erik Peterson

The bindings in the BaseX repository support the authentication of Version 13. Other bindings may need to be updated (see below).

Usage

Commands

Database commands are sent to the server with the execute() function of a session:

  1. Create a session with hostname, port, username and password.
  2. Call execute() with a database command. The result is returned as a string. If an error occurs, an exception is thrown.
  3. Optionally, call info() to get information on the executed command.
  4. Continue with step 2, or close the session with close().

Queries

The query() function of a session returns a query instance, which can be used to bind external variables and evaluate a query iteratively:

  1. Create a session, and call query() with an XQuery expression.
  2. Optionally, bind variables with bind(), and a context value with context().
  3. Iterate through the results with more() and next(), or call execute() to get the whole result at once.
  4. Optionally, call info() to get information on query evaluation, or options() to get the serialization parameters.
  5. Close the query with close().

The following PHP example is taken from our repository:

<?php
include_once 'load.php';

use BaseXClient\BaseXException;
use BaseXClient\Session;

try {
    // create session
    $session = new Session("localhost", 1984, "admin", "...");
    try {
        // create query instance, bind variable, print result
        $query = $session->query('declare variable $name external; for $i in 1 to 10 return element { $name } { $i }');
        $query->bind("name", "number");
        print $query->execute()."\n";
        $query->close();
    } catch (BaseXException $e) {
        print $e->getMessage();
    }
    // close session
    $session->close();
} catch (BaseXException $e) {
    print $e->getMessage();
}

Authentication

Updated: Digest replaced with salted authentication.

Removed: Support for digest and cram-md5 authentication, and the outdated clients.

With Version 13.0, the login handshake has changed (see here for more details). The bindings in the BaseX repository have been updated.

Clients of versions 8 to 12 can no longer connect to the server, and clients of Version 13 cannot connect to older servers.

Implementation Files

Many implementations contain the following files:

  • BaseXClient contains the code for creating a session, sending and executing commands and receiving results. An inner Query class facilitates the binding of external variables and iterative query evaluation.
  • Example demonstrates how to send database commands.
  • QueryExample shows you how to evaluate queries iteratively.
  • QueryBindExample shows you how to bind a variable to your query and evaluate the query iteratively.
  • CreateExample shows how new databases can be created by using streams.
  • AddExample shows how documents can be added to a database by using streams.

Writing a New Binding

A new binding can be written in a few hundred lines of code:

  • The byte exchange is described in the Server Protocol. The Java client serves as reference implementation.
  • \00 and \FF bytes must be escaped in both directions. To check this, store a binary resource with all 256 byte values and compare it with the returned result.
  • The state of a query (id, cached results) must be kept in the query instance, so that multiple queries can be evaluated at the same time.
  • Commands and queries return errors in different formats.

You are welcome to contribute your binding: Create a pull request, or send us a link to your repository.

Changelog

Version 13.0
  • Updated: Digest replaced with salted authentication.
  • Removed: Support for digest and cram-md5 authentication, and the outdated clients.
Version 10.0
  • Updated: The replace and store functions have been renamed to put and putBinary.
Version 8.0
  • Updated: cram-md5 replaced with digest authentication.
Version 7.2
  • Added: context() function for queries.
⚡Generated with XQuery
 
Clients