MariaDB 접속이 안 되는 이유는? 사용자와 권한 설정 트러블 슈팅

 

 

※ 이 글은 운영자가 직접 홈서버를 운영해본 경험과 MariaDB, Docker의 공식 문서를 참고해 작성한 것입니다. 문장을 다듬고 구성하는 데에 AI 보조 도구를 일부 활용했으나, 최종 내용은 운영자가 직접 검토하고 확인했습니다.

MariaDB 접속안 되는 이유? 사용자와 권한 설정 트러블슈팅

도입

6주차 월요일에는 Intel N100 홈서버에 적합한 데이터베이스가 무엇인지 고민해봤습니다. SQLite, MySQL, MariaDB, PostgreSQL을 직접 비교해본 결과, 지금 사용 중인 홈서버 환경에서는 MariaDB가 가장 무난하게 시작할 수 있는 선택지라는 결론을 내렸습니다. 다음 날인 화요일에는 Docker Compose를 활용해 MariaDB 컨테이너를 구축했고, 데이터가 저장되는 위치와 기본적인 접속 방법도 하나씩 확인해봤습니다.

수요일인 오늘은 MariaDB를 설치한 뒤 실제로 자주 마주칠 수 있는 접속 문제를 정리해보려 합니다. 컨테이너가 정상 실행 중인데도 데이터베이스에 접속되지 않거나, root 계정은 되는데 서비스용 계정은 접속되지 않거나, Access denied for user 같은 오류가 나타나는 경우입니다.

데이터베이스는 단순히 설치만 하면 끝나는 것이 아니었습니다. 누가 어디에서 접속할 수 있는지, 어떤 데이터베이스에 어떤 권한을 줄지 정리하는 과정이 필요했죠. 이번 글에서 강조하고 싶은 건 이겁니다. MariaDB의 경우, 설치 과정보다도 사용자와 권한을 관리하는 일이 훨씬 더 어렵게 다가올 수 있다는 점입니다.

Intel N100 홈서버에서 MariaDB 접속 오류가 발생했을 때 사용자 생성, 권한 부여, Host 설정, Docker Network 구성을 순서대로 점검하는 트러블슈팅 흐름을 정리했습니다.

※ 다이어그램은 운영 환경 설계를 바탕으로 AI 도구를 활용해 제작했으며, 최종 구성과 내용은 운영자가 직접 검수했습니다.
출처: 디지털 장난감

본문

MariaDB는 설치만 하면 끝일까?

MariaDB 컨테이너를 실행하고 docker compose ps에서 Up 상태를 확인하면 일단 구축은 성공한 것처럼 보입니다. 하지만 실제 서비스와 연결하려고 하면 또 다른 단계가 기다리고 있습니다. 바로 사용자와 권한 설정입니다.

데이터베이스는 여러 서비스가 함께 접근하는 저장 공간입니다. 그렇기 때문에 모든 서비스가 root 계정으로 접속하도록 두는 것은 장기적으로 볼 때 바람직하지 않습니다. WordPress, Nextcloud, n8n처럼 사용하는 서비스가 점점 많아질수록, 각 서비스별로 데이터베이스와 사용자를 따로 만들어 관리하는 것이 훨씬 더 편리합니다.

• 사용자(User) : 데이터베이스에 접속하는 계정
• 권한(Privilege) : 어떤 데이터베이스에 어떤 작업을 할 수 있는지 정한 규칙
• Host : 사용자가 어디에서 접속할 수 있는지 정한 범위
• Database : 서비스가 사용할 실제 데이터 저장 공간

접속 오류가 났을 때는 그냥 비밀번호만 다시 확인하는 것보다, 사용자 이름이나 권한, 호스트, 데이터베이스 이름까지 함께 살피는 게 좋았습니다.

Access denied 오류는 왜 발생할까?

