SQL 쿼리를 사용하는 모든 애플리케이션은 쿼리 빌더를 사용하여 코드 가독성, 유지 관리 용이성 및 보안을 향상시키는 이점을 누릴 수 있습니다. 실제로 Golang에는 이러한 작업을 수행하는 다양한 라이브러리가 있습니다. Vaunt에서는 마침내 직접 만들기로 결정하기 전에 다양한 옵션을 시도했습니다. 궁극적으로 우리는 읽기 가능하고 조건문을 가질 수 있으면서도 SQL 주입을 방지하기 위해 안전하고 변수 대체 기능을 제공하는 것을 원했습니다. 그래서 우리는 작년 말에 출시하고 발표한 tqla라는 새로운 라이브러리를 만들었습니다. 이 기사에서 이에 대한 자세한 내용을 읽을 수 있습니다.

tqla를 구축하기 전에는 SQL 쿼리 작성 로직에 Squirrel을 주로 사용했으며 이를 적극 권장합니다. 일부 영역에서는 여전히 Squirrel을 사용하고 있지만 점차적으로 새로운 쿼리 작성 로직을 tqla로 교체하고 구현하기 시작했습니다. 우리는 tqla가 코드를 유지 관리하고 다른 명령문 작성기를 사용할 때 직면한 문제를 해결하는 능력을 향상시킨 많은 사례를 발견했습니다.

실제 사용 사례

Vaunt에서는 최근 CockroachDB에서 TiDB로 데이터베이스 마이그레이션을 진행했습니다. CockroachDB는 성능이 뛰어나고 안정적이었지만 궁극적으로 OLAP 데이터베이스를 지원하기 위해 기술 스택에 추가해야 한다는 결정에 직면했습니다. 이에 대한 필요성은 오픈 소스 커뮤니티 통찰력 제품에 대한 분석 워크로드를 지원하는 것이었습니다. 기술 공간을 작게 유지하기 위해 우리는 TiDB로 발전하고 데이터베이스의 HTAP 아키텍처를 활용하기로 결정했습니다. 

CockroachDB는 PostgreSQL과 대부분 호환되며, 우리는 많은 SQL 쿼리에 PostgreSQL 구문을 사용했습니다. TiDB로 전환하려면 몇 가지 테이블을 변경하고 MySQL 구문을 사용하도록 쿼리를 업데이트해야 했습니다. 마이그레이션 중 몇몇 위치에서 조건부 쿼리 작성 문을 부적절하게 사용하고 있으며 문이 잘못 생성되고 있음을 파악하는 적절한 테스트가 부족하다는 사실을 발견했습니다.

데모

Squirrel의 README에는 조건부 쿼리 작성을 사용하여 선택적 필터로 명령문을 업데이트하는 방법에 대한 예가 있습니다.

if len(q) > 0 {
    users = users.Where("name LIKE ?", fmt.Sprint("%", q, "%"))
}

다음은 테이블을 조건부로 조인하고 선택적 필터를 추가하기 위해 쿼리 중 하나를 업데이트한 방법에 대한 실제이지만 단순화된 예입니다.

psql := squirrel.StatementBuilder.PlaceholderFormat(squirrel.Question)

statementBuilder := psql.Select(`i.id`).
From("vaunt.installations i").
Where(`entity_name = ?`, name)

if len(provider) > 0 {
    statementBuilder.Where(`provider = ?`, provider)
}

if len(repo) > 0 {
    statementBuilder.Join(`repositories as r on JSON_CONTAINS(i.repositories, CONCAT('["', r.id, '"]'))`)
    statementBuilder.Where(`r.name = ?`, repo)
}

코드에서 문제를 발견할 수 있나요? 그렇지 않더라도 걱정하지 마세요. 이는 테스트를 실행할 때까지 자체 코드 검토를 거치지 않은 문제이기도 합니다. 

여기서 문제는 빌더 기능의 결과로 명령문 빌더를 업데이트하는 것을 잊었다는 것입니다. 예를 들어 공급자 조건 필터는 다음과 같이 읽어야 합니다.

if len(provider) > 0 {
    statementBuilder = statementBuilder.Where(`provider = ?`, provider)
}

이는 비교적 간단한 실수이고 충분한 테스트 사례를 통해 쉽게 잡을 수 있지만 기술적으로 잘못된 코드는 아니기 때문에 무슨 일이 일어나고 있는지 즉시 깨닫는 데 약간의 시간이 걸릴 수 있습니다.

