CCDB CLI

CCDB provides 'ccdb' - command line interface for introspection and management of constants. It can be used as interactive shell or to execute single commands.

Example. Single command:

       (1)                           (2)  (3)
ccdb -c "mysql://john@localhost:999" ls /TOF/params

1. -c "mysql://john@localhost" - is ccdb global CCDB argument, which sets the connection string.
2. ls - is a ccdb command which (like a POSIX ls) prints a list of directories and tables belonging to /TOF/params
3. /TOF/params is an argument of the ls command.

Example. Interactive session:

ccdb -c "mysql://john@localhost:999" -i                  (1)
> ls /TOF/params                                         (2)
> help                                                   (3)
> cd /TOF                                                (4)
> cd params
> ls
> pwd                                                    (5)                                              
> q                                                      (6)

1. flag -i starts ccdb in the interactive mode.

2. ls /TOF/params - the result is exactly the same as in the above example.

3. help command provides list of commands and how to use each of them

4. ccdb interactive mode has a current working directory, with relative and absolute paths

5. Same as for POSIX shell, pwd command shows the current directory.

6. to exit interactive mode enter q, quit or press ctrl+D

Since ccdb objects have /name/paths and many other things that looks like POSIX file system, the commands are very posix-shell-like.

Connecting to DB

ccdb command uses the connection strings to connect to data source. The connection string should be provided by:

1. -c <connection string> argument (see the above example) or by

2. CCDB_CONNECTION environment variable

   export CCDB_CONNECTION=mysql://ccdb_user@hallddb.jlab.org/ccdb

If nothing is given by -c or CCDB_CONNECTION, then mysql://ccdb_user@localhost/ccdb is used.

NOTE: -c flag has the higher priority than CCDB_CONNECTION

Help system

ccdb is designed to be a self descriptive. By using 'help' 'usage' and 'example' commands one could get all the commands and how to use them.

By using 'howto' command one could get tutorials for typical situations.

Commands

Commands consistency

Command arguments are chosen to be consistent between commands. Some flags and argument formats means the same across all commands. CCDB has several classes of objects: directories, type tables, variations, run number, assignments. Some commands may be applied for different classes. For example 'info' command may be executed against directory, table or variation There are unified flags to identify objects for all commands:

• -v - Variation
• -t - Data table
• -r - Run or run-range
• -d - Directory
• -a - Assignment (usually identified by request or db ID)

Example. Info command:

ccdb -i
> info -v default                                          (1)
> info -d /TOF                                             (2)
> info -t /TOF/params                                      (3)
> info /TOF/params                                         (4)

1. Get information about "default" variation
2. Get information about "/TOF" directory.
3. Get information about "/TOF/params" type table
4. By default 'info' treat non flag argument as a name of a table.

Commands overview

This table is printed if one executes "ccdb help"

(command)	(name)	(description):
add	AddData	Add data constants
info	Info	Prints extended information about an object
vers	Versions	Show versions of data for the specified table
run	CurrentRun	gets or sets current working run
dump	Dump	Dumps datat table to a file
show	Show	Shows type table data
mkdir	MakeDirectory	Create directory
pwd	PrintWorkDir	Prints working directory
cd	ChangeDir	Change current directory
mktbl	MakeTable	Create constants type table
cat	Cat	Show assignment data by ID
ls	List	List objects in a given directory
log	Log	Get CCDB changes log

Assuming that user is in interactive mode, one may categorize the commands:

To navigate directories

• pwd - prints curent directory
• cd - switch to specified directory
• ls - list objects in the directory (wildcards are allowed)
• mkdir - creates directory

Example. Directory commands overview:

    > pwd
	> cd /TOF
	> ls
	> mkdir constants
	> ls con*

Get information about objects

• info - gets information about objects (use -v -r -d flags), see example 6.
• vers - gets all versions of the table
• cat - displays values
• dump - same as cat but dumps files to disk
• log - see logs information

Manage objects

• mkdir - creates directory
• mktbl - creates data table
• add - adds data from text file to table (variation and runranges are created automatically by add command)

Deleting objects

While CCDB discourages to delete anything. Instead, one can deprecate tables, directories or variations, which are old and not used anymore. Deprecation removes tables/directories from listings (e.g. ls command) but if old code will request the constants, they will be available.

There are still cases, when removing something might be required:

• It is possible to make a typo/mistake when creating a table/variation
• On early development stage (introducing new constants and writing code, that uses it) it might be beneficial to recreate something (e.g. a table with different set of rows). CCDB warning: this already might lead to trouble(!) but in many cases with playground SQL it is OK.
• For all other cases deletion is highly not recommended! Treat CCDB as a logbook - calibration data logbook. But still removing stuff is technically possible.

rm - command shell be used with common flags -d, -t, -v, -a to remove a directory, table, variation or assignment.

Directory/table/variation must be empty to be removed. Which means, one has to first delete all assignments from table to remove table, remove all tables to remove a directory, etc.