Struct SenderBuilder

pub struct SenderBuilder { /* private fields */ }

Accumulates parameters for a new Sender instance.

You can also create the builder from a config string or the QDB_CLIENT_CONF environment variable.

use questdb::ingress::{Protocol, SenderBuilder};
let mut sender = SenderBuilder::new(Protocol::Http, "localhost", 9009).build()?;

use questdb::ingress::{Protocol, SenderBuilder};

let mut sender = SenderBuilder::new(Protocol::Tcp, "localhost", 9009).build()?;

use questdb::ingress::SenderBuilder;

let mut sender = SenderBuilder::from_conf("https::addr=localhost:9000;")?.build()?;

use questdb::ingress::SenderBuilder;

// export QDB_CLIENT_CONF="https::addr=localhost:9000;"
let mut sender = SenderBuilder::from_env()?.build()?;

Implementations

impl SenderBuilder

pub fn from_conf<T: AsRef<str>>(conf: T) -> Result<Self>

Create a new SenderBuilder instance from the configuration string.

The format of the string is: "http::addr=host:port;key=value;...;".

Instead of "http", you can also specify "https", "tcp", and "tcps".

We recommend HTTP for most cases because it provides more features, like reporting errors to the client and supporting transaction control. TCP can sometimes be faster in higher-latency networks, but misses a number of features.

The accepted keys match one-for-one with the methods on SenderBuilder. For example, this is a valid configuration string:

“https::addr=host:port;username=alice;password=secret;”

and there are matching methods SenderBuilder::username and SenderBuilder::password. The value of addr= is supplied directly to the SenderBuilder constructor, so there’s no matching method for that.

You can also load the configuration from an environment variable. See SenderBuilder::from_env.

Once you have a SenderBuilder instance, you can further customize it before calling SenderBuilder::build, but you can’t change any settings that are already set in the config string.

pub fn from_env() -> Result<Self>

Create a new SenderBuilder instance from the configuration from the configuration stored in the QDB_CLIENT_CONF environment variable.

The format of the string is the same as for SenderBuilder::from_conf.

pub fn new<H: Into<String>, P: Into<Port>>( protocol: Protocol, host: H, port: P, ) -> Self

Create a new SenderBuilder instance with the provided QuestDB server and port, using ILP over the specified protocol.

use questdb::ingress::{Protocol, SenderBuilder};

let mut sender = SenderBuilder::new(
    Protocol::Tcp, "localhost", 9009).build()?;

pub fn bind_interface<I: Into<String>>(self, addr: I) -> Result<Self>

Select local outbound interface.

This may be relevant if your machine has multiple network interfaces.

The default is "0.0.0.0".

pub fn username(self, username: &str) -> Result<Self>

Set the username for authentication.

For TCP, this is the kid part of the ECDSA key set. The other fields are token, token_x, and token_y.

For HTTP, this is a part of basic authentication. See also: password.

pub fn password(self, password: &str) -> Result<Self>

Set the password for basic HTTP authentication. See also: username.

pub fn token(self, token: &str) -> Result<Self>

Set the Token (Bearer) Authentication parameter for HTTP, or the ECDSA private key for TCP authentication.

pub fn token_x(self, token_x: &str) -> Result<Self>

Set the ECDSA public key X for TCP authentication.

pub fn token_y(self, token_y: &str) -> Result<Self>

Set the ECDSA public key Y for TCP authentication.

pub fn auth_timeout(self, value: Duration) -> Result<Self>

Configure how long to wait for messages from the QuestDB server during the TLS handshake and authentication process. This only applies to TCP. The default is 15 seconds.

pub fn ensure_tls_enabled(&self, property: &str) -> Result<()>

Ensure that TLS is enabled for the protocol.

pub fn tls_verify(self, verify: bool) -> Result<Self>

Set to false to disable TLS certificate verification. This should only be used for debugging purposes as it reduces security.

For testing, consider specifying a path to a .pem file instead via the tls_roots method.

pub fn tls_ca(self, ca: CertificateAuthority) -> Result<Self>

Specify where to find the root certificate used to validate the server’s TLS certificate.

pub fn tls_roots<P: Into<PathBuf>>(self, path: P) -> Result<Self>

Set the path to a custom root certificate .pem file. This is used to validate the server’s certificate during the TLS handshake.

See notes on how to test with self-signed certificates.

pub fn max_buf_size(self, value: usize) -> Result<Self>

The maximum buffer size in bytes that the client will flush to the server. The default is 100 MiB.

pub fn retry_timeout(self, value: Duration) -> Result<Self>

Set the cumulative duration spent in retries. The value is in milliseconds, and the default is 10 seconds.

pub fn request_min_throughput(self, value: u64) -> Result<Self>

Set the minimum acceptable throughput while sending a buffer to the server. The sender will divide the payload size by this number to determine for how long to keep sending the payload before timing out. The value is in bytes per second, and the default is 100 KiB/s. The timeout calculated from minimum throughput is adedd to the value of request_timeout to get the total timeout value. A value of 0 disables this feature, so it’s similar to setting “infinite” minimum throughput. The total timeout will then be equal to request_timeout.

pub fn request_timeout(self, value: Duration) -> Result<Self>

Additional time to wait on top of that calculated from the minimum throughput. This accounts for the fixed latency of the HTTP request-response roundtrip. The default is 10 seconds. See also: request_min_throughput.

pub fn build(&self) -> Result<Sender>

Build the sender.

In the case of TCP, this synchronously establishes the TCP connection, and returns once the connection is fully established. If the connection requires authentication or TLS, these will also be completed before returning.

Trait Implementations

impl Clone for SenderBuilder

fn clone(&self) -> SenderBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SenderBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.