고랭(Golang)으로 MySQL 데이터베이스 연결하기: DSN 완벽 정복! (초보자 필독)

고랭(Golang)으로 MySQL 데이터베이스 연결하기: DSN 완벽 정복! (초보자 필독)

안녕하세요!

오늘은 고랭(Golang)으로 프로그래밍할 때 정말 자주 필요한 작업 중 하나인, MySQL 데이터베이스에 연결하는 방법에 대해 알아보려고 합니다.

 

데이터베이스에 연결하려면, 우리 프로그램이 데이터베이스 서버에게 "나 누구인데, 들어가도 될까?" 하고 말을 걸어야 하는데요.

 

이때 필요한 사용자 이름, 비밀번호, 서버 주소 같은 정보들을 특별한 형식의 문자열 하나에 담아서 전달합니다.

이걸 바로 DSN(Data Source Name, 데이터 소스 이름)이라고 부릅니다.

 

고랭(Go)에서는 표준 라이브러리인 database/sql 패키지와 MySQL 전용 드라이버(driver), 예를 들어 많이 사용하는 github.com/go-sql-driver/mysql 같은 것을 함께 사용해서 데이터베이스와 소통하는데요.

 

이 과정에서 가장 중요한 첫걸음이 바로 DSN을 올바르게 작성하는 것입니다.

 

오늘은 이 DSN이 어떻게 생겼고, 고랭(Go) 코드 안에서 어떻게 쉽고 안전하게 만들 수 있는지 차근차근 알아보겠습니다.

 

핵심 요약 미리보기

• MySQL DSN은 사용자 정보, 서버 주소, 데이터베이스 이름, 추가 설정 등을 정해진 규칙에 따라 적은 문자열입니다.
• DSN 문자열을 직접 만드는 것보다, go-sql-driver/mysql 드라이버가 제공하는 mysql.Config 구조체와 FormatDSN() 메서드를 사용하는 것이 훨씬 편리하고 실수를 줄일 수 있습니다.
• DSN에 추가 파라미터(parameter)를 설정해서 연결 시간 제한이나 문자 인코딩 방식 등을 원하는 대로 조절할 수 있습니다.

1. DSN 형식이란 무엇일까요?

 

DSN은 데이터베이스에 접속하는 데 필요한 모든 정보를 담고 있는 하나의 긴 문자열이라고 생각하면 쉽습니다.

 

고랭(Go)에서 MySQL에 연결할 때 사용하는 DSN의 일반적인 형식은 다음과 같은 구조를 따릅니다.

 

[사용자이름[:비밀번호]@]프로토콜(주소)/데이터베이스명[?파라미터1=값1&파라미터2=값2...]

 

각 부분이 무엇을 의미하는지 하나씩 살펴볼까요?

• 사용자이름(username): MySQL 데이터베이스에 로그인할 때 사용하는 아이디입니다.
• 비밀번호(password): 위 사용자 이름에 해당하는 비밀번호입니다. 비밀번호는 선택 사항이지만, 보통은 꼭 필요하겠죠? 사용자 이름 뒤에 콜론(:)으로 구분해서 적어줍니다. (사용자이름:비밀번호)
• 프로토콜(protocol): 데이터베이스 서버와 어떤 방식으로 통신할지를 정합니다. 보통 인터넷 네트워크를 통해 연결할 때는 tcp를 사용하고, 같은 컴퓨터 내의 특별한 통로(소켓 파일)를 통해 연결할 때는 unix를 사용합니다.
• 주소(address): 데이터베이스 서버가 어디에 있는지 알려주는 주소입니다. tcp 프로토콜(protocol)을 사용할 때는 보통 호스트이름(또는 IP주소):포트번호 형식 (예: 127.0.0.1:3306)으로 적고, unix 프로토콜(protocol)을 사용할 때는 소켓 파일의 경로를 적어줍니다.
• 데이터베이스명(dbname): 여러 데이터베이스 중에서 우리가 접속하고 싶은 특정 데이터베이스의 이름을 적습니다. 슬래시(/) 뒤에 붙여줍니다.
• 파라미터(param): 물음표(?) 뒤에는 연결에 대한 추가적인 설정을 키=값 형태로 여러 개 지정할 수 있습니다. 각 설정은 앰퍼샌드(&) 기호로 구분합니다. (예: charset=utf8mb4&parseTime=True)

