Class SenderOptions

Sender configuration options.
Properties of the object are initialized through a configuration string.
The configuration string has the following format: protocol::key=value;key=value...
The keys are case-sensitive, the trailing semicolon is optional.
The values are validated and an error is thrown if the format is invalid.

Connection and protocol options

• protocol: enum, accepted values: http, https, tcp, tcps, ws, wss, udp - The protocol used to communicate with the server.
  WS/WSS select acknowledged QWP ingress; their connect strings use the QWP configuration schema, shared with the other QuestDB clients, and are documented in QWP.md rather than in this list. UDP selects Node-only fire-and-forget QWP datagrams and uses the options below. When https, tcps, or wss is used, the connection is secured with TLS encryption.
• protocol_version: enum, accepted values: auto, 1, 2 - The protocol version used for data serialization.
  Version 1 uses text-based serialization for all data types. Version 2 uses binary encoding for doubles and arrays.
  When set to 'auto' (default for HTTP/HTTPS), the client automatically negotiates the highest supported version with the server.
  TCP/TCPS connections default to version 1.
• addr: string - Hostname and port, separated by colon. This key is mandatory, but the port part is optional.
  If no port is specified, a default will be used.
  When the protocol is HTTP/HTTPS, the port defaults to 9000. When the protocol is TCP/TCPS, the port defaults to 9009. When the protocol is UDP, the port defaults to 9007.
  WS/WSS resolve their address through the QWP configuration schema instead, documented in QWP.md.
  
  Examples: http::addr=localhost:9000, https::addr=localhost:9000, http::addr=localhost, tcp::addr=localhost:9009, udp::addr=localhost:9007

Authentication options

• username: string - Used for authentication.
  For HTTP, Basic Authentication requires the password option.
  For TCP with JWK token authentication, token option is required.
• password: string - Password for HTTP Basic authentication, should be accompanied by the username option.
• token: string - For HTTP with Bearer authentication, this is the bearer token.
  For TCP with JWK token authentication, this is the private key part of the JWK token, and must be accompanied by the username option.

TLS options

• tls_verify: enum, accepted values: on, unsafe_off - When the HTTPS or TCPS protocols are selected, TLS encryption is used.
  By default, the Sender will verify the server's certificate, but this check can be disabled by setting this option to unsafe_off.
  This is useful in non-production environments where self-signed certificates might be used, but should be avoided in production if possible.
• tls_ca: string - Path to a file containing the root CA's certificate in PEM format.
  Can be useful when self-signed certificates are used, otherwise should not be set.

Auto flush options

• auto_flush: enum, accepted values: on, off - The Sender automatically flushes the buffer by default. This can be switched off by setting this option to off.
  When disabled, the flush() method of the Sender has to be called explicitly to make sure data is sent to the server.
  Manual buffer flushing can be useful, especially when we want to control transaction boundaries.
  When the HTTP protocol is used, each flush results in a single HTTP request, which becomes a single transaction on the server side.
  The transaction either succeeds, and all rows sent in the request are inserted; or it fails, and none of the rows make it into the database.
• auto_flush_rows: integer - The number of rows that will trigger a flush. When set to 0, row-based flushing is disabled.
  The Sender will default this parameter to 75000 rows when HTTP protocol is used, and to 600 in case of TCP protocol.
• auto_flush_bytes: integer or off - Buffered-byte threshold.
  Reaching the threshold flushes after the completed row. This option is supported by udp only; on ws/wss it belongs to the QWP configuration schema.
  Defaults to max_datagram_size, so datagrams are flushed before they outgrow the configured limit. Set it to off to disable the byte trigger.
• auto_flush_interval: integer - The number of milliseconds that will trigger a flush, default value is 1000. When set to 0, interval-based flushing is disabled.
  Note that the setting is checked only when a new row is added to the buffer. There is no timer registered to flush the buffer automatically.

Buffer sizing options

• init_buf_size: integer - Initial buffer size, defaults to 64 KiB in the Sender.
• max_buf_size: integer - Maximum buffer size, defaults to 100 MiB in the Sender.
  If the buffer would need to be extended beyond the maximum size, an error is thrown.

HTTP request specific options

• request_timeout: integer - The time in milliseconds to wait for a response from the server, set to 10 seconds by default.
  This is in addition to the calculation derived from the request_min_throughput parameter.
• request_min_throughput: integer - Minimum expected throughput in bytes per second for HTTP requests, set to 100 KiB/s seconds by default.
  If the throughput is lower than this value, the connection will time out. This is used to calculate an additional timeout on top of request_timeout. This is useful for large requests. You can set this value to 0 to disable this logic.
• retry_timeout: integer - The time in milliseconds to continue retrying after a failed HTTP request, set to 10 seconds by default.
  The interval between retries is an exponential backoff starting at 10ms and doubling after each failed attempt up to a maximum of 1 second.

Other options

• stdlib_http: enum, accepted values: on, off - With HTTP protocol the Undici library is used by default. By setting this option to on the client switches to node's core http and https modules.
• max_name_len: integer - The maximum length of a table or column name, the Sender defaults this parameter to 127.
  Recommended to use the same setting as the server, which also uses 127 by default.

UDP specific options

• max_datagram_size: integer - Maximum encoded datagram size in bytes, from 1 to 65507, defaults to 1400.
  A row that cannot fit a single datagram is rejected before transmission. It is also the default for auto_flush_bytes. Supported by the udp transport only. A connection string rejects it on every other transport, and ws/wss reject it however the sender was built.
  65507 is the IPv4 maximum, but many hosts refuse well below it, so keep this at or under the path MTU unless the receiver is known to accept more. A datagram the operating system refuses is discarded before transmission and does not advance the published or acknowledged sequence.
• multicast_ttl: integer - Multicast time-to-live for outgoing datagrams, from 0 to 255, defaults to 0.
  Supported by the udp transport only. A connection string rejects it on every other transport, and ws/wss reject it however the sender was built.