API Examples

This article provides examples of how to use the Administration API in Exasol.

The following examples use curl on a Linux terminal, but you can also use other interfaces and tools.

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

Database jobs

To add or modify database parameters, the database must be stopped.

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.

List database parameters

Exasol databases are configured using parameters that are written as key-value pairs in the format "-parameter":"value". Parameters that are not explicitly defined will fall back on default values hard-coded in the application. The default values should be adequate for most use cases, but can be changed by adding custom parameter values in the configuration if needed.

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

Copy

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.

Add database parameters

To add parameters, send a PATCH request to the /api/v1/databases/$DATABASE_ID/parameters endpoint. Add the parameters you want to add in the payload as key-value pairs in the format "-parameter": "value".

Example:

curl --insecure -X "PATCH" \
"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": "1",
    "-oidcProviderClientSecret": "abcd"
  }
}'
                                                                    

Remove database parameters

To remove parameters, send a DELETE request to the /api/v1/databases/$DATABASE_ID/parameters endpoint. Specify the parameters to be removed as query strings directly after the endpoint.

Do not include a parameter value in the query string, only the parameter name.
The parameter name must begin with a dash (-).
Use ampersand (&) before each additional query string.

Example:

curl --insecure -X "DELETE" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/parameters?parameter=-oidcProviderClientSecret&parameter=-param_name2" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN"
                                                                    

Replace database parameters

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".

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"
  }
}'
                                                                    

Verification

To verify that the configuration has been updated, send a GET request to the /api/v1/databases/$DATABASE_ID/parameters endpoint again.

Cluster jobs

Get cluster information

To get information about clusters, send a GET request to the /api/v1/databases/$DATABASE_ID/clusters endpoint.

Copy

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

To get information about a specific cluster, send a GET request to the /api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID endpoint.

Copy

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

Add a cluster

To add a worker cluster, send a POST request to the /api/v1/databases/$DATABASE_ID/clusters endpoint and include the new cluster’s name and instance type in the payload.

Example:

Copy

curl --insecure -X "POST" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/clusters" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "worker_cluster1",
  "instanceType": "c5d.2xlarge"
}'

If the database was running when you created the new cluster, the cluster will automatically start. To manually start a cluster, see Start a Cluster.

Delete a cluster

To delete a cluster, send a DELETE request to the /api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID endpoint.

Copy

curl -k -X "DELETE" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN"

When you delete a cluster, all associated resources for the cluster are removed. The data in the data store (S3 bucket) is not deleted.

The main cluster cannot be deleted.

Scale a cluster

Vertical scaling refers to increasing or decreasing the compute power and RAM in a cluster. In an Exasol cluster deployed on AWS, vertical scaling is done by changing the EC2 instance type using the Exasol Administration API. For more information, see Sizing Guidelines.

To change the instance type for the nodes in a cluster, send a PUT request to the /api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/scale endpoint.

Example:

Copy

curl --insecure -X "PUT" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/scale" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Basic $AUTH_TOKEN" \
-d '{
"instanceType": "c5d.4xlarge"
}'

Changing the instance type will stop and restart the specified cluster. Changing the instance type for the main cluster will result in a system downtime of at least several minutes.

To scale the main cluster, you must first stop all worker clusters.

Stop a cluster

To stop a cluster, send a PUT request to the /api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/stop endpoint.

Copy

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

All worker clusters must be stopped before stopping the main cluster.

If you want to also stop the nodes after stopping the cluster, add ?stopInstances=true after the endpoint.

Copy

curl -k -X "PUT" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/stop?stopInstances=true" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN"

Start a cluster

To start a cluster, send a PUT request to the /api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/start endpoint.

Copy

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

To start a worker cluster, the main cluster must be running.

If the cluster nodes are offline and you want to start the nodes before the cluster starts up, add ?startInstances=true after the endpoint name.

Copy

curl -k -X "PUT" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/clusters/$CLUSTER_ID/start?startInstances=true" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN"

Verification

To verify your changes, send a GET request to the /api/v1/databases/$DATABASE_ID/clusters endpoint again.

Volumes

Create remote archive volume

To create a remote archive volume, send a PUT request to the /api/v1/databases/$DATABASE_ID/volumes endpoint.

Specify the url to the bucket (url), the volume name (volumeName), and the volume type (volumeType) as a part of the request.

Example:

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://my_bucket.s3.eu-west-1.amazonaws.com",
  "volumeName": "RemoteArchiveVolume1",
  "volumeType": "s3"
  "username": "$BUCKET_USER"
  "password": "$BUCKET_PASSWORD"
}'