MariaDB 접속 문제에서 가장 자주 보게 되는 메시지 중 하나는 Access denied for user입니다. 이 메시지는 사용자가 존재하지 않거나, 비밀번호가 틀렸거나, 해당 Host에서 접속할 권한이 없거나, 데이터베이스에 접근할 권한이 부족할 때 나타날 수 있습니다.

원인	확인할 항목	예상 상황
비밀번호 오류	.env, 서비스 설정값	입력한 비밀번호와 실제 DB 비밀번호가 다름
사용자 없음	mysql.user 테이블	서비스용 사용자를 만들지 않음
권한 부족	SHOW GRANTS	DB는 있지만 해당 사용자에게 권한이 없음
Host 제한	User와 Host 조합	localhost 계정과 % 계정을 혼동
Docker network 문제	서비스명, network 연결	localhost 대신 컨테이너 서비스명을 써야 함

같은 Access denied라도 원인은 여러 가지일 수 있습니다. 그래서 오류 메시지를 보고 곧바로 설정을 바꾸기보다, 어떤 계정이 어느 Host에서 어떤 DB에 접근하려는지 먼저 확인하는 편이 안전했습니다.

root 계정만 사용하는 문제

MariaDB를 처음 설치하면 root 계정으로 접속하는 게 가장 쉬워 보일 수 있습니다. 실제로 root 계정은 관리자 권한이 모두 있어서 테스트할 때는 사용이 편리하죠. 하지만 모든 작업, 특히 서비스와의 연결까지 전부 root 계정으로 처리하면 관리가 복잡해지고, 보안에도 문제가 생길 수 있습니다.

• 서비스별 권한 구분이 어렵습니다.
• 어느 서비스가 어떤 DB를 사용하는지 추적하기 어려워질 수 있습니다.
• 실수로 다른 DB에 접근하거나 변경할 위험이 커집니다.
• 비밀번호가 노출될 경우 영향 범위가 커집니다.

따라서 운영 환경에서는 서비스마다 별도의 데이터베이스와 사용자를 만드는 방식이 더 현실적이었습니다. 예를 들어 WordPress는 wordpress_db와 wordpress_user, n8n은 n8n_db와 n8n_user처럼 분리하는 식입니다.

서비스용 사용자 만들기

MariaDB에서 서비스용 사용자를 만들려면 먼저 root 계정이나 그와 같은 충분한 권한이 있는 계정으로 접속해야 합니다.

# 컨테이너 내부 접속
docker exec -it mariadb bash

# MariaDB 접속
mariadb -u root -p

접속 후에는 데이터베이스와 사용자를 생성합니다. 아래 예시는 appdb라는 데이터베이스와 appuser라는 사용자를 만드는 흐름입니다.

CREATE DATABASE appdb;

CREATE USER 'appuser'@'%'
IDENTIFIED BY 'change_this_password';

여기서 'appuser'@'%'의 %는 여러 Host에서 접속할 수 있는 사용자를 의미합니다. Docker 네트워크 내에 있는 다른 컨테이너에서 접속해야 할 때는 이 방법이 자주 쓰입니다. 하지만 실제 운영 환경에서는 접속 범위를 최대한 제한하는 것도 고려해 볼 수 있습니다.

권한 부여하기

사용자를 만든다고 해서 바로 모든 데이터베이스에 접근할 수 있는 건 아닙니다. 어떤 데이터베이스에, 어떤 권한을 줄지 따로 정해줘야 합니다.

GRANT ALL PRIVILEGES
ON appdb.*
TO 'appuser'@'%';

FLUSH PRIVILEGES;

GRANT ALL PRIVILEGES ON appdb.*는 appdb 데이터베이스 안의 모든 테이블에 대해 해당 사용자에게 권한을 부여한다는 의미입니다. FLUSH PRIVILEGES는 권한 변경을 반영하기 위해 사용하는 명령입니다.

운영 환경에서는 무조건 ALL PRIVILEGES를 주기보다 서비스가 요구하는 권한 수준을 확인하는 것이 좋습니다. 다만 홈서버 초반 실습에서는 서비스 연결 확인을 위해 이 방식으로 시작한 뒤, 이후 필요에 따라 권한 범위를 줄이는 식으로 접근할 수 있습니다.