2. DSN 예시 살펴보기

 

말로만 설명하면 감이 잘 안 올 수 있으니, 실제 DSN 예시를 보면서 이해해 보겠습니다.

 

user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local

 

이 DSN 문자열을 하나씩 해석해 볼까요?

 

• user:password: MySQL 사용자 이름은 user이고, 비밀번호는 password입니다.
• @tcp: TCP 프로토콜(protocol)을 사용해서 연결합니다.
• (127.0.0.1:3306): MySQL 서버는 127.0.0.1(내 컴퓨터를 의미하는 특별한 IP 주소, 즉 localhost)의 3306번 포트(port)에서 실행되고 있습니다. (MySQL은 보통 3306 포트를 사용합니다.)
• /dbname: 연결할 데이터베이스의 이름은 dbname입니다.
• ?charset=utf8mb4: 문자 인코딩 방식으로 utf8mb4를 사용합니다. 이렇게 설정하면 한글이나 이모지 같은 다양한 문자를 깨짐 없이 저장하고 읽어올 수 있습니다. 아주 중요한 설정입니다!
• &parseTime=True: 데이터베이스의 날짜/시간 관련 데이터(예: DATETIME, TIMESTAMP 타입)를 고랭(Go)의 time.Time 타입으로 자동으로 변환해주는 기능를 켭니다. 이 설정을 켜두면 시간 데이터를 다루기가 훨씬 편해집니다.
• &loc=Local: 시간 데이터를 처리할 때 사용할 시간대(timezone)를 컴퓨터의 로컬 시간대로 설정합니다.

3. 고랭(Go)에서 DSN 만들기 (더 스마트한 방법!)

 

DSN 문자열 형식을 알았으니, 이제 코드 안에서 직접 만들어 볼 수 있습니다.

 

하지만 위 예시처럼 직접 문자열을 조립하는 방식은 오타가 나기 쉽고, 나중에 코드를 읽거나 수정하기도 조금 불편할 수 있습니다.

 

다행히도, go-sql-driver/mysql 드라이버는 이 DSN 문자열을 훨씬 더 안전하고 깔끔하게 만들 수 있는 방법을 제공합니다.

 

바로 mysql.Config라는 구조체(struct)를 사용하는 것입니다.

 

마치 레고 블록처럼 필요한 정보 조각들을 구조체 필드(field)에 채워 넣고, 마지막에 FormatDSN()이라는 메서드를 호출하면 알아서 DSN 문자열로 딱! 만들어 줍니다.

 

코드로 직접 확인해 볼까요?

package main

import (
    "database/sql" // 데이터베이스 인터페이스 표준 패키지
    "log"          // 로그 출력을 위한 패키지
    "time"         // 시간 관련 기능을 위한 패키지

    "github.com/go-sql-driver/mysql" // MySQL 드라이버 패키지
)

func main() {
    // 1. 연결 정보 설정하기 (mysql.Config 구조체 사용)
    cfg := mysql.Config{
        User:                 "user",                                // 사용자 이름
        Passwd:               "password",                            // 비밀번호
        Net:                  "tcp",                                 // 프로토콜
        Addr:                 "127.0.0.1:3306",                      // 서버 주소 및 포트
        DBName:               "dbname",                              // 데이터베이스 이름
        AllowNativePasswords: true,                                // 네이티브 비밀번호 방식 허용 (보안 설정에 따라 필요할 수 있음)
        ParseTime:            true,                                // time.Time 자동 변환 활성화
        Loc:                  time.Local,                            // 로컬 시간대 사용
        // 여기에 다른 파라미터들도 추가할 수 있습니다. 예: Timeout, ReadTimeout 등
    }

    // 2. DSN 문자열 생성 및 데이터베이스 핸들 얻기
    // cfg.FormatDSN() 메서드가 설정된 정보로 DSN 문자열을 만들어 줍니다.
    db, err := sql.Open("mysql", cfg.FormatDSN())
    if err != nil {
        // sql.Open 자체는 실제로 연결하지 않으므로, 여기서 에러는 주로 DSN 포맷 오류 등입니다.
        log.Fatal("데이터베이스 핸들 생성 실패:", err)
    }
    // defer 키워드는 main 함수가 끝나기 직전에 db.Close()가 반드시 호출되도록 보장합니다.
    // 이렇게 해야 사용한 연결 리소스를 깔끔하게 정리할 수 있습니다.
    defer db.Close()

    // 3. 실제로 데이터베이스에 연결되는지 확인 (Ping)
    // sql.Open()은 연결 준비만 하고, db.Ping()이 실제로 연결을 시도하고 확인합니다.
    err = db.Ping()
    if err != nil {
        log.Fatal("데이터베이스 연결 실패:", err)
    }

    log.Println("데이터베이스에 성공적으로 연결되었습니다!")
}

 