For other storage options, use the appropriate url and volumeType. For example:

Azure Blob Storage

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://$STORAGE_CONTAINER.blob.corewindows.net/container_name",
    "volumeName": "RemoteArchiveVolume1",
    "volumeType": "azure"
    "username": "$CONTAINER_USER"
    "password": "$CONTAINER_PASSWORD"
}'

Google Cloud Storage

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://$BUCKET_NAME.storage.googleapis.com",
    "volumeName": "RemoteArchiveVolume1",
    "volumeType": "gs"
    "username": "$BUCKET_USER"
    "password": "$BUCKET_PASSWORD"
}'

FTP/FTPS

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "ftps://$FTP_SERVER:2021/$OPTIONAL_DIRECTORY/",
    "volumeName": "RemoteArchiveVolume1",
    "volumeType": "ftp"
  "username": "$FTP_USER"
  "password": "$FTP_PASSWORD"
}'

Samba

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "smb:////$SAMBA_SERVER:2139/$OPTIONAL_DIRECTORY/",
    "volumeName": "RemoteArchiveVolume1",
    "volumeType": "smb"
    "username": "$SAMBA_USER"
    "password": "$SAMBA_PASSWORD"
}'

Apache Hadoop

Copy

curl --insecure -X "POST" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/volumes" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://$HADOOP_SERVER:2080/my_backup_directory/",
    "volumeName": "RemoteArchiveVolume1",
    "volumeType": "webhdfs"
    "username": "$HADOOP_USER"
    "password": "$HADOOP_PASSWORD"
}'

The ports in the URL examples are the default ports. Most protocols allow you to set the port.

Verification

To verify that the new remote archive volume was created, send a GET request to the /api/v1/databases/$DATABASE_ID/volumes endpoint.

Copy

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

Backups

To learn more about backups, see Backup and Restore.

Run manual backup

Each backup is written to an archive volume. By default, an S3 bucket is created during deployment and configured as a remote archive volume. The name of the remote archive volume is cloud_data_remote_volume.

To get information about existing archive volumes for the database, send a GET request to the /api/v1/databases/$DATABASE_ID/volumes endpoint.

Copy

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

To create a backup, send a PUT request to the /api/v1/databases/$DATABASE_ID/backups/start endpoint and specify the backup level (level) and expiration time (expire) in the request.

The backup level parameter indicates if this is a full or incremental backup. For more information about backup types, see Backup Essentials.
The expiration time parameter determines when the backup is considered invalid and can be automatically cleaned up. Expiration time is given in the format #w #d #h #m.

Example:

Copy

curl --insecure -X "PUT" \
"https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/backups/start" \
-H "accept: application/json" \
-H "Authorization: Basic $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"backupVolumeId": 10001,
"backupVolumeName": "r0001",
"level": 0,
"expire": "1w"
}'

Abort a backup

To abort a backup that is in progress, send a PUT request to the /api/v1/databases/$DATABASE_ID/backups/abort endpoint.

Copy

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

Restore database from backup

The database must be stopped.

To get information about existing backups for a database, send a GET request to /api/v1/databases/$DATABASE_ID/backups.

Copy

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

To restore a backup, send a PUT request to the /api/v1/databases/$DATABASE_ID/backups/restore endpoint, and include the backup ID and restore type for the backup in the request.

Copy

curl -k -X "PUT" \
  "https://$NODE_IP:4444/api/v1/databases/$DATABASE_ID/backups/restore" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "backupId": "$VOLUME_ID $BACKUP_ID $DATABASE_ID",
  "restoreType": "blocking"
}'

When the backup has been successfully restored, the database will automatically start.

Licenses

Upload license

To upload a license, send a POST request to the /api/v1/license endpoint and include the path to the license file.

Copy

curl -X 'POST' --insecure "https://$NODE_IP:4444/api/v1/license" \
  -H "accept: application/json" \
  -H "Authorization: Basic $AUTH_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@$FILENAME"

Uploading a license overwrites the existing license. If you install and activate a temporary license you cannot keep the old license file inactive on the system and then reactivate it. You must upload the old license again.

The uploaded license is automatically applied after a few minutes.

API Examples

Database jobs

List database parameters

Add database parameters

Example:

Remove database parameters

Example:

Replace database parameters

Example:

Verification

Cluster jobs

Get cluster information

Add a cluster

Example:

Delete a cluster

Scale a cluster

Example:

Stop a cluster

Start a cluster

Verification

Volumes

Create remote archive volume

Example:

Verification

Backups

Run manual backup

Example:

Abort a backup

Restore database from backup

Licenses

Upload license

PRODUCT

RESOURCES