Skip to content

[FLINK-39142] Add Glue Schema Registry Protobuf SQL format factory (stacked on Avro #236) #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fmorillo7694 merged 5 commits into from
Aug 10, 2026
Merged

[FLINK-39142] Add Glue Schema Registry Protobuf SQL format factory (stacked on Avro #236) #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5c6cd3b
[FLINK-39142] Add Glue Schema Registry Protobuf SQL format factory
fmorillo7694 Aug 8, 2026
d3146a0
test(protobuf-glue): Add credential-gated SQL e2e module with Kinesis…
fmorillo7694 Aug 10, 2026
f6cdaa0
test(protobuf-glue): Fix table credential option keys and add missing…
fmorillo7694 Aug 10, 2026
4caff9e
test(protobuf-glue): Use HTTP1_1 for Kinesis client against Localstack
fmorillo7694 Aug 10, 2026
afaa483
test(protobuf-glue): Cover pre-existing schema and missing-schema err…
fmorillo7694 Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 283 additions & 0 deletions docs/content/docs/connectors/table/formats/protobuf-glue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,283 @@
---
title: "Protobuf (Glue Schema Registry)"
weight: 3
type: docs
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

# Protobuf Format (AWS Glue Schema Registry)

{{< label "Format: Serialization Schema" >}}
{{< label "Format: Deserialization Schema" >}}

The Protobuf Glue Schema Registry format (`protobuf-glue`) allows you to read and write Protocol Buffers data with schemas managed by [AWS Glue Schema Registry](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html).

Dependencies
------------

{{< sql_connector_download_table "protobuf-glue" >}}

The Protobuf-Glue format is not part of the binary distribution.
See how to link with it for cluster execution [here]({{< ref "docs/dev/configuration/overview" >}}).

#### SQL Client JAR

For SQL Client usage, download the fat JAR `flink-sql-protobuf-glue-schema-registry` from the table above and place it in the `lib/` directory of your Flink installation. The SQL JAR bundles all required dependencies including the AWS Glue Schema Registry serializer/deserializer libraries.

#### Maven Dependency

To use the format in a DataStream or Table API program, add the following dependency to your project:

```xml
<dependency>
<groupId>org.apache.flink</groupId>
<artifactId>flink-protobuf-glue-schema-registry</artifactId>
<version>6.0.0</version>
</dependency>
```

How to create a table with Protobuf-Glue format
-------------------------------------------------

Here is an example to create a table using the Kinesis connector with the Protobuf-Glue format:

```sql
CREATE TABLE KinesisTable (
`user_id` BIGINT,
`item_id` BIGINT,
`category` STRING,
`behavior` STRING,
`ts` TIMESTAMP(3)
) WITH (
'connector' = 'kinesis',
'stream.arn' = 'arn:aws:kinesis:us-east-1:012345678901:stream/my-stream',
'aws.region' = 'us-east-1',
'source.init.position' = 'LATEST',
'format' = 'protobuf-glue',
'protobuf-glue.aws.region' = 'us-east-1',
'protobuf-glue.registry.name' = 'my-registry',
'protobuf-glue.schema.name' = 'my-protobuf-schema'
);
```


Protobuf Descriptor Auto-Generation
-------------------------------------

When writing data (sink), the Protobuf-Glue format automatically generates a Protobuf descriptor (`.proto` schema definition) from the Flink table schema and registers it with Glue Schema Registry using `DataFormat.PROTOBUF`.

When reading data (source), the format strips the GSR header bytes (18 bytes: 1 header version byte + 1 compression byte + 16 UUID bytes) from incoming records and deserializes the Protobuf payload into Flink `RowData`.

Format Options
--------------

<table class="table table-bordered">
<thead>
<tr>
<th class="text-left" style="width: 25%">Option</th>
<th class="text-center" style="width: 8%">Required</th>
<th class="text-center" style="width: 7%">Forwarded</th>
<th class="text-center" style="width: 10%">Default</th>
<th class="text-center" style="width: 10%">Type</th>
<th class="text-center" style="width: 40%">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><h5>format</h5></td>
<td>required</td>
<td>no</td>
<td style="word-wrap: break-word;">(none)</td>
<td>String</td>
<td>Specify the format identifier. Use <code>'protobuf-glue'</code>.</td>
</tr>
<tr>
<td><h5>protobuf-glue.aws.region</h5></td>
<td>required</td>
<td>yes</td>
<td style="word-wrap: break-word;">(none)</td>
<td>String</td>
<td>AWS region for the Glue Schema Registry.</td>
</tr>
<tr>
<td><h5>protobuf-glue.registry.name</h5></td>
<td>required</td>
<td>yes</td>
<td style="word-wrap: break-word;">(none)</td>
<td>String</td>
<td>Name of the Glue Schema Registry.</td>
</tr>
<tr>
<td><h5>protobuf-glue.schema.name</h5></td>
<td>required</td>
<td>yes</td>
<td style="word-wrap: break-word;">(none)</td>
<td>String</td>
<td>Schema name under which to register/look up the schema in Glue Schema Registry.</td>
</tr>
<tr>
<td><h5>protobuf-glue.aws.endpoint</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">(none)</td>
<td>String</td>
<td>Custom AWS endpoint URL for Glue Schema Registry.</td>
</tr>
<tr>
<td><h5>protobuf-glue.cache.size</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">200</td>
<td>Integer</td>
<td>Maximum number of items in the schema cache.</td>
</tr>
<tr>
<td><h5>protobuf-glue.cache.ttlMs</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">86400000</td>
<td>Long</td>
<td>Cache TTL in milliseconds. Defaults to 1 day (86400000 ms).</td>
</tr>
<tr>
<td><h5>protobuf-glue.schema.autoRegistration</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">false</td>
<td>Boolean</td>
<td>Whether to auto-register schemas with Glue Schema Registry when writing data.</td>
</tr>
<tr>
<td><h5>protobuf-glue.schema.compatibility</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">NONE</td>
<td>String</td>
<td>Schema compatibility mode. Supported values: <code>NONE</code>, <code>DISABLED</code>, <code>BACKWARD</code>, <code>BACKWARD_ALL</code>, <code>FORWARD</code>, <code>FORWARD_ALL</code>, <code>FULL</code>, <code>FULL_ALL</code>.</td>
</tr>
<tr>
<td><h5>protobuf-glue.schema.compression</h5></td>
<td>optional</td>
<td>yes</td>
<td style="word-wrap: break-word;">NONE</td>
<td>String</td>
<td>Compression type for schema data. Supported values: <code>NONE</code>, <code>ZLIB</code>.</td>
</tr>
</tbody>
</table>

Data Type Mapping
-----------------

The Protobuf-Glue format maps between Flink SQL types and Protobuf types as follows:

<table class="table table-bordered">
<thead>
<tr>
<th class="text-left">Flink SQL Type</th>
<th class="text-left">Protobuf Type</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>BOOLEAN</code></td>
<td><code>bool</code></td>
</tr>
<tr>
<td><code>INT</code></td>
<td><code>int32</code></td>
</tr>
<tr>
<td><code>BIGINT</code></td>
<td><code>int64</code></td>
</tr>
<tr>
<td><code>FLOAT</code></td>
<td><code>float</code></td>
</tr>
<tr>
<td><code>DOUBLE</code></td>
<td><code>double</code></td>
</tr>
<tr>
<td><code>STRING</code></td>
<td><code>string</code></td>
</tr>
<tr>
<td><code>BYTES</code></td>
<td><code>bytes</code></td>
</tr>
<tr>
<td><code>ARRAY</code></td>
<td><code>repeated</code></td>
</tr>
<tr>
<td><code>MAP</code></td>
<td><code>map</code></td>
</tr>
<tr>
<td><code>ROW</code></td>
<td><code>message</code> (nested)</td>
</tr>
</tbody>
</table>

Usage with Kinesis and Firehose Connectors
------------------------------------------

### Kinesis Source

```sql
CREATE TABLE KinesisSource (
`user_id` BIGINT,
`event_type` STRING,
`payload` STRING,
`event_time` TIMESTAMP(3)
) WITH (
'connector' = 'kinesis',
'stream.arn' = 'arn:aws:kinesis:us-east-1:012345678901:stream/events',
'aws.region' = 'us-east-1',
'source.init.position' = 'LATEST',
'format' = 'protobuf-glue',
'protobuf-glue.aws.region' = 'us-east-1',
'protobuf-glue.registry.name' = 'my-registry',
'protobuf-glue.schema.name' = 'events-protobuf'
);
```

### Firehose Sink

```sql
CREATE TABLE FirehoseSink (
`user_id` BIGINT,
`event_type` STRING,
`payload` STRING,
`event_time` TIMESTAMP(3)
) WITH (
'connector' = 'firehose',
'delivery-stream' = 'my-delivery-stream',
'aws.region' = 'us-east-1',
'format' = 'protobuf-glue',
'protobuf-glue.aws.region' = 'us-east-1',
'protobuf-glue.registry.name' = 'my-registry',
'protobuf-glue.schema.name' = 'events-protobuf',
'protobuf-glue.schema.autoRegistration' = 'true'
);
```
23 changes: 23 additions & 0 deletions docs/data/protobuf-glue.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
################################################################################
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
################################################################################

version: 6.0.0
flink_compatibility: [ "2.0" ]
variants:
- maven: flink-protobuf-glue-schema-registry
sql_url: https://repo.maven.apache.org/maven2/org/apache/flink/flink-sql-protobuf-glue-schema-registry/$full_version/flink-sql-protobuf-glue-schema-registry-$full_version.jar
Loading
Loading