Fix init script decoding with configurable charsets

[dlwhdgus0810]

Windows-1252 initialization scripts are decoded as UTF-8, corrupting accented characters before SQL reaches the database. Add an explicit Charset overload to ScriptUtils.runInitScript and JdbcDatabaseContainer.withInitScriptCharset so callers can select the script encoding. Existing calls continue to use UTF-8.

The container setting applies to all scripts configured through withInitScript or withInitScripts. JDBC URL TC_INITSCRIPT remains UTF-8, as documented. This changes file decoding, not the database character set.

Regression coverage uses a Windows-1252 fixture containing é and UTF-8 controls. The Windows-1252 case failed on the original implementation. All 62 database-commons and JDBC tests pass, along with both module check tasks (Checkstyle, Spotless, Javadoc, and API compatibility). Docker-backed Oracle integration was not run.

Fixes #8776.

Summary by CodeRabbit

• New Features
  • JDBC initialization scripts can be read using a configured character encoding; UTF-8 remains the default.
• Documentation
  • Clarified that configured initialization scripts default to UTF-8 and follow the container’s charset setting, while scripts loaded through TC_INITSCRIPT are always read as UTF-8.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 28573aae-05b7-4c35-82ad-2f3a4b204a1a

📥 Commits

Reviewing files that changed from the base of the PR and between cf0731f and e5071ad.

📒 Files selected for processing: 3

• modules/database-commons/src/main/java/org/testcontainers/ext/ScriptUtils.java
• modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java
• modules/postgresql/src/test/java/org/testcontainers/postgresql/PostgreSQLContainerTest.java

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.

📝 Walkthrough

JDBC initialization scripts can now use a configured charset. Script loading defaults to UTF-8, and JDBC containers pass the configured charset to the script loader. Tests cover UTF-8 and Windows-1252 scripts.

Changes: Initialization script charset support

Layer / File(s)	Summary
Script loading charset contract modules/database-commons/src/main/java/org/testcontainers/ext/ScriptUtils.java, modules/database-commons/src/test/java/org/testcontainers/ext/ScriptUtilsTest.java, modules/database-commons/src/test/resources/init-*.sql	ScriptUtils adds a charset-aware overload and keeps UTF-8 as the default. Unit tests and SQL fixtures cover UTF-8, Windows-1252, and null charset handling.
JDBC container integration modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java, modules/postgresql/src/test/java/org/testcontainers/postgresql/PostgreSQLContainerTest.java, modules/postgresql/src/test/resources/somepath/init_postgresql_windows-1252.sql, docs/modules/databases/jdbc.md	JdbcDatabaseContainer adds withInitScriptCharset and passes the setting to script loading. A PostgreSQL integration test checks a Windows-1252 script. The JDBC documentation describes charset defaults and the TC_INITSCRIPT behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant JdbcDatabaseContainer
  participant ScriptUtils
  participant DatabaseDelegate
  JdbcDatabaseContainer->>ScriptUtils: Run script with configured charset
  ScriptUtils->>DatabaseDelegate: Execute decoded SQL statements

Loading

Suggested reviewers: kiview

Merge Risk: ⚪ Minimal · up to e5071

Container-configured initialization scripts can use the selected decoding charset without changing the default or JDBC URL script behavior. No merge-blocking risk remains.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: configurable character-set handling for initialization scripts.
Description check		The description explains the bug, the implemented APIs, default behavior, scope, regression coverage, test results, skipped integration testing, and linked issue.
Linked Issues check		The changes satisfy the coding requirements in [#8776]. ScriptUtils.runInitScript accepts a selected Charset, and the existing overload retains UTF-8. JdbcDatabaseContainer.withInitScriptCharset…
Out of Scope Changes check		The changes remain within [#8776]. Production changes configure initialization-script decoding. Tests, encoded fixtures, and documentation verify or explain that behavior. No unrelated production chan…

Full details: Linked Issues check

Explanation

The changes satisfy the coding requirements in [#8776]. ScriptUtils.runInitScript accepts a selected Charset, and the existing overload retains UTF-8. JdbcDatabaseContainer.withInitScriptCharset applies the selected charset to scripts configured with withInitScript and withInitScripts. Tests cover UTF-8, Windows-1252, null validation, and container execution. Documentation records the UTF-8 behavior of TC_INITSCRIPT.

Full details: Out of Scope Changes check

Explanation

The changes remain within [#8776]. Production changes configure initialization-script decoding. Tests, encoded fixtures, and documentation verify or explain that behavior. No unrelated production change is identified.

• Fix all pre-merge checks with AI

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kiview]

Thank you @dlwhdgus0810, made some small adjustments in follow-up commits, and going to merge it once CI is green.