Skip to main content
Version: v4

Configuration Options

Quick reference for all harperdb-config.yaml top-level sections.

For how to apply configuration (YAML file, environment variables, CLI, Operations API), see Configuration Overview.

http​

Configures the Harper component server (HTTP, REST API, WebSocket). See HTTP Configuration for full details.

http:
  port: 9926
  securePort: 4443
  cors: true
  timeout: 120000
  mtls: false
  logging:
    level: info
    path: ~/hdb/log/http.log
  • sessionAffinity — Route requests from same client to same worker thread (ip or header name)
  • compressionThreshold — Response size threshold for Brotli compression; Default: 1200 (bytes)
  • cors — Enable CORS; Default: true
  • corsAccessList — Allowed domains for CORS requests
  • corsAccessControlAllowHeaders — Access-Control-Allow-Headers value for OPTIONS preflight
  • headersTimeout — Max wait for complete HTTP headers (ms); Default: 60000
  • maxHeaderSize — Max HTTP header size (bytes); Default: 16394
  • requestQueueLimit — Max estimated request queue time (ms) before 503; Default: 20000
  • keepAliveTimeout — Inactivity before closing keep-alive connection (ms); Default: 30000
  • port — HTTP port; Default: 9926
  • securePort — HTTPS port; requires TLS configuration; Default: null
  • http2 — Enable HTTP/2; Default: false (Added in: v4.5.0)
  • timeout — Request timeout (ms); Default: 120000
  • mtls — Enable mTLS authentication for incoming connections; sub-options: user, required, certificateVerification (see Certificate Verification)
  • logging — HTTP request logging (disabled by default, Added in: v4.6.0); sub-options: level, path, timing, headers, id. See Logging Configuration

threads​

Worker thread pool configuration.

threads:
  count: 11
  maxHeapMemory: 300
  • count — Number of worker threads; Default: CPU count minus one
  • maxHeapMemory — Heap limit per thread (MB)
  • heapSnapshotNearLimit — Take heap snapshot when approaching limit
  • debug — Enable debugging; sub-options: port, startingPort, host, waitForDebugger

authentication​

Authentication and session configuration. Added in: v4.1.0; enableSessions added in v4.2.0. See Authentication Configuration.

authentication:
  authorizeLocal: true
  cacheTTL: 30000
  enableSessions: true
  operationTokenTimeout: 1d
  refreshTokenTimeout: 30d
  • authorizeLocal — Auto-authorize loopback requests as superuser; Default: true
  • cacheTTL — Session cache duration (ms); Default: 30000
  • enableSessions — Cookie-based sessions; Default: true
  • operationTokenTimeout — Access token lifetime; Default: 1d
  • refreshTokenTimeout — Refresh token lifetime; Default: 1d
  • logging — Authentication event logging (Added in: v4.6.0); sub-options: path, level, tag, stdStreams. See Logging Configuration

operationsApi​

Harper Operations API endpoint configuration. See Operations API Overview.

operationsApi:
  network:
    port: 9925
    cors: true
  tls:
    certificate: ~/hdb/keys/certificate.pem
    privateKey: ~/hdb/keys/privateKey.pem
  • network.cors / network.corsAccessList — CORS settings
  • network.domainSocket — Unix socket path for CLI communication; Default: <rootPath>/hdb/operations-server
  • network.headersTimeout / network.keepAliveTimeout / network.timeout — Timeout settings (ms)
  • network.port — Operations API port; Default: 9925
  • network.securePort — HTTPS port; Default: null
  • tls — TLS override for the Operations API; sub-options: certificate, certificateAuthority, privateKey. See tls

tls​

Global TLS configuration for HTTPS and TLS sockets (used by HTTP and MQTT). Can be a single object or an array for SNI. See TLS and Certificate Management.

tls:
  certificate: ~/hdb/keys/certificate.pem
  certificateAuthority: ~/hdb/keys/ca.pem
  privateKey: ~/hdb/keys/privateKey.pem
  • certificate — Path to TLS certificate; Default: <rootPath>/keys/certificate.pem
  • certificateAuthority — Path to CA file; Default: <rootPath>/keys/ca.pem
  • privateKey — Path to private key; Default: <rootPath>/keys/privateKey.pem
  • ciphers — Allowed TLS cipher suites

mqtt​

MQTT protocol configuration. Added in: v4.2.0. See MQTT Configuration.

mqtt:
  network:
    port: 1883
    securePort: 8883
  webSocket: true
  requireAuthentication: true
  • network.port — Insecure MQTT port; Default: 1883
  • network.securePort — Secure MQTT port; Default: 8883
  • network.mtls — Enable mTLS for MQTT connections; sub-options: user, required, certificateAuthority, certificateVerification
  • webSocket — Enable MQTT over WebSocket on HTTP port; Default: true
  • requireAuthentication — Require credentials or mTLS; Default: true
  • logging — MQTT event logging (Added in: v4.6.0); sub-options: path, level, tag, stdStreams. See Logging Configuration

