Go Migrate 튜토리얼

1. Go Migrate 개요

Go Migrate는 Go 언어로 작성된 데이터베이스 마이그레이션 관리 도구입니다. Go 프로젝트용 명령줄 인터페이스(CLI)로 사용하거나 라이브러리로 가져올 수 있습니다. Go Migrate는 다양한 데이터베이스 드라이버 및 마이그레이션 소스를 지원하며 올바른 순서로 데이터베이스에 마이그레이션 파일을 적용할 수 있습니다.

2. 버전

Go Migrate는 다음과 같은 여러 버전을 지원합니다:

  • Master: 새로운 기능 및 버그 수정이 포함된 최신 버전
  • v4: 프로덕션 환경에 적합한 안정 버전
  • v3: 더 이상 지원되지 않으며 사용해서는 안 됨

3. 설치

Go Migrate를 사용하려면 Go 패키지를 설치해야 합니다. 다음 명령어를 실행하여 설치합니다:

go get -u -d github.com/golang-migrate/migrate/v4
cd $GOPATH/src/github.com/golang-migrate/migrate/v4

3. Go Migrate 사용

Go Migrate는 CLI 또는 Go 프로젝트의 라이브러리로 사용할 수 있습니다.

3.0 데이터베이스 연결 URL

CLI 또는 Go 코드를 사용하는 경우 데이터베이스 URL을 구성해야 합니다.

URL 형식:

dbdriver://username:password@host:port/dbname?param1=true&param2=false

이 URL은 데이터베이스에 연결하고 연결 매개변수를 지정하는 데 사용되는 데이터베이스 연결 URL입니다. 각 부분에 대한 설명은 다음과 같습니다:

  1. dbdriver://: 이는 데이터베이스 드라이버를 지정하는 데 사용되는 프로토콜 식별자입니다. 예: mysql.
  2. username:password: 이는 인증에 사용되는 사용자 이름과 암호입니다. 일반적으로 사용자 이름과 암호는 콜론(:)으로 분리됩니다.
  3. @: 이 기호는 사용자 이름과 암호를 호스트 이름 및 포트와 구분하는 데 사용됩니다.
  4. host:port: 이는 데이터베이스 서버의 호스트 이름과 포트 번호입니다. 호스트 이름은 데이터베이스 서버의 IP 주소 또는 도메인 이름이며 포트 번호는 데이터베이스 서버가 수신 대기하는 포트입니다.
  5. /dbname: 이는 연결할 데이터베이스의 이름입니다.
  6. ?param1=true&param2=false: 이 부분은 추가 연결 매개변수를 지정하는 데 사용되는 쿼리 매개변수입니다. 이 예제에서 두 개의 매개변수가 있습니다.

이러한 쿼리 매개변수는 데이터베이스 드라이버 및 데이터베이스 서버의 특정 요구 사항에 따라 설정되어 연결의 특정 속성 또는 동작을 구성할 수 있습니다.

PostgreSQL 연결 매개변수

postgres://postgres:password@localhost:5432/example?sslmode=disable

SQLite 연결 매개변수

sqlite3://path/to/database?query

MongoDB 연결 매개변수

mongodb://user:password@host:port/dbname?query

3.1 CLI 사용

3.1.1 기본 사용

CLI를 사용하려면 다음 명령어를 실행합니다:

migrate -source file://path/to/migrations -database postgres://localhost:5432/database up 2

이 명령은 지정된 소스에서 마이그레이션을 적용하여 주어진 데이터베이스에 적용합니다. 숫자 "2"는 적용할 마이그레이션 수를 나타냅니다.

3.1.2 Docker 사용

Go Migrate를 Docker와 함께 사용할 수도 있습니다. 다음 명령어를 실행합니다:

docker run -v {{ migration dir }}:/migrations --network host migrate/migrate -path=/migrations/ -database postgres://localhost:5432/database up 2

이 명령은 Docker 컨테이너에서 Go Migrate를 실행하고 지정된 소스에서 마이그레이션을 적용하여 주어진 데이터베이스에 적용합니다.

3.2 Go 프로젝트에서의 사용

