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.
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¶meter=-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.
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:
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
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"
}'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"
}'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"
}'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"
}'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.
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.
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:
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.
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.
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.
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.
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.
