Introduction

When schema.sql does not run in Spring Boot 2.0, the root cause is usually initialization mode, datasource type, or interaction with JPA schema generation settings. Spring Boot changed defaults across versions, so many guides from older releases no longer match runtime behavior.

The fix is to make initialization intent explicit and verify startup logs for datasource script execution. This article outlines a practical troubleshooting sequence that works in most Boot 2.x setups.

Core Sections

1. Set initialization mode intentionally

In Boot 2.0, script execution depends on datasource initialization mode.

spring.datasource.initialization-mode=always

If set to embedded, scripts only run for embedded databases (H2/HSQL/Derby). External MySQL/PostgreSQL will skip schema.sql.

2. Resolve conflicts with Hibernate DDL

spring.jpa.hibernate.ddl-auto can conflict with SQL script initialization.

spring.jpa.hibernate.ddl-auto=none

If set to create or update, Hibernate may manage schema separately, creating confusion about whether schema.sql executed.

3. Confirm file placement and naming

By default, schema.sql should be on classpath root (src/main/resources/schema.sql). For platform-specific scripts, use naming conventions and configure platform property.

spring.datasource.platform=postgres
# allows schema-postgres.sql, data-postgres.sql

Misplaced files are a frequent cause when packaging changes between IDE and jar execution.

4. Debug startup execution path

Enable SQL initialization logs and inspect startup output.

logging.level.org.springframework.jdbc.datasource.init=DEBUG

If scripts still do not run, create a minimal reproducible app with same datasource settings. This isolates framework behavior from unrelated auto-configurations.

5. Build repeatable verification around Spring Boot SQL initialization behavior

After implementation works once, lock in behavior with repeatable verification artifacts. At minimum, maintain one baseline case, one edge case, and one failure-path case with expected outcomes written down in plain language. This prevents accidental regressions when dependencies, runtime versions, or surrounding infrastructure change.

Use lightweight automation for these checks so they run in local development and CI. A practical pattern is to keep a tiny fixture dataset and one command that executes the critical path end to end. If that command fails, engineers can reproduce issues quickly without rebuilding the entire environment from scratch.

1verification checklist
2- baseline scenario with expected output
3- edge scenario with constrained input
4- failure scenario with expected error behavior
5- runtime and dependency versions captured

Treat this checklist as versioned code-adjacent documentation. Updating Spring Boot SQL initialization behavior without updating its verification contract is a common source of drift and support incidents.

6. Operational guidance and maintenance strategy

The long-term reliability of Spring Boot SQL initialization behavior depends on observability and change discipline. Add structured logging and targeted metrics around the most failure-prone stages so you can answer quickly: what input was processed, what branch was taken, and why output changed. Incident response improves dramatically when these signals exist before the outage.

Also define ownership for changes. When libraries, runtime versions, or platform policies evolve, someone should review compatibility and re-run validation artifacts before rollout. Small proactive checks are cheaper than emergency rollback windows.

Finally, schedule periodic contract checks even when no incident is active. Silent drift accumulates over time through dependency updates and environment differences. Preventive checks keep Spring Boot SQL initialization behavior predictable and reduce production surprises.

Common Pitfalls

• Leaving initialization mode at embedded while using external database.
• Letting Hibernate DDL generation mask or override SQL script expectations.
• Placing schema.sql outside effective runtime classpath.
• Assuming behavior from different Spring Boot version documentation.
• Debugging only SQL errors without checking datasource init logs.

Summary

schema.sql execution in Spring Boot 2.0 is controlled by explicit initialization settings and datasource context. Set initialization mode deliberately, avoid conflicting Hibernate DDL behavior, and verify file placement on classpath. With debug logging enabled, you can quickly determine whether scripts were skipped, not found, or failed during execution.