Spring Boot DataSource url 에러, 원인 5가지로 5분 만에 해결하기

***************************
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

이 빨간 스택트레이스 앞에서 "코드는 멀쩡한데 왜 안 떠?" 하고 멘붕이 왔다면, 이 글 하나로 끝냅니다. 결론부터 말하면 이 에러는 딱 5가지 원인 중 하나입니다. 자기 케이스만 골라 복붙하고 떠나세요.

에러 메시지의 진짜 의미

Spring Boot는 클래스패스에 JDBC 관련 라이브러리가 있으면 DataSourceAutoConfiguration을 발동시킵니다. 이 자동설정의 동작 흐름은 이렇습니다.

1. spring.datasource.url 값을 찾는다.
2. 없으면 → H2 / HSQLDB / Derby 같은 임베디드 DB로 폴백을 시도한다.
3. 임베디드 DB도 클래스패스에 없으면 → "더 이상 만들 수 있는 DataSource가 없다"며 기동을 중단한다.

즉 **"명시적 url도 없고, 폴백할 임베디드 DB도 없다"**는 두 가지가 동시에 성립할 때 던져지는 예외입니다. 그래서 해결책도 "url을 주거나" 또는 "임베디드 DB를 넣거나" 두 갈래로 나뉩니다.

원인별 진단과 해결 5선

① spring.datasource.url 자체가 없다

• 증상: 가장 흔한 케이스. yml/properties에 url 설정이 통째로 빠짐.
• 확인: src/main/resources/application.yml 에서 spring.datasource.url 키 검색.
• 해결: 아래 복붙 코드 모음의 DB별 설정을 그대로 추가.

② 잘못된 프로파일이 활성화됨 (application-prod.yml 미로딩)

• 증상: 로컬 yml엔 url이 있는데 다른 프로파일로 떠서 그 설정이 안 읽힘.
• 확인: 부팅 로그에서 이 라인을 보세요.

The following 1 profile is active: "prod"

기대한 프로파일과 다르다면 그게 범인입니다.

• 해결: 의도한 프로파일을 명시적으로 지정.

java -jar app.jar --spring.profiles.active=prod
# 또는 환경변수
export SPRING_PROFILES_ACTIVE=prod

application-prod.yml 파일명이 정확한지, 그 안에 url이 있는지도 함께 확인하세요.

③ JDBC 드라이버 의존성 누락

• 증상: url은 적었는데 Failed to determine a suitable driver class가 같이 뜬다.
• 확인: ./gradlew dependencies | grep -i mysql 같은 명령으로 드라이버가 실제로 들어왔는지 확인.
• 해결: 사용하는 DB에 맞는 드라이버 추가(아래 코드 참고).

메시지 차이 팁: 드라이버는 있는데 url이 없으면 'url' attribute is not specified, url은 있는데 드라이버가 없으면 Failed to determine a suitable driver class가 부각됩니다. 어느 문장이 강조됐는지로 ①과 ③을 구분하세요.

④ H2 등 임베디드 DB 미포함

• 증상: 빠른 테스트만 하려는데 아무 DB 설정도 안 했고 H2도 안 넣음.
• 해결: 테스트/로컬 용도라면 H2 하나만 넣어도 자동 폴백으로 바로 뜹니다.

runtimeOnly 'com.h2database:h2'

⑤ ${} placeholder가 해석되지 않음

• 증상: yml에 ${DB_URL}로 써놨는데 환경변수가 비어서 빈 문자열이 들어감.
• 확인: 환경변수가 실제로 주입됐는지 echo $DB_URL로 점검.
• 해결: IntelliJ 실행 구성의 Environment variables, Docker environment:, JVM -DDB_URL=... 옵션 중 하나로 주입하거나, 기본값 문법을 쓰세요.

spring:
  datasource:
    url: ${DB_URL:jdbc:h2:mem:testdb}
    password: ${DB_PASSWORD:}

${DB_URL:기본값} 형태면 환경변수가 없어도 콜론 뒤 기본값으로 폴백되어 기동이 안 막힙니다. 12-factor 설정을 따르는 팀이라면 이 기본값 패턴을 표준으로 잡아두는 게 좋습니다.

복붙 가능한 설정 모음

MySQL (Spring Boot 3.x 기준)

Spring Boot 3.x부터 좌표가 mysql-connector-java → **mysql-connector-j**로 바뀌었습니다. 옛 글 보고 복붙하다 막히는 분 많으니 주의!

build.gradle

runtimeOnly 'com.mysql:mysql-connector-j'

application.yml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: ${DB_PASSWORD:root}
    driver-class-name: com.mysql.cj.jdbc.Driver

application.properties

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=root

PostgreSQL

build.gradle

runtimeOnly 'org.postgresql:postgresql'

application.yml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: ${DB_PASSWORD:postgres}

H2 (인메모리, 테스트/로컬용)

build.gradle

runtimeOnly 'com.h2database:h2'

application.yml

spring:
  datasource:
    url: jdbc:h2:mem:testdb
  h2:
    console:
      enabled: true

Maven 사용자(pom.xml)

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

runtimeOnly vs implementation

JDBC 드라이버는 코드에서 직접 클래스를 부를 일이 없으므로 runtimeOnly가 정석입니다. 실수로 드라이버 클래스명을 코드에 박지 않게 막아주는 효과도 있습니다.

DB가 아예 필요 없을 때의 회피법

웹 API만 만들고 DB는 아직 안 붙였는데 위 에러가 난다면, 자동설정 자체를 끄면 됩니다.

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class MyApplication { ... }

또는 프로퍼티 방식:

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

⚠️ 경고: 이건 "정말 DB를 안 쓸 때"만 정답입니다. JPA Repository를 하나라도 쓸 거라면 exclude는 문제를 뒤로 미루는 안티패턴이에요. 그땐 H2든 실제 DB든 url을 제대로 넣는 게 맞습니다.

실무 경험 한마디

저는 로컬 개발에선 거의 항상 docker-compose.yml로 MySQL/PostgreSQL을 띄우고, url은 ${DB_URL:jdbc:h2:mem:testdb} 같은 기본값 패턴으로 잡아둡니다. 이렇게 하면 도커를 안 켠 동료가 클론만 받아도 H2로 즉시 뜨고, 도커를 켜면 실 DB로 붙습니다. "내 PC에선 됐는데"를 줄이는 가장 싼 방법이 이 기본값 한 줄이더라고요.

3분 진단 체크리스트

1. spring.datasource.url 키가 yml에 있는가?
2. 부팅 로그의 active profile이 의도한 값인가?
3. dependencies에 DB 드라이버가 들어왔는가?
4. 테스트용이면 H2를 넣었는가?
5. ${} 환경변수가 실제로 주입되는가? (기본값 문법 권장)

자주 묻는 질문 (FAQ)

Q. url은 분명히 적었는데도 같은 에러가 나요. A. 십중팔구 프로파일 문제입니다. 부팅 로그의 The following profiles are active:를 확인하세요. url을 적은 yml과 실제 활성 프로파일이 다르면 그 설정은 무시됩니다.

Q. mysql-connector-java로 넣었는데 안 돼요. A. Spring Boot 3.x에선 좌표가 com.mysql:mysql-connector-j로 바뀌었습니다. 옛 좌표는 deprecated이니 새 좌표로 교체하세요.

Q. DB 없이 빠르게 서버만 띄우려면? A. runtimeOnly 'com.h2database:h2' 한 줄이면 인메모리 H2로 즉시 기동됩니다. 영구적으로 DB를 안 쓸 거라면 DataSourceAutoConfiguration.class를 exclude 하세요.