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 - The protocol used to communicate with the server.
When https or tcps used, the connection is secured with TLS encryption.
- 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.
Examples: http::addr=localhost:9000, https::addr=localhost:9000, http::addr=localhost, tcp::addr=localhost:9009
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 off. This is useful
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 use transactions. 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_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
- 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.
- copy_buffer: enum, accepted values: on, off - By default, the Sender creates a new buffer for every flush() call,
and the data to be sent to the server is copied into this new buffer.
Setting the flag to off results in reusing the same buffer instance for each flush() call.
Use this flag only if calls to the client are serialised.