Zero-Knowledge Database Library Test Tools

$Id: zkDB_TestTools,v 1.0 2000/05/24 16:16:36 sam Exp $

Revision

Comments

1.1

Author(s): Sam Sanjabi (sam@zks.net),

Initial draft.

Contents

  1. Introduction

  2. dbperf - Database Performance Test Tool

  3. dbcreate - Random Test Database Creation Tool

  4. dbpopulate - Test Database Creation from File

  5. Appendix: zkConfig file format

1 - Introduction

Goto : [top]

This document gives an overview of the usage of some available test tools for the Zero-Knowledge Database Library. These tools are located in the CVS source tree at /freedom/ndb/test/. It is assumed that the reader has some knowledge of the zkDB API. Documentation of the API can also be found in the source tree at /freedom/ndb/doc/zkdbAPI.html.

2 - dbperf: Database Performance Test Tool

Goto: [top]

SYNOPSIS

dbperf

[--help] [--config file] [--database file] [--iteration int] [--maxKey int] [--keySize int] [--recordSize int] [--process int] [--multiOpen] [--operation string]

A more detailed description of the functionality of these options follows below.

DESCRIPTION

dbperf is a tool to test the performance of the zkDB database library by assigning a number of processes to perform a set of operations on the database many times. For example the user can instruct dbperf to generate 20 child processes that will each perform 300 updates on a given database. Upon completion of these processes, dbperf reports the total real, user, and system time used, as well as the average number of queries per second performed by the database. If the performed operation was specified as a fetch, dbperf also reports the number of successfully found records.

OPTIONS

--help
Displays the usage information and a short summary of each option to stdout.
--config file
Allows the user to specify a configuration file (not the database config file, but one used by dbperf directly) to load the parameters instead of using the command line. The format of this config file is as that specified by zkConfig. I've included a description of this format below.
--database file
Specifies the database to test, where file is the name of the Zero-Knowledge Database Configuration File associated with the desired database. To learn more about database configuration go see the docs at http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
--iteration int
Specifies the number of times each child process performs the operation(s) requested using the operation option. The default value is 1000. Also, if the maxKey option is not specified, this also sets the maximum key value to use in database queries.
--maxKey int
Specifies the maximum key value to use in database queries. If this option isn't explicitly specified, the maximum key value becomes the same as the number of iterations undergone by each process (as specified by the iteration option above).
--keySize int
Specifies the size of the keys (in bytes) generated randomly to query the database. The default value is 64, and the keys must be at least 12 bytes long.
--recordSize int
Specifies the size of the records (in bytes) generated to insert into the database. By record we mean the data part of the key/data pair stored by the databases. The default value is 64.
--process int
Specifies the number of child processes that will each do the operation(s) requested by the operation option the required number of times (as requested by the iteration option).
--multiOpen
If this option is specified, dbperf will open and close the database interaction (using zkDB_Open and zkDB_close) between each operation performed by the child processes. If this option isn't specified, then the database interaction is opened once for each child process and closed once when the process has completed all the iterations it was was supposed to. Note that if operation is set to sequence, then it is the user's responsibility to request open and close operations himself (this will not be done automatically in multiOpen mode).
--operation string
Specify the operation to perform (fetch, update, delete or sequence). In case of a sequence, the expected format is --operation seq:string where string contains the operations to be performed. For example, --operation seq:ufdu describes a sequence of update, fetch, delete and update. When used in multiple open mode, the database open and close operations must be specified expilictly (example: "odcofudc"). The possible values for string are summarized in the following table:

string value (as regexp)

Function Behaviour

fetch

child process fetches random records from the database

update

child process updates random records in the database

delete

child process deletes random records from the database

seq:[o|c|f|u|d]*

child process performs sequence of operation defined by the string of characters that follow "seq:" where:

  • o denotes opening the interaction with the database

  • c denotes closing the interaction with the database

  • f denotes fetching a record from the database

  • u denotes updating a record in the database

  • d denotes deleteing a record from the database



FILES

Database Configuration File
Configuration file used to specify the desired test database. The format for this file is available at http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
Parameter Configuration File
As stated above, the parameters for the performance test can also be specified using a configuration file of the format specified by zkConfig (see the appendix for a description of this format).

EXAMPLES

  1. 40 Processes doing 1500 updates with 64 byte keys and 80 byte records in single-open mode would be initiated by:

       %% dbperf --database testdb.conf --iteration 1500 --recordSize 80 
                                        --process 40 --operation update
       
  2. 75 processes doing a sequence of open,delete,fetch,update,update,close 700 times with default sized keys and records in multi-open mode would be initiated by:

       %% dbperf --database testdb.conf --iteration 700 
                                        --multiOpen --operation seq:odfuuc
       
  3. 20 processes each doing 3000 updates in multi-open mode would be initiated by:

       %% dbperf --database testdb.conf --iteration 3000 
                                        --multiOpen --operation update
       

    Note that the same functionality could be achieved with the sequence notation as follows:

       %% dbperf --database testdb.conf --iteration 3000 
                                        --multiOpen --operation seq:ouc
       

    Observe that in order to use the sequence notation, the user had to explicitly open and close the database interaction himself. If the 'o' and the 'c' had been left out of the operation, the underlying zkDB interface would have returned an error. In single open mode, the opening and closing of the database is handled automatically.

3 - dbcreate: Random Test Database Creation Tool

Goto: [top]

SYNOPSIS

dbcreate

[--help] [--config file] [--database file] [--size int] [--keySize int] [--recordSize int] [--scan] [--verbose]

DESCRIPTION

dbcreate performs one of two functions:

  1. Filling in a database with a number of records so that it can be tested

  2. Scanning a database in order to find the number of records in it

