Project

General

Profile

Client Instructions

Installation

To set up UConDB client, follow these steps:

  1. Download UConDB client from: https://cdcvs.fnal.gov/redmine/projects/ucondb/files
  2. Create directory ucondb_client and untar the downloaded file there:
       $ mkdir ucondb_client
       $ cd ucondb_client
       $ tar xf <ucondb client tarfile>
    
  3. Setup the environment
       $ export PYTHONPATH=`pwd`/lib
       $ export UCONDB_BIN=`pwd`/bin
    

Creating a folder

Before you can start using UConDB, you need to create a folder in the database.
To create a folder in an existing Postgres database, you will need access to a Postgres account with permissions to create tables in a schema (e.g. namespace).

   $ python $UCONDB_BIN/create_folder.py \
       -h <database host> \
       -p <port> \
       -U <database user> \
       -w <database password> \
       -R <read account>[,...] \
       -W <read account>[,...] \
       <database name> [<schema>.]<folder name>

The options are:

  • -h <database host>, -p<port>, <database name> - required - host name, port and database name for the Postgres database.
  • -U <database user> - required - database account name authorized to create database objects.
  • -w <database password> - optional - database account password, required unless .pgpass has the appropriate entry.
  • -o <owner account> - optional - the folder objects will be owned by this role instead of the user specified with -U. The user must be a member of the role.
  • -R <account>[,...] - optional - comma-separated list of database accounts to grant read permissions to the folder.
  • -W <account>[,...] - optional - comma-separated list of database accounts to grant read and write permissions to the folder.

If you plan to access the folder via the web server, make sure to grant necessary permissions to the account you want to be used by the web server using -R or -W options.

Storing data

Once you create a folder, you can create objects there either using command line interface or via the web server:

Using command line interface

   $ python $UCONDB_BIN/put_object.py \
       -h <database host> \
       -p <port> \
       -U <database user> \
       -w <database password> \
       -f <input file> \
       -t <tag>[,...] \
       -T <validity time> \
       -k <key> \
       <database name> [<schema>.]<folder name> <object name>

This command will create a new version of the object and the object itself if it does not exist. The -h, -p, -U, -w are same options as for create_folder.py.
Other options are:

  • -f <input file> - optional - data file to upload as the object contents. If unspecified, the contents will be read from stdin.
  • -t <tag>[,...] - optional - comma separated list of tags to attach to the new version of the object
  • -T <validity time> - optional - beginning of the validity interval for the object, specified as a floating point (or integer) number. Default = 0.
  • -k <key> - optional - arbitrary string, key name to associate with the new version. Key name must be unique for the whole folder.

Using web server

You can upload and retrieve object versions via the web interface using curl or similar command line tool:

   $ curl -T /data/input_file.data http://server.fnal.gov:8080/url/path/app/data/folder_name/object_name  

The folder_name may include the database schema: <schema>.<folder name>. If unspecified, the server default schema will be used.

If configured, data uploading via the web server will require digest authentication:

   $ curl --digest -u username:password -T /data/input_file.data http://server.fnal.gov:8080/url/path/app/data/folder_name/object_name

The URL may also include some parameters:

  • tag=<tag>[,...] - comma separated list of tags to attach to the new version of the object
  • key=<key> - assign the key to the version. Must be unique for the folder.
  • tv=<tv> - assign the numeric validity time
  • override=(yes|no) - if yes, and key was specified, the key will be assigned to the new instance. If there was another version associated

Reading data

Via the web server

   $ curl -o /data/output_file.data http://server.fnal.gov:8080/url/path/app/data/folder_name/object_name  

The folder_name may include the database schema: <schema>.<folder name>. If unspecified, the server default schema will be used.

Reading data does not require any client authentication

The url may also include:

  • tag=<tag> - get the latest version with the specified tag
  • meta_only=(yes|no) - if yes, return metadata in JSON format only
  • key=<key> - get the version associated with the key
  • id=<id> - get the version by id
  • tv=<t> - get the version by the validity time
  • tr=<t> - choose from versions stored in the database at or before the specified time

Using direct database access

   $ python $UCONDB_BIN/get_object.py \
       -h <database host> \
       -p <port> \
       -U <database user> \
       -w <database password> \
       -f <output file> \
       -t <tag> \
       -T <validity time> \
       -k <key> \
       -m
       <database name> [<schema>.]<folder name> <object name>

This command will create a new version of the object and the object itself if it does not exist. The -h, -p, -U, -w are same options as for create_folder.py.
Other options are:

  • -f - optional - output file. If unspecified, the contents will be sent to stdout.
  • -t <tag> - optional - get the latest version with the specified tag
  • -T <validity time> - optional - numeric validity time. Get the version with the validity time closest to the specified time but in the past.
  • -k <key> - optional - get the version by the key.
  • -m - optional - print version metadata only, without retrieving the data.