Update JDBC docs for V2

[Paultagoras]

Summary

Added docs to support the V2 version (while keeping the V1 version of the docs)

Closes ClickHouse/clickhouse-java#1480

Checklist

• Delete items not relevant to your PR
• URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
• If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/en/integrations/index.mdx

[mshustov]

1. It's discussable. Personally, I don't think we need to create another separate entry in the docs, as JDBC v2 is an internal name. For the end user it's the same driver with some behavioural changes from version 0.8.0.
2. I didn't find a list of changes and unsupported features in JDBC starting from 0.8.0 (Transactions, for example), which is important to highlight. It's not necessarily to follow the same format, but you can see how it was done in the same JDBC driver previously https://github.com/ClickHouse/clickhouse-java/tree/v0.4.0/clickhouse-jdbc#upgrade-to-032

[laeg]

1. It's discussable. Personally, I don't think we need to create another separate entry in the docs, as JDBC v2 is an internal name. For the end user it's the same driver with some behavioural changes from version 0.8.0.

The tricky part here is the difference between a SaaS product (always showing latest rather than maintaining state) and traditional SW documentation.

But I agree with this sentiment, it also might be worth us exploring at this point how do we do "versioning" of the documentation rather than having "extra pages" - like having a version drop down and corresponding version in the URL.

Maybe we need to consider something like having JavaDocs being the "source of truth" of functionality?

At least one of the immediate things we should do is treat the sidebar as the "ideal customer journey" rather than an index. We can link in the main doc to the v1 documentation until it's deprecated.

2. I didn't find a list of changes and unsupported features in JDBC starting from 0.8.0 (Transactions, for example), which is important to highlight. It's not necessarily to follow the same format, but you can see how it was done in the same JDBC driver previously https://github.com/ClickHouse/clickhouse-java/tree/v0.4.0/clickhouse-jdbc#upgrade-to-032

I think rather than listing out all unsupported features, it would be more beneficial for a user to have a "migration guide" that has this information in and alternatives to achieving similar functionality if applicable.

[chernser]

@mshustov I think separating documents is good because:

• less confusion because information is separated by version and it is clear what should work in v2, v1
• when jdbc v1 is deprecated - we can remove v1 doc easily and revert as needed
• visit statistics.

[mshustov]

I see a few issues with docs label. should we address them from the very beginning? https://github.com/ClickHouse/clickhouse-java/issues?q=is%3Aissue%20state%3Aopen%20label%3Adocs%20label%3Ajdbc-v2

[mshustov]

we can do it a in follow-up

[mshustov]

But I agree with this sentiment, it also might be worth us exploring at this point how do we do "versioning" of the documentation rather than having "extra pages" - like having a version drop down and corresponding version in the URL.

@laeg What about using the client versioning? There will be 2 pages:

1. description: ClickHouse JDBC driver > v0.8.x (or ClickHouse JDBC driver latest)
2. description: ClickHouse JDBC driver v0.7.x

We can manually add more pages if necessary and they always transparently mapped to JDBC release version

[laeg]

yeah i would prefer if we aligned it more to release versions rather than internal code versions.

did we look into whether we could do something more elegant for versioning the docs?

[mshustov]

did we look into whether we could do something more elegant for versioning the docs?

I didn't manage to find a solution in 30min.

[mshustov]

❤️ to this section.
A minor ask: could you move it to Supported data types section?

[mshustov]

the last thing, I'd like to sort out is versioning in https://github.com/ClickHouse/clickhouse-docs/pull/3071/files#r1925045569

and (minor)moving data/time concerns to Supported types section

[laeg]

adding my comment again:

At least one of the immediate things we should do is treat the sidebar as the "ideal customer journey" rather than an index. We can link in the "v2" doc to the "v1" documentation until it's deprecated.

we can do the same for java v1 & v2 documentation

[mshustov]

At least one of the immediate things we should do is treat the sidebar as the "ideal customer journey" rather than an index. We can link in the "v2" doc to the "v1" documentation until it's deprecated.

so you want something like this?