Using the options, the user can specify how many records are to be filled and how large the key and data fields of these records should be.

OPTIONS

--help
Displays the usage information and a short summary of each option to stdout.
--config file
Allows the user to specify a configuration file (not the database config file, but one used by dbperf directly) to load the parameters instead of using the command line. The format of this config file is as that specified by zkConfig. I've included a description of this format below.
--database file
Specifies the database to test, where file is the name of the Zero-Knowledge Database Configuration File associated with the desired database. To learn more about database configuration go see the docs at http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
--size int
Specifies the number of records to be filled into the test database when that is the required function. If scan option is enabled, this parameter is ignored.
--keySize int
Specifies the size of the keys (in bytes) generated to insert into the database. The default value is 64, and the keys must be at least 12 bytes long.
--recordSize int
Specifies the size of the records (in bytes) generated to insert into the database. By record we mean the data part of the key/data pair stored by the databases. The default value is 64.
--scan
If this option is enabled, dbcreate will not insert any records into the database at all. It will simply scan the entire database and report the number of records stored in it to stdout. If the verbose option is used, dbcreate will also print each key/data pair it encounters to stdout as it scans.
--verbose
Set this option to get dbcreate to report more information about what it is doing. If the scan option is active, it will report each encountered key/data pair in the database. Otherwise (if we are filling in the database with records), the program will report its percentage completion to stdout

FILES

Database Configuration File
Configuration file used to specify the desired test database. The format for this file is available at http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
Parameter Configuration File
As stated above, the parameters for the performance test can also be specified using a configuration file of the format specified by zkConfig (see the appendix for a description of this format).

EXAMPLES

  1. Inserting 900 records into the database specified by "testdb.conf" with 32 byte keys and 80 byte records.

       %% dbcreate --database testdb.conf --size 900 --keySize 32
                                          --recordSize 80
       
  2. List the records in the database and report their number

       %% dbperf --database testdb.conf --scan --verbose
       

4 - dbpopulate: Test Database Creation from File

Goto: [top]

SYNOPSIS

dbpopulate

[--help] [--config file] [--database file] [--size int] [--startKey int] [--keySize int] [--recordSize int] [--source file] [--scan] [--fetch] [--output file] [--verbose]

DESCRIPTION

dbpopulate performs the same function as dbcreate, but reads and outputs database record to and from files.

OPTIONS

--help
Displays this information

--config <filename>
Specify which configuration file you wish to use (you can specify a configuration file in which the other parameters can be specified).

--database <filename>
Name and location of the database configuration file.

--size <int>
Number of entries to add to database (default 1000).

--startKey <int>
Key number to use first key for the numbering sequence (default 1).

--keySize <int>
Specifies the key size (default 64 bytes). Minimum key size is 12 bytes.

--recordSize <int>
Specifies the record size (default 64 bytes).

--scan
Scan the database with a cursor and dump the records to an output file. Reports number of records found. Can't be set if --fetch is set.

--fetch
Do an ordered fetch of all records in the database one by one, and dump them to the output file. Can't be set if --scan is set.

--source <filename>
Populate database from the source file.

--output <filename>
Write data from the scan or fetch operations to the file

--verbose
Toggle verbosity on/off. The verbosity can also be toggled by sending the SIGUSR1 signal to a running dbpopulate process.

FILES

Database Configuration File
Configuration file used to specify the desired test database. The format for this file is available at http://caesar.zks.net/devnet/cvs/freedom/ndb/doc/zkdb-conf.html.
Parameter Configuration File
As stated above, the parameters for the performance test can also be specified using a configuration file of the format specified by zkConfig (see the appendix for a description of this format).

EXAMPLES

  1. Inserting 1000 records into the database specified by "testdb.conf" from the file "testdb.src" with 32 byte keys and 80 byte records.

       %% dbpopulate --database testdb.conf --size 1000 --keySize 32
                                            --recordSize 80 --source testdb.src
       
  2. Dump the records in order of increasing keys to "testdb.out"

       %% dbpopulate --database testdb.conf --fetch --output testdb.out --verbose

5 - Appendix: zkConfig file format

Goto: [top]

The zkConfig file format is the same as that of a windows .INI file. To save you the trouble of going out and figuring out what that is, I will present the format of this file here. The file is split into sections demarkated by [SECTION_NAME], with each section containing parameter/value pairs. Lines whose first non-white space character is a ';' are considered comment lines. Here is the general format:

    ; Comment line

    [SECTION_NAME_1]

    PARM_NAME_11 = PARM_VALUE_11
    PARM_NAME_12 = PARM_VALUE_12
    ...
    PARM_NAME_1n = PARM_VALUE_1n

    [SECTION_NAME_2]

    PARM_NAME_21 = PARM_VALUE_21
    PARM_NAME_22 = PARM_VALUE_22
    ...
    PARM_NAME_2n = PARM_VALUE_2n

    .  .  .

    [SECTION_NAME_m]

    PARM_NAME_m1 = PARM_VALUE_m1
    PARM_NAME_m2 = PARM_VALUE_m2
    ...
    PARM_NAME_mn = PARM_VALUE_mn

In the case of these tools (dbperf say), section names are omitted since there is only one. For example, a configuration file that would run dbperf on database "testdb" in multiOpen mode with 20 child processes each doing 300 fetches with 128 byte keys would be:

    ; Filename: configtest.conf
    ; Filetype: dbperf configuration file 

    database  = "testdb.conf"
    iteration = 300
    keySize   = 128
    process   = 20
    multiOpen = 1
    operation = fetch

and the operation would be invoked with the command line dbperf --config configtest.conf.