From 01355fe985c203986ecc1dc3d8d315abb2672a1b Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 1 Apr 2025 13:42:20 +0200 Subject: [PATCH 01/14] add a component to support client versioning --- .../language-clients/java/jdbc.md | 4 +- .../ClientVersionDropdown.js | 109 ++++++++++++++++++ .../ClientVersionDropdown/styles.module.css | 56 +++++++++ 3 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 src/theme/ClientVersionDropdown/ClientVersionDropdown.js create mode 100644 src/theme/ClientVersionDropdown/styles.module.css diff --git a/docs/integrations/language-clients/java/jdbc.md b/docs/integrations/language-clients/java/jdbc.md index 3220a71a47d..f47a30fce09 100644 --- a/docs/integrations/language-clients/java/jdbc.md +++ b/docs/integrations/language-clients/java/jdbc.md @@ -10,10 +10,12 @@ title: 'JDBC Driver (0.8+)' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; - +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' # JDBC Driver (0.8+) + + `clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md). We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical. diff --git a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js new file mode 100644 index 00000000000..ed5daf2d924 --- /dev/null +++ b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js @@ -0,0 +1,109 @@ +import React, {useState, useEffect, useRef} from 'react'; +import Link from '@docusaurus/Link'; +import styles from './styles.module.css' +import ReactDOM from 'react-dom'; + +const ClientVersionDropdown = () => { + + const [displayDropdown, setDisplayDropdown] = useState(false) + const [dropdownPosition, setDropdownPosition] = useState({top: 0, left: 0}); + const buttonRef = useRef(null); + const onClickHandler = () => { + setDisplayDropdown(!displayDropdown) + } + + // Calculate and update dropdown position when it's displayed + useEffect(()=> { + if (displayDropdown && buttonRef.current) { + const buttonRect = buttonRef.current.getBoundingClientRect(); + setDropdownPosition({ + top: buttonRect.bottom + window.scrollY, + left: buttonRect.left + window.scrollX + }) + } + }, [displayDropdown]) + + // Close the dropdown menu when clicking outside + useEffect(()=>{ + const handleClickOutside = (event) => { + if (buttonRef.current && !buttonRef.current.contains(event.target)) + setDisplayDropdown(false); + }; + + if (displayDropdown) { + document.addEventListener('mousedown', handleClickOutside); + } + + return () => { + document.removeEventListener('mousedown', handleClickOutside) + } + }, [displayDropdown]) + + const items = [ + { + 'version': 'v0.8+', + 'slug': '/integrations/language-clients/java/jdbc' + }, + { + 'version': 'v0.7.x', + 'slug': '/integrations/language-clients/java/jdbc-v1' + }, + ] + + // Render dropdown menu in a portal + const renderDropdown = () => { + if (!displayDropdown) return null; + + const dropdownStyle = { + position: 'absolute', + top: `${dropdownPosition.top}px`, + left: `${dropdownPosition.left}px`, + backgroundColor: 'white', + border: '1px solid #ccc', + borderRadius: '4px', + boxShadow: '0 2px 10px rgba(0,0,0,0.1)', + zIndex: 1000, + minWidth: '120px' + }; + + return ReactDOM.createPortal( +
+ {items.map((item, index) => ( + + {item.version} + + ))} +
, + document.body + ); + + } + + return( + <> +
+
+ {items[0]["version"]} +
+ +
+ + {renderDropdown()} + + ) +} + +export default ClientVersionDropdown \ No newline at end of file diff --git a/src/theme/ClientVersionDropdown/styles.module.css b/src/theme/ClientVersionDropdown/styles.module.css new file mode 100644 index 00000000000..04b8e1c3f40 --- /dev/null +++ b/src/theme/ClientVersionDropdown/styles.module.css @@ -0,0 +1,56 @@ +/* Styling of the top level container */ + +.dropDownButton { + display: flex; + margin-bottom: 24px; + align-items: center; + width: fit-content; + cursor: pointer; + border-style: solid; + border-width: 1px; + border-radius: 10px; + padding: 0px 15px 0px 10px; +} + +.versionText{ + +} + +/* Styling of the triangle in the dropdown button */ + +.triangle { + position: relative; + display: inline-block; + margin-right: 5px; +} + +.triangle::after { + content: ""; + position: absolute; + top: 50%; + right: -15px; /* Adjust as needed */ + width: 0; + height: 0; + border-left: 5px solid transparent; + border-right: 5px solid transparent; + transform: translateY(-50%); +} + +[data-theme='dark'] .triangle::after { + border-top: 5px solid #ffff; /* Color of triangle */ +} + +[data-theme='light'] .triangle::after { + border-top: 5px solid #000; /* Color of triangle */ +} + +.dropdownItem { + display: block; + padding: 8px 16px; + text-decoration: none; + color: black; +} + +.dropdownItem:hover { + background-color: #f5f5f5; +} From d55089d4d2970380515fce4e61fd8b6e60bf8491 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 1 Apr 2025 13:42:36 +0200 Subject: [PATCH 02/14] update client page with versioning dropdown --- docs/integrations/language-clients/java/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/language-clients/java/index.md b/docs/integrations/language-clients/java/index.md index 729729f9d33..27154a99b31 100644 --- a/docs/integrations/language-clients/java/index.md +++ b/docs/integrations/language-clients/java/index.md @@ -12,7 +12,7 @@ import CodeBlock from '@theme/CodeBlock'; # Java Clients Overview - [Client 0.8+](./client.md) -- [JDBC 0.8+](./jdbc.md) +- [JDBC 0.8+](./jdbc) - [R2DBC Driver](./r2dbc.md) ## ClickHouse Client {#clickhouse-client} From 558acb094e7d5270a983c007975804cbbfff1360 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 1 Apr 2025 16:21:11 +0200 Subject: [PATCH 03/14] add ClientVersioningDropdown --- .../language-clients/java/jdbc-v1.md | 14 ++++- .../language-clients/java/jdbc.md | 15 +++-- .../ClientVersionDropdown.js | 61 +++++++++++-------- .../ClientVersionDropdown/styles.module.css | 17 ++++++ 4 files changed, 76 insertions(+), 31 deletions(-) diff --git a/docs/integrations/language-clients/java/jdbc-v1.md b/docs/integrations/language-clients/java/jdbc-v1.md index ac6ab4a9dc0..7e01649ebdc 100644 --- a/docs/integrations/language-clients/java/jdbc-v1.md +++ b/docs/integrations/language-clients/java/jdbc-v1.md @@ -2,15 +2,27 @@ title: 'JDBC Driver' description: 'Page describing the JDBC driver for ClickHouse' slug: /integrations/language-clients/java/jdbc-v1 +displayed_sidebar: integrations --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; - +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' # JDBC Driver + + `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/integrations/sql-clients/sql-console), it provides additional features like custom type mapping, transaction support, and standard synchronous `UPDATE` and `DELETE` statements, etc., so that it can be easily used with legacy applications and tools. :::note diff --git a/docs/integrations/language-clients/java/jdbc.md b/docs/integrations/language-clients/java/jdbc.md index f47a30fce09..641714af3f0 100644 --- a/docs/integrations/language-clients/java/jdbc.md +++ b/docs/integrations/language-clients/java/jdbc.md @@ -14,15 +14,20 @@ import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDro # JDBC Driver (0.8+) - + `clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md). We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical. -:::note -If you're looking for a prior version of the JDBC driver docs, please see [here](/integrations/language-clients/java/jdbc-v1.md). -::: - ## Changes from 0.7.x {#changes-from-07x} In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you: diff --git a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js index ed5daf2d924..b060df5c4ad 100644 --- a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js +++ b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js @@ -2,16 +2,30 @@ import React, {useState, useEffect, useRef} from 'react'; import Link from '@docusaurus/Link'; import styles from './styles.module.css' import ReactDOM from 'react-dom'; +import {useHistory} from "react-router-dom"; -const ClientVersionDropdown = () => { +const ClientVersionDropdown = (props) => { + const history = useHistory() const [displayDropdown, setDisplayDropdown] = useState(false) const [dropdownPosition, setDropdownPosition] = useState({top: 0, left: 0}); const buttonRef = useRef(null); + const dropdownRef = useRef(null); + const onClickHandler = () => { setDisplayDropdown(!displayDropdown) } + const handleLinkClick = (e, slug) => { + e.preventDefault(); + + // Navigate after a slight delay to ensure the click event completes + setTimeout(() => { + setDisplayDropdown(false); + history.push(slug); + }, 10); + }; + // Calculate and update dropdown position when it's displayed useEffect(()=> { if (displayDropdown && buttonRef.current) { @@ -26,8 +40,18 @@ const ClientVersionDropdown = () => { // Close the dropdown menu when clicking outside useEffect(()=>{ const handleClickOutside = (event) => { - if (buttonRef.current && !buttonRef.current.contains(event.target)) + + if (dropdownRef.current && dropdownRef.current.contains(event.target)) { + if (event.target.tagName === 'A') { + return; + } + } + + // Otherwise close if clicked outside button or dropdown + if (buttonRef.current && !buttonRef.current.contains(event.target) && + dropdownRef.current && !dropdownRef.current.contains(event.target)) { setDisplayDropdown(false); + } }; if (displayDropdown) { @@ -39,36 +63,22 @@ const ClientVersionDropdown = () => { } }, [displayDropdown]) - const items = [ - { - 'version': 'v0.8+', - 'slug': '/integrations/language-clients/java/jdbc' - }, - { - 'version': 'v0.7.x', - 'slug': '/integrations/language-clients/java/jdbc-v1' - }, - ] - // Render dropdown menu in a portal const renderDropdown = () => { if (!displayDropdown) return null; - const dropdownStyle = { - position: 'absolute', + const dropdownStyleDynamic = { top: `${dropdownPosition.top}px`, left: `${dropdownPosition.left}px`, - backgroundColor: 'white', - border: '1px solid #ccc', - borderRadius: '4px', - boxShadow: '0 2px 10px rgba(0,0,0,0.1)', - zIndex: 1000, - minWidth: '120px' }; return ReactDOM.createPortal( -
- {items.map((item, index) => ( +
+ {props.versions.map((item, index) => ( { textDecoration: 'none', color: 'inherit' }} + onClick={(e) => handleLinkClick(e, item.slug)} > {item.version} @@ -96,7 +107,7 @@ const ClientVersionDropdown = () => { ref={buttonRef} >
- {items[0]["version"]} + {props.versions[0]["version"]}
@@ -106,4 +117,4 @@ const ClientVersionDropdown = () => { ) } -export default ClientVersionDropdown \ No newline at end of file +export default ClientVersionDropdown diff --git a/src/theme/ClientVersionDropdown/styles.module.css b/src/theme/ClientVersionDropdown/styles.module.css index 04b8e1c3f40..b110e13f33e 100644 --- a/src/theme/ClientVersionDropdown/styles.module.css +++ b/src/theme/ClientVersionDropdown/styles.module.css @@ -54,3 +54,20 @@ .dropdownItem:hover { background-color: #f5f5f5; } + +.dropdownStyleStatic { + position: absolute; + margin-top: 2px; + border-radius: 4px; + box-shadow: 0 2px 10px rgba(0,0,0,0.1); + z-index: 1000; + +} + +[data-theme='dark'] .dropdownStyleStatic { + background-color: #3c3c3c; +} + +[data-theme='light'] .dropdownStyleStatic { + background-color: white; +} From 70c3f22346972048b96a4fa52a54e8964b0d5664 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 1 Apr 2025 16:33:23 +0200 Subject: [PATCH 04/14] update style guide --- contribute/style-guide.md | 43 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/contribute/style-guide.md b/contribute/style-guide.md index 7b694031df7..df077b8e53a 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -250,3 +250,46 @@ should pass. Finally open another PR on the docs repo again to remove the file from the exception list and add it to `sidebars.js` in the appropriate sidebar. +## Client versioning + +Docusaurus supports versioning documentation, however it is opinionated and +aimed more at use cases where you have a single product with set releases, or +multiple products with their own releases. + +Due to the fact that we have many +different integrations in ClickHouse, each of which may need versioned documentation, +we use the following custom `ClientVersionDropdown` component for versioning of +client documentation: + +```markdown + +``` + +To use this component, import it into the markdown page: + +```markdown +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' +``` + +Add it underneath the H1 element on the page and pass it an array of objects +representing versions and the slug of the page: + +```markdown +# JDBC Driver (0.8+) + + +``` + +Note that the component will display the first item as the 'selected' version, so +it is important to make sure the order of the objects is correct. + +Add this component on every 'versioned' page for the client. From 86908192493c339e40262581a7b3095a1ba4e4b9 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 1 Apr 2025 16:36:47 +0200 Subject: [PATCH 05/14] update style guide to mention need to add displayed_sidebar to old version pages --- contribute/style-guide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/contribute/style-guide.md b/contribute/style-guide.md index df077b8e53a..dd1df0e4f7f 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -293,3 +293,12 @@ Note that the component will display the first item as the 'selected' version, s it is important to make sure the order of the objects is correct. Add this component on every 'versioned' page for the client. + +In addition, add to every 'archived' version page the following frontmatter item: + +```markdown +displayed_sidebar: integrations +``` + +This will make sure that the sidebar displays, even if this particular page is +not shown in the sidebar. From 6ee9c713fac18319e44b5e41886efbf885093fff Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 22 Apr 2025 12:20:25 +0200 Subject: [PATCH 06/14] add version component to java client --- .../language-clients/java/client-v1.md | 16 ++++++++++++-- .../language-clients/java/client.md | 22 +++++++++++++------ 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/integrations/language-clients/java/client-v1.md b/docs/integrations/language-clients/java/client-v1.md index 7c46aa250e9..13cf9557dda 100644 --- a/docs/integrations/language-clients/java/client-v1.md +++ b/docs/integrations/language-clients/java/client-v1.md @@ -7,8 +7,20 @@ slug: /integrations/language-clients/java/client-v1 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; - -# Client (0.7.x and earlier) +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; + +# Java client (0.7.x and earlier) + + Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/interfaces/http). The library provides own API to send requests to a server. diff --git a/docs/integrations/language-clients/java/client.md b/docs/integrations/language-clients/java/client.md index aafaf24e662..133cf965c04 100644 --- a/docs/integrations/language-clients/java/client.md +++ b/docs/integrations/language-clients/java/client.md @@ -10,15 +10,23 @@ title: 'Java Client (0.8+)' import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; - -# Java Client (0.8+) +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; + +# Java client (0.8+) + + Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/interfaces/http). -The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*). - -:::note -If you're looking for a prior version of the java client docs, please see [here](/integrations/language-clients/java/client-v1.md). -::: +The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*). ## Setup {#setup} From 2ab526532a075c04e9e611387a43c1eb3b036b09 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Tue, 22 Apr 2025 12:35:15 +0200 Subject: [PATCH 07/14] Fix frontmatter --- docs/integrations/language-clients/java/client-v1.md | 1 + docs/integrations/language-clients/java/jdbc-v1.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/integrations/language-clients/java/client-v1.md b/docs/integrations/language-clients/java/client-v1.md index 13cf9557dda..babfa28101d 100644 --- a/docs/integrations/language-clients/java/client-v1.md +++ b/docs/integrations/language-clients/java/client-v1.md @@ -2,6 +2,7 @@ title: 'Client (0.7.x and earlier)' description: 'Java client library to communicate with a DB server through its protocols.' slug: /integrations/language-clients/java/client-v1 +displayed_sidebar: 'integrations' --- import Tabs from '@theme/Tabs'; diff --git a/docs/integrations/language-clients/java/jdbc-v1.md b/docs/integrations/language-clients/java/jdbc-v1.md index 7e01649ebdc..23c5334326a 100644 --- a/docs/integrations/language-clients/java/jdbc-v1.md +++ b/docs/integrations/language-clients/java/jdbc-v1.md @@ -2,7 +2,7 @@ title: 'JDBC Driver' description: 'Page describing the JDBC driver for ClickHouse' slug: /integrations/language-clients/java/jdbc-v1 -displayed_sidebar: integrations +displayed_sidebar: 'integrations' --- import Tabs from '@theme/Tabs'; From f1648ae22ab7822bfa034feef85dff1f96e92e99 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 19:19:38 +0200 Subject: [PATCH 08/14] Rework ClientVersioning component to use snippets --- .../java/{client-v1.md => client/_v0_7.mdx} | 22 --- .../java/{client.md => client/_v0_8.mdx} | 72 +++----- .../language-clients/java/client/client.mdx | 23 +++ .../language-clients/java/index.md | 4 +- .../java/{jdbc-v1.md => jdbc/_v0_7.mdx} | 164 ++++++++---------- .../java/{jdbc.md => jdbc/_v0_8.mdx} | 100 ++++------- .../language-clients/java/jdbc/jdbc.mdx | 23 +++ sidebars.js | 4 +- .../ClientVersionDropdown.js | 101 +++++++---- 9 files changed, 255 insertions(+), 258 deletions(-) rename docs/integrations/language-clients/java/{client-v1.md => client/_v0_7.mdx} (96%) rename docs/integrations/language-clients/java/{client.md => client/_v0_8.mdx} (96%) create mode 100644 docs/integrations/language-clients/java/client/client.mdx rename docs/integrations/language-clients/java/{jdbc-v1.md => jdbc/_v0_7.mdx} (87%) rename docs/integrations/language-clients/java/{jdbc.md => jdbc/_v0_8.mdx} (84%) create mode 100644 docs/integrations/language-clients/java/jdbc/jdbc.mdx diff --git a/docs/integrations/language-clients/java/client-v1.md b/docs/integrations/language-clients/java/client/_v0_7.mdx similarity index 96% rename from docs/integrations/language-clients/java/client-v1.md rename to docs/integrations/language-clients/java/client/_v0_7.mdx index babfa28101d..ae308fa49bb 100644 --- a/docs/integrations/language-clients/java/client-v1.md +++ b/docs/integrations/language-clients/java/client/_v0_7.mdx @@ -1,27 +1,5 @@ ---- -title: 'Client (0.7.x and earlier)' -description: 'Java client library to communicate with a DB server through its protocols.' -slug: /integrations/language-clients/java/client-v1 -displayed_sidebar: 'integrations' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; - -# Java client (0.7.x and earlier) - - Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/interfaces/http). The library provides own API to send requests to a server. diff --git a/docs/integrations/language-clients/java/client.md b/docs/integrations/language-clients/java/client/_v0_8.mdx similarity index 96% rename from docs/integrations/language-clients/java/client.md rename to docs/integrations/language-clients/java/client/_v0_8.mdx index 133cf965c04..eb2a6a1b187 100644 --- a/docs/integrations/language-clients/java/client.md +++ b/docs/integrations/language-clients/java/client/_v0_8.mdx @@ -1,38 +1,14 @@ ---- -sidebar_label: 'Client 0.8+' -sidebar_position: 2 -keywords: ['clickhouse', 'java', 'client', 'integrate'] -description: 'Java ClickHouse Connector 0.8+' -slug: /integrations/language-clients/java/client -title: 'Java Client (0.8+)' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; - -# Java client (0.8+) - - -Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/interfaces/http). +Java client library to communicate with a DB server through its protocols. The current implementation only supports the [HTTP interface](/interfaces/http). The library provides its own API to send requests to a server. The library also provides tools to work with different binary data formats (RowBinary* & Native*). ## Setup {#setup} - Maven Central (project web page): https://mvnrepository.com/artifact/com.clickhouse/client-v2 - Nightly builds (repository link): https://s01.oss.sonatype.org/content/repositories/snapshots/com/clickhouse/ - +
@@ -65,9 +41,9 @@ implementation 'com.clickhouse:client-v2:0.8.2' ## Initialization {#initialization} The Client object is initialized by `com.clickhouse.client.api.Client.Builder#build()`. Each client has its own context and no objects are shared between them. -The Builder has configuration methods for convenient setup. +The Builder has configuration methods for convenient setup. -Example: +Example: ```java showLineNumbers Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") @@ -80,9 +56,9 @@ Example: ### Authentication {#authentication} -Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. +Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. -Authentication by a password requires setting user name password by calling `setUsername(String)` and `setPassword(String)`: +Authentication by a password requires setting user name password by calling `setUsername(String)` and `setPassword(String)`: ```java showLineNumbers Client client = new Client.Builder() .addEndpoint("https://clickhouse-cloud-instance:8443/") @@ -99,7 +75,7 @@ Authentication by an access token requires setting access token by calling `setA .build(); ``` -Authentication by a SSL Client Certificate require setting username, enabling SSL Authentication, setting a client sertificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly: +Authentication by a SSL Client Certificate require setting username, enabling SSL Authentication, setting a client sertificate and a client key by calling `setUsername(String)`, `useSSLAuthentication(boolean)`, `setClientCertificate(String)` and `setClientKey(String)` accordingly: ```java showLineNumbers Client client = new Client.Builder() .useSSLAuthentication(true) @@ -111,18 +87,18 @@ Client client = new Client.Builder() :::note SSL Authentication may be hard to troubleshoot on production because many errors from SSL libraries provide not enough information. For example, if client certificate and key do not match then server will terminate connection immediately (in case of HTTP it will be connection initiation stage where no HTTP requests are send so no response is sent). -Please use tools like [openssl](https://docs.openssl.org/master/man1/openssl/) to verify certificates and keys: +Please use tools like [openssl](https://docs.openssl.org/master/man1/openssl/) to verify certificates and keys: - check key integrity: `openssl rsa -in [key-file.key] -check -noout` - check client certificate has matching CN for a user: - get CN from an user certificate - `openssl x509 -noout -subject -in [user.cert]` - - verify same value is set in database `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (query will output `auth_params` with something like ` {"common_names":["some_user"]}`) + - verify same value is set in database `select name, auth_type, auth_params from system.users where auth_type = 'ssl_certificate'` (query will output `auth_params` with something like ` {"common_names":["some_user"]}`) ::: ## Configuration {#configuration} -All settings are defined by instance methods (a.k.a configuration methods) that make the scope and context of each value clear. +All settings are defined by instance methods (a.k.a configuration methods) that make the scope and context of each value clear. Major configuration parameters are defined in one scope (client or operation) and do not override each other. Configuration is defined during client creation. See `com.clickhouse.client.api.Client.Builder`. @@ -189,9 +165,9 @@ Configuration is defined during client creation. See `com.clickhouse.client.api. ### ClickHouseFormat {#clickhouseformat} -Enum of [supported formats](/interfaces/formats). It includes all formats that ClickHouse supports. +Enum of [supported formats](/interfaces/formats). It includes all formats that ClickHouse supports. -* `raw` - user should transcode raw data +* `raw` - user should transcode raw data * `full` - the client can transcode data by itself and accepts a raw data stream * `-` - operation not supported by ClickHouse for this format @@ -337,7 +313,7 @@ client.insert(String tableName, List data) **Parameters** -`tableName` - name of the target table. +`tableName` - name of the target table. `data` - collection DTO (Data Transfer Object) objects. @@ -379,7 +355,7 @@ Configuration options for insert operations. ### InsertResponse {#insertresponse} -Response object that holds result of insert operation. It is only available if the client got response from a server. +Response object that holds result of insert operation. It is only available if the client got response from a server. :::note This object should be closed as soon as possible to release a connection because the connection cannot be re-used until all data of previous response is fully read. @@ -405,13 +381,13 @@ CompletableFuture query(String sqlQuery) **Parameters** -`sqlQuery` - a single SQL statement. The Query is sent as is to a server. +`sqlQuery` - a single SQL statement. The Query is sent as is to a server. `settings` - request settings. **Return value** -Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. +Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** @@ -452,15 +428,15 @@ CompletableFuture query(String sqlQuery, Map quer **Parameters** -`sqlQuery` - sql expression with placeholders `{}`. +`sqlQuery` - sql expression with placeholders `{}`. `queryParams` - map of variables to complete the sql expression on server. -`settings` - request settings. +`settings` - request settings. **Return value** -Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. +Future of `QueryResponse` type - a result dataset and additional information like server side metrics. The Response object should be closed after consuming the dataset. **Examples** @@ -503,7 +479,7 @@ List queryAll(String sqlQuery) **Return value** -Complete dataset represented by a list of `GenericRecord` objects that provide access in row style for the result data. +Complete dataset represented by a list of `GenericRecord` objects that provide access in row style for the result data. **Examples** @@ -546,7 +522,7 @@ Configuration options for query operations. ### QueryResponse {#queryresponse} -Response object that holds result of query execution. It is only available if the client got a response from a server. +Response object that holds result of query execution. It is only available if the client got a response from a server. :::note This object should be closed as soon as possible to release a connection because the connection cannot be re-used until all data of previous response is fully read. @@ -590,7 +566,7 @@ Returns a `TableSchema` object with list of table columns. ### getTableSchemaFromQuery(String sql) {#gettableschemafromquerystring-sql} -Fetches schema from a SQL statement. +Fetches schema from a SQL statement. **Signatures** @@ -610,8 +586,8 @@ Returns a `TableSchema` object with columns matching the `sql` expression. ### register(Class<?> clazz, TableSchema schema) {#registerclasslt-clazz-tableschema-schema} -Compiles serialization and deserialization layer for the Java Class to use for writing/reading data with `schema`. The method will create a serializer and deserializer for the pair getter/setter and corresponding column. -Column match is found by extracting its name from a method name. For example, `getFirstName` will be for the column `first_name` or `firstname`. +Compiles serialization and deserialization layer for the Java Class to use for writing/reading data with `schema`. The method will create a serializer and deserializer for the pair getter/setter and corresponding column. +Column match is found by extracting its name from a method name. For example, `getFirstName` will be for the column `first_name` or `firstname`. **Signatures** diff --git a/docs/integrations/language-clients/java/client/client.mdx b/docs/integrations/language-clients/java/client/client.mdx new file mode 100644 index 00000000000..299c3df1323 --- /dev/null +++ b/docs/integrations/language-clients/java/client/client.mdx @@ -0,0 +1,23 @@ +--- +sidebar_label: 'Client' +sidebar_position: 2 +keywords: ['clickhouse', 'java', 'client', 'integrate'] +description: 'Java ClickHouse Connector' +slug: /integrations/language-clients/java/client +title: 'Java Client' +--- + +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; +import v07 from './_v0_7.mdx' +import v08 from './_v0_8.mdx' + + diff --git a/docs/integrations/language-clients/java/index.md b/docs/integrations/language-clients/java/index.md index 27154a99b31..2f1d92083db 100644 --- a/docs/integrations/language-clients/java/index.md +++ b/docs/integrations/language-clients/java/index.md @@ -11,8 +11,8 @@ import CodeBlock from '@theme/CodeBlock'; # Java Clients Overview -- [Client 0.8+](./client.md) -- [JDBC 0.8+](./jdbc) +- [Client 0.8+](./client/client.mdx) +- [JDBC 0.8+](./jdbc/jdbc.mdx) - [R2DBC Driver](./r2dbc.md) ## ClickHouse Client {#clickhouse-client} diff --git a/docs/integrations/language-clients/java/jdbc-v1.md b/docs/integrations/language-clients/java/jdbc/_v0_7.mdx similarity index 87% rename from docs/integrations/language-clients/java/jdbc-v1.md rename to docs/integrations/language-clients/java/jdbc/_v0_7.mdx index 23c5334326a..cb7c27b051a 100644 --- a/docs/integrations/language-clients/java/jdbc-v1.md +++ b/docs/integrations/language-clients/java/jdbc/_v0_7.mdx @@ -1,27 +1,5 @@ ---- -title: 'JDBC Driver' -description: 'Page describing the JDBC driver for ClickHouse' -slug: /integrations/language-clients/java/jdbc-v1 -displayed_sidebar: 'integrations' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' - -# JDBC Driver - - `clickhouse-jdbc` implements the standard JDBC interface. Being built on top of [clickhouse-client](/integrations/sql-clients/sql-console), it provides additional features like custom type mapping, transaction support, and standard synchronous `UPDATE` and `DELETE` statements, etc., so that it can be easily used with legacy applications and tools. @@ -39,69 +17,69 @@ Latest JDBC (0.7.2) version uses Client-V1 ### Setup {#setup} - - -```xml - - - com.clickhouse - clickhouse-jdbc - 0.7.2 - - shaded-all - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -// use uber jar with all dependencies included, change classifier to http for smaller jar -implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all") -``` - - - -```groovy -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -// use uber jar with all dependencies included, change classifier to http for smaller jar -implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all' -``` - - + + + ```xml + + + com.clickhouse + clickhouse-jdbc + 0.7.2 + + shaded-all + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + // use uber jar with all dependencies included, change classifier to http for smaller jar + implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + // use uber jar with all dependencies included, change classifier to http for smaller jar + implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all' + ``` + + Since version `0.5.0`, we are using Apache HTTP Client that's packed the Client. Since there is not a shared version of the package, you need to add a logger as a dependency. - - -```xml - - - org.slf4j - slf4j-api - 2.0.16 - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/org.slf4j/slf4j-api -implementation("org.slf4j:slf4j-api:2.0.16") -``` - - - -```groovy -// https://mvnrepository.com/artifact/org.slf4j/slf4j-api -implementation 'org.slf4j:slf4j-api:2.0.16' -``` - - + + + ```xml + + + org.slf4j + slf4j-api + 2.0.16 + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/org.slf4j/slf4j-api + implementation("org.slf4j:slf4j-api:2.0.16") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/org.slf4j/slf4j-api + implementation 'org.slf4j:slf4j-api:2.0.16' + ``` + + ## Configuration {#configuration} @@ -138,7 +116,7 @@ JDBC Driver supports same data formats as client library does. - Decimal - `SET output_format_decimal_trailing_zeros=1` in 21.9+ for consistency - Enum - can be treated as both string and integer - UInt64 - mapped to `long` (in client-v1) - ::: +::: ## Creating Connection {#creating-connection} @@ -170,7 +148,7 @@ try (Connection conn = dataSource.getConnection(...); :::note - Use `PreparedStatement` instead of `Statement` - ::: +::: It's easier to use but slower performance compare to input function (see below): @@ -367,19 +345,19 @@ On Linux, the equivalent settings alone may not resolve the issue. Additional st 1. Adjust the following Linux kernel parameters in `/etc/sysctl.conf` or a related configuration file: - - `net.inet.tcp.keepidle`: 60000 - - `net.inet.tcp.keepintvl`: 45000 - - `net.inet.tcp.keepinit`: 45000 - - `net.inet.tcp.keepcnt`: 8 - - `net.inet.tcp.always_keepalive`: 1 - - `net.ipv4.tcp_keepalive_intvl`: 75 - - `net.ipv4.tcp_keepalive_probes`: 9 - - `net.ipv4.tcp_keepalive_time`: 60 (You may consider lowering this value from the default 300 seconds) +- `net.inet.tcp.keepidle`: 60000 +- `net.inet.tcp.keepintvl`: 45000 +- `net.inet.tcp.keepinit`: 45000 +- `net.inet.tcp.keepcnt`: 8 +- `net.inet.tcp.always_keepalive`: 1 +- `net.ipv4.tcp_keepalive_intvl`: 75 +- `net.ipv4.tcp_keepalive_probes`: 9 +- `net.ipv4.tcp_keepalive_time`: 60 (You may consider lowering this value from the default 300 seconds) 2. After modifying the kernel parameters, apply the changes by running the following command: - ```shell - sudo sysctl -p +```shell +sudo sysctl -p ``` After Setting those settings, you need to ensure that your client enables the Keep Alive option on the socket: @@ -407,4 +385,4 @@ try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.H .query(sql) .executeAndWait(); } -``` +``` \ No newline at end of file diff --git a/docs/integrations/language-clients/java/jdbc.md b/docs/integrations/language-clients/java/jdbc/_v0_8.mdx similarity index 84% rename from docs/integrations/language-clients/java/jdbc.md rename to docs/integrations/language-clients/java/jdbc/_v0_8.mdx index 641714af3f0..f8208e5693e 100644 --- a/docs/integrations/language-clients/java/jdbc.md +++ b/docs/integrations/language-clients/java/jdbc/_v0_8.mdx @@ -1,29 +1,5 @@ ---- -sidebar_label: 'JDBC 0.8+' -sidebar_position: 4 -keywords: ['clickhouse', 'java', 'jdbc', 'driver', 'integrate'] -description: 'ClickHouse JDBC driver' -slug: /integrations/language-clients/java/jdbc -title: 'JDBC Driver (0.8+)' ---- - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' - -# JDBC Driver (0.8+) - - `clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md). We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical. @@ -50,34 +26,34 @@ In 0.8 we tried to make the driver more strictly follow the JDBC specification, ### Setup {#setup} - - -```xml - - - com.clickhouse - clickhouse-jdbc - 0.8.2 - shaded-all - -``` - - - - -```kotlin -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -implementation("com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all") -``` - - - -```groovy -// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -implementation 'com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all' -``` - - + + + ```xml + + + com.clickhouse + clickhouse-jdbc + 0.8.2 + shaded-all + + ``` + + + + + ```kotlin + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + implementation("com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all") + ``` + + + + ```groovy + // https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc + implementation 'com.clickhouse:clickhouse-jdbc:0.8.2:shaded-all' + ``` + + ## Configuration {#configuration} @@ -169,7 +145,7 @@ try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (? ``` ## `HikariCP` {#hikaricp} - + ```java showLineNumbers // connection pooling won't help much in terms of performance, // because the underlying implementation has its own pool. @@ -224,14 +200,14 @@ On Linux, the equivalent settings alone may not resolve the issue. Additional st 1. Adjust the following Linux kernel parameters in `/etc/sysctl.conf` or a related configuration file: - - `net.inet.tcp.keepidle`: 60000 - - `net.inet.tcp.keepintvl`: 45000 - - `net.inet.tcp.keepinit`: 45000 - - `net.inet.tcp.keepcnt`: 8 - - `net.inet.tcp.always_keepalive`: 1 - - `net.ipv4.tcp_keepalive_intvl`: 75 - - `net.ipv4.tcp_keepalive_probes`: 9 - - `net.ipv4.tcp_keepalive_time`: 60 (You may consider lowering this value from the default 300 seconds) + - `net.inet.tcp.keepidle`: 60000 + - `net.inet.tcp.keepintvl`: 45000 + - `net.inet.tcp.keepinit`: 45000 + - `net.inet.tcp.keepcnt`: 8 + - `net.inet.tcp.always_keepalive`: 1 + - `net.ipv4.tcp_keepalive_intvl`: 75 + - `net.ipv4.tcp_keepalive_probes`: 9 + - `net.ipv4.tcp_keepalive_time`: 60 (You may consider lowering this value from the default 300 seconds) 2. After modifying the kernel parameters, apply the changes by running the following command: @@ -243,4 +219,4 @@ After Setting those settings, you need to ensure that your client enables the Ke ```java properties.setProperty("socket_keepalive", "true"); -``` +``` \ No newline at end of file diff --git a/docs/integrations/language-clients/java/jdbc/jdbc.mdx b/docs/integrations/language-clients/java/jdbc/jdbc.mdx new file mode 100644 index 00000000000..c6571ab92a2 --- /dev/null +++ b/docs/integrations/language-clients/java/jdbc/jdbc.mdx @@ -0,0 +1,23 @@ +--- +sidebar_label: 'JDBC' +sidebar_position: 4 +keywords: ['clickhouse', 'java', 'jdbc', 'driver', 'integrate'] +description: 'ClickHouse JDBC driver' +slug: /integrations/language-clients/java/jdbc +title: 'JDBC Driver' +--- + +import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; +import v07 from './_v0_7.mdx' +import v08 from './_v0_8.mdx' + + diff --git a/sidebars.js b/sidebars.js index 232758d2a0e..a4c91ef2428 100644 --- a/sidebars.js +++ b/sidebars.js @@ -645,8 +645,8 @@ const sidebars = { id: "integrations/language-clients/java/index" }, // "integrations/language-clients/java/index", - "integrations/language-clients/java/client", - "integrations/language-clients/java/jdbc", + "integrations/language-clients/java/client/client", + "integrations/language-clients/java/jdbc/jdbc", "integrations/language-clients/java/r2dbc" ] }, diff --git a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js index b060df5c4ad..b85eef7bea5 100644 --- a/src/theme/ClientVersionDropdown/ClientVersionDropdown.js +++ b/src/theme/ClientVersionDropdown/ClientVersionDropdown.js @@ -2,52 +2,88 @@ import React, {useState, useEffect, useRef} from 'react'; import Link from '@docusaurus/Link'; import styles from './styles.module.css' import ReactDOM from 'react-dom'; -import {useHistory} from "react-router-dom"; +import {useHistory, useLocation} from "react-router-dom"; const ClientVersionDropdown = (props) => { - - const history = useHistory() - const [displayDropdown, setDisplayDropdown] = useState(false) + const history = useHistory(); + const location = useLocation(); + const [displayDropdown, setDisplayDropdown] = useState(false); const [dropdownPosition, setDropdownPosition] = useState({top: 0, left: 0}); + const [selectedVersionIndex, setSelectedVersionIndex] = useState(0); const buttonRef = useRef(null); const dropdownRef = useRef(null); + // Find version from URL parameter on initial load + useEffect(() => { + const searchParams = new URLSearchParams(location.search); + const versionParam = searchParams.get('v'); + + if (versionParam) { + // Find the matching version in our versions array + const foundIndex = props.versions.findIndex(item => + item.version === versionParam || + item.version.replace('.', '') === versionParam || + item.version.toLowerCase().replace(/[^a-z0-9]/g, '') === versionParam.toLowerCase() + ); + + if (foundIndex !== -1) { + setSelectedVersionIndex(foundIndex); + } + } + }, [location.search, props.versions]); + const onClickHandler = () => { - setDisplayDropdown(!displayDropdown) - } + setDisplayDropdown(!displayDropdown); + }; - const handleLinkClick = (e, slug) => { + const handleLinkClick = (e, slug, index) => { e.preventDefault(); - // Navigate after a slight delay to ensure the click event completes setTimeout(() => { setDisplayDropdown(false); - history.push(slug); + setSelectedVersionIndex(index); + + // Get the version string from the selected version + const versionString = props.versions[index].version; + + // Determine the URL to navigate to + let targetUrl; + if (slug) { + // If slug provided, navigate to that page + targetUrl = slug; + } else { + // Otherwise update the URL parameter on the current page + const searchParams = new URLSearchParams(location.search); + + // Convert the version to a URL-friendly format + const versionParam = versionString.replace(/\./g, '').replace(/\+/g, ''); + + searchParams.set('v', versionParam); + targetUrl = `${location.pathname}?${searchParams.toString()}`; + } + + history.push(targetUrl); }, 10); }; - // Calculate and update dropdown position when it's displayed - useEffect(()=> { + useEffect(() => { if (displayDropdown && buttonRef.current) { const buttonRect = buttonRef.current.getBoundingClientRect(); setDropdownPosition({ top: buttonRect.bottom + window.scrollY, left: buttonRect.left + window.scrollX - }) + }); } - }, [displayDropdown]) + }, [displayDropdown]); - // Close the dropdown menu when clicking outside - useEffect(()=>{ + useEffect(() => { const handleClickOutside = (event) => { - if (dropdownRef.current && dropdownRef.current.contains(event.target)) { if (event.target.tagName === 'A') { return; } } - // Otherwise close if clicked outside button or dropdown if (buttonRef.current && !buttonRef.current.contains(event.target) && dropdownRef.current && !dropdownRef.current.contains(event.target)) { setDisplayDropdown(false); @@ -59,11 +95,10 @@ const ClientVersionDropdown = (props) => { } return () => { - document.removeEventListener('mousedown', handleClickOutside) - } - }, [displayDropdown]) + document.removeEventListener('mousedown', handleClickOutside); + }; + }, [displayDropdown]); - // Render dropdown menu in a portal const renderDropdown = () => { if (!displayDropdown) return null; @@ -81,14 +116,14 @@ const ClientVersionDropdown = (props) => { {props.versions.map((item, index) => ( handleLinkClick(e, item.slug)} + onClick={(e) => handleLinkClick(e, item.slug, index)} > {item.version} @@ -96,10 +131,14 @@ const ClientVersionDropdown = (props) => {
, document.body ); + }; + + const selectedVersion = props.versions[selectedVersionIndex]; - } + // Get the MDXContent component + const MDXContent = selectedVersion.snippet; - return( + return ( <>
{ ref={buttonRef} >
- {props.versions[0]["version"]} + {selectedVersion.version}
{renderDropdown()} + +
+ {MDXContent && typeof MDXContent === 'function' && } +
- ) -} + ); +}; -export default ClientVersionDropdown +export default ClientVersionDropdown; From a203900fe8f0a89a5226b961512ae73e58196a68 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 19:40:47 +0200 Subject: [PATCH 09/14] Update documentation --- contribute/style-guide.md | 109 +++++++++++++++++++++++++++++++------- 1 file changed, 90 insertions(+), 19 deletions(-) diff --git a/contribute/style-guide.md b/contribute/style-guide.md index e766aef5cd5..003f4edb448 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -253,53 +253,124 @@ sidebar. ## Client versioning +### Background + Docusaurus supports versioning documentation, however it is opinionated and aimed more at use cases where you have a single product with set releases, or multiple products with their own releases. -Due to the fact that we have many -different integrations in ClickHouse, each of which may need versioned documentation, -we use the following custom `ClientVersionDropdown` component for versioning of -client documentation: +Due to the fact that we have many different integrations in ClickHouse, each of +which may need versioned documentation, we use the following custom +`ClientVersionDropdown` component for versioning of client documentation: ```markdown ``` -To use this component, import it into the markdown page: +### How to use it -```markdown +Versioned folders are structured as follows: + +```text +. +├── client +│ ├── _v0_7.mdx +│ ├── _v0_8.mdx +│ └── client.mdx +├── index.md +├── jdbc +│ ├── _v0_7.mdx +│ ├── _v0_8.mdx +│ └── jdbc.mdx +└── r2dbc.md +``` + +* The content for each version is placed in a snippet. For example `_v0_7.mdx` + * Snippets begin with `_` + * Snippets do not contain front-matter + * These snippets import any components they may need (See `_v0_7.mdx` for example) + * They should be .mdx files +* There is a single page for all versions. For example `client.mdx` + * This page contains frontmatter + * It imports the `` component + * It should be a .mdx file + +To use this component, import it into the single page: + +```js import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown' ``` -Add it underneath the H1 element on the page and pass it an array of objects -representing versions and the slug of the page: +Also import the two snippets: -```markdown -# JDBC Driver (0.8+) +```js +import v07 from './_v0_7.mdx' +import v08 from './_v0_8.mdx' +``` + +Pass it an array of objects representing versions and their respective snippets: +```markdown ``` -Note that the component will display the first item as the 'selected' version, so +**Note**: The component will display the first item as the 'selected' version, so it is important to make sure the order of the objects is correct. -Add this component on every 'versioned' page for the client. +### URL parameters -In addition, add to every 'archived' version page the following frontmatter item: +If you need to share a link to the page you can do it through URL params: -```markdown -displayed_sidebar: integrations +```response +/docs/integrations/language-clients/java/client?v=v08 ``` -This will make sure that the sidebar displays, even if this particular page is -not shown in the sidebar. +When using URL parameters to control which version of documentation is displayed, +there are conventions to follow for reliable functionality. +Here's how the `?v=v08` parameter relates to the snippet selection: + +#### How It Works + +The URL parameter acts as a selector that matches against the `version` property +in your component configuration. For example: + +- URL: `docs/api?v=v08` +- Matches: `version: 'v0.8+'` in your dropdown configuration + +#### Conventions That Work + +- **Simple Version Strings**: Parameters like `?v=v08`, `?v=v07` work by +- matching against stripped versions of your configured version names. + +- **Flexible Matching**: The implementation supports: + - Removing dots: `v0.8` matches `?v=v08` + - Ignoring plus signs: `v0.8+` matches `?v=v08` + - Case-insensitive matching: `v0.8` matches `?v=V08` + +- **Preserving Other Parameters**: Other URL parameters are preserved when +switching versions. + +#### What Won't Work + +- **Partial Matches**: `?v=8` won't match `v0.8` with the default implementation. + +- **Complex Version Strings**: Very complex versions like `?v=v1.2.3-beta.4` +require more sophisticated matching logic. (Reach out to the docs team if required) + +- **Non-Standard Formats**: Version formats not accounted for in the matching +logic might fail. + +#### Best Practices + +1. Keep version strings in consistent formats for predictable results. + +2. Use simplified version parameters in URLs (e.g., `v08` instead of `v0.8.x`). From cba424184600351f3183eb3b2ebfe1261b599054 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 20:06:32 +0200 Subject: [PATCH 10/14] solve floating pages issue --- contribute/style-guide.md | 10 ++++++---- .../java/client/{ => _snippets}/_v0_7.mdx | 0 .../java/client/{ => _snippets}/_v0_8.mdx | 0 .../language-clients/java/client/client.mdx | 4 ++-- .../java/jdbc/{ => _snippets}/_v0_7.mdx | 0 .../java/jdbc/{ => _snippets}/_v0_8.mdx | 0 docs/integrations/language-clients/java/jdbc/jdbc.mdx | 4 ++-- 7 files changed, 10 insertions(+), 8 deletions(-) rename docs/integrations/language-clients/java/client/{ => _snippets}/_v0_7.mdx (100%) rename docs/integrations/language-clients/java/client/{ => _snippets}/_v0_8.mdx (100%) rename docs/integrations/language-clients/java/jdbc/{ => _snippets}/_v0_7.mdx (100%) rename docs/integrations/language-clients/java/jdbc/{ => _snippets}/_v0_8.mdx (100%) diff --git a/contribute/style-guide.md b/contribute/style-guide.md index 003f4edb448..4911653d767 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -274,13 +274,15 @@ Versioned folders are structured as follows: ```text . ├── client -│ ├── _v0_7.mdx -│ ├── _v0_8.mdx +│ ├── _snippets +│ │ ├── _v0_7.mdx +│ │ └── _v0_8.mdx │ └── client.mdx ├── index.md ├── jdbc -│ ├── _v0_7.mdx -│ ├── _v0_8.mdx +│ ├── _snippets +│ │ ├── _v0_7.mdx +│ │ └── _v0_8.mdx │ └── jdbc.mdx └── r2dbc.md ``` diff --git a/docs/integrations/language-clients/java/client/_v0_7.mdx b/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx similarity index 100% rename from docs/integrations/language-clients/java/client/_v0_7.mdx rename to docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx diff --git a/docs/integrations/language-clients/java/client/_v0_8.mdx b/docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx similarity index 100% rename from docs/integrations/language-clients/java/client/_v0_8.mdx rename to docs/integrations/language-clients/java/client/_snippets/_v0_8.mdx diff --git a/docs/integrations/language-clients/java/client/client.mdx b/docs/integrations/language-clients/java/client/client.mdx index 299c3df1323..eb4df152520 100644 --- a/docs/integrations/language-clients/java/client/client.mdx +++ b/docs/integrations/language-clients/java/client/client.mdx @@ -8,8 +8,8 @@ title: 'Java Client' --- import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'; -import v07 from './_v0_7.mdx' -import v08 from './_v0_8.mdx' +import v07 from './_snippets/_v0_7.mdx' +import v08 from './_snippets/_v0_8.mdx' Date: Wed, 23 Apr 2025 20:17:54 +0200 Subject: [PATCH 11/14] Update link --- .../integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx index f8208e5693e..4747e7b86c5 100644 --- a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx @@ -1,7 +1,7 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client.md). +`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client/client.md). We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical. ## Changes from 0.7.x {#changes-from-07x} From 1184f1198ae39c29aec630f3e1a4733953e4cb98 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 20:31:25 +0200 Subject: [PATCH 12/14] actually fix broken anchors --- .../language-clients/java/jdbc/_snippets/_v0_8.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx index 4747e7b86c5..292f4a645d9 100644 --- a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx @@ -1,8 +1,8 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client/client.md). -We recommend using the latest [java client](/integrations/language-clients/java/client.md) directly if performance/direct access is critical. +`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client/client.mdx). +We recommend using the latest [java client](/integrations/language-clients/java/client.mdx) directly if performance/direct access is critical. ## Changes from 0.7.x {#changes-from-07x} In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you: From 86f3288fe1794648a74e2afd9316fe209abc6663 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 20:58:09 +0200 Subject: [PATCH 13/14] Fix anchors --- .../language-clients/java/client/_snippets/_v0_7.mdx | 2 +- .../language-clients/java/jdbc/_snippets/_v0_8.mdx | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx b/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx index ae308fa49bb..052965fed45 100644 --- a/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx +++ b/docs/integrations/language-clients/java/client/_snippets/_v0_7.mdx @@ -4,7 +4,7 @@ import TabItem from '@theme/TabItem'; Java client library to communicate with a DB server through its protocols. Current implementation supports only [HTTP interface](/interfaces/http). The library provides own API to send requests to a server. :::warning Deprecation -This library will be deprecated soon. Use the latest [Java Client](/integrations/language-clients/java/client.md) for new projects +This library will be deprecated soon. Use the latest [Java Client](/integrations/language-clients/java/client/client.mdx) for new projects ::: ## Setup {#setup} diff --git a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx index 292f4a645d9..d37dc327934 100644 --- a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx @@ -1,8 +1,10 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -`clickhouse-jdbc` implements the standard JDBC interface using the latest [java client](/integrations/language-clients/java/client/client.mdx). -We recommend using the latest [java client](/integrations/language-clients/java/client.mdx) directly if performance/direct access is critical. +:::note +`clickhouse-jdbc` implements the standard JDBC interface using the latest java clientю +We recommend using the latest java client directly if performance/direct access is critical. +::: ## Changes from 0.7.x {#changes-from-07x} In 0.8 we tried to make the driver more strictly follow the JDBC specification, so there are some removed features that may affect you: @@ -13,7 +15,7 @@ In 0.8 we tried to make the driver more strictly follow the JDBC specification, | Response Column Renaming | `ResultSet` was mutable - for efficiency sake they're now read-only | | Multi-Statement SQL | Multi-statement support was only **simulated**, now it strictly follows 1:1 | | Named Parameters | Not part of the JDBC spec | -| Stream-based `PreparedStatement` | Early version of the driver allowed for non-jdbc usage of `PreparedStatement` - if you desire such options, we recommend looking at the [Java Client](/integrations/language-clients/java/client.md) and its [examples](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2). | +| Stream-based `PreparedStatement` | Early version of the driver allowed for non-jdbc usage of `PreparedStatement` - if you desire such options, we recommend looking at the [Java Client](/integrations/language-clients/java/client/client.mdx) and its [examples](https://github.com/ClickHouse/clickhouse-java/tree/main/examples/client-v2). | :::note `Date` is stored without timezone, while `DateTime` is stored with timezone. This can lead to unexpected results if you're not careful. @@ -67,7 +69,7 @@ In 0.8 we tried to make the driver more strictly follow the JDBC specification, **Connection Properties**: -Beyond standard JDBC properties, the driver supports the ClickHouse-specific properties offered by the underlying [java client](/integrations/language-clients/java/client.md). +Beyond standard JDBC properties, the driver supports the ClickHouse-specific properties offered by the underlying [java client](/integrations/language-clients/java/client/client.mdx). Where possible methods will return an `SQLFeatureNotSupportedException` if the feature is not supported. Other custom properties include: | Property | Default | Description | From 2888847b11710481029f7e5df2fcfb13efeb519a Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Wed, 23 Apr 2025 21:10:00 +0200 Subject: [PATCH 14/14] fix anchors --- .../language-clients/java/jdbc/_snippets/_v0_8.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx index d37dc327934..5a70168e2ab 100644 --- a/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx +++ b/docs/integrations/language-clients/java/jdbc/_snippets/_v0_8.mdx @@ -81,7 +81,7 @@ Where possible methods will return an `SQLFeatureNotSupportedException` if the f ## Supported data types {#supported-data-types} -JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client.md). +JDBC Driver supports the same data formats as the underlying [java client](/integrations/language-clients/java/client/client.mdx). ### Handling Dates, Times, and Timezones {#handling-dates-times-and-timezones} `java.sql.Date`, `java.sql.Time`, and `java.sql.Timestamp` can complicate how Timezones are calculated - though they're of course supported, @@ -170,7 +170,7 @@ try (HikariDataSource ds = new HikariDataSource(poolConfig); ``` ## More Information {#more-information} -For more information, see our [GitHub repository](https://github.com/ClickHouse/clickhouse-java) and [Java Client documentation](/integrations/language-clients/java/client.md). +For more information, see our [GitHub repository](https://github.com/ClickHouse/clickhouse-java) and [Java Client documentation](/integrations/language-clients/java/client/client.mdx). ## Troubleshooting {#troubleshooting}