이 설정의 또 다른 가독성 문제는 조건부 조인이 초기 select 문과 분리되어 있다는 것입니다. 각 부분을 올바른 위치에 배치하도록 빌더를 재구성할 수 있지만 여러 번 중복된 조건문 확인이 필요하고 여전히 일부 가독성 문제가 발생합니다.

tqla 사용

Squirrel을 사용한 위의 데모는 다시 작성되었으며 tqla의 해당 데모는 다음과 같습니다.

t, err := tqla.New(tqla.WithPlaceHolder(tqla.Question))
if err != nil {
    return nil, err
}

query, args, err := t.Compile(`
    SELECT i.id
    FROM vaunt.installations as i
    {{ if .Repo }}
    JOIN vaunt.repositories as r on JSON_CONTAINS(i.repositories, CONCAT('["', r.id, '"]'), '$')
    {{ end }}
    WHERE entity_name = {{ .Name}}
    {{ if .Provider }}
    AND i.provider = {{ .Provider }}
    {{ end }}
    {{ if .Repo }}
    AND r.name = {{ .Repo }}
    {{ end }}
    `, data)
if err != nil {
    return nil, err
}

보시다시피, tqla의 템플릿 구문을 사용하면 조건절을 매우 간단하게 통합할 수 있습니다. Tqla는 설정 중인 변수를 지정된 자리 표시자로 자동으로 바꾸고 SQL 드라이버와 함께 명령문을 실행하는 데 사용할 수 있는 인수를 제공합니다.

Squirrel과 유사하게, 이 명령문 작성 접근 방식은 테스트하기 쉽습니다. 템플릿 빌더에 전달하고 출력을 검증할 다양한 데이터 객체 세트를 생성할 수 있기 때문입니다.

가장 적합한 곳에 쿼리의 조건부 부분을 쉽게 추가할 수 있다는 것을 알 수 있습니다. 예를 들어 FROM 문 바로 뒤에 조건부 JOIN이 있습니다. 여전히 여러 조건 확인이 있지만 템플릿이 지나치게 복잡해지지는 않습니다.

맞춤 기능

SQL 빌더의 유지 관리성을 향상시키는 데 도움이 되는 또 다른 멋진 tqla 기능은 일부 변환 논리를 추상화하기 위해 템플릿에서 사용할 수 있는 사용자 정의 함수를 정의하는 기능입니다.

다음은 Golang의 time.Time 값을 sql.NullTime으로 변환하는 함수를 사용하여 미리 변환할 필요 없이 데이터 개체에 삽입을 수행할 수 있는 방법의 예입니다.

funcs := template.FuncMap{
    "time": func(t time.Time) sql.NullTime {
        if t.IsZero() {
            return sql.NullTime{Valid: false}
        }
        return sql.NullTime{Time: t, Valid: true}
    },
}

t, err := tqla.New(tqla.WithPlaceHolder(tqla.Question), tqla.WithFuncMap(funcs))
if err != nil {
    return err
}

tqla funcs 맵에 이 함수가 정의되어 있으므로 이제 time.Time 필드인 데이터 객체의 매개변수를 제공하여 쿼리 템플릿에서 자유롭게 사용할 수 있습니다. 서로 다른 필드가 있는 동일한 템플릿에서 이 함수를 여러 번 호출할 수도 있습니다.

다음은 간단한 예입니다.

statement, args, err := t.Compile(`
    INSERT INTO events
        (name, created_at, merged_at, closed_at)
    VALUES ( 
        {{ .Name }},
        {{ time .CreatedAt }},
        {{ time .MergedAt }},
        {{ time .ClosedAt }}
    )`, eventData)

결론

결론적으로, 우리는 tqla를 사용하면 쿼리 작성 논리의 유지 관리성을 향상시키는 동시에 동적 쿼리 생성을 위한 강력한 유틸리티를 제공할 수 있다고 믿습니다. 템플릿 구조의 단순성 덕분에 코드를 깔끔하게 읽을 수 있고 잠재적인 오류를 더 빠르게 디버깅할 수 있습니다.

우리는 다양한 유형의 애플리케이션에서 SQL 쿼리를 작성하는 간단하고 유지 관리 가능하며 안전한 방법을 원하는 다른 사용자에게 좋은 옵션을 제공하기 위해 이 라이브러리를 공유하기 위해 tqla 오픈 소스를 만들었습니다.

관심이 있으시면 저장소를 확인하시고 어떤 식으로든 도움이 되었다면 별점을 주세요. 기능 요청이나 버그 신고를 자유롭게 보내주세요!

저희는 언제나 피드백과 기여를 환영합니다.

향후 개발 소식을 계속 확인하려면 X에서 팔로우하거나 Discord에 참여하세요!