ferox: Instructions file for Claude Code

pgclient — CLAUDE.md

Proje Özeti

Hafif bir masaüstü PostgreSQL client uygulaması. Rust + egui/eframe ile yazılmış. Hedef: DBeaver/DataGrip'e alternatif, <50MB RAM, <200ms startup.

Gerçek ölçümler (v0.2.3): ~45–47 MB RAM, 6.9 MB binary (release LTO) v-next: binary 9.86 MB'a çıktı (+%43) — sebebi keyring crate'in Windows backend'i (windows-native-keyring-store), beklenenin aksine security-framework/zbus gibi zaten linkli bir şeyin üstüne binmiyor, tam bir regex motoru (regex+aho-corasick+regex-automata) getiriyor. Bilinçli bir trade-off olarak kabul edildi (gerçek şifre şifrelemesinin güvenlik değeri arttı) — ama gelecekte RAM/boyut bütçesi tekrar gündeme gelirse ilk bakılacak yer burası.

Not: Cargo paket adı ferox-pg (crates.io yayını için, v0.2.9'da yeniden adlandırıldı); binary adı hâlâ ferox.

Tech Stack

• GUI: egui 0.29 + eframe (immediate-mode, pure Rust; accesskit devre dışı)
• DB Driver: tokio-postgres 0.7 (async, pure Rust; simple_query text protokol)
• Async: tokio (current-thread runtime, ayrı std::thread içinde)
• TLS: native-tls + postgres-native-tls
• SSH: russh 0.44
• Config: serde + toml
• Export: serde_json + manuel CSV + INSERT (db/query.rs::insert_statements)
• File Dialog: rfd 0.14 (native OS diyaloğu)
• SQL Highlighting: sıfırdan yazılmış tokenizer — src/ui/syntax.rs (syntect yok)
• i18n: sıfırdan yazılmış — src/i18n.rs (sıfır bağımlılık)

Mimari — Kritik Kural

UI thread (eframe) ↔ DB thread arası haberleşme SADECE mpsc kanalları ile:

• Sender<DbCommand> → UI'dan DB'ye komut
• Sender<DbEvent> → DB'den UI'a sonuç
• DB thread kendi current_thread tokio runtime'ını std::thread::spawn içinde oluşturur
• spawn_blocking ile sync recv, sonra async tokio-postgres

Bu pattern'i ASLA değiştirme. eframe main thread'i bloke eden hiçbir şey yapma.

Modül Yapısı

src/
├── main.rs           — eframe init, current_thread tokio runtime
├── app.rs            — PgClientApp, eframe::App impl, event loop
├── config.rs         — ConnectionProfile, AppConfig (TOML)
├── history.rs        — QueryHistory (kalıcı, max 500)
├── snippets.rs       — Saved queries (Ctrl+Shift+S, name+SQL, TOML-persisted)
├── i18n.rs           — Lang enum (En|Tr), I18n(pub Lang) newtype, ~100+ method
├── logger.rs         — crash log (panic hook)
├── secrets.rs        — OS keychain (DB/SSH şifreleri, AI API key) — `keyring` crate
├── dbeaver.rs        — DBeaver bağlantı import'u (data-sources.json + AES ile şifreli credentials-config.json)
├── update.rs         — GitHub releases güncelleme kontrolü (ayrı thread, mpsc, sadece sürüm karşılaştırır)
├── db/
│   ├── mod.rs
│   ├── connection.rs — DbCommand/DbEvent, db_worker, execute_query (simple_query)
│   ├── query.rs      — CellValue enum, QueryResult
│   ├── metadata.rs   — Schema/table/column/index/FK introspection
│   ├── dump.rs       — Şema dump'ı (.sql, yapı ± veri) — katalogdan üretilir, pg_dump gerekmez
│   └── ssh.rs        — SSH tunnel (russh)
└── ui/
    ├── mod.rs
    ├── sidebar.rs        — SidebarAction, schema tree, context menu
    ├── query_panel.rs    — SQL editör, BrowseState, sayfalama
    ├── result_table.rs   — egui_extras::TableBuilder, sort, inline edit
    ├── tab_manager.rs    — Tab lifecycle, yönlendirme, sağ-tık menüsü
    ├── connection_dialog.rs
    ├── dashboard.rs      — DB dashboard (tablo boyutları, bağlantılar, index)
    ├── explain.rs        — EXPLAIN ANALYZE ağaç görünümü
    ├── er_diagram.rs     — ER diyagramı
    ├── autocomplete.rs   — Tablo/sütun otomatik tamamlama
    ├── import_dialog.rs  — CSV import onay diyaloğu (kolon isimleri CSV header'ından)
    ├── dbeaver_dialog.rs — DBeaver import önizleme/seçim diyaloğu
    ├── home.rs           — Karşılama ekranı (bağlantı yokken): sayaç kartları, Quick Start, kısayollar, son sorgular
    ├── theme.rs          — Renk token'ları, card_frame/card_header/empty_state, ikon fontu kurulumu
    └── syntax.rs         — Sıfırdan SQL/JSON tokenizer (keyword/type/string/comment)