The first problem was an index lookup. Unicode-bound parameters changed the access path for existing CHAR/VARCHAR columns, so I changed ordinary string binding with sendStringParametersAsUnicode=false. That investigation and its execution-plan comparisons are in the preceding article.

The next problem appeared after I kept selected attributes nationalized to preserve Unicode writes. Those writes worked for the databases that needed them, but reading the same mapped attributes from some other hospitals failed:

Could not extract column x from JDBC ResultSet
The conversion from varchar to NCHAR is unsupported.

Removing @Nationalized would undo the Unicode requirement. Changing every hospital’s schema would affect existing programs outside this application. I needed to understand why the read was rejected before choosing where to intervene.

This led through Hibernate’s JDBC type selection and result extractor into the SQL Server driver’s conversion rules. The final implementation changed those rules at application startup using reflection and Unsafe. It solved a compatibility problem at a private library boundary and introduced maintenance risks that are part of this account.

One application mapping, different physical columns

Most of the relevant legacy columns were ordinary character columns, but some hospitals had requested NVARCHAR columns to store a wider set of characters. The application reused an entity mapping across those databases. The same attribute could therefore meet a different physical column type depending on the connection.

The simplified mapping below keeps the nationalized annotation while using a neutral column and property name. A separate null-to-empty converter is omitted; it does not explain the driver’s rejection.

@Column(name = "DISPLAY_NAME", length = 50)
@Nationalized
var displayName: String

sendStringParametersAsUnicode=false governs ordinary character binding. It does not override setNString, which sends Unicode regardless of that property. Hibernate can use the national setter for this mapping, so the connection setting and @Nationalized can coexist. The URL property is sendStringParametersAsUnicode; setSendStringParametersAsUnicode is the Java setter name. Microsoft’s property reference documents that boundary.

The complication is that a JDBC type mapping provides both a binder and an extractor. The annotation affects how the attribute is read as well as how it is sent.

Physical columnShared attribute mappingRelevant observation
NVARCHARNationalizedThe intended Unicode write path was available.
VARCHARThe same nationalized mappingThe driver rejected the national getter for a non-null value.

The read error did not establish corrupted data. It established a disagreement between the actual result-column type and the type requested by the application’s getter.

Establish which code is making that request

The application’s retained build pins com.microsoft.sqlserver:mssql-jdbc:10.2.0.jre11. The JDBC links below resolve to that release’s source commit. For Hibernate, the linked reference source is ORM 6.6.11, which makes the call path reproducible to inspect; it is not evidence of the exact Hibernate binary deployed at the time of the incident.

The Java excerpts preserve the relevant library operations. Where a method is shortened, the omitted behavior is identified. In particular, the national-method fallback and the driver’s null/encryption conditions should not disappear from the explanation.

1. The dialect makes national JDBC types available

I first followed the mapping into the dialect’s type contributions. In the reference source, SQLServerDialect.contributeTypes calls super.contributeTypes(...). The national-type registration below belongs to the common Dialect.contributeTypes implementation. The rest of the method registers unrelated types and is omitted.

public void contributeTypes(TypeContributions typeContributions,
                            ServiceRegistry serviceRegistry) {
    registerColumnTypes(typeContributions, serviceRegistry);
    final NationalizationSupport nationalizationSupport = getNationalizationSupport();
    final JdbcTypeRegistry jdbcTypeRegistry =
        typeContributions.getTypeConfiguration().getJdbcTypeRegistry();
    if (nationalizationSupport == NationalizationSupport.EXPLICIT) {
        jdbcTypeRegistry.addDescriptor(NCharJdbcType.INSTANCE);
        jdbcTypeRegistry.addDescriptor(NVarcharJdbcType.INSTANCE);
        jdbcTypeRegistry.addDescriptor(LongNVarcharJdbcType.INSTANCE);
        jdbcTypeRegistry.addDescriptor(NClobJdbcType.DEFAULT);
    }
    // Unrelated type registrations omitted.
}

This registration is part of Hibernate’s type configuration. It is not a per-row inspection of a hospital’s physical column. The nationalized attribute uses the corresponding type descriptor, but that does not guarantee every database behind the mapping has an NVARCHAR column.

2. The generic extractor delegates the actual read

The next stop was BasicExtractor.extract. With trace logging removed, its control flow is:

@Override
public J extract(ResultSet rs, int paramIndex, WrapperOptions options)
        throws SQLException {
    final J value = doExtract(rs, paramIndex, options);
    if (value == null || rs.wasNull()) {
        return null;
    }
    return value;
}

