zkaoudi commented on code in PR #128:
URL: https://github.com/apache/wayang-website/pull/128#discussion_r3801799742
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,579 @@
+---
+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 worked on JDBC support 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 support 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 API, separating the Java-facing JDBC API layer
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.
+
+Before going further, it is useful to clarify the terminology used in this
post. The **Wayang JDBC driver** refers to the complete implementation. It
consists of a **client-side JDBC layer** that implements the Java-facing
`java.sql` API, a **JDBC protocol** used for communication, and a **JDBC
server** that receives requests and connects them to Apache Wayang.
+
+Apache Wayang already provides a SQL API, 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 Wayang JDBC driver 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 client-side JDBC layer from
the Wayang execution environment through a set of components that work together.
+
+## Architecture
+
+The Wayang JDBC driver 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 driver
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 client-side JDBC layer provides the JDBC-facing objects used by the
application, including the Java `Driver`, `Connection`, `Statement`,
`ResultSet`, 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 client-side
JDBC layer and the server. It covers requests, responses, errors, metadata,
result data, and protocol versioning. This keeps the client-side layer 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
client-side JDBC layer.
+
+Apache Wayang remains responsible for the actual SQL processing. The Wayang
JDBC driver 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 client-side JDBC layer and the
JDBC server:
+
+```text
+Client-side JDBC layer
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the client-side JDBC layer speaks the Java `java.sql` API, 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 Wayang JDBC driver in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the client-side JDBC layer,
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 client-side JDBC layer 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 client-side JDBC layer 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 client-side JDBC layer. The
Java application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the
client-side JDBC layer sends a `FETCH` request. The server reads the next page
from the `CursorStore` and returns it to the client-side JDBC layer. 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 Wayang JDBC driver is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the client-side JDBC layer contain the Wayang runtime, or
should query execution happen separately?
+
+**Decision:** The Wayang JDBC driver separates the client-side JDBC layer from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
+ ↓
+JDBC Server
+ ↓
+Apache Wayang
+```
+
+**Why:** This keeps the client-side JDBC layer 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 client-side JDBC layer and JDBC server need to exchange
requests, responses, errors, metadata, and result data without relying on each
other's internal Java objects.
+
+**Decision:** The client-side JDBC layer and JDBC server communicate through a
defined TCP protocol using length-prefixed JSON messages.
+
+```text
+JDBC Driver
Review Comment:
JDBC Client
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,579 @@
+---
+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 worked on JDBC support 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 support 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 API, separating the Java-facing JDBC API layer
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.
+
+Before going further, it is useful to clarify the terminology used in this
post. The **Wayang JDBC driver** refers to the complete implementation. It
consists of a **client-side JDBC layer** that implements the Java-facing
`java.sql` API, a **JDBC protocol** used for communication, and a **JDBC
server** that receives requests and connects them to Apache Wayang.
+
+Apache Wayang already provides a SQL API, 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 Wayang JDBC driver 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 client-side JDBC layer from
the Wayang execution environment through a set of components that work together.
+
+## Architecture
+
+The Wayang JDBC driver 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 driver
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 client-side JDBC layer provides the JDBC-facing objects used by the
application, including the Java `Driver`, `Connection`, `Statement`,
`ResultSet`, 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 client-side
JDBC layer and the server. It covers requests, responses, errors, metadata,
result data, and protocol versioning. This keeps the client-side layer 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
client-side JDBC layer.
+
+Apache Wayang remains responsible for the actual SQL processing. The Wayang
JDBC driver 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 client-side JDBC layer and the
JDBC server:
+
+```text
+Client-side JDBC layer
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the client-side JDBC layer speaks the Java `java.sql` API, 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 Wayang JDBC driver in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the client-side JDBC layer,
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 client-side JDBC layer 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 client-side JDBC layer 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 client-side JDBC layer. The
Java application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the
client-side JDBC layer sends a `FETCH` request. The server reads the next page
from the `CursorStore` and returns it to the client-side JDBC layer. 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 Wayang JDBC driver is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the client-side JDBC layer contain the Wayang runtime, or
should query execution happen separately?
+
+**Decision:** The Wayang JDBC driver separates the client-side JDBC layer from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
Review Comment:
JDBC Client
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,579 @@
+---
+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 worked on JDBC support 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 support 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 API, separating the Java-facing JDBC API layer
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.
+
+Before going further, it is useful to clarify the terminology used in this
post. The **Wayang JDBC driver** refers to the complete implementation. It
consists of a **client-side JDBC layer** that implements the Java-facing
`java.sql` API, a **JDBC protocol** used for communication, and a **JDBC
server** that receives requests and connects them to Apache Wayang.
+
+Apache Wayang already provides a SQL API, 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 Wayang JDBC driver 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 client-side JDBC layer from
the Wayang execution environment through a set of components that work together.
+
+## Architecture
+
+The Wayang JDBC driver 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 driver
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 client-side JDBC layer provides the JDBC-facing objects used by the
application, including the Java `Driver`, `Connection`, `Statement`,
`ResultSet`, 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 client-side
JDBC layer and the server. It covers requests, responses, errors, metadata,
result data, and protocol versioning. This keeps the client-side layer 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
client-side JDBC layer.
+
+Apache Wayang remains responsible for the actual SQL processing. The Wayang
JDBC driver 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 client-side JDBC layer and the
JDBC server:
+
+```text
+Client-side JDBC layer
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the client-side JDBC layer speaks the Java `java.sql` API, 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 Wayang JDBC driver in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the client-side JDBC layer,
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 client-side JDBC layer 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 client-side JDBC layer 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 client-side JDBC layer. The
Java application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the
client-side JDBC layer sends a `FETCH` request. The server reads the next page
from the `CursorStore` and returns it to the client-side JDBC layer. 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 Wayang JDBC driver is structured this way, not
just what the code does.
+
+### 1. Client–server separation
+
+**Problem:** Should the client-side JDBC layer contain the Wayang runtime, or
should query execution happen separately?
+
+**Decision:** The Wayang JDBC driver separates the client-side JDBC layer from
the server-side Wayang execution environment.
+
+```text
+Java Application
+ ↓
+JDBC Driver
+ ↓
+JDBC Server
+ ↓
+Apache Wayang
+```
+
+**Why:** This keeps the client-side JDBC layer 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 client-side JDBC layer and JDBC server need to exchange
requests, responses, errors, metadata, and result data without relying on each
other's internal Java objects.
+
+**Decision:** The client-side JDBC layer and JDBC 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 client-side JDBC layer 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 client-side JDBC
layer presents the standard JDBC API, 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.
+
+### Client-side JDBC layer
+
+The client-side JDBC module implements the Java-facing layer that 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 client-side JDBC layer
and the JDBC 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
client-side JDBC layer 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/
Review Comment:
This needs to be replaced with wayang-jdbc-client
##########
blog/2026-08-08-gsoc-2026-wayang-jdbc-driver.md:
##########
@@ -0,0 +1,579 @@
+---
+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 worked on JDBC support 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 support 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 API, separating the Java-facing JDBC API layer
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.
+
+Before going further, it is useful to clarify the terminology used in this
post. The **Wayang JDBC driver** refers to the complete implementation. It
consists of a **client-side JDBC layer** that implements the Java-facing
`java.sql` API, a **JDBC protocol** used for communication, and a **JDBC
server** that receives requests and connects them to Apache Wayang.
+
+Apache Wayang already provides a SQL API, 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 Wayang JDBC driver 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 client-side JDBC layer from
the Wayang execution environment through a set of components that work together.
+
+## Architecture
+
+The Wayang JDBC driver 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 driver
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 client-side JDBC layer provides the JDBC-facing objects used by the
application, including the Java `Driver`, `Connection`, `Statement`,
`ResultSet`, 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 client-side
JDBC layer and the server. It covers requests, responses, errors, metadata,
result data, and protocol versioning. This keeps the client-side layer 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
client-side JDBC layer.
+
+Apache Wayang remains responsible for the actual SQL processing. The Wayang
JDBC driver 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 client-side JDBC layer and the
JDBC server:
+
+```text
+Client-side JDBC layer
+ │
+ │ TCP + length-prefixed JSON protocol
+ ▼
+JDBC Server
+```
+
+In short, the client-side JDBC layer speaks the Java `java.sql` API, 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 Wayang JDBC driver in a few clear phases.
+
+<div style={{textAlign: 'center'}}>
+ <img width="90%" alt="SQL query journey through the client-side JDBC layer,
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 client-side JDBC layer 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 client-side JDBC layer 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 client-side JDBC layer. The
Java application consumes rows through the standard `ResultSet.next()` method.
+
+When the current page is exhausted and more rows are available, the
client-side JDBC layer sends a `FETCH` request. The server reads the next page
from the `CursorStore` and returns it to the client-side JDBC layer. 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.
Review Comment:
"The driver, protocol, and server" --> "The client-side layer, protocol, and
server"
--
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]
