bisql

# bisql bisql은 Go용 양방향 SQL 템플릿 엔진입니다. SQL 클라이언트에서 실행 가능한 유효한 SQL 문이면서 동시에 애플리케이션용 매개변수화된 쿼리 빌더인 SQL 템플릿을 작성할 수 있습니다. 지시문은 SQL 주석으로 표현되므로 동일한 텍스트가 두 상황 모두에서 작동합니다. ## 주요 기능 - **양방향 SQL**: 템플릿은 유효한 SQL이며, 지시문은 주석입니다. 동일한 텍스트가 클라이언트(샘플 값 포함)에서 실행되고 Go에서 매개변수화된 문 `(SQL, Args)`을 생성합니다. - **명시적 모델**: 빈 절이나 매달린 연결자의 암시적 제거가 없습니다. 작성자는 예측 가능한 출력을 위해 동적 조각(예: `1 = 1`)을 고정합니다. - **지시문**: 바인딩(`/* expr */리터럴`), 리터럴 보간(`/*^ expr */리터럴`), 조건문(`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`), 루프(`/*%for x in xs*/`), 포함(`/*%! @include name */`). - **조각 포함**: `@include`를 통해 구성된 재사용 가능한 SQL 조각으로, `fs.FS`, 인메모리 레지스트리 또는 사용자 정의 로더에서 해석됩니다. 순환/깊이 가드가 있는 재귀를 지원합니다. - **방언 지원**: MySQL, SQLite, PostgreSQL, Oracle, SQL Server용 플레이스홀더 생성. PostgreSQL용 배열 바인딩. - **표현식 언어**: 조건 및 반복 가능 항목에 expr-lang을 사용하며, 비교, 논리 연산, 선택적 체이닝, nil 병합, `in`, `len`을 지원합니다. - **안전한 설계**: 임의 값의 원시 텍스트 대체가 없으며, 동적 식별자는 `/*%if*/` 분기를 통해 화이트리스트에 등록되어야 합니다. ## 사용법 템플릿은 `.sql` 파일입니다. 임의의 `fs.FS`(예: 임베디드)에서 `ParseFile`로 파싱한 다음 매개변수 맵 또는 구조체로 빌드합니다. ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // 매개변수화된 SQL fmt.Println(stmt.Args) // 바인드 인자 ``` ## 작성 규칙 - 동적 조각을 고정합니다(예: `AND` 체인은 `1 = 1`, `OR` 체인은 `1 = 0`). - 목록의 경우 선행 연결자(`and`/`or`)를 사용하거나 쉼표 목록의 경우 0행 시드에서 `union all select`를 사용합니다. - 문자열/식별자는 SQL 표준 이중화로 인용하며, 백슬래시 이스케이프는 인식되지 않습니다. - 파서 주석(제거됨)에는 `/*%! … */`를, 일반 블록 주석에는 `/** … */`를 사용합니다. ## 패키지 구조 - `bisql`: 공개 API(Parser, Parse, Expand, 로더). - `dialect/`: 방언 정의. - `expr/`: 평가자 인터페이스 및 Scope. - `internal/`: 템플릿 계층 및 기본 평가자. ## 개발 도구 체인은 `mise.toml`에 고정되어 있으며, `mise run check`로 fmt, build, vet, lint, 테스트를 실행합니다. PostgreSQL 통합 테스트는 빌드 태그와 DSN이 필요합니다. 전체 문서는 [Go Reference](https://pkg.go.dev/github.com/mpyw/bisql)를 참조하세요.