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

  • Added support for configuring the character encoding used to read database initialization scripts.
  • Initialization scripts use UTF-8 by default, with options to specify another charset such as Windows-1252.
  • The selected charset applies to all initialization scripts configured for the container.

• Documentation

  • Added guidance on configuring script encoding and clarified its scope and defaults.

[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: 980052e2-ae6e-4af8-a19e-2c4a66b4eec2

📥 Commits

Reviewing files that changed from the base of the PR and between 8e54951 and b2a2dd8.

📒 Files selected for processing (9)

• docs/modules/databases/jdbc.md
• 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-utf-8.sql
• modules/database-commons/src/test/resources/init-windows-1252.sql
• modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java
• modules/jdbc/src/test/java/org/testcontainers/containers/JdbcDatabaseContainerTest.java
• modules/jdbc/src/test/resources/init-utf-8.sql
• modules/jdbc/src/test/resources/init-windows-1252.sql

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds configurable charset handling for JDBC initialization scripts. UTF-8 remains the default. JdbcDatabaseContainer passes the configured charset to ScriptUtils, with tests and documentation for 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/..., modules/database-commons/src/test/...	ScriptUtils accepts an optional Charset and uses UTF-8 by default. Tests cover UTF-8, Windows-1252, and null validation.
JDBC container integration modules/jdbc/src/main/java/..., modules/jdbc/src/test/..., docs/modules/databases/jdbc.md	JdbcDatabaseContainer adds withInitScriptCharset(Charset) and passes the configured charset to each initialization script. Tests and documentation describe the 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: Pass configured charset and script path
  ScriptUtils->>ScriptUtils: Read and decode the script
  ScriptUtils->>DatabaseDelegate: Execute decoded SQL statements

Loading

Suggested reviewers: eddumelendez

Merge Risk: ⚪ Minimal · up to b2a2d

The charset configuration preserves UTF-8 defaults and propagates the configured charset to container initialization scripts. No actionable merge risk is identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 4 files. (5 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: fixing initialization script decoding by supporting configurable character sets.
Description check	✅ Passed	The description explains the broken behavior, the implementation, preserved UTF-8 defaults, scope, documentation behavior, regression coverage, test results, skipped integration testing, and linked is…
Linked Issues check	✅ Passed	The pull request addresses #8776. ScriptUtils.runInitScript accepts a configurable Charset and reads the script with that charset. Existing calls retain the UTF-8 default. `JdbcDatabaseContainer.w…
Out of Scope Changes check	✅ Passed	The changes remain within #8776. The production changes implement charset selection for initialization scripts. The tests, encoded fixtures, and JDBC documentation verify and document that behavior. N…

Full details: Docstring Coverage

Explanation

Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 4 files. (5 skipped: 5 unsupported.)

• 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.}