Fix lỗi Spring Boot: Failed to configure a DataSource — thuộc tính 'url' chưa được chỉ định

Tình Huống Gặp Phải

Bạn thêm dependency JPA hoặc JDBC, chạy ứng dụng và gặp lỗi này ngay khi khởi động:

***************************
APPLICATION FAILED TO START
***************************

Description:

Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.

Reason: Failed to determine a suitable driver class

Action:

Consider the following:
    If you want an embedded database (H2, HSQL or Derby), please put it on the classpath.
    If you have database settings to be loaded from a particular profile you may need to activate it (no profiles are currently active).

Spring Boot phát hiện spring-boot-starter-data-jpa hoặc spring-boot-starter-jdbc trên classpath và cố gắng tạo bean DataSource. Không có URL, không có driver — không có gì để làm việc, vì vậy nó dừng lại ngay lập tức.

Nguyên Nhân Gây Ra Lỗi

Các starter liên quan đến database kích hoạt cơ chế auto-configuration của Spring Boot. Ngay khi phát hiện chúng trên classpath, Spring Boot sẽ cố gắng tạo bean DataSource. Nếu không có spring.datasource.url đã được cấu hình (MySQL, PostgreSQL, v.v.) hoặc database nhúng (H2, HSQL, Derby) để tự động khởi động, ứng dụng sẽ thất bại khi khởi động.

Ba tình huống phổ biến nhất gây ra lỗi này:

Bạn sao chép dependency từ project khác nhưng quên mang theo cấu hình application.properties
Bạn đang xây dựng module mới và chưa thiết lập database
Cấu hình datasource đã có nhưng nằm sai file hoặc gắn với Spring profile chưa được kích hoạt

Cách Khắc Phục — Chọn Phương Án Phù Hợp

Phương Án 1: Thêm Database URL vào application.properties

Kết nối đến database thực? Thêm các dòng sau là xong:

# application.properties

# Ví dụ MySQL
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=yourpassword
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# Ví dụ PostgreSQL
# spring.datasource.url=jdbc:postgresql://localhost:5432/mydb
# spring.datasource.username=postgres
# spring.datasource.password=yourpassword

JDBC driver tương ứng cũng cần có trong dependencies. Với MySQL trong Maven:

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

Phương Án 2: Thêm H2 cho Development / Testing Local

Chưa có database thực? H2 chạy hoàn toàn trong bộ nhớ — không cần thiết lập gì thêm. Chỉ cần thêm dependency:

<!-- Maven -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

# Gradle
runtimeOnly 'com.h2database:h2'

Spring Boot tự động cấu hình database H2 mà không cần thêm properties. Rất phù hợp cho unit test và giai đoạn phát triển ban đầu khi bạn chưa muốn khởi chạy một DB server đầy đủ.

Phương Án 3: Loại Trừ DataSource Auto-Configuration

Đôi khi dependency được kéo vào như transitive dep và ứng dụng của bạn thực ra không dùng database. Hoặc bạn đang tự cấu hình datasource trong code. Trong cả hai trường hợp, hãy báo cho Spring Boot biết để bỏ qua:

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class
})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Thích dùng properties hơn? Hiệu quả tương đương:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

Bẫy Thường Gặp: Sai Spring Profile Đang Active

Nhiều team tách cấu hình thành các file theo profile: application-dev.properties, application-prod.properties, v.v. URL datasource nằm trong một trong các file đó. Nhưng Spring Boot chỉ đọc file application.properties gốc khi không có profile nào được kích hoạt — và không tìm thấy gì cả.

Kiểm tra profile đang chạy, hoặc đặt rõ ràng trong properties:

spring.profiles.active=dev

Từ command line:

java -jar myapp.jar --spring.profiles.active=dev

Dành Cho Người Dùng application.yml

Cấu hình YAML trông như thế này:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: yourpassword
    driver-class-name: com.mysql.cj.jdbc.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true

YAML rất nhạy cảm với indentation. Chỉ một khoảng trắng đặt sai chỗ là cấu hình hỏng âm thầm — không có lỗi rõ ràng, chỉ là giá trị bị thiếu khi chạy. Dán cấu hình của bạn vào YAML ↔ JSON Converter của ToolCraft để phát hiện lỗi cú pháp trước khi chúng gây rắc rối. Công cụ chạy hoàn toàn trên trình duyệt, không có thông tin nào rời khỏi máy bạn.

Xác Nhận Đã Sửa Được Lỗi

Khởi động lại ứng dụng. Một lần khởi động thành công sẽ trông như thế này:

HikariPool-1 - Starting...
HikariPool-1 - Added connection com.mysql.cj.jdbc.ConnectionImpl@...
HikariPool-1 - Start completed.

Started MyApplication in 3.421 seconds (process running for 3.8)

Không còn block APPLICATION FAILED TO START. Đó là tín hiệu xanh của bạn.

Muốn kiểm tra chắc chắn hơn? Thêm một smoke test thực sự mở kết nối:

@SpringBootTest
class DataSourceTest {

    @Autowired
    DataSource dataSource;

    @Test
    void connectionShouldSucceed() throws Exception {
        try (Connection conn = dataSource.getConnection()) {
            assertThat(conn.isValid(1)).isTrue();
        }
    }
}

Mẹo Phòng Tránh

Duy trì file application-dev.properties với cấu hình DB local hoạt động được (hoặc fallback H2) để developer mới có thể chạy ứng dụng ngay mà không cần thiết lập gì từ đầu
Trong CI pipeline, cố định --spring.profiles.active=test và dùng H2 hoặc Testcontainers — giữ cho test được cô lập và tái hiện được trên mọi máy
Validate YAML trước khi commit. Công cụ converter đã dẫn link ở trên giúp phát hiện lỗi indentation vô hình trong hầu hết các trình soạn thảo văn bản
Kiểm tra định kỳ pom.xml hoặc build.gradle — các transitive dependency âm thầm kéo vào spring-boot-starter-data-jpa thường xuyên hơn bạn nghĩ