권한 확인하기

접속 문제가 계속된다면 사용자가 실제로 어떤 권한을 가지고 있는지 확인해야 합니다.

SHOW GRANTS FOR 'appuser'@'%';

사용자와 Host 조합도 함께 확인할 수 있습니다.

SELECT User, Host
FROM mysql.user;

여기서 중요한 것은 MariaDB에서는 사용자 이름만이 아니라 Host까지 함께 계정을 구분한다는 점입니다. 예를 들어 'appuser'@'localhost'와 'appuser'@'%'는 같은 이름처럼 보이지만 다른 계정으로 취급될 수 있습니다.

• 'user'@'localhost' : 같은 컨테이너 또는 로컬에서 접속하는 경우
• 'user'@'%' : 여러 Host에서 접속할 수 있도록 허용하는 경우
• 'user'@'172.%' : 특정 대역에서만 접속하도록 제한하는 경우

이 차이를 제대로 알지 못하면, 비밀번호가 맞아도 접속이 안 되는 상황이 생길 수 있습니다.

Docker 환경에서 자주 하는 실수

Docker 환경에서는 데이터베이스 접속 주소를 잘못 입력하는 경우도 많습니다. 특히 다른 컨테이너에서 MariaDB에 접속할 때 localhost를 쓰면 문제가 생길 수 있습니다.

애플리케이션 컨테이너 입장에서 localhost는 MariaDB 컨테이너가 아니라 자기 자신을 의미합니다. 같은 Docker network 안에서 MariaDB 컨테이너에 접속하려면 서비스명이나 컨테이너 이름을 사용해야 하는 경우가 많습니다.

# 잘못 이해하기 쉬운 예
DB_HOST=localhost

# Docker Compose network 안에서 사용할 수 있는 예
DB_HOST=mariadb

정확한 값은 Compose 설정에 따라 달라질 수 있습니다. 같은 네트워크에 연결되어 있는지, 서비스 이름이 무엇인지, 그리고 데이터베이스 포트가 내부 포트인지 외부 포트인지도 꼭 확인해야 합니다.

# Docker network 확인
docker network ls

# 특정 network 상세 확인
docker network inspect 네트워크이름

# Compose 설정 최종 확인
docker compose config

운영 시 권장하는 계정 분리 방식

홈서버에서 여러 서비스를 운영하다 보면 데이터베이스 계정을 분리하는 게 정말 중요하다는 걸 알게 됩니다. 처음에는 모든 서비스가 같은 DB와 계정을 쓰는 게 편리하게 느껴질 수도 있지만, 시간이 지나면 어디서 문제가 생겼는지 파악하기가 점점 더 어려워질 수 있어요. 각 서비스마다 계정을 따로 만드는 게 번거롭게 느껴질 수 있지만, 나중에 문제가 생겼을 때 원인을 금방 찾을 수 있어 훨씬 도움이 됩니다.

서비스	DB 이름 예시	사용자 예시	운영 이유
WordPress	wordpress_db	wordpress_user	블로그 데이터 분리
Nextcloud	nextcloud_db	nextcloud_user	파일 메타데이터 분리
n8n	n8n_db	n8n_user	워크플로우 기록 분리
테스트 서비스	test_db	test_user	운영 데이터와 실험 데이터 분리

이런 방식은 처음에는 약간 번거롭게 느껴질 수 있지만, 서비스가 많아지면 각 데이터가 어떤 서비스와 연관되어 있는지 한눈에 파악할 수 있어 더 편리해집니다.

운영 로그

아래 표는 6주차 수요일을 기준으로 정리한 MariaDB 사용자 및 권한 설정 점검 항목입니다. 실제로 사용되는 계정명, 데이터베이스 이름, 호스트 범위 등은 운영 환경이나 보안 정책에 따라 달라질 수 있습니다.

