[jdbc-v2] Support multi-dot notation for database names #2663

devdavidkarlsson · 2025-11-20T14:05:26Z

Description

This PR adds support for multi-dot notation in database names without requiring quotes, enabling table references like a.b.c where a.b is the database name and c is the table name.

Changes

Grammar: Updated ANTLR databaseIdentifier rule to support multiple dot-separated identifiers: identifier (DOT identifier)*
Parser Logic: Added extractTableName() helper method in SqlParserFacade to properly unquote each identifier part separately and join them correctly
Tests: Added testMultiDotNotation() test method with 3 test cases:
- Unquoted multi-dot: SELECT * FROM a.b.c WHERE id = ?
- Quoted identifiers: SELECT * FROM `db.part1`.`table` WHERE id = ?
- INSERT statement: INSERT INTO a.b.c (col1, col2) VALUES (?, ?)

Testing

✅ All 367 existing tests continue to pass
✅ New test validates parsing of multi-dot database names
✅ Verified against ClickHouse server with databases containing dots in their names

Example Usage

-- Database with dot in name (must be quoted when creating)
CREATE DATABASE `test.db`;
CREATE TABLE `test.db`.users (id UInt32, name String) ENGINE = MergeTree ORDER BY id;

-- Can now be referenced in JDBC with proper parsing
SELECT * FROM `test.db`.users WHERE id = ?;
INSERT INTO `test.db`.users VALUES (?, ?);

The JDBC driver now correctly parses these statements and extracts the full table name test.db.users for metadata operations.

Fixes ClickHouse#2650 Changes: - Updated ANTLR grammar databaseIdentifier rule to support multiple dot-separated identifiers: identifier (DOT identifier)* - Added extractTableName() helper method in SqlParserFacade to properly handle multi-part table identifiers by unquoting each part separately - Added testMultiDotNotation() test with 3 test cases covering SELECT, INSERT, and quoted identifiers - All 367 existing tests continue to pass This allows database names like 'a.b' in table references such as 'a.b.c' or '`db.part1`.`table`' to be parsed correctly.

windsurf-bot

💡 To request another review, post a new comment with "/windsurf-review".

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java

Addresses PR feedback: Only append dot after database identifier if table identifier is not null to avoid trailing dots.

devdavidkarlsson · 2025-11-20T14:10:24Z

/windsurf-review

windsurf-bot

Looks good to me 🤙

💡 To request another review, post a new comment with "/windsurf-review".

jdbc-v2/src/main/antlr4/com/clickhouse/jdbc/internal/parser/antlr4/ClickHouseParser.g4

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java

chernser · 2025-11-21T22:28:00Z

Good day, @devdavidkarlsson !
Thank you for the contribution!

I've left comments.
Build fails with:

Error:  Tests run: 1182, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 3.501 s <<< FAILURE! -- in TestSuite
Error:  com.clickhouse.jdbc.internal.JavaCCParserTest.testMultiDotNotation -- Time elapsed: 0.010 s <<< FAILURE!
java.lang.AssertionError: expected [false] but found [true]
	at org.testng.Assert.fail(Assert.java:110)
	at org.testng.Assert.failNotEquals(Assert.java:1413)
	at org.testng.Assert.assertFalse(Assert.java:78)
	at org.testng.Assert.assertFalse(Assert.java:88)
	at com.clickhouse.jdbc.internal.BaseSqlParserFacadeTest.testMultiDotNotation(BaseSqlParserFacadeTest.java:169)

Address PR feedback: Handle multi-dot notation directly in the parser grammar rather than in post-processing Java code. Changes: - ANTLR: Simplified to use getText() directly from parser, removed extractTableName() method that was walking the parse tree - JavaCC: Modified tableIdentifier rule to parse all dot-separated identifiers and split database/table within the grammar action - Both parsers now handle the logic in the grammar/parser itself

devdavidkarlsson · 2025-11-24T15:26:02Z

@chernser new attempt: I added the JavaCC (.jj) and got rid of extractTableName, tests should be green now.
Thank you 🙏

devdavidkarlsson · 2025-11-24T15:33:21Z

/windsurf-review

devdavidkarlsson · 2025-11-25T08:09:29Z

/windsurf-review

windsurf-bot

💡 To request another review, post a new comment with "/windsurf-review".

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java

jdbc-v2/src/main/javacc/ClickHouseSqlParser.jj

