zkaoudi commented on code in PR #128:
URL: https://github.com/apache/wayang-website/pull/128#discussion_r3783309211
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
Review Comment:
"SQL capabilities" --> "an SQL API"
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
Review Comment:
Again it's not clear what is JDBC server and what is JDBC client here. This
needs to be clarified above or in the first figure.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
Review Comment:
could we also use the jdbc driver from a python program? If so, maybe it's
worth mentioning that.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Layered architecture of the Apache Wayang JDBC
implementation from Java application to Apache Wayang"
src="/img/blog/wayang-jdbc/architecture.png" />
+</div>
+
+The flow starts with a Java application. The application uses the standard
JDBC API to connect, submit SQL queries, and consume results.
+
+The Wayang JDBC driver is the client-side JDBC implementation. It provides the
JDBC-facing objects used by the application, including the driver, connection,
statement, result set, and database metadata objects. Its main responsibility
is to translate JDBC operations into requests that can be understood by the
server.
+
+The Wayang JDBC protocol defines the communication between the driver and
server. It covers requests, responses, errors, metadata, result data, and
protocol versioning. This keeps the driver and server connected through a
defined boundary instead of requiring them to depend directly on each other's
internal classes.
+
+The Wayang JDBC server handles JDBC requests on the Wayang side. It manages
client sessions, dispatches requests, validates queries, executes SQL, manages
result cursors, provides metadata, and returns errors or results to the driver.
+
+Apache Wayang remains responsible for the actual SQL processing. The JDBC
layer does not replace Wayang's SQL execution system; it provides a standard
entry point into it. Once the server passes a query into Wayang's SQL API,
Wayang handles planning, optimization, and execution.
+
+The key communication boundary is between the JDBC driver and the JDBC server:
+
+```text
+JDBC Driver
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the driver speaks JDBC, the protocol carries the requests, the
server manages the JDBC session and execution lifecycle, and Apache Wayang
performs the actual SQL processing.
+
+With these components in place, a JDBC query can travel from an application to
Wayang and return results through the standard `ResultSet` interface. Let's
follow that journey step by step.
+
+## How a SQL Query Works
+
+Consider a simple SQL query:
+
+```sql
+SELECT ID, NAME, CITY
+FROM fs.people
+ORDER BY ID;
+```
+
+This query travels through the JDBC implementation in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the Wayang JDBC driver,
protocol, server, Wayang execution, cursor store, and result fetching"
src="/img/blog/wayang-jdbc/sql-journey.png" />
+</div>
+
+### Phase 1 — Submit the query
+
+The Java application uses the standard JDBC API. When the application calls
`Statement.executeQuery()`, the JDBC driver receives the SQL query.
+
+The driver converts that JDBC operation into an `EXECUTE_QUERY` request and
sends it to the JDBC server.
+
+### Phase 2 — Validate and execute
+
+On the server side, the JDBC server identifies the client session and
validates the SQL query against the read-only policy. This is important because
the server is the boundary between the JDBC client and Wayang's execution
system.
+
+After validation, the server passes the SQL query to Wayang's SQL API through
`SqlContext`. From there, Wayang handles planning, optimization, and execution
on the selected execution platform.
+
+### Phase 3 — Produce the result
+
+After execution, the server obtains the query rows and column metadata. The
rows are associated with a server-side cursor so they can be consumed
incrementally instead of requiring the client to handle the entire result at
once.
+
+The `CursorStore` keeps track of this server-side result state for the session.
+
+### Phase 4 — Consume results
+
+The server returns the first result page to the JDBC driver. The Java
application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the driver
sends a `FETCH` request. The server reads the next page from the `CursorStore`
and returns it to the client. This continues until the result set is exhausted.
+
+The important distinction is that query execution and result fetching are
separate:
+
+```text
+EXECUTE_QUERY
+ ↓
+Execute SQL
+ ↓
+Create result/cursor
+ ↓
+Return first page
+```
+
+```text
+ResultSet.next()
+ ↓
+Need more rows?
+ ↓
+FETCH
+ ↓
+CursorStore
+ ↓
+Next page
+```
+
+Each `ResultSet.next()` does not execute the SQL query again. The query is
executed once, and later fetches retrieve additional pages from the server-side
cursor.
+
+> The JDBC application only sees the standard JDBC interface. The driver,
protocol, and server handle the communication and lifecycle details, while
Apache Wayang remains responsible for SQL processing and execution.
+
+## Key Design Decisions
+
+This section explains why the JDBC implementation is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the JDBC driver contain the Wayang runtime, or should
query execution happen separately?
+
+**Decision:** The implementation separates the client-side JDBC driver from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
+ ↓
+JDBC Server
+ ↓
+Apache Wayang
+```
+
+**Why:** This keeps the JDBC client separate from the Wayang runtime, provides
a clear boundary between JDBC and Wayang, and allows the server to manage
execution and resources.
+
+**Trade-off:** This separation introduces network communication and
server-side lifecycle management.
+
+### 2. A dedicated driver–server protocol
+
+**Problem:** The driver and server need to exchange requests, responses,
errors, metadata, and result data without relying on each other's internal Java
objects.
+
+**Decision:** The driver and server communicate through a defined TCP protocol
using length-prefixed JSON messages.
+
+```text
+JDBC Driver
+ │
+ │ TCP
+ │
+ │ Length-prefixed JSON
+ ▼
+JDBC Server
+```
+
+**Why:** The protocol gives both sides a clear communication contract and
makes the boundary between the JDBC client implementation and the server
implementation explicit.
+
+**Trade-off:** The protocol must be maintained as part of the project,
including versioning, error representation, and message compatibility.
+
+### 3. Server-side read-only validation
+
+**Problem:** The project scope is read-only SQL execution, and that policy
needs to be enforced at the correct boundary.
+
+**Decision:** The server validates incoming SQL against the read-only policy
before sending it to Wayang.
+
+```text
+SQL Query
+ ↓
+JDBC Server
+ ↓
+Read-only validation
+ ↙ ↘
+Allowed Rejected
+ ↓
+Wayang
+```
+
+**Why:** The server is the execution boundary, so it should enforce the policy
rather than relying only on the client.
+
+**Trade-off:** The server needs validation logic before query execution can
begin.
+
+### 4. Cursor-based result paging
+
+**Problem:** A query may return many rows, and returning the entire result set
in a single response is not a good fit for the client/server protocol.
+
+**Decision:** The server uses a logical cursor and returns results in pages.
+
+```text
+Execute Query
+ ↓
+Results
+ ↓
+CursorStore
+ ↓
+Page 1
+ ↓
+FETCH
+ ↓
+Page 2
+ ↓
+FETCH
+ ↓
+Page 3
+```
+
+**Why:** Paging allows the JDBC `ResultSet` to consume results incrementally
instead of requiring one large response.
+
+**Trade-off:** The server must maintain cursor state and clean it up correctly.
+
+### 5. Hierarchical resource ownership
+
+**Problem:** JDBC objects have dependent lifecycles, and the server has
corresponding resources that must not leak.
+
+**Decision:** Resource ownership follows the JDBC object hierarchy.
+
+```text
+Connection
+ ↓
+Statement
+ ↓
+ResultSet
+ ↓
+Server Cursor
+```
+
+When a connection closes, its statements, result sets, and associated server
resources are cleaned up. When a statement closes or replaces its result set,
the result-set and cursor resources are released. When a result set closes, its
server-side cursor is released. If a client disconnects, the server cleans up
the session and the resources belonging to that client.
+
+**Why:** This makes lifecycle behavior predictable and helps prevent leaked
server-side cursors or stale session resources.
+
+**Trade-off:** The implementation needs explicit ownership tracking on both
the client side and the server side.
+
+Together, these decisions keep the system understandable: the driver presents
JDBC, the protocol defines communication, the server owns execution policy and
lifecycle, and Wayang performs the SQL processing.
+
+## What Was Implemented
+
+This section summarizes the concrete functionality delivered during the
project.
+
+### JDBC driver
+
+The client-side JDBC module implements the JDBC-facing layer that Java
applications use directly.
+
+**Connection**
+
+- JDBC driver registration
+- Connection establishment
+- JDBC URL handling
+- Connection lifecycle
+
+**Statement**
+
+- Statement creation
+- SQL query submission
+- Query execution
+- Statement lifecycle
+
+**ResultSet**
+
+- Result navigation
+- Typed value access
+- `wasNull()`
+- Result paging
+- ResultSet lifecycle
+
+**Metadata**
+
+- `ResultSetMetaData`
+- `DatabaseMetaData`
+- Catalog information
+- Schema information
+- Table information
+- Column information
+- JDBC type information
+
+### JDBC protocol
+
+The protocol module defines the contract between the driver and the server.
+
+Implemented protocol functionality includes:
+
+- Request and response messages
+- Protocol versioning
+- Query execution requests
+- Fetch requests
+- Metadata requests
+- Error responses
+- Result data transfer
+- Length-prefixed JSON framing
+
+The important point is that the protocol is the boundary between the JDBC
client implementation and the server-side implementation.
+
+### JDBC server
+
+The server-side module receives JDBC protocol requests and turns them into
Wayang operations.
+
+Implemented server functionality includes:
+
+- Client session management
+- Request dispatching
+- SQL query execution
+- Read-only SQL validation
+- Result and cursor management
+- Result paging
+- Metadata retrieval
+- Error handling
+- Resource cleanup
+
+This is the part of the system where a JDBC request becomes an actual Wayang
SQL operation.
+
+### Wayang SQL integration
+
+The JDBC server connects to Wayang's existing SQL functionality instead of
replacing it.
+
+```text
+JDBC Request
+ ↓
+JDBC Server
+ ↓
+Wayang SQL API
+ ↓
+Query Processing
+ ↓
+Results
+```
+
+The integration allows SQL submitted through JDBC to be passed into Wayang's
SQL API, processed by Wayang, and returned through the JDBC result-handling
path. The exact upstream files and classes changed for this integration should
be listed with the final PRs and commits after final upstream verification.
+
+### Repository map
+
+The implementation is organized around the same major areas described above:
+
+```text
+wayang-jdbc/
+│
+├── wayang-jdbc-driver/
+│ └── Client-side JDBC implementation
+│
+├── wayang-jdbc-protocol/
+│ └── Driver ↔ Server communication
+│
+├── wayang-jdbc-server/
+│ └── Server-side JDBC implementation
+```
+
+If you want to understand the client, start with the driver. If you want to
understand communication, start with the protocol. If you want to understand
execution, start with the server.
+
+With the core JDBC functionality implemented, the next question is how well it
behaves in practice. The implementation was validated through automated tests
and end-to-end execution.
+
+## Testing & Validation
+
+The JDBC implementation was validated across the client, protocol, server, and
Wayang integration layers. Testing focused on JDBC behavior, request and
response handling, query execution, result and metadata processing, error
handling, and resource lifecycle to ensure that the complete flow works
consistently from the application to Wayang and back.
+
+<div style={{textAlign: 'center'}}>
Review Comment:
Maybe this figure is not required. It doesn't add much to the text.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
Review Comment:
"The JDBC implementation" --> "The JDBC driver implementation"
It's important this detail, because we also have the JDBC template as
platforms and it can be confusing what we mean.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Layered architecture of the Apache Wayang JDBC
implementation from Java application to Apache Wayang"
src="/img/blog/wayang-jdbc/architecture.png" />
+</div>
+
+The flow starts with a Java application. The application uses the standard
JDBC API to connect, submit SQL queries, and consume results.
+
+The Wayang JDBC driver is the client-side JDBC implementation. It provides the
JDBC-facing objects used by the application, including the driver, connection,
statement, result set, and database metadata objects. Its main responsibility
is to translate JDBC operations into requests that can be understood by the
server.
+
+The Wayang JDBC protocol defines the communication between the driver and
server. It covers requests, responses, errors, metadata, result data, and
protocol versioning. This keeps the driver and server connected through a
defined boundary instead of requiring them to depend directly on each other's
internal classes.
+
+The Wayang JDBC server handles JDBC requests on the Wayang side. It manages
client sessions, dispatches requests, validates queries, executes SQL, manages
result cursors, provides metadata, and returns errors or results to the driver.
+
+Apache Wayang remains responsible for the actual SQL processing. The JDBC
layer does not replace Wayang's SQL execution system; it provides a standard
entry point into it. Once the server passes a query into Wayang's SQL API,
Wayang handles planning, optimization, and execution.
+
+The key communication boundary is between the JDBC driver and the JDBC server:
Review Comment:
I would say that driver is the entire implementation which consists of the
client, the protocol, and the server
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
Review Comment:
in this file, why "JDBC server" is a separate box? Shouldn't it be part of
the Wayang JDBC driver? Maybe at this stage you don't need this box at all.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Layered architecture of the Apache Wayang JDBC
implementation from Java application to Apache Wayang"
src="/img/blog/wayang-jdbc/architecture.png" />
+</div>
+
+The flow starts with a Java application. The application uses the standard
JDBC API to connect, submit SQL queries, and consume results.
+
+The Wayang JDBC driver is the client-side JDBC implementation. It provides the
JDBC-facing objects used by the application, including the driver, connection,
statement, result set, and database metadata objects. Its main responsibility
is to translate JDBC operations into requests that can be understood by the
server.
+
+The Wayang JDBC protocol defines the communication between the driver and
server. It covers requests, responses, errors, metadata, result data, and
protocol versioning. This keeps the driver and server connected through a
defined boundary instead of requiring them to depend directly on each other's
internal classes.
+
+The Wayang JDBC server handles JDBC requests on the Wayang side. It manages
client sessions, dispatches requests, validates queries, executes SQL, manages
result cursors, provides metadata, and returns errors or results to the driver.
+
+Apache Wayang remains responsible for the actual SQL processing. The JDBC
layer does not replace Wayang's SQL execution system; it provides a standard
entry point into it. Once the server passes a query into Wayang's SQL API,
Wayang handles planning, optimization, and execution.
+
+The key communication boundary is between the JDBC driver and the JDBC server:
Review Comment:
by "JDBC driver" you mean "JDBC client"?
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
Review Comment:
I would replace "SQL capabilities" with "SQL API", as capabilities can also
be seen as the SQL platforms we support.
Also JDBC client is unclear what it means here. So either you change it or
introduce the term or visualize it in the figure before.
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Layered architecture of the Apache Wayang JDBC
implementation from Java application to Apache Wayang"
src="/img/blog/wayang-jdbc/architecture.png" />
+</div>
+
+The flow starts with a Java application. The application uses the standard
JDBC API to connect, submit SQL queries, and consume results.
+
+The Wayang JDBC driver is the client-side JDBC implementation. It provides the
JDBC-facing objects used by the application, including the driver, connection,
statement, result set, and database metadata objects. Its main responsibility
is to translate JDBC operations into requests that can be understood by the
server.
+
+The Wayang JDBC protocol defines the communication between the driver and
server. It covers requests, responses, errors, metadata, result data, and
protocol versioning. This keeps the driver and server connected through a
defined boundary instead of requiring them to depend directly on each other's
internal classes.
+
+The Wayang JDBC server handles JDBC requests on the Wayang side. It manages
client sessions, dispatches requests, validates queries, executes SQL, manages
result cursors, provides metadata, and returns errors or results to the driver.
+
+Apache Wayang remains responsible for the actual SQL processing. The JDBC
layer does not replace Wayang's SQL execution system; it provides a standard
entry point into it. Once the server passes a query into Wayang's SQL API,
Wayang handles planning, optimization, and execution.
+
+The key communication boundary is between the JDBC driver and the JDBC server:
+
+```text
+JDBC Driver
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the driver speaks JDBC, the protocol carries the requests, the
server manages the JDBC session and execution lifecycle, and Apache Wayang
performs the actual SQL processing.
+
+With these components in place, a JDBC query can travel from an application to
Wayang and return results through the standard `ResultSet` interface. Let's
follow that journey step by step.
+
+## How a SQL Query Works
+
+Consider a simple SQL query:
+
+```sql
+SELECT ID, NAME, CITY
+FROM fs.people
+ORDER BY ID;
+```
+
+This query travels through the JDBC implementation in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the Wayang JDBC driver,
protocol, server, Wayang execution, cursor store, and result fetching"
src="/img/blog/wayang-jdbc/sql-journey.png" />
+</div>
+
+### Phase 1 — Submit the query
+
+The Java application uses the standard JDBC API. When the application calls
`Statement.executeQuery()`, the JDBC driver receives the SQL query.
+
+The driver converts that JDBC operation into an `EXECUTE_QUERY` request and
sends it to the JDBC server.
+
+### Phase 2 — Validate and execute
+
+On the server side, the JDBC server identifies the client session and
validates the SQL query against the read-only policy. This is important because
the server is the boundary between the JDBC client and Wayang's execution
system.
+
+After validation, the server passes the SQL query to Wayang's SQL API through
`SqlContext`. From there, Wayang handles planning, optimization, and execution
on the selected execution platform.
+
+### Phase 3 — Produce the result
+
+After execution, the server obtains the query rows and column metadata. The
rows are associated with a server-side cursor so they can be consumed
incrementally instead of requiring the client to handle the entire result at
once.
+
+The `CursorStore` keeps track of this server-side result state for the session.
+
+### Phase 4 — Consume results
+
+The server returns the first result page to the JDBC driver. The Java
application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the driver
sends a `FETCH` request. The server reads the next page from the `CursorStore`
and returns it to the client. This continues until the result set is exhausted.
+
+The important distinction is that query execution and result fetching are
separate:
+
+```text
+EXECUTE_QUERY
+ ↓
+Execute SQL
+ ↓
+Create result/cursor
+ ↓
+Return first page
+```
+
+```text
+ResultSet.next()
+ ↓
+Need more rows?
+ ↓
+FETCH
+ ↓
+CursorStore
+ ↓
+Next page
+```
+
+Each `ResultSet.next()` does not execute the SQL query again. The query is
executed once, and later fetches retrieve additional pages from the server-side
cursor.
+
+> The JDBC application only sees the standard JDBC interface. The driver,
protocol, and server handle the communication and lifecycle details, while
Apache Wayang remains responsible for SQL processing and execution.
+
+## Key Design Decisions
+
+This section explains why the JDBC implementation is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the JDBC driver contain the Wayang runtime, or should
query execution happen separately?
+
+**Decision:** The implementation separates the client-side JDBC driver from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
+ ↓
+JDBC Server
+ ↓
+Apache Wayang
+```
+
+**Why:** This keeps the JDBC client separate from the Wayang runtime, provides
a clear boundary between JDBC and Wayang, and allows the server to manage
execution and resources.
+
+**Trade-off:** This separation introduces network communication and
server-side lifecycle management.
+
+### 2. A dedicated driver–server protocol
+
+**Problem:** The driver and server need to exchange requests, responses,
errors, metadata, and result data without relying on each other's internal Java
objects.
+
+**Decision:** The driver and server communicate through a defined TCP protocol
using length-prefixed JSON messages.
+
+```text
+JDBC Driver
+ │
+ │ TCP
+ │
+ │ Length-prefixed JSON
+ ▼
+JDBC Server
+```
+
+**Why:** The protocol gives both sides a clear communication contract and
makes the boundary between the JDBC client implementation and the server
implementation explicit.
+
+**Trade-off:** The protocol must be maintained as part of the project,
including versioning, error representation, and message compatibility.
+
+### 3. Server-side read-only validation
+
+**Problem:** The project scope is read-only SQL execution, and that policy
needs to be enforced at the correct boundary.
+
+**Decision:** The server validates incoming SQL against the read-only policy
before sending it to Wayang.
+
+```text
+SQL Query
+ ↓
+JDBC Server
+ ↓
+Read-only validation
+ ↙ ↘
+Allowed Rejected
+ ↓
+Wayang
+```
+
+**Why:** The server is the execution boundary, so it should enforce the policy
rather than relying only on the client.
+
+**Trade-off:** The server needs validation logic before query execution can
begin.
+
+### 4. Cursor-based result paging
+
+**Problem:** A query may return many rows, and returning the entire result set
in a single response is not a good fit for the client/server protocol.
+
+**Decision:** The server uses a logical cursor and returns results in pages.
+
+```text
+Execute Query
+ ↓
+Results
+ ↓
+CursorStore
+ ↓
+Page 1
+ ↓
+FETCH
+ ↓
+Page 2
+ ↓
+FETCH
+ ↓
+Page 3
+```
+
+**Why:** Paging allows the JDBC `ResultSet` to consume results incrementally
instead of requiring one large response.
+
+**Trade-off:** The server must maintain cursor state and clean it up correctly.
+
+### 5. Hierarchical resource ownership
+
+**Problem:** JDBC objects have dependent lifecycles, and the server has
corresponding resources that must not leak.
+
+**Decision:** Resource ownership follows the JDBC object hierarchy.
+
+```text
+Connection
+ ↓
+Statement
+ ↓
+ResultSet
+ ↓
+Server Cursor
+```
+
+When a connection closes, its statements, result sets, and associated server
resources are cleaned up. When a statement closes or replaces its result set,
the result-set and cursor resources are released. When a result set closes, its
server-side cursor is released. If a client disconnects, the server cleans up
the session and the resources belonging to that client.
+
+**Why:** This makes lifecycle behavior predictable and helps prevent leaked
server-side cursors or stale session resources.
+
+**Trade-off:** The implementation needs explicit ownership tracking on both
the client side and the server side.
+
+Together, these decisions keep the system understandable: the driver presents
JDBC, the protocol defines communication, the server owns execution policy and
lifecycle, and Wayang performs the SQL processing.
+
+## What Was Implemented
+
+This section summarizes the concrete functionality delivered during the
project.
+
+### JDBC driver
+
+The client-side JDBC module implements the JDBC-facing layer that Java
applications use directly.
+
+**Connection**
+
+- JDBC driver registration
+- Connection establishment
+- JDBC URL handling
+- Connection lifecycle
+
+**Statement**
+
+- Statement creation
+- SQL query submission
+- Query execution
+- Statement lifecycle
+
+**ResultSet**
+
+- Result navigation
+- Typed value access
+- `wasNull()`
+- Result paging
+- ResultSet lifecycle
+
+**Metadata**
+
+- `ResultSetMetaData`
+- `DatabaseMetaData`
+- Catalog information
+- Schema information
+- Table information
+- Column information
+- JDBC type information
+
+### JDBC protocol
+
+The protocol module defines the contract between the driver and the server.
+
+Implemented protocol functionality includes:
+
+- Request and response messages
+- Protocol versioning
+- Query execution requests
+- Fetch requests
+- Metadata requests
+- Error responses
+- Result data transfer
+- Length-prefixed JSON framing
+
+The important point is that the protocol is the boundary between the JDBC
client implementation and the server-side implementation.
+
+### JDBC server
+
+The server-side module receives JDBC protocol requests and turns them into
Wayang operations.
+
+Implemented server functionality includes:
+
+- Client session management
+- Request dispatching
+- SQL query execution
+- Read-only SQL validation
+- Result and cursor management
+- Result paging
+- Metadata retrieval
+- Error handling
+- Resource cleanup
+
+This is the part of the system where a JDBC request becomes an actual Wayang
SQL operation.
+
+### Wayang SQL integration
+
+The JDBC server connects to Wayang's existing SQL functionality instead of
replacing it.
+
+```text
+JDBC Request
+ ↓
+JDBC Server
+ ↓
+Wayang SQL API
+ ↓
+Query Processing
+ ↓
+Results
+```
+
+The integration allows SQL submitted through JDBC to be passed into Wayang's
SQL API, processed by Wayang, and returned through the JDBC result-handling
path. The exact upstream files and classes changed for this integration should
be listed with the final PRs and commits after final upstream verification.
+
+### Repository map
+
+The implementation is organized around the same major areas described above:
+
+```text
+wayang-jdbc/
+│
+├── wayang-jdbc-driver/
+│ └── Client-side JDBC implementation
+│
+├── wayang-jdbc-protocol/
+│ └── Driver ↔ Server communication
+│
+├── wayang-jdbc-server/
+│ └── Server-side JDBC implementation
+```
+
+If you want to understand the client, start with the driver. If you want to
understand communication, start with the protocol. If you want to understand
execution, start with the server.
+
+With the core JDBC functionality implemented, the next question is how well it
behaves in practice. The implementation was validated through automated tests
and end-to-end execution.
+
+## Testing & Validation
+
+The JDBC implementation was validated across the client, protocol, server, and
Wayang integration layers. Testing focused on JDBC behavior, request and
response handling, query execution, result and metadata processing, error
handling, and resource lifecycle to ensure that the complete flow works
consistently from the application to Wayang and back.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Validated JDBC application to Apache Wayang result
flow" src="/img/blog/wayang-jdbc/testing-validation.svg" />
+</div>
+
+## Demo / How to Run
+
+The JDBC module includes a small local demo for exploring CSV-backed datasets.
The demo lists available CSV files, shows their SQL-style table names, lets the
user select a dataset, and then runs simple analysis operations on the selected
file.
+
+This demo is intentionally beginner-friendly. It helps show how external data
can be represented as logical SQL-style tables, while keeping the data itself
in ordinary CSV files.
+
+### Prerequisites
+
+- Java 17 JDK
+- Git
+- Bash
+
+Verify the required tools:
+
+```text
+java -version
+javac -version
+git --version
+```
+
+The demo requires a JDK because the client is compiled with `javac`.
+
+### 1. Get the code
+
+```text
+git clone https://github.com/apache/wayang.git
+cd wayang
+```
+
+### 2. Run the CSV selection demo
+
+Run:
+
+```text
+bash wayang-jdbc/demo/run-demo-client.sh
+```
+
+The script compiles and runs `CsvSelectionOperationsDemo.java`. It discovers
available CSV files from `wayang-jdbc/demo/data`, maps each CSV file to a
SQL-style table name under the `fs` schema, and lets the user select a CSV file
by number or name.
+
+For example, the demo can show files such as:
+
+```text
+ecommerce_sales_analytics.csv -> fs.ecommerce_sales_analytics
+heart_disease_risk_2026.csv -> fs.heart_disease_risk_2026
+people.csv -> fs.people
+student_performance_dataset.csv -> fs.student_performance_dataset
+```
+
+Selecting `heart_disease_risk` loads `heart_disease_risk_2026.csv` and
performs simple operations such as:
+
+- total row count
+- column listing
+- first 5 rows preview
+- numeric summaries such as min, max, and average
+- heart-disease-specific grouping and averages
+
+### 3. What the demo shows
+
+This demo helps demonstrate the idea that Wayang is not a database and does
not store the data itself. The CSV files remain in the data folder, while the
demo shows how they can be treated as logical SQL-style tables such as
`fs.heart_disease_risk_2026`.
Review Comment:
Can't the demo actually execute an SQL query against these datasets?
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,578 @@
+---
+slug: gsoc-2026-wayang-jdbc-driver
+title: Introducing JDBC Support for Apache Wayang
+authors: [makarandhinge]
+tags: [wayang, jdbc, gsoc]
+---
+
+# Introducing JDBC Support for Apache Wayang
+
+As part of Google Summer of Code 2026, I implemented a JDBC driver for Apache
Wayang, enabling Java applications to interact with Wayang through the standard
JDBC API.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Apache Wayang JDBC driver project hero image"
src="/img/blog/wayang-jdbc/hero-image.png" />
+</div>
+
+Apache Wayang provides a unified way to express and execute data processing
workloads across different execution platforms. This project introduces a JDBC
interface around Wayang's SQL capabilities, separating the standard JDBC client
experience from the underlying Wayang execution system.
+
+<!--truncate-->
+
+## Why JDBC?
+
+JDBC is the standard database interface for Java applications. It provides
familiar concepts such as connections, statements, result sets, and metadata,
which many Java developers already understand.
+
+Apache Wayang already provides SQL capabilities, but the missing piece was a
standard JDBC interface for external applications. This project addresses that
gap by making Wayang accessible through the JDBC API without requiring
applications to depend directly on Wayang-specific APIs.
+
+The impact goes beyond providing another way for Java applications to execute
SQL. JDBC provides a bridge between Wayang's cross-platform data processing
capabilities and the broader SQL ecosystem. By exposing Wayang through a
standard database interface, applications and tools that already understand
JDBC can potentially interact with Wayang without requiring Wayang-specific
integrations.
+
+This opens the door to integrating Wayang with external business intelligence
and data analysis tools such as Tableau, Power BI, and other JDBC-compatible
applications. Such integrations could allow users to work with familiar SQL and
BI interfaces while benefiting from Wayang's ability to execute data processing
workloads across different execution platforms.
+
+The JDBC layer therefore acts as an integration boundary: applications
interact through a standard database interface, while Wayang remains
responsible for SQL processing, optimization, and execution across its
supported platforms.
+
+To make this possible, the project separates the JDBC client from the Wayang
execution environment through a set of components that work together.
+
+## Architecture
+
+The JDBC implementation is organized into separate components so that the
JDBC-facing API, communication protocol, server-side request handling, and
Wayang execution remain independently manageable.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Layered architecture of the Apache Wayang JDBC
implementation from Java application to Apache Wayang"
src="/img/blog/wayang-jdbc/architecture.png" />
+</div>
+
+The flow starts with a Java application. The application uses the standard
JDBC API to connect, submit SQL queries, and consume results.
+
+The Wayang JDBC driver is the client-side JDBC implementation. It provides the
JDBC-facing objects used by the application, including the driver, connection,
statement, result set, and database metadata objects. Its main responsibility
is to translate JDBC operations into requests that can be understood by the
server.
+
+The Wayang JDBC protocol defines the communication between the driver and
server. It covers requests, responses, errors, metadata, result data, and
protocol versioning. This keeps the driver and server connected through a
defined boundary instead of requiring them to depend directly on each other's
internal classes.
+
+The Wayang JDBC server handles JDBC requests on the Wayang side. It manages
client sessions, dispatches requests, validates queries, executes SQL, manages
result cursors, provides metadata, and returns errors or results to the driver.
+
+Apache Wayang remains responsible for the actual SQL processing. The JDBC
layer does not replace Wayang's SQL execution system; it provides a standard
entry point into it. Once the server passes a query into Wayang's SQL API,
Wayang handles planning, optimization, and execution.
+
+The key communication boundary is between the JDBC driver and the JDBC server:
+
+```text
+JDBC Driver
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the driver speaks JDBC, the protocol carries the requests, the
server manages the JDBC session and execution lifecycle, and Apache Wayang
performs the actual SQL processing.
+
+With these components in place, a JDBC query can travel from an application to
Wayang and return results through the standard `ResultSet` interface. Let's
follow that journey step by step.
+
+## How a SQL Query Works
+
+Consider a simple SQL query:
+
+```sql
+SELECT ID, NAME, CITY
+FROM fs.people
+ORDER BY ID;
+```
+
+This query travels through the JDBC implementation in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the Wayang JDBC driver,
protocol, server, Wayang execution, cursor store, and result fetching"
src="/img/blog/wayang-jdbc/sql-journey.png" />
+</div>
+
+### Phase 1 — Submit the query
+
+The Java application uses the standard JDBC API. When the application calls
`Statement.executeQuery()`, the JDBC driver receives the SQL query.
+
+The driver converts that JDBC operation into an `EXECUTE_QUERY` request and
sends it to the JDBC server.
+
+### Phase 2 — Validate and execute
+
+On the server side, the JDBC server identifies the client session and
validates the SQL query against the read-only policy. This is important because
the server is the boundary between the JDBC client and Wayang's execution
system.
+
+After validation, the server passes the SQL query to Wayang's SQL API through
`SqlContext`. From there, Wayang handles planning, optimization, and execution
on the selected execution platform.
+
+### Phase 3 — Produce the result
+
+After execution, the server obtains the query rows and column metadata. The
rows are associated with a server-side cursor so they can be consumed
incrementally instead of requiring the client to handle the entire result at
once.
+
+The `CursorStore` keeps track of this server-side result state for the session.
+
+### Phase 4 — Consume results
+
+The server returns the first result page to the JDBC driver. The Java
application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the driver
sends a `FETCH` request. The server reads the next page from the `CursorStore`
and returns it to the client. This continues until the result set is exhausted.
+
+The important distinction is that query execution and result fetching are
separate:
+
+```text
+EXECUTE_QUERY
+ ↓
+Execute SQL
+ ↓
+Create result/cursor
+ ↓
+Return first page
+```
+
+```text
+ResultSet.next()
+ ↓
+Need more rows?
+ ↓
+FETCH
+ ↓
+CursorStore
+ ↓
+Next page
+```
+
+Each `ResultSet.next()` does not execute the SQL query again. The query is
executed once, and later fetches retrieve additional pages from the server-side
cursor.
+
+> The JDBC application only sees the standard JDBC interface. The driver,
protocol, and server handle the communication and lifecycle details, while
Apache Wayang remains responsible for SQL processing and execution.
+
+## Key Design Decisions
+
+This section explains why the JDBC implementation is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the JDBC driver contain the Wayang runtime, or should
query execution happen separately?
+
+**Decision:** The implementation separates the client-side JDBC driver from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
+ ↓
+JDBC Server
+ ↓
+Apache Wayang
+```
+
+**Why:** This keeps the JDBC client separate from the Wayang runtime, provides
a clear boundary between JDBC and Wayang, and allows the server to manage
execution and resources.
+
+**Trade-off:** This separation introduces network communication and
server-side lifecycle management.
+
+### 2. A dedicated driver–server protocol
+
+**Problem:** The driver and server need to exchange requests, responses,
errors, metadata, and result data without relying on each other's internal Java
objects.
+
+**Decision:** The driver and server communicate through a defined TCP protocol
using length-prefixed JSON messages.
+
+```text
+JDBC Driver
+ │
+ │ TCP
+ │
+ │ Length-prefixed JSON
+ ▼
+JDBC Server
+```
+
+**Why:** The protocol gives both sides a clear communication contract and
makes the boundary between the JDBC client implementation and the server
implementation explicit.
+
+**Trade-off:** The protocol must be maintained as part of the project,
including versioning, error representation, and message compatibility.
+
+### 3. Server-side read-only validation
+
+**Problem:** The project scope is read-only SQL execution, and that policy
needs to be enforced at the correct boundary.
+
+**Decision:** The server validates incoming SQL against the read-only policy
before sending it to Wayang.
+
+```text
+SQL Query
+ ↓
+JDBC Server
+ ↓
+Read-only validation
+ ↙ ↘
+Allowed Rejected
+ ↓
+Wayang
+```
+
+**Why:** The server is the execution boundary, so it should enforce the policy
rather than relying only on the client.
+
+**Trade-off:** The server needs validation logic before query execution can
begin.
+
+### 4. Cursor-based result paging
+
+**Problem:** A query may return many rows, and returning the entire result set
in a single response is not a good fit for the client/server protocol.
+
+**Decision:** The server uses a logical cursor and returns results in pages.
+
+```text
+Execute Query
+ ↓
+Results
+ ↓
+CursorStore
+ ↓
+Page 1
+ ↓
+FETCH
+ ↓
+Page 2
+ ↓
+FETCH
+ ↓
+Page 3
+```
+
+**Why:** Paging allows the JDBC `ResultSet` to consume results incrementally
instead of requiring one large response.
+
+**Trade-off:** The server must maintain cursor state and clean it up correctly.
+
+### 5. Hierarchical resource ownership
+
+**Problem:** JDBC objects have dependent lifecycles, and the server has
corresponding resources that must not leak.
+
+**Decision:** Resource ownership follows the JDBC object hierarchy.
+
+```text
+Connection
+ ↓
+Statement
+ ↓
+ResultSet
+ ↓
+Server Cursor
+```
+
+When a connection closes, its statements, result sets, and associated server
resources are cleaned up. When a statement closes or replaces its result set,
the result-set and cursor resources are released. When a result set closes, its
server-side cursor is released. If a client disconnects, the server cleans up
the session and the resources belonging to that client.
+
+**Why:** This makes lifecycle behavior predictable and helps prevent leaked
server-side cursors or stale session resources.
+
+**Trade-off:** The implementation needs explicit ownership tracking on both
the client side and the server side.
+
+Together, these decisions keep the system understandable: the driver presents
JDBC, the protocol defines communication, the server owns execution policy and
lifecycle, and Wayang performs the SQL processing.
+
+## What Was Implemented
+
+This section summarizes the concrete functionality delivered during the
project.
+
+### JDBC driver
+
+The client-side JDBC module implements the JDBC-facing layer that Java
applications use directly.
+
+**Connection**
+
+- JDBC driver registration
+- Connection establishment
+- JDBC URL handling
+- Connection lifecycle
+
+**Statement**
+
+- Statement creation
+- SQL query submission
+- Query execution
+- Statement lifecycle
+
+**ResultSet**
+
+- Result navigation
+- Typed value access
+- `wasNull()`
+- Result paging
+- ResultSet lifecycle
+
+**Metadata**
+
+- `ResultSetMetaData`
+- `DatabaseMetaData`
+- Catalog information
+- Schema information
+- Table information
+- Column information
+- JDBC type information
+
+### JDBC protocol
+
+The protocol module defines the contract between the driver and the server.
+
+Implemented protocol functionality includes:
+
+- Request and response messages
+- Protocol versioning
+- Query execution requests
+- Fetch requests
+- Metadata requests
+- Error responses
+- Result data transfer
+- Length-prefixed JSON framing
+
+The important point is that the protocol is the boundary between the JDBC
client implementation and the server-side implementation.
+
+### JDBC server
+
+The server-side module receives JDBC protocol requests and turns them into
Wayang operations.
+
+Implemented server functionality includes:
+
+- Client session management
+- Request dispatching
+- SQL query execution
+- Read-only SQL validation
+- Result and cursor management
+- Result paging
+- Metadata retrieval
+- Error handling
+- Resource cleanup
+
+This is the part of the system where a JDBC request becomes an actual Wayang
SQL operation.
+
+### Wayang SQL integration
+
+The JDBC server connects to Wayang's existing SQL functionality instead of
replacing it.
+
+```text
+JDBC Request
+ ↓
+JDBC Server
+ ↓
+Wayang SQL API
+ ↓
+Query Processing
+ ↓
+Results
+```
+
+The integration allows SQL submitted through JDBC to be passed into Wayang's
SQL API, processed by Wayang, and returned through the JDBC result-handling
path. The exact upstream files and classes changed for this integration should
be listed with the final PRs and commits after final upstream verification.
+
+### Repository map
+
+The implementation is organized around the same major areas described above:
+
+```text
+wayang-jdbc/
+│
+├── wayang-jdbc-driver/
+│ └── Client-side JDBC implementation
+│
+├── wayang-jdbc-protocol/
+│ └── Driver ↔ Server communication
+│
+├── wayang-jdbc-server/
+│ └── Server-side JDBC implementation
+```
+
+If you want to understand the client, start with the driver. If you want to
understand communication, start with the protocol. If you want to understand
execution, start with the server.
+
+With the core JDBC functionality implemented, the next question is how well it
behaves in practice. The implementation was validated through automated tests
and end-to-end execution.
+
+## Testing & Validation
+
+The JDBC implementation was validated across the client, protocol, server, and
Wayang integration layers. Testing focused on JDBC behavior, request and
response handling, query execution, result and metadata processing, error
handling, and resource lifecycle to ensure that the complete flow works
consistently from the application to Wayang and back.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="Validated JDBC application to Apache Wayang result
flow" src="/img/blog/wayang-jdbc/testing-validation.svg" />
+</div>
+
+## Demo / How to Run
+
+The JDBC module includes a small local demo for exploring CSV-backed datasets.
The demo lists available CSV files, shows their SQL-style table names, lets the
user select a dataset, and then runs simple analysis operations on the selected
file.
+
+This demo is intentionally beginner-friendly. It helps show how external data
can be represented as logical SQL-style tables, while keeping the data itself
in ordinary CSV files.
+
+### Prerequisites
+
+- Java 17 JDK
+- Git
+- Bash
+
+Verify the required tools:
+
+```text
+java -version
+javac -version
+git --version
+```
+
+The demo requires a JDK because the client is compiled with `javac`.
+
+### 1. Get the code
+
+```text
+git clone https://github.com/apache/wayang.git
+cd wayang
+```
+
+### 2. Run the CSV selection demo
+
+Run:
+
+```text
+bash wayang-jdbc/demo/run-demo-client.sh
+```
+
+The script compiles and runs `CsvSelectionOperationsDemo.java`. It discovers
available CSV files from `wayang-jdbc/demo/data`, maps each CSV file to a
SQL-style table name under the `fs` schema, and lets the user select a CSV file
by number or name.
+
+For example, the demo can show files such as:
+
+```text
+ecommerce_sales_analytics.csv -> fs.ecommerce_sales_analytics
+heart_disease_risk_2026.csv -> fs.heart_disease_risk_2026
+people.csv -> fs.people
+student_performance_dataset.csv -> fs.student_performance_dataset
+```
+
+Selecting `heart_disease_risk` loads `heart_disease_risk_2026.csv` and
performs simple operations such as:
+
+- total row count
+- column listing
+- first 5 rows preview
+- numeric summaries such as min, max, and average
+- heart-disease-specific grouping and averages
+
+### 3. What the demo shows
+
+This demo helps demonstrate the idea that Wayang is not a database and does
not store the data itself. The CSV files remain in the data folder, while the
demo shows how they can be treated as logical SQL-style tables such as
`fs.heart_disease_risk_2026`.
+
+Important note: this specific demo currently reads the CSV folder directly for
learning purposes. It does not yet query through the JDBC driver and server. A
full JDBC client would instead ask the Wayang JDBC server for metadata and send
SQL queries through the JDBC driver.
+
+### 4. Important demo files
+
+```text
+wayang-jdbc/demo/
+├── run-demo-client.sh
+├── CsvSelectionOperationsDemo.java
+└── data/
+ ├── ecommerce_sales_analytics.csv
+ ├── heart_disease_risk_2026.csv
+ ├── people.csv
+ └── student_performance_dataset.csv
+```
+
+- `run-demo-client.sh` compiles and runs the CSV selection demo.
+- `CsvSelectionOperationsDemo.java` contains the demo logic.
+- `data/` contains the CSV datasets that are exposed as logical `fs.<table>`
names.
+
+### 5. Common problems
+
+| Problem | Check
|
+| -------------------------------------- |
------------------------------------------ |
+| `Unsupported class file major version` | Use Java 17
|
+| `javac: command not found` | Install a JDK, not only a JRE
|
+| No CSV files are listed | Check `wayang-jdbc/demo/data`
|
+| File selection fails | Select by the shown number or table
prefix |
+
+This demo will evolve alongside the JDBC integration. The next step is
connecting the same style of discovery and query flow through the JDBC driver
and server.
+
+## Challenges & Lessons Learned
+
+One of the main challenges was that implementing JDBC is not only about
exposing methods from the `java.sql` interfaces. JDBC objects have
relationships and lifecycle rules:
+
+```text
+Connection → Statement → ResultSet → Server Cursor
+```
+
+Keeping these resources consistent across both the client and server required
careful lifecycle handling. Closing a result set, replacing a statement result,
closing a connection, or losing a client session all need to release the
correct server-side resources.
+
+Another challenge was designing the client-server protocol. JDBC operations
had to be represented as request and response messages, with support for
framing, errors, metadata, result data, and protocol versioning. A clear
communication contract became essential because the JDBC client API and the
Wayang execution environment run on different sides of the system.
+
+Result handling also required more than simply returning rows. The
implementation needed to coordinate the full path:
+
+```text
+Query execution → result materialization → cursor → pages → ResultSet
+```
+
+This required thinking about JDBC behavior on the client side and state
management on the server side at the same time.
+
+Integrating JDBC with Wayang was another important part of the work. The goal
was not to duplicate Wayang's SQL processing, optimizer, or execution
responsibilities. The JDBC layer had to adapt to Wayang's existing SQL
capabilities and provide a standard interface around them.
+
+Working on this as part of an Apache project also meant learning how to work
inside an existing open-source codebase. I had to understand the project
structure, discuss design choices, respond to feedback, write documentation,
and think about how future contributors would understand and maintain the
implementation.
+
+The main lessons I took from this project are:
+
+- Designing an API means understanding its lifecycle and behavioral contracts,
not just implementing interfaces.
+- Client-server systems require careful handling of state, errors, and
resource ownership.
+- Integrating with an existing open-source project requires adapting to its
architecture rather than building in isolation.
+- Documentation and a reproducible demo are part of making an implementation
genuinely useful.
+
+## Current State & Remaining Work
+
+The JDBC implementation now provides the core infrastructure required for
applications to connect to Apache Wayang through JDBC, submit SQL queries,
receive results, and access metadata.
+
+### Current state
+
+Completed:
+
+- JDBC driver and connection handling
+- Statement and ResultSet support
+- JDBC metadata
+- Driver–server protocol
+- JDBC server
+- SQL execution through Wayang
+- Result paging and cursor management
+- Error and resource handling
+- Demo and documentation
+
+### What's left
+
+**Future improvements**
+
+- Additional JDBC features
+- Streaming large result sets
+- Query cancellation
+- Authentication and TLS
+- Broader JDBC-tool compatibility testing
+- Performance improvements
+- Packaging and distribution improvements
+
+## Project Resources
+
+<div style={{display: 'grid', gap: '1rem', gridTemplateColumns:
'repeat(auto-fit, minmax(240px, 1fr))'}}>
+ <div style={{border: '1px solid #e5e7eb', borderRadius: '12px', padding:
'1rem'}}>
+ <h3>Source Code</h3>
+ <p>The complete JDBC implementation and related project changes.</p>
+ <p style={{color: '#f29007', fontWeight: 600}}>Coming soon →</p>
+ </div>
+ <div style={{border: '1px solid #e5e7eb', borderRadius: '12px', padding:
'1rem'}}>
+ <h3>Pull Request</h3>
+ <p>The upstream contribution containing the JDBC implementation.</p>
+ <p style={{color: '#f29007', fontWeight: 600}}>Coming soon →</p>
+ </div>
+</div>
+
+Before the final GSoC submission, these placeholders should be replaced with
the stable source code and pull request URLs.
+
+## Conclusion & Future Work
+
+The project introduced a JDBC interface for Apache Wayang, allowing Java
applications to interact with Wayang through a familiar standard API. The
implementation connects the JDBC client layer with Wayang's SQL capabilities
through a dedicated protocol and server, while handling query execution,
results, metadata, and resource lifecycle.
+
+This provides a foundation for making Apache Wayang easier to integrate with
Java applications and future JDBC-compatible tooling.
+
+Future work can continue in a few areas:
Review Comment:
This part felt repetitive as there is a "future improvements" part above
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