점검 항목	확인 방법	운영 판단
MariaDB 상태	docker compose ps	컨테이너 실행 여부 확인
root 접속	mariadb -u root -p	관리자 접속 가능 여부 확인
사용자 목록	SELECT User, Host FROM mysql.user;	User와 Host 조합 확인
권한 확인	SHOW GRANTS	서비스 DB 접근 권한 확인
Docker 접속 주소	DB_HOST 값 확인	localhost와 서비스명 혼동 방지

에디터의 해석 노트 (Editor's Lab Note)

• MariaDB를 처음 구축했을 때는 설치만 끝나면 사용할 수 있을 것이라 생각했습니다.
• 하지만 실제 운영에서는 사용자, 권한, 접속 범위를 정리하는 일이 더 중요했습니다.
• 서비스가 늘어날수록 root 계정 하나에 의존하는 방식은 관리하기 어려워질 수 있었습니다.
• Docker 환경에서는 localhost와 서비스명, network 연결 관계를 함께 확인해야 했습니다.

참고 링크 (References)

1. MariaDB CREATE USER
2. MariaDB GRANT
3. MariaDB SHOW GRANTS
4. MariaDB FLUSH
5. Docker Compose networking

트러블슈팅

문제: Access denied for user 오류가 발생함

MariaDB 접속 시 Access denied for user 오류가 발생하면 비밀번호만 다시 입력해보는 경우가 많습니다. 하지만 실제 원인은 비밀번호 외에도 사용자 생성 여부, Host 제한, 권한 부족, Docker network 설정일 수 있습니다.

확인: 사용자, Host, 권한, 접속 주소, 환경 변수를 순서대로 점검

# 사용자와 Host 확인
SELECT User, Host
FROM mysql.user;

# 권한 확인
SHOW GRANTS FOR 'appuser'@'%';

# Compose 설정 확인
docker compose config

# MariaDB 로그 확인
docker compose logs mariadb --tail=100

원인: 비밀번호 오류, 권한 부족, Host 제한, localhost와 Docker 서비스명 혼동, .env 값 불일치

해결: 사용자와 Host 조합을 확인하고, 필요한 경우 GRANT로 권한을 다시 부여한 뒤 FLUSH PRIVILEGES를 실행

GRANT ALL PRIVILEGES
ON appdb.*
TO 'appuser'@'%';

FLUSH PRIVILEGES;

현재 구성에서는 권한 오류가 발생했을 때 바로 계정을 삭제하고 다시 만드는 것보다, 먼저 SHOW GRANTS와 mysql.user 정보를 확인하는 편이 더 안전했습니다.

마무리

MariaDB의 권한 설정을 정리하면서 단순히 서버만 켜두면 되는 일이 아니라는 걸 새삼 느꼈습니다. 누가, 어디에서 접속하는지부터 시작해서 각 사용자가 어떤 데이터베이스에서 무슨 작업을 할 수 있는지 꼼꼼하게 정리해야 한다는 점이 생각보다 신경 쓸 부분이 많았습니다. 데이터베이스 운영은 세심한 권한 관리가 기본임을 다시 한번 깨달았습니다.

화요일에는 MariaDB를 설치해서 기본 환경을 준비했습니다. 그리고 수요일에는 MariaDB에 접속할 수 있도록 사용자 계정과 권한을 정리했어요. 처음에는 root 계정 하나로 모든 작업을 처리하는 게 편하게 느껴지지만, 서비스가 점점 많아지면 이런 방식은 관리가 점점 더 어려워질 수 있겠더라고요.

이번 수요일에 느낀 점은 한마디로 정리할 수 있습니다. 데이터베이스는 단순히 실행하는 것보다, 누가 어디에서 무엇을 할 수 있는지 제대로 정리하는 과정이 훨씬 더 중요하다는 사실이었습니다. 목요일에는 이 흐름을 이어가며 MariaDB의 인덱싱과 성능 튜닝의 기초 내용을 함께 살펴볼 예정입니다.