The important call happens before the null check: doExtract. The generic wrapper cannot explain the failure on its own. I had to follow the extractor supplied by the attribute’s JDBC type.

3. NVarcharJdbcType selects getNString

NVarcharJdbcType.getExtractor returns an anonymous BasicExtractor. This is its ResultSet overload; the two CallableStatement overloads are omitted:

@Override
public <X> ValueExtractor<X> getExtractor(final JavaType<X> javaType) {
    return new BasicExtractor<>(javaType, this) {
        @Override
        protected X doExtract(ResultSet rs, int paramIndex, WrapperOptions options)
                throws SQLException {
            if (options.getDialect().supportsNationalizedMethods()) {
                return javaType.wrap(rs.getNString(paramIndex), options);
            }
            else {
                return javaType.wrap(rs.getString(paramIndex), options);
            }
        }
    };
}

For the SQL Server path under investigation, this reached getNString. The fallback in the reference implementation matters: the general statement is not that every dialect always calls the national getter. It depends on the dialect’s national-method support.

The same descriptor’s binder selects setNString or setString using that support check. This connects the successful nationalized write to the nationalized read that failed on another schema.

4. The driver requests NCHAR internally

The pinned driver’s SQLServerResultSet.getNString is small enough to show in full:

@Override
public String getNString(int columnIndex) throws SQLException {
    loggerExternal.entering(getClassNameLogging(), "getNString", columnIndex);
    checkClosed();
    String value = (String) getValue(columnIndex, JDBCType.NCHAR);
    loggerExternal.exiting(getClassNameLogging(), "getNString", value);
    return value;
}

This explained the NCHAR in the error even though the Hibernate descriptor was named NVarcharJdbcType. The driver passes JDBCType.NCHAR into its value-reading machinery. That internal request does not mean the table was altered to a fixed-width column or that Hibernate issued a schema migration.

5. The value reader checks the allowed conversion

I then followed getValue into dtv.java. The method obtains the physical server type from typeInfo; encrypted columns have additional base-type handling. After preparation, the relevant branch is:

if (null != streamGetterArgs) {
    if (!streamGetterArgs.streamType.convertsFrom(typeInfo))
        DataTypes.throwConversionError(
            typeInfo.getSSType().toString(), streamGetterArgs.streamType.toString());
} else {
    if (!baseSSType.convertsTo(jdbcType) && !isNull) {
        if (encrypted) {
            if (!Util.isBinaryType(jdbcType.getIntValue())) {
                DataTypes.throwConversionError(baseSSType.toString(), jdbcType.toString());
            }
        } else {
            DataTypes.throwConversionError(baseSSType.toString(), jdbcType.toString());
        }
    }

    streamGetterArgs = InputStreamGetterArgs.getDefaultArgs();
}

This excerpt omits value preparation and subsequent decoding, but retains the stream, null and encryption conditions around the rejection. For the non-null, unencrypted getNString case, the decisive condition was !baseSSType.convertsTo(jdbcType).

At that point the two inputs were clear: the column supplied a server-side VARCHAR type, while the getter requested JDBCType.NCHAR. The remaining question was how convertsTo decided whether that pair was allowed.

Find the missing entry in the conversion map

In DataTypes.java, SSType.convertsTo delegates to GetterConversion.converts:

boolean convertsTo(JDBCType jdbcType) {
    return GetterConversion.converts(this, jdbcType);
}

// Inside GetterConversion:
static final boolean converts(SSType fromSSType, JDBCType toJDBCType) {
    return conversionMap.get(fromSSType.category).contains(toJDBCType.category);
}

The check operates on categories rather than individual SQL type names. The source column falls into SSType.Category.CHARACTER; the requested NCHAR falls into JDBCType.Category.NCHARACTER.

The relevant getter declaration has no NCHARACTER destination:

CHARACTER(SSType.Category.CHARACTER, EnumSet.of(
    JDBCType.Category.NUMERIC, JDBCType.Category.DATE,
    JDBCType.Category.TIME, JDBCType.Category.TIMESTAMP,
    JDBCType.Category.CHARACTER, JDBCType.Category.LONG_CHARACTER,
    JDBCType.Category.BINARY, JDBCType.Category.GUID)),

Historical debugger capture of the CHARACTER conversion-map entry: eight allowed destinations, with NCHARACTER absent

The debugger capture made the failure concrete. I could see the CHARACTER entry and its eight destinations. The requested national-character category was missing. The exception followed from a specific membership test, rather than a vague inability of Java strings to hold Unicode.

The map is also worth following. The driver initializes it from the enum declarations:

private final EnumSet<JDBCType.Category> to;

