The dboo command line

Here is a brief guide for how to use the dboo command line.

Batch mode

In batch mode dboo command acts like a normal command line tool. You write the whole command with login details and the database command to execute on one line.

Immediately after dboo are the connection details followed by double dash ‘–’ and there after the commands to execute on the database. Any number of commands can be added by separating them with double dash:

> dboo -u=root -p=MyPassword -- create user AnotherUser --groups=AnotherGroup,AGroup --password=SecretPassword
> dboo MyNewDatabase -u=MyNewUser -p=UserPwd -- "select<Car>(eq(numberofdoors, 2))"

Interactive mode

In interactive mode, the user have access to auto completion. It is quite useful for trying out queries and doing things more interactively. Interactive mode is always entered into if no other commands are specified after the connection details.

You can specify the password either on the command line:

> dboo -u=root -p=MyPassword

Or be prompted by using option -p, leaving out the assignment operator:

> dboo -u=root -p
Logging in as root to dboo::server on localhost:8822.
password:

You exit interactive mode by pressing Ctrl-C twice from an empty dboo prompt, or by typing the exit command:

dboo root@dboo::server> <Press Ctrl-C>
(To exit, press ^C again or type exit)  <Press Ctrl-C again>
dboo root@dboo::server> exiting

dboo root@dboo::server> exit
exiting

Redirection while in interactive mode

In batch mode you can use the normal terminal redirection operators to redirect the output. interactive mode has similar > and < operators (but they are implemented internally in dboo).

dboo tom@mydb> select<Car>(eq(numberofdoors, 2)) > ~/data/CarsWithTwoDoors.json

Auto completion

While in interactive mode, you can use the tab key to get a suggestion of commands, arguments and option values. When writing queries, class names and operations are also suggested.

Connecting to the server database

Running dboo without any arguments will make it enter interactive mode. From here you can connect to a database using the connect command. If you enter any arguments, they will be interpreted as arguments to the connect command. connect without a database name will connect to the server database, which is what you want when creating databases or users.

Connecting to the server database while inside interactive mode:

> dboo
dboo> connect -u=root -p
Logging in as root to dboo::server on localhost:8822.
password: ***
dboo root@dboo::server>

Connecting to the server database from the command line:

> dboo -u=root -p
Logging in as root to dboo::server on localhost:8822.
password: ***
dboo root@dboo::server>

By default, connect will use your computer user name as login name, so to use any other name you need to use the -u=<username> option. Also, by default, an empty password is assumed. -p without a password will force a password prompt. You can specify a password at the prompt with -p=<password>.

Useful server commands

The following commands are worth a bit deeper introduction as they are commonly used while working on the server database. Optional parameters are shown within square brackets here:

Create

Commands for creating databases, users and groups:

create database <databaseid> [–groups=<group1>,<group2>,… ] [–description=<text>] [–filepath=<path to database>]

Creates a database with the name <databaseid> and associates it with the specified groups. If a group does not exist it will be created. Description is a textual comment about the database and filepath is a location for it. You should normally not specify its location if you are happy with it being located in the default place.

Add

add user <user_id> [–password[=<password>]] [–groups<group1>,<group2>,… ] [–description=<text>]

Creates a user with the name <user_id> and associates it with the specified groups. If a group does not exist it will be created. Description is a textual comment about the user. If –password is specified without an argument, the user will be asked for it.

add group <groupid> [–description=<text>]

Creates a group with the name <groupid>. Description is a textual comment about the group.

List

Commands for listing databases, users and groups:

list databases [–groups] [–description] [–path] [–type_indices_path] [–field_indices_path] [–all]

Lists all database names. Add any of the options to show more information about each database.

list users [–groups] [–description]

Lists all user names. Add any of the options to show more information about each user.

list groups [–description]

Lists all group names. With the option –description, any group descriptions are shown as well.

Modify

Commands for modifying databases, users and groups:

modify database <databaseid> [–add_groups=<groups to add>] [–rm_groups=<groups to remove>] [–description=<new description>] [–filepath=<new filepath>] [–new_database_name=<new databaseid>]

Modifies the database with name <databaseid>. –add_groups adds groups to the database while –rm_groups removes groups. –description sets the description. –filepath changes the known file path for the database, it doesn’t move the database files. Currently the best process to do this is: 1) shut down server and start server again (this will ensure the database is not loaded), 3) run modify database <databaseid> –filepath=<path>, 4) shut down server, 5) move the files yourself through command line, 6) start server. –new_database_name changes the name of the database.

