qp, REST API’nin komut satırı istemcisidir. Bir sorgu talebi açar, bir inceleyici onaylayıp worker çalıştırana kadar bekler ve sonucu indirir. Etrafına kurulacak hiçbir şey gerektirmeyen tek bir statik ikili dosyadır; terminale de CI işine de uyar. Kendi deposunda yaşar: QueryProxy/qp.

qp yalnızca API’nin izin verdiğini yapabilir. Talep onaylayamaz; özellikle sahibinin kendi talebini onaylayamaz, hiçbir şeyi aşamaz. Web arayüzünden açılmış bir talepte olduğu gibi, bir inceleyici onaylamadan hiçbir şey çalışmaz; SQL korumaları ve maskeleme olağan biçimde geçerlidir.

Kurulum

Platformunuzun arşivini sürümler sayfasından indirin. Linux, macOS ve Windows için, amd64 ve arm64 ikili dosyaları vardır. qp’yi PATH’inize koyun.

Sürüm iş akışı sağlama toplamı dosyasını cosign ile anahtarsız (keyless) imzalar. Kullanmadan önce indirmeyi doğrulayın:

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/QueryProxy/qp/\.github/workflows/release\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt
sha256sum --ignore-missing -c checksums.txt

Kimlik doğrulama

Web arayüzünde (Profile) bir kişisel erişim token’ı oluşturun. Token’ın kapsamları ve bir son kullanma tarihi vardır; hattın yalnızca ihtiyacı olanı verin:

Kullanım	Token’ın ihtiyacı
`qp submit`	`requests:submit` (bağlantıyı adıyla aramayı da kapsar)
`qp submit --wait`	ek olarak `requests:read`, sonuç için de `results:read`
`qp status`	`requests:read`
`qp results`	`results:read`; `--format json` için ek olarak `requests:read`

export QP_URL=https://queryproxy.example.com
export QP_TOKEN='12|qp_...'

--url ve --token ortam değişkenlerini geçersiz kılar. Ortamı tercih edin: bayrak değeri süreç listesinde görünür. qp token’ı asla yazdırmaz ve hata mesajlarından temizler. Düz http:// URL’si çalışır; yerel makineyi göstermiyorsa uyarı verir ama token’ı şifresiz yollar. qp yönlendirmeleri izlemez, bu yüzden QP_URL’yi son adrese ayarlayın.

Komutlar

qp submit

qp submit --conn <id|ad> --file report.sql --reason "aylık rapor" --wait

Bayrak	Anlamı
`--conn`	Bağlantı kimliği ya da tam adı (sayı her zaman kimlik sayılır)
`--file`	SQL’in bulunduğu dosya; `-` standart girdiyi okur
`--reason`	İfadenin neden gerektiği; onaylayan görür
`--title`	Kısa başlık, isteğe bağlı
`--wait`	Onayı ve çalışmayı bekler, sonra sonucu yazdırır
`--timeout`	`--wait` ile: bu süre sonunda vazgeçer. Varsayılan `30m`; `0` sonsuza kadar bekler
`--poll-interval`	`--wait` ile: sunucuya ne sıklıkta sorulacağı. Varsayılan `3s`
`--format`, `--output`	`--wait` ile: `qp results` ile aynı

İlerleme standart hataya gider. --wait olmadan standart çıktı yalnızca talep kimliğini taşır; bu yüzden id=$(qp submit ...) çalışır. --wait ile yalnızca sonucu taşır. Zaman aşımı ya da Ctrl-C beklemeyi durdurur ama talebi iptal etmez: talep sunucuda kalır ve qp status <id> onu izler.

qp status

qp status <id> talebi yazdırır; --json ile JSON olarak. Bitmiş bir talepte qp submit --wait ile aynı çıkış kodlarını verir.

qp results

qp results <id> tamamlanmış bir talebin saklanan sonucunu, bağlantının maskeleme kurallarıyla zaten maskelenmiş olarak indirir.

--format csv (varsayılan) sonucu sunucunun gönderdiği biçimde yazar.
--format json sütun adlarıyla anahtarlanmış nesnelerden oluşan tek bir dizi yazar, akış olarak. Değerler tam metinlerini korur; yinelenen sütun adları yinelenen anahtar üretir.
--output <dosya> standart çıktı yerine dosyaya yazar. Dosya, zaten varsa da, 0600 kipinde olur.

Sunucu sonucu satır tavanında kestiyse qp bunu standart hatada söyler.

qp version sürümü yazdırır.

Çıkış kodları

Kod	Anlamı
`0`	Başarıyla tamamlandı
`1`	Kullanım, yapılandırma, ağ ya da API hatası: hatalı token, bilinmeyen bağlantı, korumanın reddettiği SQL
`2`	Talep reddedildi
`3`	Talep çalışırken başarısız oldu ya da iptal edildi
`4`	Talep bitmeden `--timeout` doldu
`130`	Kesildi

Bir hat içinde

- run: qp submit --conn prod-reporting --file sql/report.sql --reason "gecelik rapor $GITHUB_RUN_ID" --wait --timeout 2h --output report.csv
  env:
    QP_URL: ${{ vars.QP_URL }}
    QP_TOKEN: ${{ secrets.QP_TOKEN }}

İş, bir inceleyici karar verene kadar bekler; bu yüzden --timeout’a ekibinizin onay hızına uyan bir değer verin ve kısa sürede sona eren bir token kullanın.

Sonraki adımlar

qp’nin arkasındaki uç noktalar için REST API ve kişisel erişim token’ları.
Kimin nasıl onayladığı için Onay akışı.
Token hijyeni için Üretim güvenliği.