MariaDB 강좌 / 로컬·원격 접속과 연결 오류 해결하기

MariaDB 연결 오류는 서버 도달 여부, 포트·프로토콜, 계정 매칭, 인증과 DB 권한을 순서대로 나누어 확인하면 원인을 좁힐 수 있습니다. 원격 연결은 서버의 수신 주소·방화벽·계정 출발지 조건과 암호화가 모두 맞아야 하며, 먼저 로컬 TCP 연결부터 검증하는 편이 좋습니다.

클라이언트·서버·접속 경로를 분리해 확인하기

클라이언트가 설치되었다는 사실과 MariaDB 서버가 실행 중이라는 사실은 다릅니다. ODBC 드라이버만 설치한 경우에도 서버는 없을 수 있습니다. 설치 환경·서비스 이름·실행 파일 경로는 시스템마다 다르므로 Windows 설치와 서비스 확인 또는 Ubuntu 설치와 서버 실행 절차에서 실제 값을 확인합니다. 서버 자체의 설치·서비스 상태는 Windows에 MariaDB 설치하고 서버 실행하기 또는 Ubuntu에 MariaDB 설치하고 서버 실행하기으로 확인하고, 도달한 뒤 허용 작업은 사용자 계정 만들고 필요한 권한만 부여하기의 권한 검사로 분리합니다.

로컬 TCP 경로를 명시해 재현하기

클라이언트와 서버가 같은 PC에 있고 서버가 3306에서 실행 중이라는 전제입니다. 실제 포트가 다르면 해당 값으로 바꿉니다. --password 뒤에 암호를 적지 않고 프롬프트로 입력합니다.

mariadb --protocol=tcp --host=127.0.0.1 --port=3306 --user=course_user --password --default-character-set=utf8mb4 shopcourse

SELECT VERSION(),@@hostname,@@port,DATABASE();
SELECT USER(),CURRENT_USER();
SHOW GRANTS;

버전·호스트·포트가 예상 서버인지, DATABASE()가 shopcourse인지, CURRENT_USER()가 의도한 권한 계정인지 확인합니다. localhost는 환경에 따라 소켓·이름 있는 파이프·TCP가 달라질 수 있으므로 이 예제는 --protocol=tcp와 127.0.0.1로 경로를 고정합니다. 명령줄 클라이언트의 연결 옵션을 참고하세요.

정상 조회로 연결과 데이터 권한 구분하기

학습용 MariaDB 서버의 shopcourse에 course_user로 접속합니다. 명령줄 클라이언트와 UTF-8 SQL 파일 실행 방법대로 코드를 UTF-8 파일에 저장하고 SOURCE C:/mariadb-lab/lesson.sql;처럼 실제 파일 경로로 실행할 수 있습니다. SQL 문은 운영체제 터미널이 아닌 MariaDB 연결 안에서 실행합니다.

먼저 SELECT VERSION(), DATABASE();와 SHOW TABLES;로 대상 서버·DB·이름 중복을 확인합니다. 아래 products_44_lab는 이 글의 독립된 연습용 이름입니다. 이미 존재하면 정의와 행을 확인하고, 보관할 자료가 없는 이 글의 실습 테이블임이 확실할 때만 마지막 절의 정리 순서로 지운 뒤 다시 만듭니다. 기존 강좌의 동명 없는 테이블이나 운영 데이터는 삭제하지 않습니다.