private static final EnumMap<SSType.Category, EnumSet<JDBCType.Category>> conversionMap =
    new EnumMap<>(SSType.Category.class);

static {
    for (SSType.Category category : SSType.Category.VALUES)
        conversionMap.put(category, EnumSet.noneOf(JDBCType.Category.class));

    for (GetterConversion conversion : VALUES)
        conversionMap.get(conversion.from).addAll(conversion.to);
}

The map’s sets are populated with addAll; they are not aliases for the enum’s to sets. Changing an enum’s set after class initialization therefore does not update the map used by converts. This is why the workaround had to reach the effective map, not just the declaration I first found.

The driver also has a separate UpdaterConversion table, whose ordinary-character source entry includes national-character server targets. Seeing that asymmetry was useful: conversion permissions are directional. That table is an updater path, however, so it does not by itself prove how every prepared-statement insert works. The setNString binder and the observed write behavior are the relevant evidence for this application’s writes.

Reconsider the alternatives with the failure located

I considered five ways forward. Each moved the complexity to a different place:

OptionRequirement it could satisfyCost or unresolved problem
Remove @Nationalized and use ordinary binding everywhereAvoid the nationalized mapping that selected the failing getter.It would abandon the explicit Unicode write path needed by some hospitals.
Inspect physical column types during queries and change JDBC descriptorsAdapt extraction to each schema.It requires schema-aware behavior in the query path. Descriptor mutation also needs careful scoping when mappings are shared.
Maintain a table describing which columns are nationalized, then select descriptorsMake those exceptions explicit.It adds metadata that must stay consistent with the real hospital schemas, while retaining the descriptor-selection problem.
Remove the annotation and use native SQL for creates, updates and deletesControl write-side SQL separately.A cast cannot recover characters already lost during non-Unicode parameter transmission. The read mapping also still needs its own validation.
Fork the JDBC driverMake the missing getter rule an ordinary source change.It creates a separately built and maintained driver, including responsibility for later upstream fixes.

These were considered alternatives, not five completed prototypes with comparative benchmarks. The schema-aware and fork approaches remained possible engineering directions. My implementation instead changed the loaded driver’s getter rules during startup, keeping the existing hospital schemas and nationalized mappings.

That choice concentrated the compatibility behavior at the point rejecting the read. It also coupled the application to private driver internals. Avoiding a fork did not remove that dependency; it changed how the patch was installed.

Install the compatibility rule during Spring initialization

A shared Spring configuration bean ran an @PostConstruct hook. The affected application’s component scan included that bean. The hook added JDBCType.Category.NCHARACTER to the getter destinations and conversion-map entries for CHARACTER and LONG_CHARACTER.

The debugger capture concerns CHARACTER. The retained implementation also handles the driver’s long-character category; that broader implementation scope is not proof that every long-text case was tested.

The following implementation is adapted from the retained source with neutral class/helper names and a standard logger. Its reflection targets, mutations and log-and-continue failure behavior are preserved. It is an account of the workaround, not a portable patch to install without reviewing the driver and runtime.

import jakarta.annotation.PostConstruct
import org.slf4j.LoggerFactory
import org.springframework.context.annotation.Configuration
import sun.misc.Unsafe
import java.lang.reflect.Field
import java.util.Collections
import java.util.EnumSet

@Configuration
@Suppress("UNCHECKED_CAST")
class NationalCharacterReadCompatibility {
    private val logger = LoggerFactory.getLogger(javaClass)

    @PostConstruct
    fun permitNationalReads() {
        try {
            val getterConversionClass = Class.forName("com.microsoft.sqlserver.jdbc.SSType\$GetterConversion")

            val characterEnum = getterConversionClass.staticValue("CHARACTER")
            val longCharacterEnum = getterConversionClass.staticValue("LONG_CHARACTER")

            val nCharacterCategory = Class.forName("com.microsoft.sqlserver.jdbc.JDBCType\$Category")
                .enumValue("NCHARACTER")

            addGetterTarget(characterEnum, "to", nCharacterCategory)
            addGetterTarget(longCharacterEnum, "to", nCharacterCategory)

            val conversionMapField = getterConversionClass.accessibleField("conversionMap")
            val conversionMap = conversionMapField.get(null) as MutableMap<Any, EnumSet<*>>

            val sstypeCategoryClass = Class.forName("com.microsoft.sqlserver.jdbc.SSType\$Category")
            val characterCategory = sstypeCategoryClass.enumValue("CHARACTER")
            val longCharacterCategory = sstypeCategoryClass.enumValue("LONG_CHARACTER")

            addConversionTarget(conversionMap, characterCategory, nCharacterCategory)
            addConversionTarget(conversionMap, longCharacterCategory, nCharacterCategory)
        } catch (e: Exception) {
            logger.error("Cannot install character getter compatibility", e)
        }
    }

