Replace Database Parameters

This article explains how to change custom parameter values in an Exasol database.

Exasol databases are configured using parameters written as key-value pairs in the format "-parameter":"value". Parameters that are not explicitly defined in the configuration will fall back on default values that are hard-coded in the application. The default values should be adequate for most use cases, but in some scenarios you may need to change them for a specific use case by adding custom parameter values in the configuration.

This article explains how to update existing custom parameter values.

Invalid parameters will prevent the database from starting. To avoid unnecessary downtime, create a support case to get guidance from Support before you add or change database parameters.

Prerequisites

  • The database must be stopped. For more information, see Stop a Database.

  • The custom parameters that are to be replaced must exist in the database.

Procedure - ConfD

The following examples use ConfD through the command-line tool confd_client, which is available on all database nodes. You can also access ConfD through XML-RPC in your own Python programs. For more information, see ConfD.

  1. Connect to EXAClusterOS (COS) on the cluster using c4 connect -t <DEPLOYMENT>[.<NODE>]/cos. For example:

    ./c4 connect -t 1.11/cos

    If you do not specify a node, c4 will connect to the first active node in the deployment. If the cluster is configured with an access node, the first node is the access node (usually n10).

    For more information about how to use c4 connect, see How to use c4.

  2. To find the name of the database, use the ConfD job db_list. For example:

    confd_client db_list
    - MY_DATABASE

  3. To find currently defined custom parameters, use the ConfD job db_info. Any custom parameters will be listed in the params: section. 

    confd_client db_info db_name: MY_DATABASE | grep params
     params: -forceProtocolEncryption=1 -soft_replicationborder_in_numrows=1000000

  4. If the database is running, stop it now using the ConfD job db_stop. For example:

    confd_client db_stop db_name: MY_DATABASE

  5. To replace parameters, use the ConfD job db_configure with the attribute params: followed by the parameters to be replaced. For example:

    confd_client db_configure db_name: MY_DATABASE params: '[-forceProtocolEncryption=0, -soft_replicationborder_in_numrows=2000000]'

  6. To verify that the configuration has been updated, use the ConfD job db_info. Any custom parameters will be listed in the params: section. 

    confd_client db_info db_name: MY_DATABASE | grep params
     params: -forceProtocolEncryption=0 -soft_replicationborder_in_numrows=2000000

  7. Start the database using the ConfD job db_start. For example:

    confd_client db_start db_name: MY_DATABASE

Procedure - Administration API

The following examples use curl in a Linux terminal to send REST calls to endpoints in the Administration API. You can also use other interfaces and languages to interact with the API. For more information, see Administration API.

Placeholder values are styled as Bash variables, for example: $NODE_IP. Replace the placeholders with your own values.

The option --insecure or -k tells curl to bypass the TLS certificate check. This option allows you to connect to a HTTPS server that does not have a valid certificate. Only use this option if certificate verification is not possible and you trust the server.

  1. To get information about the database, send a GET request to the /api/v1/databases endpoint.

    curl --insecure -X "GET" \
    "https://$NODE_IP:4444/api/v1/databases" \
    -H "accept: application/json" \
    -H "Authorization: Basic $AUTH_TOKEN"

    The response includes the database ID, name, and version. Additional details are included depending on the configuration and platform.

  2. To see any currently configured additional parameters, send a GET request to the /api/v1/databases/DATABASE_ID/parameters endpoint.

    curl --insecure -X "GET" \
      "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/parameters' \
      -H "accept: application/json" \
      -H "Authorization: Basic $AUTH_TOKEN"

    The response will list all additional parameters currently defined in the configuration. If no additional parameters have been configured, the result will be empty. Default parameters are not shown. For example:

    {
      "parameters": {
        "-forceProtocolEncryption": "1",
        "-soft_replicationborder_in_numrows": "1000000"
      }
    }

  3. If the database is running, stop it now by sending a PUT request to the /api/v1/databases/$DATABASE_ID/stop endpoint:

    curl --insecure -X "PUT" \
    "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/stop" \
    -H "accept: application/json" \
    -H "Authorization: Basic $AUTH_TOKEN"

  4. To replace parameters, send a PUT request to the /api/v1/databases/DATABASE_ID/parameters endpoint. Add the parameters you want to replace in the payload as key-value pairs in the format "-parameter": "value". For example:

    curl --insecure -X "PUT" \
    "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/parameters" \
    -H "accept: application/json" \
    -H "Authorization: Basic $AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "parameters": {
        "-forceProtocolEncryption": "0",
        "-soft_replicationborder_in_numrows": "2000000"
      }
    }'

  5. To verify that the configuration has been updated, send a GET request to the /api/v1/databases/DATABASE_ID/parameters endpoint again. The response now shows the updated parameter values. For example:

    {
      "parameters": {
        "-forceProtocolEncryption": "0",
        "-soft_replicationborder_in_numrows": "2000000",
      }
    }

  6. Start the database by sending a PUT request to the /api/v1/databases/DATABASE_ID/start endpoint:

    curl --insecure -X "PUT" \
    "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/start \
    -H "accept: application/json" \
    -H "Authorization: Basic $AUTH_TOKEN"