client: add BeginInsert(const Query&) overload

[iliaal]

Add Block BeginInsert(const Query& query).

The Impl already supported a fully-configured Query (settings, params, query_id, OnData, etc.). The public surface only exposed the string forms.

This lets callers do proper streaming inserts with the full Query feature set (symmetric to the Query forms already available for Select/Execute).

[slabko]

Why should we take away a part of existing API on which people probably relay? Can BeginInsert(const Query& query) be an addition to the exiting functions?

[slabko]

The main reason BeginInsert does not take a Query as a parameter is that Query instances are much more than just a query string and a query ID. They also contain a number of event handlers. These event handlers add significant complexity to the API, and it is not entirely clear how they should be handled in this context.

To avoid this issue, the decision was made not to expose the Query object in such cases. I still stand by that decision because exposing it would create an unforeseen set of use cases that people would come to rely on, making them difficult to support in the future. I am not comfortable extending the API surface area that far just yet.

If you can explain why you need it, we might try to find another solution to it.

[iliaal]

The driver is per-insert settings, not the handlers.

In my binding every streaming insert attaches Query::SetSetting(...) (async_insert, format settings, plus per-call overrides) and then calls BeginInsert. With only the string forms there's no way to scope settings to a single insert. I'd have to mutate the connection's global settings, which then leak into the next query on the same handle. The Query overload is the only way to pass settings (and bound parameters) without that shared state.

On the handlers: BeginInsert already neutralizes them. Impl::BeginInsert overwrites the caller's OnData with its own block-capture lambda, and the EnsureNull guard resets events_ to null the moment BeginInsert returns. So no handler on the passed Query survives into the SendInsertBlock/EndInsert phase. The data path runs without callbacks regardless of what the Query carries. The only window anything fires is the initial handshake inside BeginInsert, and even there OnData is replaced.

If exposing the full Query still feels too broad, an overload taking just Settings (and query_id) covers my case without touching the callback surface. Happy to go either way.

[slabko]

The data path runs without callbacks regardless of what the Query carries. The only window anything fires is the initial handshake inside BeginInsert, and even there OnData is replaced.

I'm not sure that's entirely true. The first thing that comes to mind is a server exception.

If we go down this route, could we throw an exception stating that Query callbacks are not supported for BeginInsert whenever any Query callback is set?