이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.
전역 플래그
전역 플래그는 StackQL 애플리케이션의 런타임 프로그램 동작을 지정합니다. 이러한 플래그는 StackQL 애플리케이션을 시작할 때(대화형/셸 모드 또는 비대화형 exec 모드) 명령줄에서 설정하거나 StackQL 초기화(.stackqlrc) 파일에서 로드합니다. 플래그는 다음과 같습니다.
| 플래그 | 데이터 형식 | 설명 | 기본값 |
|---|---|---|---|
--access.config | string | 호출자 액세스 구성으로, JSON 엔벨로프 {"path": "/path/to/access.json"} 형식입니다(파일 경로만 지정해도 됩니다). 액세스 관리를 활성화합니다. 호출자는 JWT, 정적 Bearer 토큰, 상호 TLS 또는 로컬 OS ID로 인증되고, 문은 정책 규칙에 따라 권한이 부여됩니다. 로컬 토큰 자격 증명은 STACKQL_CALLER_TOKEN 환경 변수에서 읽습니다. StackQL v1.0 이상에서 사용할 수 있습니다. | |
--acid | string | ACID 구성을 나타내는 JSON / YAML 문자열 | {} |
--allow-persistent-secrets | flag | 세션이 SET "$.secret_store" 문으로 영구 OS 시크릿 저장소(macOS Keychain, Linux Secret Service 또는 Windows Credential Manager)를 선택할 수 있도록 허용합니다. 플랫 파일 저장소는 이 플래그가 있어도 거부됩니다. 프로바이더 세션 및 시크릿을 참조하세요. StackQL v1.0 이상에서 사용할 수 있습니다. | false |
--allow-secret-dereference | flag | SQL 식("$secrets.name", "$auth.provider.field")에서 시크릿 및 자격 증명 값을 역참조할 수 있도록 허용합니다. 그 결과 이 값이 결과, 로그 및 영구 저장된 쿼리 아티팩트에 포함될 수 있습니다. 일반적인 프로바이더 인증에는 필요하지 않습니다. SQL의 시크릿 값을 참조하세요. StackQL v1.0 이상에서 사용할 수 있습니다. | false |
--apirequesttimeout | integer | API 요청 시간 제한(초), 0이면 시간 제한 없음 | 45 |
--approot | string | 애플리케이션 구성 및 캐시 루트 경로 | {cwd}/.stackql |
--approotfilemode | uint32 | 애플리케이션 구성 및 캐시 파일 모드 | 493 |
--auth | string | json 형식의 auth 컨텍스트 키-값 | |
--cachekeycount | integer | 캐시 초기 키 개수 | 100 |
--configfile | string | 구성 파일 전체 경로 | {cwd}/.stackqlrc |
--cpuprofile | string | cpuprofile 파일, 비어 있으면 없음 | null |
--dataflow.dependency.max | int | 지정된 쿼리의 최대 데이터 흐름 종속성 깊이 | 50 |
--dataflow.components.max | int | 지정된 쿼리에서 데이터 흐름의 약하게 연결된 구성 요소 최대 개수 | 50 |
--dbInternal | string | DBMS 유지 관리 쿼리 처리를 구성하는 JSON / YAML 문자열 | {} |
-d, --delimiter | string | csv 출력의 구분 기호입니다. 단일 문자만 허용됩니다. csv 이외의 모든 출력에서는 무시됩니다 | , |
--dryrun | flag | dryrun 플래그입니다. 전처리기만 실행하며 템플릿이 적용된 출력이 반환됩니다 | false |
--env.file | string | 시작 시 프로세스 환경으로 로드되는 선택적 dotenv 스타일 파일입니다(모든 명령). MCP reload_credentials 도구는 요청 시 이 파일을 다시 로드합니다. 파일이 없어도 허용되고, 값이 비어 있는 키는 건너뛰며, 기존 변수는 덮어씁니다. .stackqlrc 파일에서는 로드되지 않습니다. StackQL v0.10.542 이후 릴리스에서 사용할 수 있습니다. | null |
--execution.concurrency.limit | int | 쿼리 실행의 동시성 제한 | 1 |
--export.alias | string | 내보내기 별칭 접두사(네임스페이스 또는 스키마) | |
--gc | string | GC 구성을 나타내는 JSON / YAML 문자열 | {} |
-H, --hideheaders | flag | 열 머리글을 비활성화합니다. --output csv 또는 --output text에서만 유효합니다 | false |
--http.log.enabled | flag | 터미널에 http 요청 정보를 표시합니다 | false |
--http.proxy.host | string | 프록시 호스트(프록시를 사용하지 않으려면 비워 둠) | null |
--http.proxy.password | string | 프록시 암호 | null |
--http.proxy.port | integer | 프록시 포트입니다. 0 이하의 숫자를 지정하면 해당 스킴의 기본 포트가 사용됩니다(예: http -> 80) | -1 |
--http.proxy.scheme | string | 프록시 스킴, http 또는 https | http |
--http.proxy.user | string | 프록시 사용자 | null |
--http.response.maxResults | integer | http 요청당 최대 결과 수입니다. 0 이하의 숫자를 지정하면 제한이 없습니다 | -1 |
--http.response.pageLimit | integer | 리소스당 반환되는 결과의 최대 페이지 수입니다. 0 이하의 숫자를 지정하면 제한이 없습니다 | 20 |
--indirect.depth.max | integer | 간접 쿼리(뷰 및 하위 쿼리)의 최대 깊이 | 5 |
-i, --infile | string | 쿼리를 읽어 오는 입력 파일(IQL 파일) | {stdin} |
-q, --iqldata | string | 템플릿 기능에 사용하는 컨텍스트(데이터) 파일(json 또는 jsonnet 파일) | |
--loglevel | string | 로그 수준이며, fatal 중 하나여야 합니다 | fatal |
--mcp.config | string | MCP 서버의 JSON / YAML 구성 객체(stackql mcp 및 stackql srv) | {} |
--mcp.log.format | string | MCP 감사 로그 인코딩으로, jsonl 또는 otel(OTLP/JSON 로그 레코드)입니다. --mcp.config 플래그의 server.audit.format 값을 재정의합니다. 로그 형식을 참조하세요. StackQL v0.11.660 이상에서 사용할 수 있습니다. | jsonl |
--mcp.protocol.version | string | 알릴 최신 MCP 프로토콜 리비전으로, auto, 2026-07-28(세션 없는 방식 전용) 또는 2025-11-25 같은 이전 리비전입니다. --mcp.config 플래그의 server.protocol_version 값을 재정의합니다. 리비전 고정을 참조하세요. StackQL v0.12.732 이상에서 사용할 수 있습니다. | auto |
--mcp.server.type | string | MCP 서버 유형이며, reverse_proxy 중 하나입니다. MCP 서버 유형을 참조하세요. | http |
--metadatattl | integer | 캐시된 메타데이터 문서의 TTL(초) | 3600 |
--namespaces | string | 캐싱, 뷰 등을 위한 네임스페이스를 나타내는 JSON / YAML 문자열 | {} |
--offline | flag | 캐시된 데이터를 사용하여 오프라인으로 작업합니다 | false |
-f, --outfile | string | 결과를 기록할 출력 파일 | {stdout} |
-o, --output | string | 출력 형식이며, otel 중 하나여야 합니다(ndjson은 jsonl의 별칭으로 허용됩니다). otel 형식은 OpenTelemetry 로그 레코드를 내보냅니다. 출력 모드를 참조하세요. 이 형식은 StackQL v0.11.660 이상에서 사용할 수 있습니다. --otel.config 플래그에 익스포터가 구성되어 있으면 otel 레코드가 해당 엔드포인트로도 푸시됩니다 | table |
--otel.config | string | otel 출력 형식을 구성하는 JSON / YAML 문자열입니다. exporter.endpoint, exporter.headers, exporter.timeout_ms, exporter.batch_size 키는 레코드를 OTLP/HTTP 로그 엔드포인트로 푸시합니다. OTLP 엔드포인트로 푸시를 참조하세요. StackQL v0.12.732 이상에서 사용할 수 있습니다 | {} |
--preview | string | 미리 보기 기능을 활성화하는 JSON 문자열입니다. {"unstable": true} 값은 문서 기반 stackql_unstable_<provider>.<service>.<resource> 관계를 노출합니다. 이 관계는 omnisdk가 프로바이더 문서에서 직접 해석하고 실행하며, 행은 생성되는 즉시 스트리밍됩니다. 나머지 키(batchSize, flushInterval, endpoint, insecureSkipTLSVerify)는 해당 백엔드를 조정합니다. 미리 보기 기능은 안정적이지 않습니다. 동작, 구문 및 출력이 릴리스 간에 예고 없이 변경되거나 중단될 수 있으므로 프로덕션 환경에서 의존하지 마세요. v1.0부터는 동일한 옵트인으로 stackql_preview.iac.run 및 stackql_preview.iac.destroy 관계가 노출됩니다. 이 관계는 omnisdk를 통해 선언된 리소스 집합을 적용하고 해체하며, 상태는 애플리케이션 루트 아래에 보관됩니다. 미리 보기 기능을 참조하세요 | {} |
--querycachesize | integer | 쿼리 계획용 LRU 캐시의 크기(항목 수) | 10000 |
--registry | string | 프로바이더 레지스트리 위치와 프로바이더 문서 서명 검증을 구성하는 JSON / YAML 문자열 | --registry 참조 |
--session | string | 세션 구성을 나타내는 JSON / YAML 문자열 | {} |
--sqlBackend | string | SQL 백엔드 시스템 구성을 나타내는 JSON / YAML 문자열 | --sqlBackend 참조 |
--store.txn | string | Txn 저장소 구성을 나타내는 JSON / YAML 문자열 | {} |
--tls.CABundle | string | CA 번들 경로이며, 지정하지 않으면 시스템 기본값이 사용됩니다 | |
--tls.allowInsecure | flag | 안전하지 않은 인증서 신뢰를 허용합니다(권장하지 않음) | |
--var | string | jsonnet 데이터 파일을 통해 StackQL 쿼리에 가져올 키/값 쌍으로 제공되는 외부 변수 | |
-v, --verbose | flag | 자세한 출력 | false |
-h, --help | stackql의 상황별 도움말 | ||
--version | StackQL 프로그램의 버전을 표시합니다 |
--registry
--registry 플래그는 프로바이더 문서를 읽어 올 위치와 해당 문서의 서명을 검증할지 여부를 구성합니다. 값은 다음 키가 포함된 JSON 문자열입니다.
| 키 | 설명 | 기본값 |
|---|---|---|
url | 레지스트리 URL. 생략하면 공개 StackQL 프로바이더 레지스트리가 사용됩니다. | 공개 레지스트리 |
localDocRoot | 레지스트리에서 다운로드하는 대신 읽어 오는 프로바이더 문서가 있는 로컬 디렉터리. 프로바이더를 개발할 때 사용됩니다. | |
srcPrefix | 레지스트리 루트 아래에서 프로바이더 소스 문서가 있는 경로 접두사. | src |
verifyConfig.nopVerify | true 값은 서명 검증을 건너뜁니다. false로 설정하면 문서 기반 미리 보기 관계를 포함하여 읽는 모든 프로바이더 및 서비스 문서에 포함된 ML-DSA-65(FIPS 204) 서명이 필요합니다. | true |
verifyConfig.publicKeys | 프라이빗 레지스트리용으로 키 ID를 16진수로 인코딩된 ML-DSA-65 공개 키에 매핑하는 JSON 객체. 내장된 프로덕션 키 대신 사용되며, 명시적인 빈 객체는 오류입니다. | 내장 키 |
예제: 서명된 프로바이더 문서 요구
공개 레지스트리에서 읽는 모든 프로바이더 및 서비스 문서에 대해 서명 검증을 활성화하며, 내장된 프로덕션 키로 검사합니다.
stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell
예제: 로컬 디렉터리에서 서명되지 않은 문서 읽기
레지스트리가 개발 중인 프로바이더 문서 디렉터리를 가리키도록 합니다. 해당 문서는 서명되지 않았으므로 검증은 비활성화된 상태로 유지됩니다.
stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
서명 검증은 StackQL v1.0 이상에서 사용할 수 있으며 기본적으로 비활성화되어 있습니다. 서명은 문서의 정확한 YAML 바이트를 대상으로 하므로, 서식이나 줄 바꿈 변경을 포함한 모든 편집은 서명을 무효화합니다. 레지스트리의 pqsig sign-doc 도구로 다시 서명하세요. 서명되지 않은 로컬 개발 문서는 nopVerify: true 설정을 유지해야 합니다. 이전의 인증서 옵션과 .sig 사이드카 파일은 더 이상 사용되지 않으며, 사이드카만으로 게시된 아카이브는 검증된 방식으로 사용하기 전에 다시 게시해야 합니다. 검증은 문서를 읽을 때 문서를 인증합니다. 아카이브 다운로드 및 추출은 대상이 아닙니다.
--sqlBackend
--sqlBackend 플래그는 StackQL의 외부 SQL 백엔드를 구성하여, 기본 임베디드 SQL 엔진 대신 외부 데이터베이스 엔진(예: PostgreSQL)을 사용할 수 있게 합니다. 이 기능은 쿼리 처리, 영구 스토리지 또는 기존 데이터베이스 인프라와의 통합에 외부 데이터베이스를 활용할 때 유용합니다.
값은 다음 키가 포함된 JSON 문자열입니다.
| 키 | 설명 | 예제 값 |
|---|---|---|
dbEngine | 데이터베이스 엔진 유형 | postgres_tcp |
sqlDialect | 사용할 SQL 방언 | postgres |
dsn | 데이터베이스의 데이터 원본 이름(연결 문자열) | 아래 예제 참조 |
예제: PostgreSQL 백엔드 사용
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
shell
예제: Databricks PostgreSQL 인터페이스 사용
Databricks는 StackQL SQL 백엔드로 사용할 수 있는 PostgreSQL 호환 인터페이스를 제공합니다. DSN은 Databricks 자격 증명과 함께 표준 PostgreSQL 연결 문자열 형식을 사용합니다.
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
shell
사용자 이름이나 암호의 특수 문자(예: @)는 DSN에서 URL 인코딩해야 합니다(예: @ 문자는 %40이 됩니다).