Skip to main content
Skip table of contents

Usage guide

All of the DCT APIs are available as commands in dct-toolkit. To find the list of all commands which are available, use the following command:

CODE
./dct-toolkit -h

This will print the list of all commands grouped by the appropriate entity names. 

Examples

  • The list of available options for a particular command can be requested with the following command:

    CODE
    ./dct-toolkit <command_name> -h
  • There are currently many options for provisioning a VDB, some options are only valid for a particular DB type. For example, the unique_name option is only applicable to Oracle DBs. For better ease of use, dct-toolkit has subcommands created under the provisioning command, with options that are relevant to that particular subcommand. For example, these are the subcommands under the provision_vdb_by_snapshot command:

    CODE
    oracle
    sybase
    mssql
    appdata
    postgres

    For provisioning an Oracle VDB, use the following command:

    CODE
    dct-toolkit provision_vdb_by_snapshot oracle source_data_id=<dsourceId> --auto_select_repository unique_name=<uniqueName>

    For provisioning a Sybase-ASE VDB, use the following command:

    CODE
    dct-toolkit provision_vdb_by_snapshot sybase source_data_id=<dsourceId> --auto_select_repository --truncate_log_on_checkpoint
  • For getting the list of registered engines, use the following command: 

    CODE
    dct-toolkit get_registered_engines

    The above command will only print important fields in the response.
    For printing all of the fields in the response, use the following command: 

    CODE
    -A/--all-columns
    CODE
    dct-toolkit get_registered_engines -A

    To list only the selected columns that are useful to the user, use the following command:

    CODE
    --columns/-c
    CODE
    dct-toolkit get_registered_engines --columns=id,name,cpu_core_count...

    For advanced use cases, dct-toolkit also provides an option to specify a jsonpath expression to extract required objects from the JSON response. This can be requested with the following command:

    CODE
    --jsonpath/-jp
    CODE
    dct-toolkit get_registered_engines --jsonpath=<json path expression starting with $>

    Note, these options are available for all of the commands available in dct-toolkit. 

  • For commands that use a request body, dct-toolkit provides -body, which can be used to specify a JSON body (instead of using individual options).

    CODE
    dct-toolkit token_info --body=<JSON body to POST to DCT>

    Help regarding the exact structure of JSON request and response body can be requested for all of the commands with the following command:

    CODE
    -jh/--jsonhelp
    CODE
    dct-toolkit token_info -jh
  • dct-toolkit provides an easy to use and understand format for specifying tags. For example, the following command adds two tags – {key=purpose, value=testing} and {key=key1, value=value1}

    CODE
    dct-toolkit create_environment_tags environmentId=<envId> tags purpose=testing key1=value1
  • Some of the DCT APIs trigger an asynchronous job and return a jobId in response. dct-toolkit, by default, will wait for the asynchronous job to be completed and will report the end state of the job.

    • There is an option to not wait for the completion of an asynchronous job. Use the following command with the --no-wait option: 

      CODE
      dct-toolkit refresh_environment environmentId=<envId> --no-wait
  • If the user intends on specifying the API key via an environment variable, dct-toolkit provides a command to get the encrypted version of the API key. 

    CODE
    dct-toolkit encrypt_api_key apiKey=<DCT api key> dctUrl=<DCT instance URL>

--json/-js and --csv/-cs option examples

  • For the --json/-js option, to print the DCT response as it is received from DCT instance users can use following command:

    CODE
    dct-toolkit get_environments --json
    dct-toolkit get_environment_by_id environmentId=<environment Id> --json
  • To print the repositories object from environment object in JSON format users can use following command:

    CODE
    dct-toolkit get_environments --json --expand=repositories

  • For the --csv/-cs option, to print the DCT response in CSV format users can use the following command:

    CODE
    dct-toolkit get_environments --csv
  • To print the repositories object from the environment object in CSV format users can use the following command:

    CODE
    dct-toolkit get_environments --csv --expand=repositories

Object IDs and names

Object IDs in DCT are opaque Strings which are globally unique and thus unambiguously represent exactly one object in the system. However, since Object IDs are often not known ahead of time (and not friendly to remember or work with), dct-toolkit will accept an object name wherever an object id is expected in any of the command parameters, as long as the object name is globally unique. For example, the following dct-toolkit commands are equivalent if AppFS_DEV is the name corresponding to the VDB with id MSSQL_DB_CONTAINER-10 and is globally unique.

CODE
dct-toolkit get_vdb_by_id vdb_id="2-MSSQL_DB_CONTAINER-10"
dct-toolkit get_vdb_by_id vdb_id="AppFS_DEV"


However, if the object name is not unique, in this example if 2 or more VDBs have the same name, using the VDB name would fail:

CODE
dct-toolkit get_vdb_by_id vdb_id="AppFS_DEV"
Multiple objects match the provided ID.


The solution would then be to search for the VDBs with that name and identify the ID of the VDB:

CODE
dct-toolkit search_vdbs name=AppFS_DEV -c id,database_type,name,engine_name,group_name  
                                                                                                               
            id             |  database_type  |  name       |     engine_name      |   group_name    |
----------------------------------------------------------------------------------------------------
  2-MSSQL_DB_CONTAINER-10  |          MSSql  |  AppFS_DEV  |   dev-engine-1       |   dev-group     |
 3-MSSQL_DB_CONTAINER-127  |          MSSql  |  AppFS_DEV  |   dev-engine-2       |   qa-group      |
---
response_metadata:
  total: 2


Here is another example where names are used instead of IDs for multiple parameters:

CODE
dct-toolkit provision_vdb_by_snapshot appdata source_data_id="AppFS_MASK" name="AppFS_DEV" environment_id="Postgres_Target" environment_user_id="delphix" --auto_select_repository target_group_id='DEV' mount_point="/mnt/provision/AppFS_DEV"


Note that object names in DCT are case sensitive, meaning that AppFS_DEV is not equivalent to appfs_dev.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.