queryapigate

QueryAPIGate는 데이터베이스에 대해 SQL을 실행하고 결과를 JSON, NDJSON, XML, YAML, CSV, TSV 또는 Excel로 반환하는 자체 호스팅 단일 Flask 서비스입니다. 쿼리를 한 번 저장하면 컨트롤러, 리포지토리 계층, 페이지네이션, 인증 또는 직렬화 보일러플레이트를 작성하지 않고도 타입이 지정되고 인젝션에 안전한 파라미터와 실행 이력을 갖춘 버전 관리 REST 엔드포인트가 됩니다. 다중 데이터베이스 지원에는 MySQL, PostgreSQL, ClickHouse, SQLite, H2, DuckDB용 네이티브 드라이버와 드라이버 jar가 있는 모든 것(Oracle, SQL Server, DB2, Snowflake 등)을 위한 범용 JDBC가 포함됩니다. 동일한 SQL 가드, 풀링, 파라미터 바인딩, 출력 형식이 기반 데이터베이스와 관계없이 적용됩니다. 보안 및 접근 제어 기능: - SHA-256 해시 키 저장을 사용하는 API 키 인증. - 데이터베이스 연결 비밀번호는 QUERYAPIGATE_SECRET_KEY를 통해 저장 시 암호화되며, 연결이 열릴 때 메모리에서만 복호화됩니다. - 범위 지정 API 키: 키를 특정 연결 및/또는 저장된 쿼리의 허용 목록으로 제한하며, 쓰기 접근은 명시적으로 활성화하지 않는 한 꺼져 있습니다. - 컬렉션: 저장된 쿼리를 그룹화하고 키에 전체 그룹을 부여하며, 쿼리를 이동하면 어떤 키가 접근 권한을 얻거나 잃는지 미리 보여줍니다. - 명명된 권한 역할: 생성 시 키에 복사되는 재사용 가능한 템플릿. - API 키 만료, 폐기, 키별 속도 제한, IP 허용 목록(CIDR 범위). - 기본적으로 단일 SELECT/WITH/SHOW/DESCRIBE/EXPLAIN 문만 허용하는 SQL 가드와 바인딩된 :name 파라미터. 저장된 쿼리는 버전 관리됩니다. 같은 이름으로 저장하면 덮어쓰지 않고 새 버전이 생성되며, ?version=1은 여전히 이전 버전을 실행합니다. 파라미터는 타입, 기본값, 필수/선택, 열거형, 숫자 범위, 길이, 패턴을 선언할 수 있으며, 잘못된 입력은 데이터베이스에 도달하기 전에 필드별 400으로 거부됩니다. 응답 형식(JSON, NDJSON, XML, YAML, CSV, TSV, XLSX)은 요청별로 ?format=을 통해 선택할 수 있습니다. 페이지네이션은 ?page와 ?page_size를 사용하며 X-Has-More 헤더가 있습니다. 전체 내보내기의 경우 ?stream=true는 버퍼링 대신 데이터베이스 커서에서 전체 결과를 스트리밍하며, MySQL, PostgreSQL, ClickHouse에서 1,000,000행 결과와 평탄한 서버 메모리로 검증되었습니다. CLI 명령(queryapigate export)은 cron/systemd/Kubernetes CronJob 사용을 위해 동일한 스트리밍 경로를 감쌉니다. 쿼리 캐싱은 cache_ttl, Cache-Control, ETag, 조건부 요청, 304 Not Modified, X-Cache HIT/MISS 헤더를 지원하며 쓰기에는 절대 적용되지 않습니다. 속도 제한은 서버 전체 IP 키 기반 제한과 선택적 독립 키별 제한을 결합합니다. 관측성에는 요청 ID로 태그된 구조화 JSON 로그, 쿼리별 실행 타이밍, 느린 쿼리 경고, /metrics의 Prometheus 메트릭(요청/쿼리 수, 지연 시간, 연결 풀 점유율, 속도 제한 거부 포함)이 포함됩니다. 기록 메트릭을 위한 번들 Grafana 대시보드도 제공됩니다. OpenAPI 3.0은 /openapi.json에서 생성되며(CI에서 공식 검증기에 대해 검증됨) 모든 저장된 쿼리가 타입이 지정된 엔드포인트로 제공됩니다. /docs는 Swagger UI를 제공하며 각 키가 접근할 수 있는 범위로 필터링됩니다. /ui의 내장 관리 UI는 연결 관리, 구문 강조 및 스키마 탐색이 있는 SQL 편집기, 쿼리 실행/미리보기, EXPLAIN, 저장된 쿼리 및 버전 관리, API 키 관리, 관리 변경 감사 로그, 쿼리별 실행 이력, 접을 수 있는 JSON 트리로 응답 검사, 숫자 결과에 대한 빠른 막대 차트, 원클릭 "copy as curl"/"copy as TSV"를 다룹니다. 읽기 전용 Settings 화면은 모든 환경 변수와 유효 값을 보여주며, 비밀은 구성 여부만 보고됩니다. 설치는 선택적 드라이버 추가 기능(mysql, postgres, clickhouse, h2, duckdb, all, encryption)과 함께 pip를 통해 이루어집니다. SQLite와 DuckDB는 외부 런타임이 필요 없고, H2와 범용 JDBC는 Java 런타임이 필요합니다. Docker도 지원됩니다. `queryapigate examples load` 명령은 네 가지 실제 예제 시나리오(리포팅 API, 대시보드 데이터, 스트리밍 내보내기, 파트너 통합)를 컬렉션, 쿼리, 역할, 즉시 사용 가능한 API 키로 설치합니다. 테스트에는 단위 테스트, CI에서 실제 MySQL, PostgreSQL, ClickHouse, H2 서버에 대한 통합 테스트, DuckDB 통합 테스트, Hypothesis를 사용한 SQL 가드 퍼즈 테스트, mypy 정적 타입 검사, ruff 린팅, 모든 푸시에 대한 CI가 포함됩니다. 프로젝트는 FSL-1.1-MIT 라이선스이며 Python 3.9+가 필요합니다.