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.
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.
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.
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.
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.
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 serviceWhen 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=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.