코드 설명

• 먼저 mysql.Config 타입의 변수 cfg를 만들고, 필요한 연결 정보(사용자 이름, 비밀번호, 주소, 데이터베이스 이름 등)를 각 필드(field)에 채워 넣습니다. 훨씬 명확하게 정보를 관리할 수 있죠?
• 그다음 sql.Open() 함수를 호출하는데, 첫 번째 인자로는 사용할 드라이버 이름("mysql")을, 두 번째 인자로는 cfg.FormatDSN() 메서드가 반환하는 DSN 문자열을 전달합니다. sql.Open() 함수는 실제로 데이터베이스에 바로 연결하는 것이 아니라, 앞으로 데이터베이스 작업을 수행할 때 사용할 *sql.DB 타입의 객체(데이터베이스 핸들)를 준비해 줍니다.
• defer db.Close()는 아주 중요한 습관입니다. 프로그램이 어떤 경로로 종료되든 상관없이, 함수가 끝나기 직전에 db.Close()를 호출해서 사용했던 데이터베이스 연결 자원을 확실하게 반납하도록 예약하는 역할을 합니다.
• 마지막으로 db.Ping() 메서드를 호출해서 실제로 데이터베이스 서버와 통신이 가능한지 확인합니다. 여기서 에러(error)가 없다면 성공적으로 연결된 것입니다!

4. 추가 연결 파라미터들

DSN 문자열의 물음표(?) 뒤에 붙는 파라미터(parameter)는 앞에서 본 charset, parseTime, loc 외에도 여러 가지가 있습니다. 이를 통해 연결 동작을 더 세밀하게 제어할 수 있는데요. 몇 가지 유용한 파라미터(parameter)들을 더 알아보겠습니다.

• collation: 문자열을 비교하거나 정렬할 때 사용할 규칙(콜레이션)을 지정합니다. charset과 함께 설정하는 경우가 많습니다. (예: collation=utf8mb4_unicode_ci)
• timeout: 데이터베이스에 새로 연결을 시도할 때, 응답을 기다리는 최대 시간(초 단위)을 설정합니다. 이 시간이 지나도 연결되지 않으면 실패 처리합니다. (예: timeout=5s)
• readTimeout: 연결이 성공한 후, 데이터를 읽는 작업(예: SELECT 쿼리 실행)이 얼마나 오래 걸릴 수 있는지 최대 시간 제한을 설정합니다. (예: readTimeout=30s)
• writeTimeout: 데이터를 쓰는 작업(예: INSERT, UPDATE 쿼리 실행)의 최대 시간 제한을 설정합니다. (예: writeTimeout=30s)

이 외에도 다양한 파라미터(parameter)들이 있습니다.

 

모든 파라미터(parameter) 목록과 자세한 설명은 go-sql-driver/mysql 드라이버의 공식 문서(documentation)를 참고하시면 가장 정확합니다.

 

mysql.Config 구조체를 사용할 때는 이 파라미터(parameter)들도 해당 필드(field)에 설정하거나, Params 맵 필드(field)를 통해 추가할 수 있습니다.

 

마무리하며

 

고랭(Golang) 애플리케이션(application)과 MySQL 데이터베이스를 성공적으로 연결하려면 DSN을 올바르게 작성하는 것이 정말 중요합니다.

 

오늘 살펴본 것처럼, DSN의 구조를 이해하고 특히 mysql.Config 구조체와 FormatDSN() 메서드를 활용하면, 훨씬 읽기 쉽고 오류 발생 가능성이 적은 코드를 작성할 수 있습니다.

 

이렇게 튼튼하게 연결 설정을 해두면, 앞으로 데이터베이스 관련 작업을 할 때 훨씬 안정적이고 유지보수하기 좋은 코드를 만들 수 있을 것입니다.

---