Go Migrate를 Go 프로젝트에서 사용하려면 필요한 패키지와 라이브러리를 가져와야 합니다. 다음은 예시입니다:

import (
    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/github"
)

func main() {
    m, err := migrate.New(
        "github://mattes:personal-access-token@mattes/migrate_test",
        "postgres://localhost:5432/database?sslmode=enable")
    m.Steps(2)
}

이 코드는 지정된 소스와 데이터베이스로 Go Migrate를 초기화하고, Steps 메서드를 사용하여 2개의 마이그레이션을 적용합니다.

기존 데이터베이스 클라이언트를 사용하려면 다음 예시를 참조하세요:

import (
    "database/sql"
    _ "github.com/lib/pq"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, err := sql.Open("postgres", "postgres://localhost:5432/database?sslmode=enable")
    driver, err := postgres.WithInstance(db, &postgres.Config{})
    m, err := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "postgres", driver)
    m.Up()
}

이 코드는 필요한 패키지를 가져오고 sql 패키지를 사용하여 데이터베이스 클라이언트를 초기화합니다. 그런 다음 NewWithDatabaseInstance 메서드를 사용하여 소스와 데이터베이스 드라이버를 지정하여 새 Go Migrate 인스턴스를 만듭니다. 마지막으로 Up 메서드를 사용하여 마이그레이션을 적용합니다.

4. 지원되는 데이터베이스 드라이버

Go Migrate는 다음과 같은 여러 데이터베이스 드라이버를 지원합니다:

  • PostgreSQL
  • PGX v4
  • PGX v5
  • Redshift
  • Ql
  • Cassandra
  • SQLite
  • SQLite3
  • SQLCipher
  • MySQL/MariaDB
  • Neo4j
  • MongoDB
  • CrateDB
  • Shell
  • Google Cloud Spanner
  • CockroachDB
  • YugabyteDB
  • ClickHouse
  • Firebird
  • MS SQL Server

5. 지원되는 마이그레이션 소스

Go Migrate는 다음과 같은 여러 마이그레이션 소스를 지원합니다:

  • 파일 시스템: 로컬 파일 시스템에서 마이그레이션을 읽기
  • io/fs: Go io/fs 패키지를 사용하여 마이그레이션 읽기
  • Go-Bindata: jteeuwen/go-bindata 패키지를 사용하여 내장된 이진 데이터에서 마이그레이션 읽기
  • pkger: markbates/pkger 패키지를 사용하여 내장된 이진 데이터에서 마이그레이션 읽기
  • GitHub: 원격 GitHub 저장소에서 마이그레이션 읽기
  • GitHub Enterprise: 원격 GitHub Enterprise 저장소에서 마이그레이션 읽기
  • Bitbucket: 원격 Bitbucket 저장소에서 마이그레이션 읽기
  • Gitlab: 원격 Gitlab 저장소에서 마이그레이션 읽기
  • AWS S3: Amazon Web Services S3에서 마이그레이션 읽기
  • Google Cloud Storage: Google Cloud Platform Storage에서 마이그레이션 읽기

프로젝트 요구 사항에 따라 위에 언급된 지원되는 파일 저장소 소스에 데이터베이스 마이그레이션 파일을 저장할 수 있습니다.

6. 마이그레이션 파일

Go Migrate의 마이그레이션 파일은 특정한 파일 이름과 내용 형식을 갖습니다.

6.1 마이그레이션 파일 이름 형식

각 마이그레이션은 "up" 마이그레이션 파일과 해당하는 "down" 마이그레이션 파일로 구성됩니다. 마이그레이션 파일 이름은 다음 형식을 준수해야 합니다:

{version}_{title}.up.{extension}
{version}_{title}.down.{extension}

version은 마이그레이션을 적용해야 하는 순서를 나타내는 고유한 번호입니다. title은 마이그레이션의 선택적 설명입니다. extension은 사용 중인 데이터베이스 시스템에 따라 달라집니다(예: SQL 변형에 대해 .sql 사용).

6.2 마이그레이션 내용 형식

