apache/seatunnel · warning

TIMESTAMP_TZ is written to Xugu as a plain TIMESTAMP: the…

Error message

TIMESTAMP_TZ is written to Xugu as a plain TIMESTAMP: the timezone offset is dropped and only the wall-clock value is stored. This is a known Xugu JDBC driver limitation (bug [E19138]).

What it means

XuguJdbcRowConverter.setValueToStatementByDataType writes TIMESTAMP_TZ (OffsetDateTime) values. The Xugu JDBC driver crashes on batch writes of timezone-formatted values for TIMESTAMP WITH TIME ZONE columns (bug E19138), so the converter intentionally drops the offset and stores only the wall-clock Timestamp. This is lossy for the timezone component; the warning fires once per process (guarded by TIMESTAMP_TZ_WARNED).

Solutions

1. Normalize all timestamps to a single timezone (e.g. UTC) upstream so dropping the offset is harmless
2. Change the Xugu target column to plain TIMESTAMP and document that only local time is stored
3. Upgrade the Xugu JDBC driver if a fix for E19138 becomes available and remove the workaround
4. Convert offsets manually in a transform before the sink if offsets must be preserved

Example fix

// before: OffsetDateTime with offset 2024-01-01T10:00+08:00 -> stored as 10:00 without offset
// after: normalize upstream
OffsetDateTime normalized = odt.withOffsetSameInstant(ZoneOffset.UTC);
// stored as UTC wall-clock consistently

// Ensure offsets are uniform before writing TIMESTAMP_TZ to Xugu:
for (OffsetDateTime v : values) {
    if (!v.getOffset().equals(ZoneOffset.UTC)) {
        log.warn("Non-UTC offset will be dropped for Xugu TIMESTAMP_TZ write: " + v.getOffset());
    }
}

When it happens

Trigger: Writing any OffsetDateTime value with a non-UTC (or any) offset to a Xugu TIMESTAMP WITH TIME ZONE column via SeaTunnel JDBC sink, especially in batch mode.

Common situations: Syncing data from PostgreSQL/Oracle timestamptz sources into Xugu; multi-timezone applications where the offset matters for downstream consumers.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• The timestamp_tz column
• The timestamp_tz column
• The timestamp_tz column
• COMMON-17
• COMMON-19

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/57744b15540e1146. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/internal/dialect/xugu/XuguJdbcRowConverter.java:59

    public String converterName() {
        return DatabaseIdentifier.XUGU;
    }

    @Override
    protected void setValueToStatementByDataType(
            Object value,
            PreparedStatement statement,
            SeaTunnelDataType<?> seaTunnelDataType,
            int statementIndex,
            @Nullable String sourceType)
            throws SQLException {
        if (seaTunnelDataType.getSqlType().equals(SqlType.TIMESTAMP_TZ)) {
            // LOSSY PATH: Xugu JDBC driver crashes on batch writes of OffsetDateTime /
            // timezone-formatted strings for TIMESTAMP WITH TIME ZONE columns (bug [E19138]).
            // The timezone offset is intentionally dropped; only the wall-clock value is stored.
            // This is a documented limitation — not silent data loss.
            if (TIMESTAMP_TZ_WARNED.compareAndSet(false, true)) {
                log.warn(
                        "TIMESTAMP_TZ is written to Xugu as a plain TIMESTAMP: the timezone"
                                + " offset is dropped and only the wall-clock value is stored."
                                + " This is a known Xugu JDBC driver limitation (bug [E19138]).");
            }
            OffsetDateTime odt = (OffsetDateTime) value;
            statement.setTimestamp(statementIndex, Timestamp.valueOf(odt.toLocalDateTime()));
        } else {
            super.setValueToStatementByDataType(
                    value, statement, seaTunnelDataType, statementIndex, sourceType);
        }
    }
}

View on GitHub (pinned to cf67b549a7)