USE shopcourse;
CREATE TABLE products_44_lab (
  product_id INT NOT NULL AUTO_INCREMENT,
  product_name VARCHAR(100) NOT NULL,
  category VARCHAR(30) NOT NULL,
  price DECIMAL(10,2) NOT NULL,
  stock INT NOT NULL DEFAULT 0,
  note VARCHAR(100) NULL DEFAULT NULL,
  PRIMARY KEY (product_id),
  CONSTRAINT ck_p44_price CHECK (price >= 0),
  CONSTRAINT ck_p44_stock CHECK (stock >= 0)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
INSERT INTO products_44_lab (product_id,product_name,category,price,stock,note) VALUES (1, '노트', '문구', 3500.00, 20, NULL),
  (2, '볼펜', '문구', 1500.00, 0, ''),
  (3, '머그컵', '생활', 8000.00, 12, '선물 포장'),
  (4, '스탠드', '생활', 25000.00, 5, NULL),
  (5, '파일', '문구', 1500.00, 50, ''),
  (6, '케이블', '전자', 8000.00, 0, '호환 확인');

SELECT COUNT(*) FROM products_44_lab;

결과는 6입니다. SELECT 1이 성공했다고 모든 DB·테이블에 접근할 수 있는 것은 아닙니다. 실제 사용할 DB와 테이블에서 허용 작업을 확인합니다. 연결 암호를 로그·스크린샷·공개 원고에 넣지 않고 오류 코드와 비밀값을 제거한 메시지를 기록합니다.

원격 접속은 필요한 수신 주소와 출발지만 허용하기

먼저 원격 서버의 관리자에게 사용할 사설 주소·포트·허용할 클라이언트 주소·TLS 정책을 확인합니다. Ubuntu 패키지 환경에서는 /etc/mysql/mariadb.conf.d/50-server.cnf 같은 실제 설정 파일의 [mariadbd] 또는 [mysqld] 구역을 확인할 수 있지만, 파일 위치는 설치 방식에 따라 다릅니다. 변경 전 설정을 백업하고 적용 파일이 맞는지 확인합니다.

[mariadbd]
bind-address = 10.0.0.10
port = 3306

10.0.0.10은 설명용 사설 주소이므로 실제 서버에 존재하는 주소로 바꿉니다. 해당 주소에서 수신하도록 설정하고 정책에 맞는 방화벽에서 특정 클라이언트 출발지만 허용합니다. 서버 재시작은 연결 중단을 동반할 수 있으므로 영향과 복구 경로를 확인한 뒤 수행합니다. 계정도 정확한 클라이언트 호스트 조건으로 별도 구성해야 합니다. MariaDB 원격 접속 구성 안내를 확인하세요.

원격 TCP에서 인증서와 계정 매칭 확인하기

아래 명령은 이름이 해석되는 실제 서버와 신뢰할 CA 파일이 준비된 경우의 예입니다. db.example.internal과 파일 경로를 실제 값으로 바꾸며, 이름이 인증서와 일치해야 합니다. 로컬 실습 서버의 성공을 원격 네트워크·TLS 검증까지 완료한 것으로 해석하지 않습니다.

mariadb --protocol=tcp --host=db.example.internal --port=3306 --user=app_user --password --ssl --ssl-verify-server-cert --ssl-ca=C:/mariadb-lab/ca.pem

허용된 SSH 터널이나 VPN을 사용할 수도 있지만, 터널을 통과한 서버 측 출발지와 MariaDB 계정의 Host 매칭은 실제 경로로 확인해야 합니다. 0.0.0.0 수신·모든 주소 허용·인증서 검증 해제를 연결 오류의 관례적인 해결책으로 사용하지 않습니다.

오류를 재현하고 원상복구할 항목 기록하기

서버까지 도달하지 못하면 클라이언트 주소·DNS·수신 포트·방화벽을, 도달 후 Access denied면 실제 계정·Host·플러그인·암호를 점검합니다. Unknown database나 테이블 권한 오류는 접속 이후의 별도 단계입니다. 설정을 바꿨다면 변경 항목과 원래 값, 재시작 여부를 기록하고 원래 파일·정책으로 되돌리는 방법을 확인합니다.

반복하기 전 현재 DB와 실제 정의·행을 확인하고 필요한 자료를 백업합니다. 보관할 데이터가 없는 이 글의 전용 실습 객체만 아래 순서로 정리합니다. 외래키가 있으면 자식부터 지웁니다. DROP TABLE은 구조와 데이터를 모두 없애며 일반적인 ROLLBACK으로 복원되지 않으므로 취소 가능한 DML 실습과 분리합니다.

DROP TABLE shopcourse.products_44_lab;