logging​

Application logging. Added in: v4.1.0; per-component logging added in v4.6.0. See Logging Configuration.

logging:
  level: warn
  root: ~/hdb/log
  stdStreams: false
  auditLog: false
  rotation:
    interval: 1D
    maxSize: 100M
  • level — Log verbosity (trace → debug → info → warn → error → fatal → notify); Default: warn
  • file — Write to file; Default: true
  • root — Log directory; Default: <rootPath>/log
  • path — Explicit log file path (overrides root)
  • stdStreams — Write to stdout/stderr; Default: false
  • console — Include console.* output; Default: true
  • auditLog — Enable table transaction audit logging; Default: false
  • auditRetention — Audit log retention duration; Default: 3d
  • external — Logging for components using the logger API; sub-options: level, path
  • rotation.enabled / rotation.compress / rotation.interval / rotation.maxSize / rotation.path — Log file rotation (activates when interval or maxSize is set)
  • auditAuthEvents.logFailed / auditAuthEvents.logSuccessful — Log failed/successful authentication events; Default: false

replication​

Native WebSocket-based replication (Plexus). Added in: v4.4.0. See Replication and Clustering.

replication:
  hostname: server-one
  url: wss://server-one:9933
  databases: '*'
  routes:
    - wss://server-two:9933
  • hostname — This instance's hostname within the cluster
  • url — WebSocket URL peers use to connect to this instance
  • databases — Databases to replicate; Default: "*" (all). Each entry supports name and sharded
  • routes — Peer nodes; URL strings or {hostname, port, startTime, revokedCertificates} objects
  • port — Replication port
  • securePort — Secure replication port; Default: 9933 (changed from 9925 in v4.5.0)
  • enableRootCAs — Verify against Node.js Mozilla CA store; Default: true
  • blobTimeout — Blob transfer timeout (ms); Default: 120000
  • failOver — Failover to alternate node if peer unreachable; Default: true
  • shard — Shard ID for traffic routing; see Sharding
  • mtls.certificateVerification — Certificate revocation checking (CRL/OCSP) for replication connections; see Certificate Verification
  • logging — Replication event logging; sub-options: path, level, tag, stdStreams. See Logging Configuration

storage​

Database storage configuration. See Database Overview and Compaction.

storage:
  path: ~/hdb/database
  caching: true
  compression: true
  compactOnStart: false
  • writeAsync — Disable disk sync for higher throughput (disables durability guarantees); Default: false
  • caching — In-memory record caching; Default: true
  • compression — LZ4 record compression; Default: true (enabled by default since v4.3.0). Sub-options: dictionary, threshold
  • compactOnStart — Compact all non-system databases on startup; Default: false (Added in: v4.3.0)
  • compactOnStartKeepBackup — Retain compaction backups; Default: false
  • maxTransactionQueueTime — Max write queue time before 503; Default: 45s
  • noReadAhead — Advise OS against read-ahead; Default: false
  • prefetchWrites — Prefetch before write transactions; Default: true
  • path — Database files directory; Default: <rootPath>/database
  • blobPaths — Blob storage directory or directories; Default: <rootPath>/blobs (Added in: v4.5.0)
  • pageSize — Database page size (bytes); Default: OS default
  • reclamation.threshold / reclamation.interval / reclamation.evictionFactor — Background storage reclamation settings (Added in: v4.5.0)

databases​

Per-database and per-table file path overrides. Must be set before the database/table is created. See Database Overview.

databases:
  myDatabase:
    path: /data/myDatabase
    auditPath: /data/myDatabase-audit
    tables:
      myTable:
        path: /data/myTable
  • <dbName>.path — Database files directory
  • <dbName>.auditPath — Audit log directory for this database
  • <dbName>.tables.<tableName>.path — Table files directory

analytics​

Analytics aggregation configuration. See Analytics Overview.

analytics:
  aggregatePeriod: 60
  replicate: false
  • aggregatePeriod — Aggregation interval (seconds); Default: 60 (Added in: v4.5.0)
  • replicate — Replicate analytics data across cluster; Default: false

localStudio​

Local Harper Studio GUI. See Studio.

localStudio:
  enabled: true
  • enabled — Enable local Studio at http://localhost:<port>; Default: false

componentsRoot​

Path to local component files. Added in: v4.2.0 (previously customFunctionsRoot). See Components.

componentsRoot: ~/hdb/components

rootPath​

Root directory for all Harper persistent data, config, logs, and components.

rootPath: /var/lib/harper

Component Configuration​

Installed components are configured directly at the root of harperdb-config.yaml using the component name as the key — not nested under a components: section. See Components.

my-component:
  package: 'HarperDB-Add-Ons/my-component'
  port: 4321
  • <component-name>.package — NPM package name, GitHub repo (user/repo), or local path
  • <component-name>.port — Port for the component; Default: value of http.port