Okera Database Command-Line Interface

The Database Command-line Interface (CLI) provides client access to running Okera Database services.

Installation

For a fresh setup, you can install with:

# linux
curl -O https://s3.amazonaws.com/okera-release-useast/1.2.3/cli/linux/odb && chmod 755 ./odb

# osx
curl -O https://s3.amazonaws.com/okera-release-useast/1.2.3/cli/darwin/odb && chmod 755 ./odb

# verify the download executes
./odb --help

Configuration

The server location and/or default database can be specified to the CLI through the database use command or can be configured from a configuration file which is helpful if interacting with the same server and/or database repeatedly. The configuration file is stored in ~/.okera/configs.json.

To configure the location of the catalog service, the file should contain:

{
  "cdas_rest_server": "<host:port of catalog admin>"
  "database": "<name of the database>"
}

Quick Start

Below are the set of commands to get started with odb and demonstrate some of Okera’s capabilities. In this tutorial, authentication is done using tokens that have already been created.

# configure odb as admin user, verify it can see the sample tables
./odb database --cdas_rest_server <host:port of catalog admin> use okera_sample
./odb set-token <TOKEN>
./odb set-ssl enable (only required if SSL is enabled in ODAS)
./odb show configs
./odb database list
./odb dataset cat sample

# we, by default, create a single role, the admin_role, which has system wide access. as

# the admin, you can create and grant roles. we'll create a role, "test_role" and grant

# that to users in the "test" group.
./odb dataset hive-ddl "show tables in okera_sample"
./odb dataset hive-ddl "create role test_role"
./odb dataset hive-ddl "show roles"
./odb dataset hive-ddl "grant role test_role to group test"

# next, we will give select (aka read) access to the sample table to this new role
./odb dataset hive-ddl "grant select on table okera_sample.sample to role test_role"

# Switch to a user that only has the test role, they should now be able to read from
# the sample table. you'll notice they don't have access to the other tables and dbs.
<switch to user with group 'test'>

# run
./odb set-token <TOKEN>
./odb dataset list
./odb dataset cat sample

# trying to read from the users table will fail with an authorization error as this role
# has only been granted one table.
./odb dataset cat users

# to register new databases/datasets, use the database hive-ddl command. This
# is hiveql compatible. for example:
./odb dataset hive-ddl "create database test_db"
./odb dataset hive-ddl "create external table test_db.new_table(...) LOCATION 's3://...'"

Getting started

To get started, run:

odb --help

Which will display the list of available commands. To use most commands, you will need a login token. Use:

odb get-token --help

for the available options.

For all commands entering

odb *command* --help

will display the available options and a brief description of each option.

To see your currently saved configuration options, you can enter:

odb show configs
odb show status

Will return a response in the form:

Server <host:port> is up and accessible.

When the server is up and available. <host:port> reflects the configured server and port.

odb database list

Will list the databases available to you on the configured server.

odb dataset list

Will list the datasets available to you in the selected database.