    private fun addGetterTarget(enumObj: Any, fieldName: String, newValue: Any) {
        val field = enumObj.javaClass.accessibleField(fieldName)
        val unsafe = unsafeInstance()
        val fieldOffset = unsafe.objectFieldOffset(field)

        @Suppress("UNCHECKED_CAST")
        val mutableSet = field.get(enumObj) as MutableSet<Any?>
        mutableSet.add(newValue)

        unsafe.putObject(enumObj, fieldOffset, Collections.unmodifiableSet(mutableSet))
    }

    private fun addConversionTarget(
        conversionMap: MutableMap<Any, EnumSet<*>>,
        category: Any,
        newValue: Any
    ) {
        (conversionMap[category] as? MutableSet<Any?>)?.add(newValue)
    }

    private fun Class<*>.accessibleField(fieldName: String): Field =
        getDeclaredField(fieldName).apply { isAccessible = true }

    private fun Class<*>.staticValue(fieldName: String): Any =
        accessibleField(fieldName).get(null)

    private fun Class<*>.enumValue(constantName: String): Enum<*> =
        enumConstants.first { (it as Enum<*>).name == constantName } as Enum<*>

    private fun unsafeInstance(): Unsafe {
        val unsafeField = Unsafe::class.java.getDeclaredField("theUnsafe")
        unsafeField.isAccessible = true
        return unsafeField.get(null) as Unsafe
    }
}

There are three distinct operations here. Reflection obtains the private driver classes, enum constants and fields. The helper mutates the existing to set and uses Unsafe.putObject to replace its private final reference with an unmodifiable wrapper. Finally, the hook adds the national destination to the already-built map entries that the conversion check actually consults.

The change does not rewrite a table or convert previously damaged data. It lets this driver accept a national getter for those server-side character categories. Parameter transmission remains governed by the ordinary binding setting and the selected national setters.

What the workaround leaves me responsible for

The mechanism explains how the compatibility rule was installed. It also exposes concrete weaknesses:

  • Private implementation dependency. Class names, field names and category layout belong to the pinned driver. An upgrade must recheck the assumptions and behavior.
  • Shared scope. The static map belongs to the loaded driver class. The change affects other reads using that class, not just one entity or one hospital connection.
  • Type-unsafe field replacement. The declared to field is an EnumSet, but Collections.unmodifiableSet returns a wrapper that is not an EnumSet. Unsafe bypasses the assignment checks; making a wrapper unmodifiable does not make that replacement type-safe or freeze the separate conversion map.
  • Incomplete failure handling. Exceptions are logged and swallowed. The code can continue after a failed or partially applied mutation, and a missing map entry can be skipped by the safe cast. Successful application startup is not evidence that both rules were installed.
  • Initialization order. @PostConstruct identifies when this configuration bean initializes. It does not establish that every datasource consumer or other startup bean waits for it.

For a maintained version, I would require explicit initialization dependencies and a postcondition check, and fail startup rather than silently continue if the required compatibility rule was absent. I would also compare a supported custom Hibernate mapping or a verified driver change that removes private-field mutation. Those are follow-up improvements, not behavior present in the shown implementation.

Nor does an allowed conversion prove character fidelity. The real collation and stored representation still determine what a column can hold. A correct validation matrix needs reads and writes against supported CHAR/VARCHAR and NCHAR/NVARCHAR definitions, nulls, empty values, and representative Korean and other Unicode characters. Supplementary characters and long-text categories need explicit coverage where the product supports them.

Keep the two causes and their evidence separate

The outbound issue was a mismatch between lookup-column types and the parameters sent to SQL Server. The inbound issue was a mismatch between physical result-column types and Hibernate’s national getter. The first required looking at query plans and binding; the second required following a library call to its rejection condition.

The historical production result for the complete binding and compatibility fix was 20% lower database CPU usage and 80% shorter execution time for queries that had missed their intended indexes. Those figures do not isolate the reflection hook’s effect. The library code and debugger capture establish the conversion mechanism; they do not replace a benchmark or a round-trip test across every hospital schema.

The investigation changed my next step each time: a plan difference led to parameter types; explicit Unicode mappings exposed a read failure; the getter led to a concrete conversion map; and that map made the compatibility options precise enough to compare. The remaining responsibility is to keep the runtime patch’s scope and failure behavior as visible as the problem it addressed.