Address bot feedback about quoted identifiers containing dots. Changes: - ANTLR: Use ClickHouseSqlUtils.unescape() instead of SQLUtils.unquoteIdentifier() to properly handle escaped backticks - JavaCC: Already working correctly (no changes needed) - Added comprehensive test suite with 15 test cases covering all ClickHouse-relevant scenarios for quoted identifiers with dots Test coverage: Case SQL Pattern Database Table ---- ------------------------------------ ---------------- --------------- 1 db.table db table 2 `db`.`table` db table 3 db.`table.name` db table.name 4 `db.part1`.`table` db.part1 table 5 db.`table.name` db table.name 6 `db.part1`.table db.part1 table 7 db.`tab``le` db tab`le 8 `my db`.`table name!@#` my db table name!@# 9 `db.part1`.`table.name` AS t db.part1 table.name 10 db.`a.b.c.d` db a.b.c.d 11 `db.part1.part2`.`table` db.part1.part2 table 12 db.part1.table2 db.part1 table2 13 `db.part1`.`part2`.`table` db.part1.part2 table 14 db.part1.`table.name` db.part1 table.name 15 `db.part1`.part2.table3 db.part1.part2 table3 All 1104 tests passing (367 base tests × 3 parsers + 1 new test × 3).

devdavidkarlsson · 2025-11-25T09:38:45Z

/windsurf-review

windsurf-bot

💡 To request another review, post a new comment with "/windsurf-review".

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java

chernser · 2025-11-25T16:53:38Z

Good day, @devdavidkarlsson !
Will review today.

chernser · 2025-11-25T16:58:22Z

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java

                super.enterColumnExprPrecedence3(ctx);
            }

+            private String unquoteTableIdentifier(String rawTableId) {


strange - I thought I've left the comment that it should be actually handle by parser.
Because one of the points to have parser is to avoid writing this kind of methods.

chernser · 2025-11-25T16:59:38Z

jdbc-v2/src/main/javacc/ClickHouseSqlParser.jj

    {
-        if (record && t != null && token_source.table == null) {
-            token_source.table = ClickHouseSqlUtils.unescape(t.image);
+        if (record && token_source.table == null && parts.size() > 0) {


why parser cannot do it for us?

chernser

Please try to get clean table and database names using parser only.

…the parsing, instead of in the java code

windsurf-bot bot reviewed Nov 20, 2025

View reviewed changes

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java Outdated Show resolved Hide resolved

Fix extractTableName to check identifier before appending dot

1f9c61f

Addresses PR feedback: Only append dot after database identifier if table identifier is not null to avoid trailing dots.

windsurf-bot bot reviewed Nov 20, 2025

View reviewed changes

chernser reviewed Nov 21, 2025

View reviewed changes

jdbc-v2/src/main/antlr4/com/clickhouse/jdbc/internal/parser/antlr4/ClickHouseParser.g4 Show resolved Hide resolved

chernser reviewed Nov 21, 2025

View reviewed changes

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java Outdated Show resolved Hide resolved

devdavidkarlsson added 2 commits November 24, 2025 16:21

Merge branch 'ClickHouse:main' into fix/jdbc-v2-multi-dot-notation

5287098

windsurf-bot bot reviewed Nov 25, 2025

View reviewed changes

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java Outdated Show resolved Hide resolved

jdbc-v2/src/main/javacc/ClickHouseSqlParser.jj Show resolved Hide resolved

devdavidkarlsson force-pushed the fix/jdbc-v2-multi-dot-notation branch from ba2f40a to 823b35d Compare November 25, 2025 09:37

windsurf-bot bot reviewed Nov 25, 2025

View reviewed changes

jdbc-v2/src/main/java/com/clickhouse/jdbc/internal/SqlParserFacade.java Outdated Show resolved Hide resolved

chernser reviewed Nov 25, 2025

View reviewed changes

chernser requested changes Nov 25, 2025

View reviewed changes

The JavaCC and ANTLR grammars in updated to handle the ticks part of …

12f27b4

…the parsing, instead of in the java code

[jdbc-v2] Support multi-dot notation for database names #2663

Are you sure you want to change the base?

[jdbc-v2] Support multi-dot notation for database names #2663

Uh oh!

Conversation

devdavidkarlsson commented Nov 20, 2025

Description

Changes

Testing

Example Usage

Uh oh!

windsurf-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devdavidkarlsson commented Nov 20, 2025

Uh oh!

windsurf-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chernser commented Nov 21, 2025

Uh oh!

devdavidkarlsson commented Nov 24, 2025

Uh oh!

devdavidkarlsson commented Nov 24, 2025

Uh oh!

devdavidkarlsson commented Nov 25, 2025

Uh oh!

windsurf-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

devdavidkarlsson commented Nov 25, 2025

Uh oh!

windsurf-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chernser commented Nov 25, 2025

Uh oh!

chernser Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

chernser Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

chernser left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants