Utilities

Restart

Restarts the Harper instance.

Operation is restricted to super_user roles only

• operation (required) - must always be restart

Body

{
  "operation": "restart"
}

Response: 200

{
  "message": "Restarting HarperDB. This may take up to 60 seconds."
}

---

Restart Service

Restarts servers for the specified Harper service.

Operation is restricted to super_user roles only

• operation (required) - must always be restart_service

• service (required) - must be one of: http_workers, clustering_config or clustering

• replicated (optional) - must be a boolean. If set to true, Harper will replicate the restart service operation across all nodes in the cluster. The restart will occur as a rolling restart, ensuring that each node is fully restarted before the next node begins restarting.

Body

{
  "operation": "restart_service",
  "service": "http_workers"
}

Response: 200

{
  "message": "Restarting http_workers"
}

---

System Information

Returns detailed metrics on the host system.

Operation is restricted to super_user roles only

• operation (required) - must always be system_information

• attributes (optional) - string array of top level attributes desired in the response, if no value is supplied all attributes will be returned. Available attributes are: ['system', 'time', 'cpu', 'memory', 'disk', 'network', 'harperdb_processes', 'table_size', 'metrics', 'threads', 'replication']

Body

{
  "operation": "system_information"
}

---

Delete Records Before

Delete data before the specified timestamp on the specified database table exclusively on the node where it is executed. Any clustered nodes with replicated data will retain that data.

Operation is restricted to super_user roles only

• operation (required) - must always be delete_records_before

• date (required) - records older than this date will be deleted. Supported format looks like: YYYY-MM-DDThh:mm:ss.sZ

• schema (required) - name of the schema where you are deleting your data

• table (required) - name of the table where you are deleting your data

Body

{
  "operation": "delete_records_before",
  "date": "2021-01-25T23:05:27.464",
  "schema": "dev",
  "table": "breed"
}

Response: 200

{
  "message": "Starting job with id d3aed926-e9fe-4ec1-aea7-0fb4451bd373",
  "job_id": "d3aed926-e9fe-4ec1-aea7-0fb4451bd373"
}

---

Export Local

Exports data based on a given search operation to a local file in JSON or CSV format.

• operation (required) - must always be export_local

• format (required) - the format you wish to export the data, options are json & csv

• path (required) - path local to the server to export the data

• search_operation (required) - search_operation of search_by_hash, search_by_value, search_by_conditions or sql

• filename (optional) - the name of the file where your export will be written to (do not include extension in filename). If one is not provided it will be autogenerated based on the epoch.

Body

{
  "operation": "export_local",
  "format": "json",
  "path": "/data/",
  "search_operation": {
      "operation": "sql",
      "sql": "SELECT * FROM dev.breed"
  }
}

Response: 200

{
  "message": "Starting job with id 6fc18eaa-3504-4374-815c-44840a12e7e5"
}

---

Export To S3

Exports data based on a given search operation from table to AWS S3 in JSON or CSV format.

• operation (required) - must always be export_to_s3

• format (required) - the format you wish to export the data, options are json & csv

• s3 (required) - details your access keys, bucket, bucket region and key for saving the data to S3

• search_operation (required) - search_operation of search_by_hash, search_by_value, search_by_conditions or sql

Body

{
    "operation": "export_to_s3",
    "format": "json",
    "s3": {
        "aws_access_key_id": "YOUR_KEY",
        "aws_secret_access_key": "YOUR_SECRET_KEY",
        "bucket": "BUCKET_NAME",
        "key": "OBJECT_NAME",
        "region": "BUCKET_REGION"
    },
    "search_operation": {
        "operation": "sql",
        "sql": "SELECT * FROM dev.dog"
    }
}

Response: 200

{
  "message": "Starting job with id 9fa85968-4cb1-4008-976e-506c4b13fc4a",
  "job_id": "9fa85968-4cb1-4008-976e-506c4b13fc4a"
}

---

Install Node Modules

This operation is deprecated, as it is handled automatically by deploy_component and restart. Executes npm install against specified custom function projects.

Operation is restricted to super_user roles only

• operation (required) - must always be install_node_modules

• projects (required) - must ba an array of custom functions projects.

• dry_run (optional) - refers to the npm --dry-run flag: https://docs.npmjs.com/cli/v8/commands/npm-install#dry-run. Defaults to false.

Body

{
  "operation": "install_node_modules",
  "projects": [
    "dogs",
    "cats"
  ],
  "dry_run": true
}

---

Set Configuration

Modifies the Harper configuration file parameters. Must follow with a restart or restart_service operation.

Operation is restricted to super_user roles only

• operation (required) - must always be set_configuration

• logging_level (example/optional) - one or more configuration keywords to be updated in the Harper configuration file

• clustering_enabled (example/optional) - one or more configuration keywords to be updated in the Harper configuration file

Body

{
  "operation": "set_configuration",
  "logging_level": "trace",
  "clustering_enabled": true
}

Response: 200

{
  "message": "Configuration successfully set. You must restart HarperDB for new config settings to take effect."
}

---

Get Configuration

Returns the Harper configuration parameters.

Operation is restricted to super_user roles only

• operation (required) - must always be get_configuration

Body

{
  "operation": "get_configuration"
}

Response: 200

{
  "http": {
    "compressionThreshold": 1200,
    "cors": false,
    "corsAccessList": [
      null
    ],
    "keepAliveTimeout": 30000,
    "port": 9926,
    "securePort": null,
    "timeout": 120000
  },
  "threads": 11,
  "authentication": {
    "cacheTTL": 30000,
    "enableSessions": true,
    "operationTokenTimeout": "1d",
    "refreshTokenTimeout": "30d"
  },
  "analytics": {
    "aggregatePeriod": 60
  },
  "replication": {
    "hostname": "node1",
    "databases": "*",
    "routes": null,
    "url": "wss://127.0.0.1:9925"
  },
  "componentsRoot": "/Users/hdb/components",
  "localStudio": {
    "enabled": false
  },
  "logging": {
    "auditAuthEvents": {
      "logFailed": false,
      "logSuccessful": false
    },
    "auditLog": true,
    "auditRetention": "3d",
    "file": true,
    "level": "error",
    "root": "/Users/hdb/log",
    "rotation": {
      "enabled": false,
      "compress": false,
      "interval": null,
      "maxSize": null,
      "path": "/Users/hdb/log"
    },
    "stdStreams": false
  },
  "mqtt": {
    "network": {
      "port": 1883,
      "securePort": 8883
    },
    "webSocket": true,
    "requireAuthentication": true
  },
  "operationsApi": {
    "network": {
      "cors": true,
      "corsAccessList": [
        "*"
      ],
      "domainSocket": "/Users/hdb/operations-server",
      "port": 9925,
      "securePort": null
    }
  },
  "rootPath": "/Users/hdb",
  "storage": {
    "writeAsync": false,
    "caching": true,
    "compression": false,
    "noReadAhead": true,
    "path": "/Users/hdb/database",
    "prefetchWrites": true
  },
  "tls": {
    "privateKey": "/Users/hdb/keys/privateKey.pem"
  }
}

---

Add Certificate

Adds or updates a certificate in the hdb_certificate system table. If a private_key is provided it will not be stored in hdb_certificate, it will be written to file in <ROOTPATH>/keys/. If a private_key is not passed the operation will search for one that matches the certificate. If one is not found an error will be returned.

Operation is restricted to super_user roles only

• operation (required) - must always be add_certificate

• name (required) - a unique name for the certificate

• certificate (required) - a PEM formatted certificate string

• is_authority (required) - a boolean indicating if the certificate is a certificate authority

• hosts (optional) - an array of hostnames that the certificate is valid for

• private_key (optional) - a PEM formatted private key string

Body

{
  "operation": "add_certificate",
  "name": "my-cert",
  "certificate": "-----BEGIN CERTIFICATE-----ZDFAay... -----END CERTIFICATE-----",
  "is_authority": false,
  "private_key": "-----BEGIN RSA PRIVATE KEY-----Y4dMpw5f... -----END RSA PRIVATE KEY-----"
}

Response: 200

{
  "message": "Successfully added certificate: my-cert"
}

---

Remove Certificate

Removes a certificate from the hdb_certificate system table and deletes the corresponding private key file.

Operation is restricted to super_user roles only

• operation (required) - must always be remove_certificate

• name (required) - the name of the certificate

Body

{
  "operation": "remove_certificate",
  "name": "my-cert"
}

Response: 200

{
  "message": "Successfully removed my-cert"
}

---

List Certificates

Lists all certificates in the hdb_certificate system table.

Operation is restricted to super_user roles only

• operation (required) - must always be list_certificates

Body

{
  "operation": "list_certificates"
}

Response: 200

[
  {
    "name": "HarperDB-Certificate-Authority-node1",
    "certificate": "-----BEGIN CERTIFICATE-----\r\nTANBgkqhk... S34==\r\n-----END CERTIFICATE-----\r\n",
    "private_key_name": "privateKey.pem",
    "is_authority": true,
    "details": {
      "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.",
      "subject": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.",
      "serial_number": "5235345",
      "valid_from": "Aug 27 15:00:00 2024 GMT",
      "valid_to": "Aug 25 15:00:00 2034 GMT"
    },
    "is_self_signed": true,
    "uses": [
      "https",
      "wss"
    ]
  },
  {
    "name": "node1",
    "certificate": "-----BEGIN CERTIFICATE-----\r\ngIEcSR1M... 5bv==\r\n-----END CERTIFICATE-----\r\n",
    "private_key_name": "privateKey.pem",
    "is_authority": false,
    "details": {
      "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.",
      "subject": "CN=node.1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.",
      "subject_alt_name": "IP Address:127.0.0.1, DNS:localhost, IP Address:0:0:0:0:0:0:0:1, DNS:node.1",
      "serial_number": "5243646",
      "valid_from": "Aug 27 15:00:00 2024 GMT",
      "valid_to": "Aug 25 15:00:00 2034 GMT"
    },
    "is_self_signed": true,
    "uses": [
      "https",
      "wss"
    ]
  }
]