마이그레이션 파일의 내용은 데이터베이스 시스템에 따라 다양하며, 일반적으로 SQL을 직접 작성하는 것을 포함합니다.

예를 들어, 다음은 두 개의 마이그레이션 파일입니다:

  • 000001_create_users_table.up.sql
  • 000001_create_users_table.down.sql

마이그레이션 파일 000001_create_users_table.up.sql

CREATE TABLE IF NOT EXISTS users(
   user_id serial PRIMARY KEY,
   username VARCHAR (50) UNIQUE NOT NULL,
   password VARCHAR (50) NOT NULL,
   email VARCHAR (300) UNIQUE NOT NULL
);

마이그레이션 파일 000001_create_users_table.down.sql, down 파일은 일반적으로 이전 작업을 되돌리는 데 사용됩니다.

DROP TABLE IF EXISTS users;

6.3 이주의 가역성

가역적인 마이그레이션을 작성하는 것이 최선의 실천 방법으로 여겨집니다. 이것은 up과 down 마이그레이션이 모든 버전에서 실행될 수 있어야 함을 의미하며, 이를 통해 데이터베이스 상태를 효과적으로 다시 생성하고 정리할 수 있습니다.

가역성을 보장하기 위해 각 마이그레이션은 대응하는 "up"과 "down" 마이그레이션 파일을 가져야 합니다. "up" 마이그레이션 파일에는 마이그레이션을 적용하는 작업이 포함되어 있으며, "down" 마이그레이션 파일에는 마이그레이션을 취소하는 작업이 포함되어 있습니다.

7. MySQL의 사용법

Go Migrate는 MySQL 데이터베이스를 지원합니다. MySQL 데이터베이스에 연결하려면 데이터베이스 URL은 다음 형식이어야 합니다:

mysql://user:password@tcp(host:port)/dbname?query

URL에는 마이그레이션 테이블 이름, TLS 매개변수 등과 같은 쿼리 매개변수를 포함할 수 있습니다. 쿼리 매개변수의 전체 목록은 Go Migrate MySQL 문서를 참조하십시오.

7.1 URL 쿼리 매개변수

  • x-migrations-table: 마이그레이션 테이블의 이름.
  • x-no-lock: GET_LOCK/RELEASE_LOCK 문을 건너뛰기 위해 true로 설정합니다. 멀티 마스터 MySQL 버전에 유용합니다.
  • x-statement-timeout: 지정된 밀리초를 초과하는 모든 명령을 중단합니다.
  • dbname: 연결할 데이터베이스의 이름.
  • user: 로그인할 사용자.
  • password: 사용자의 비밀번호.
  • host: 연결할 호스트.
  • port: 바인딩할 포트.
  • tls: TLS/SSL 암호화 연결 매개변수.
  • x-tls-ca: CA (인증 기관) 파일의 위치.
  • x-tls-cert: 클라이언트 인증서 파일의 위치.
  • x-tls-key: 개인 키 파일의 위치.
  • x-tls-insecure-skip-verify: SSL을 사용할지 여부.

7.2 기존 클라이언트와 함께 사용하기

기존 MySQL 클라이언트와 함께 Go Migrate를 사용하는 경우, 클라이언트를 생성할 때 multiStatements=true 매개변수를 사용해야 합니다. 다음은 예시입니다:

package main

import (
    "database/sql"

    _ "github.com/go-sql-driver/mysql"
    "github.com/golang-migrate/migrate/v4"
    "github.com/golang-migrate/migrate/v4/database/mysql"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    db, _ := sql.Open("mysql", "user:password@tcp(host:port)/dbname?multiStatements=true")
    driver, _ := mysql.WithInstance(db, &mysql.Config{})
    m, _ := migrate.NewWithDatabaseInstance(
        "file:///migrations",
        "mysql",
        driver,
    )

    m.Steps(2)
}

이 코드는 필요한 패키지를 가져와 MySQL 데이터베이스 클라이언트를 생성하고, 데이터베이스 인스턴스로 Go Migrate를 초기화합니다. 그런 다음 Steps 메서드를 사용하여 두 개의 마이그레이션을 적용합니다.