modify user <userid> [–password[=<password>]] [–add_groups=<groups to add>] [–rm_groups=<groups to remove>] [–description=<new description>] [–new_userid=<user_id>]

Modifies the user with name <user_id>. –add_groups adds groups to the user while –rm_groups removes groups. –description sets the description. –new_userid changes the name of the user. If –password is specified without an argument, the user will be asked for it.

modify group <groupid> [–description=<new description>] [–new_groupid=<groupid>]

Modifies the group with name <groupid>. –description sets the description. –new_groupid changes the name of the group.

Drop

Commands for deleting databases, users and groups:

drop database <databaseid> [–force]

Deletes the database with name <databaseid>. Without the option –force, a confirmation question will be asked. With the –force option, the database will be deleted without asking. Note that only the dboo server’s definition of the database is deleted. The database files will not be deleted.

drop user <user_id> [–force]

Deletes the user with name <user_id>. Without the option –force, a confirmation question will be asked. With the –force option, the user will be deleted without asking.

drop group <groupid> [–force]

Deletes the group with name <groupid>. Without the option –force, a confirmation question will be asked. With the –force option, the group will be deleted without asking.

Connecting to a user database

connect with a database name will connect to the specified database, which is what you want when running queries.

Connecting to a database while inside interactive mode:

> dboo
dboo> connect MyNewDatabase -u=MyNewUser -p
Logging in as MyNewUser to MyNewDatabase on localhost:8822.
password: ***
dboo MyNewUser@MyNewDatabase>

Connecting to the database from the command line:

> dboo MyNewDatabase -u=MyNewUser -p
Logging in as MyNewUser to MyNewDatabase on localhost:8822.
password: ***
dboo MyNewUser@MyNewDatabase>

Query commands

When connected to a database, you can use queries to search for objects or erase them. This section will not give a full description of the query language, just a quick guide:

The following commands all uses the same query syntax to select objects:

select<>() [–format=json|xml|simple] [–max_objects=<number of objects>] [–verbose] [–fetch_referenced_objects]

Retrieves objects from the database based on search criteria and outputs them either to standard out or to a redirection. The objects can be output in json, xml or a simplified format. –verbose outputs some timing information. –fetch_referenced_objects also outputs all objects referenced from the selected objects.

count<>() [–verbose]

Counts objects on the database based on search criteria and outputs the number to the standard out. –verbose outputs some timing information.

erase<>() [–verbose]

Erases objects on the database based on search criteria. –verbose outputs some timing information.

The query language is compiled code when used in c++, hence it’s c++ syntax:

select<ClassName>()

Selects all objects of class ClassName.

select<ClassName>(eq(MyField, MyValue))

Selects all objects of class ClassName who’s field MyField has value MyValue. There are a number of operators for selecting larger than, lower than etc. Use the tab key to find choices here (or check the reference manual).

Selects all objects of class Motorbike and objects of class Tractor with power less than and return them in a vector with element type Vehicle. When querying through the dboo tool, the return type doesn’t really matter that much, but in c++ it would make more sense:

dboo MyNewUser@MyNewDatabase> select<Vehicle>(set_union(select<Motorbike>(), select<Tractor>(lt(power, 201))))

Erases all objects in the intersection of all objects of class Motorbike with color=’green’ and power greater than 100:

dboo MyNewUser@MyNewDatabase> erase<Motorbike>(set_isect(select<Motorbike>(eq(color, 'green')), select<Motorbike>(gt(power, 100))))

Changing password

set password

Changes the password of the currently logged in user. The user will be asked for old password and the new.

Backup & restore commands

Backups can be made to clear text files or a binary format. For clear text, the type information is in xml and the data in json.

backup [–file=<path>] [–prefix=<file prefix>] [–directory=<path>] [–overwrite] [–binary]

Writes all objects to the specified output. If –file is used, write the output to the specified path. If –prefix and –directory are used, write to the specified directory and generate a file name. If –prefix is not specified in this case, the name will be based on the database name. –overwrite overwrites any existing files with the same name and –binary outputs the file in binary, default output is in clear text. If no output is specified, the backup will be to the standard out. Redirection ‘>’ to a file may also be used. Note that only selectable objects and their referenced objects are output in the current version. Only objects that are part of type indices can be selected. Normally this is the case, but it is not necessary to have that in dboo.

restore [–do_not_restore_types] [–file=<path>] [–binary]

Restores objects from an input. Either specify a file with option –file or use redirection ‘<’ from a file. With the option –do_not_restore_type, the types will not be read from the files but assumed to already be in the database. Currently, the restore command can not recognize whether the input is binary or clear text, so use the –binary flag to indicate which it is.