Add support for appending queries in sql based connectors

[Jessie212]

Description

Document added support for appending queries with context in sql based connectors.

Additional context and related issues

#14500

Release notes

(x) This is not user-visible or docs only and no release notes are required.
( ) Release notes are required, please propose a release note for me.
( ) Release notes are required, with the following suggested text:

# Section
* Fix some things. ({issue}`issuenumber`)

[Jessie212]

Hello, @s2lomon I need to document this feature and am hoping you can assist me. What must a user do to implement this?

[ebyhr]

cc: @kokosing @Praveen2112

[kokosing]

@hashhar Can you please help here?

[hashhar]

Ack, I'll share a short summary here later today.

[posulliv]

@Jessie212 we've been using this in production so figured I would share my notes on it.

We have been using it with Oracle and SQLServer but any JDBC based connector supports it.

The config we are using in our catalog properties is:

query.comment-format=$QUERY_ID,$SOURCE,$USER

$QUERY_ID, $SOURCE, and $USER are replaced with the relevant values when the comment is appended to the SQL sent to the underlying data source.

You can specify any format for the query comment; we just chose to go with a comma-separated format.

There is also an ability to add a $TRACE_TOKEN but we are not using that at the moment.

[hashhar]

To add some more context, if query.comment-format is set to a non-blank value (default is blank, i.e. this feature is disabled) then all occurrences of $QUERY_ID, $SOURCE, $USER and $TRACE_TOKEN in the query.comment-format are replaced with actual values and pre-pended to the query we send to remote database.

As example with query.comment-format=query_id: $QUERY_ID, source: $SOURCE, username: $USER, may your query succeed each query sent to remote database will look like:

/* query_id: <query_id>, source: <source>, username: <user>, may your query succeed */ <actual_query_sent_by_trino>

The goal is to allow admins to log query on the datasource so they can correlate which queries come from where and are part of which query id on Trino side.

[wendigo]

Actually I believe that the comment is added at the end of the query @hashhar and there are no spaces between /* and */

[hashhar]

oh yes, it gets appended to the end https://github.com/trinodb/trino/pull/14500/files#diff-45098b72713117f087df848fb61feb4d1b6a26e84113908efba191743d6f50aeR48

So <actual_query_sent_by_trino> /*query_id: <query_id>, source: <source>, username: <user>, may your query succeed*/ in the above example. Thanks for the correction.

[s2lomon]

I think that also it's good to mention, that since it's a standard Trino property, we can add env vars to the format, enriching the meta information about the requests.

[Jessie212]

I'm not sure we need this level of explanation or if examples are necessary, but that depends on where this content ends up.

[Jessie212]

I've cautiously added the content as a fragment, and applied it to the SQL Server and Oracle connectors. I would like to know if it's safe to include this fragment to the rest of the JDBC connectors?

[kokosing]

I would like to know if it's safe to include this fragment to the rest of the JDBC connectors?

That is tricky question. From point of view Trino the same code applies to all JDBC connectors. However it is vendor specific as this appendix can be removed either by vendor specific JDBC driver or logging of the query could lose it.

We can either add it to all and risk that some of them are actually not supported. Or safely document only those that we are sure that are supported. I would prefer the former.

[mosabua]

I agree with @kokosing .. we should put the burden on the user and document them for all connectors where it applies with a warning that it might not work for the reasons he outlines. Users can then test and confirm. Also ... it might work in some scenarios with a connector and not work with the same connector in others..

[mosabua]

Please reword or set up a meeting with me to collaborate @Jessie212

[mosabua]

Please squash commits and improve commit message @Jessie212