Struct Sender

pub struct Sender { /* private fields */ }

Connects to a QuestDB instance and inserts data via the ILP protocol.

• To construct an instance, use Sender::from_conf or the SenderBuilder.
• To prepare messages, use Buffer objects.
• To send messages, call the flush method.

Implementations

impl Sender

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

Create a new Sender instance from the given 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.

Keys in the config string correspond to same-named methods on SenderBuilder.

For the full list of keys and values, see the docs on SenderBuilder.

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

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.

pub fn from_env() -> Result<Self>

Create a new Sender from the configuration stored in the QDB_CLIENT_CONF environment variable. The format is the same as that accepted by Sender::from_conf.

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.

pub fn flush_and_keep_with_flags( &mut self, buf: &Buffer, transactional: bool, ) -> Result<()>

Send the batch of rows in the buffer to the QuestDB server, and, if the transactional parameter is true, ensure the flush will be transactional.

A flush is transactional iff all the rows belong to the same table. This allows QuestDB to treat the flush as a single database transaction, because it doesn’t support transactions spanning multiple tables. Additionally, only ILP-over-HTTP supports transactional flushes.

If the flush wouldn’t be transactional, this function returns an error and doesn’t flush any data.

The function sends an HTTP request and waits for the response. If the server responds with an error, it returns a descriptive error. In the case of a network error, it retries until it has exhausted the retry time budget.

All the data stays in the buffer. Clear the buffer before starting a new batch.

pub fn flush_and_keep(&mut self, buf: &Buffer) -> Result<()>

Send the given buffer of rows to the QuestDB server.

All the data stays in the buffer. Clear the buffer before starting a new batch.

To send and clear in one step, call Sender::flush instead.

pub fn flush(&mut self, buf: &mut Buffer) -> Result<()>

Send the given buffer of rows to the QuestDB server, clearing the buffer.

After this function returns, the buffer is empty and ready for the next batch. If you want to preserve the buffer contents, call Sender::flush_and_keep. If you want to ensure the flush is transactional, call Sender::flush_and_keep_with_flags.

With ILP-over-HTTP, this function sends an HTTP request and waits for the response. If the server responds with an error, it returns a descriptive error. In the case of a network error, it retries until it has exhausted the retry time budget.

With ILP-over-TCP, the function blocks only until the buffer is flushed to the underlying OS-level network socket, without waiting to actually send it to the server. In the case of an error, the server will quietly disconnect: consult the server logs for error messages.

HTTP should be the first choice, but use TCP if you need to continuously send data to the server at a high rate.

To improve the HTTP performance, send larger buffers (with more rows), and consider parallelizing writes using multiple senders from multiple threads.

pub fn must_close(&self) -> bool

Tell whether the sender is no longer usable and must be dropped.

This happens when there was an earlier failure.

This method is specific to ILP-over-TCP and is not relevant for ILP-over-HTTP.

Trait Implementations

impl Debug for Sender

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

Formats the value using the given formatter.