Tutorial

Remote Databases

If enabled at compilation time, upscaledb can seamlessly access remote Databases and Environments. This chapter gives an overview about the API and about upszilla, a unix daemon/win32 service which can serve Databases.

The upscaledb server can be embedded into applications. It runs in separate threads and is capable of handling many requests in parallel.

Prerequisites

upscaledb uses regular TCP sockets to send network requests and Google protocol buffers for the protocol. The protocol buffer library and the google protocol compiler have to be installed on your system. To simplify the compilation on Windows, a separate package with precompiled dependencies is provided on http://upscaledb.com.

To compile the Unix server, you also require libuv (http://github.com/joyent/libuv).

On Linux/Unix the libraries have to be installed manually, and ./configure will disable the remote functionality if the libraries can not be found.

Accessing Remote Databases from your application

To access a remote server from your application, just specify a URL instead of a filename.

ups_status_t st = ups_env_create(&env, "ups://localhost:8080/customers", 0, 0, 0);

Alternatively, you can use:

ups_status_t st = ups_env_open(env, "ups://localhost:8080/customers", 0, 0);

In case of remote Databases/Environments, it does not matter if you use ups_env_create or ups_env_open. In each case the client will only connect to the remote Database (or Environment). The Database (Environment) will not really be opened or created - it was already opened or created by the server. The creating/opening on client side is just use to connect to the server and acquire internal communication handles.

The hostname, port and the path of your Database (here: “customers”) depend on the configuration of the server.

Have a look at the sample samples/client1.c to see a full example.

Embedding a server into your application

The network server is a library which has no more than a few functions. You can use it to embed the server into your application or to write your own standalone server. upscaledb comes with its own standalone server. It is described in the following chapters.

The sample samples/server1.c creates a full server application which serves an Environment with several Databases.

The upszilla daemon/server

As mentioned above, upscaledb has its own standalone Win32 service or Unix daemon, respectively. It’s implemented in tools/upszilla.c.. It understands configuration files written in JSON. An example configuration file is in tools/upszilla.config. upszilla can compile as a Unix daemon and a Win32 service. They are both described in the next two chapters. Afterwards, the configuration is explained.

upszilla - The Win32 Service

When compiling on Windows, upszilla can run either as a Win32 console process or as a Win32 service. The following command line parameters are supported:

  • -h or --help: print a help screen\
  • -f or --foreground: runs in foreground (as a Win32 console application)\
  • -l <n> or --log_level=<n>: sets the logging level; values are 0 (print debug messages), 1 (print information messages), 2 (print warning messages), 3 (print fatal messages). Default is 1. When running as a Service, log messages will be written to the Event log.\
  • -c <file> or --config=<file>: sets the path of the configuration file. If no configuration file is specified then the default configuration file is read from the current directory; it has the same path as the executable, but with a different extension (usually, the path is upszilla.config; if you rename the executable, i.e. to upsserver.exe, then the default configuration path is upsserver.config). Using a default configuration path is helpful if running as a Win32 service.\
  • -i or --install: Install this service in the Service Database; this is a mandatory step before actually running the service.\
  • -u or --uninstall: Uninstalls this service.\
  • -s or --start: Starts the service; fails if service was not installed yet.\
  • -x or --stop: Stops the service

upszilla - The Unix daemon

When compiling on Unix, upszilla can run either as a user process or as a background daemon. By default it runs as a background daemon.

  • -h or --help: print a help screen\
  • -f or --foreground: runs in foreground\
  • -l <n> or --log_level=<n>: sets the logging level; values are 0 (print debug messages), 1 (print information messages), 2 (print warning messages), 3 (print fatal messages). Default is 1. When running as a Daemon, log messages will be written to syslog.\
  • -c <file> or --config=<file>: sets the path of the configuration file. If no configuration file is specified then the default configuration file is read from the current directory; it has the same path as the executable, but with a different extension (usually, the path is upszilla.config; if you rename the executable, i.e. to upsserver, then the default configuration path is upsserver). \
  • -p <file> or—pid=@: writes the pid of the daemon to the

upszilla configuration files

upszilla configuration files are JSON files. An example is in tools/upszilla.config. It describes global parameters like port or paths for http access logs. And it describes all Environments that are served by upszilla. You can specify an arbitrary number of Environments, each with its own http path. This path is then used when connecting to the server (ups://servername:port/path).

In addition, you can specify all databases in each Environment, and whether the Environment should be created if it does not yet exist. In this case also all Databases in this Environment will be created.