YENİPublication of @aurabase/aurabase-js v0.7.5 NPM Packages & Rust Crate v0.1.2Değişiklik günlüğüne bakın →

Mühendislik · 10 dk. okuma

pg_graphql ile Hasura ve PostGraphile, Postgres üzerinde

Affane Daylami · Fondateur · 31 Temmuz 2026

Bloga geri dön

Postgres üzerindeki bir GraphQL API'si, araca bağlı olarak çok farklı anlamlara gelir. PostGraphile ayrı bir Düğüm sunucusu dağıtır. Hasura veritabanınızın önüne bir GraphQL motoru dağıtır. pg_graphql Postgres içinde çalışır — bu, Aurabase tarafından benimsenen yaklaşımdır. Bu bir uygulama ayrıntısı değildir: barındırmanız, güvenliğini sağlamanız ve sürdürmeniz gerekenleri değiştirir.

Bu sayfa otomatik olarak çevrildi. İngilizce versiyonu yetkilidir.

pg_graphql, Supabase tarafından sağlanan açık kaynaklı bir Postgres uzantısıdır — bir Aurabase buluşu değildir. Oluşturduğumuz şey, platformun yerel ve isteğe bağlı entegrasyonudur: tedarik edilecek bir hizmet değil, proje başına kontrol edilecek bir kutu. Bu gönderi, gerçek mimarinin ayrıntılarını verir, nasıl etkinleştirileceğini gösterir ve ödünleşimleri Hasura ve PostGraphile v5 ile dürüstçe karşılaştırır.

Temeller
  • pg_graphql, Postgres içinde bir SQL uzantısı olarak çalışır; Hasura ve PostGraphile'den farklı olarak dağıtılacak ayrı bir GraphQL sunucusu yoktur.
  • Aurabase tarafından sağlanan sarmalayıcı işlevi SECURITY INVOKER'dir: RLS politikalarınız, paralel olarak sürdürülecek ikinci bir izin sistemi olmadan otomatik olarak uygulanır.
  • Yalnızca proje başına etkinleştirme etkinleştirme — aura projects graphql-enable veya Studio — hiçbir projede varsayılan olarak etkinleştirilmez.
  • Hasura, Haziran 2025'te GraphQL motorunu terk etmeden resmi olarak PromptQL ve AI aracılarına odaklandı.
  • PostGraphile v5, 24 Mart 2026'da genel kullanıma sunuldu; hareketsiz bir proje değil, doğrudan ve aktif bir rakip.
#
Genel Bakış

pg_graphql, tek cümleyle

pg_graphql SQL şemanızı inceler ve Geçiş kurallarına uygun bir GraphQL şeması oluşturur — <table>Collection, edges, node, sütun türüne göre filtreler, imlece göre sayfalandırma. Elle yazılacak veya bakımı yapılacak bir SDL yok: GraphQL şeması Postgres şemanızı takip eder.

Mimari açısından önemli olan nokta şu; bu şema üreteci veritabanının içinde bir SQL fonksiyonu olarak yaşıyor, yanında bir HTTP prosesi olarak değil. Aurabase, uzantının 1.6.1 sürümünü (7 Mayıs 2026'da yayımlandı) Postgres görüntüsüne — Supabase tarafından dağıtılan resmi .deb paketine sabitler . Hem paylaşılan kümeye hem de ayrılmış Postgres örneklerine yüklenir.

pg_graphql'nin uzun süredir yerel olarak etkinleştirildiği Supabase'den geliyorsanız, mantık size tanıdık gelecektir. Ayrıntılı karşılaştırmamız ve geçiş kılavuzumuz, aynı kalan RLS şemasının ve ilkelerinin geri kalanını kapsar.

#
Bağlam 2026

Hasura ve PostGraphile'de neler değişti?

“Postgres üzerinde anlık GraphQL”in iki tarihi rakibinden hiçbiri ortadan kaybolmadı. Konumları değişti ve güncellenmiş bir makale, iki yıl önceki duruma atıfta bulunmak yerine bunu yansıtmalıdır.

Hasura Haziran 2025'te, kurucu ortağı Tanmai Gopal tarafından imzalanan "GraphQL'den PromptQL'ye: Yeni Bir Bölüm Başlıyor" açık başlığıyla bir gönderi yayınladı. Mesaj: Şirket, yol haritasını AI aracıları için tasarlanmış bir veri erişim katmanı olan PromptQL üzerine yeniden odaklıyor. GraphQL motoru kaldırılmadı - Hasura ana sayfası onu hala "savaşta test edilmiş" olarak gösteriyor - ancak artık öncelikli mesaj değil.

PostGraphile kendi adına tam tersini yaptı. 2023'ten beri beta olarak geliştirilmekte olan 5. sürümü, Grafast adı verilen yeni bir sorgu planlama motoruyla 24 Mart 2026'da genel kullanıma sunuldu. Bu, enerjisi tükenen bir proje değil: son sürüm olan 5.1.4, 5 Ağustos 2026 tarihlidir. npm paketi yalnızca 16 - 22 Ağustos 2026 haftasında 119.230 indirme saydı (npm kaydı, 23 Ağustos 2026'ya danışıldı).

Astuce

Pratik sonuç: gerçek boş alan "Postgres üzerinde GraphQL değil, kimse ona dokunmuyor" - tek komutla etkinleştirilen ve barındırılacak hizmet olmadan özel GraphQL sıfır yapılandırma yuvasıdır. Hasura stratejik tercihle bundan uzaklaşıyor; PostGraphile hiçbir zaman onu hedeflemedi, modeli “Kendinizi entegre etmek için Node.js kütüphanesi” olarak kaldı.

#
Mimarlık

Her çözümün gerçekte nereye döndüğü

Diğer her şeyi (işletme maliyeti, saldırı yüzeyi, gecikme) yapılandıran fark, GraphQL motorunun çalıştığı yerdir.

Nereye dönüyorSQL uzantısı, Postgres içindePostgres önünde ayrı GraphQL sunucusu (Go)Node.js kitaplığı/sunucusu, Postgres öncesinde
Dağıtım gerekliYok - bir proje bayrağıyla etkinleştirildiEvet — Hasura motorunu barındırın ve ölçeklendirinEvet — Düğüm sürecini barındırın veya sunucunuzla entegre edin
İzin modeliEski Postgres RLS (GÜVENLİK ÇAĞIRICI)Hasura'nin rol/tablo başına kendi izin sistemiRLS Postgres pgSettings aracılığıyla — yerel delegasyon da
Varsayılan olarak iç gözlemDevre dışıMotor konfigürasyonuna bağlı olarakSunucu yapılandırmasına bağlı olarak
Konumlandırma 2026Postgres BaaS'nin yerel seçeneğiHaziran 2025'ten bu yana PromptQL/IA'ya yeniden odaklanıldıGA v5 Mart 2026'dan beri aktif proje
AURABAZHAŞURAPOSTGRAFİK V5

Dürüst olmak gerekirse: PostGraphile ayrıca pgSettings ve rol değiştirme yoluyla Postgres'ye yetkilendirme yetkisi verir - yerel RLS, pg_graphql'ye özel değildir. Farklı olan şey, bu köprüyü kimin barındırdığı ve yapılandırdığıdır: PostGraphile adresinde sizsiniz; Aurabase adresinde bu zaten yapılmıştır.

#
Kaputun altında

Aurabase bir projede pg_graphql'yi nasıl etkinleştirir?

Etkinleştirme, proje başına isteğe bağlıdır ve Postgres motor projeleri için ayrılmıştır - bir MongoDB projesi, isteği reddeder (GRAPHQL_UNSUPPORTED_ENGINE), pg_graphql, diğer motorda eşdeğeri olmayan bir Postgres uzantısıdır.

CLI aracılığıyla veya doğrudan yönetim planını çağırarak:

terminalbash
# Idempotent: Halihazırda etkinleştirilmiş bir projeyi geri çağırmak hiçbir şeyi yeniden yaratmaz
aura projects graphql-enable <project_id>

# HTTP eşdeğeri (yönetim düzlemi, JWT konsolu)
curl -X POST "$AURA_CONTROL_URL/v1/control/projects/$PROJECT_ID/graphql/enable" \
  -H "Authorization: Bearer $CONSOLE_JWT"

Sunucu tarafında çağrı, provizörün tek bir işlemde yürüttüğü bir graphql_enable işini yürütür: uzantının yüklenmesi, şemanızda graphql() işlevinin oluşturulması, uygulama rollerine GRANT'lar. Bir adım başarısız olursa her şey iptal edilir; sarmalayıcı asla yarıya kadar kurulmaz ve graphql_enabled yalnızca tam başarıdan sonra true'ye geçer.

Hem paylaşılan Postgres kümesinde hem de proje başına özel bir CNPG örneğinde çalışır; iki farklı Postgres görüntüsü, ancak aynı uzantı mekanizması. Tahsis edilmiş örneklerde, uzantı doğrudan SQL yerine CNPG operatörünün bildirim temelli bildirimi aracılığıyla yüklenir; bu yakın zamanda yapılan bir düzeltmedir. Özel bir küme, uygulama süper kullanıcı erişimi olmadan çalışır ve pg_graphql, CREATE EXTENSION için tam olarak bu ayrıcalığa ihtiyaç duyar.

Studio'da aynı akış Tablo Yapılandırması sekmesinden geçer. Buradaki bir düğme, uzantıyı proje düzeyinde etkinleştirir - yukarıdakiyle aynı HTTP çağrısı, yakınsamaya kadar yoklama ile. Daha sonra ikinci bir kontrol, editörden ayrılmadan totalCount ve GraphQL koleksiyonundaki toplama alanlarını etkinleştirmek veya devre dışı bırakmak için tablo başına bir @graphql yönergesi ayarlar.

Tek komut görünümü: etkinleştirme → iş parçacıklı provizyon (idempotent, zaten uçuştaysa işlem yok) → DDL işlemi (uzantı, sarmalayıcı işlevi, GRANT'lar) → graphql_enabled işaretini yalnızca tam başarıdan sonra ayarlayın → istekler /rpc/graphql aracılığıyla mümkündür.

#
Güvenlik

Eski RLS, bakımı yapılacak ikinci bir sistem değil

Aurabase tarafından ayarlanan işlev SECURITY INVOKER'dir - Postgres'nin varsayılan davranışı, gelecekteki bir yeniden düzenleyicinin onu kazara değiştirmemesi için açıklanmıştır. Gerçek arayanın ayrıcalıklarıyla çalışır (aura_anon, aura_authenticated veya aura_service_role, JWT talebine bağlı olarak), dolayısıyla RLS politikalarınız tam olarak REST isteğinde olduğu gibi uygulanır.

Neden GÜVENLİK TANIMLAYICI olmasın

Bir SECURITY DEFINER işlevi, dahili olarak kontrol edilen RLS işlevinin tamamını atlar: uygulama rolünü değiştirmeden süper kullanıcı bağlantısı altında graphql.resolve çağrılması, RLS olsun veya olmasın tüm sahiplerin satırlarını döndürür. Bu seçimin önlediği kiracılar arası risk tam olarak budur.

Hasura'de mimari yapı itibariyle farklıdır: motor her GraphQL sorgusunu Hasura'ye özgü izin kurallarıyla sınırlandırılmış bir SQL sorgusuna dönüştürür. Bu kurallar, kendi katmanındaki rol ve tablo başına tanımlanır; Postgres RLS'ye paralel bir sistemdir, ona bir delegasyon değildir. Erişim kurallarını denetlemek için tek bir yer yerine iki yer.

İçgözlem ({ __schema { ... } }), her Aurabase projesinde varsayılan olarak devre dışı kalır; bu, platformun geri kalanıyla tutarlı bir duruştur. Apollo Studio veya graphql-codegen gibi bir aracın ihtiyacı varsa COMMENT ON SCHEMA aracılığıyla şema ile etkinleştirilebilir.

#
öğretici

Etkinleştirin ve GraphQL API'nizi sorgulayın

graphql_enabled ile true arası bir kez olduğunda, ağ geçidinde özel bir /graphql rotası görünmez. İstek, SDK'dan çağrılan herhangi bir Postgres işlevi gibi, genel RPC proxy'si üzerinden gider.

query.shbash
curl -X POST "$NEXT_PUBLIC_AURABASE_URL/v1/db/$PROJECT_ID/rpc/graphql" \
  -H "apikey: $NEXT_PUBLIC_AURABASE_ANON_KEY" -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { postsCollection(first: 10, filter: { published: { eq: true } }) { edges { node { id title created_at } } } }"}'

Yanıt, ek Aurabase sarmalama olmadan GraphQL spesifikasyonunu ({ data, errors }) takip eder: ağ geçidi, hedeflenen RPC'nin graphql olduğunu algılar ve sıradan bir RPC'nin aksine onu yeniden sarmaz. Standart bir GraphQL istemcisi (Apollo, urql, graphql-request) çıktıyı olduğu gibi tüketir.

Diyagramdaki bir @graphql yönergesi aracılığıyla etkinleştirme sonrasında varsayılan olarak iki ayar ayarlanır: max_rows: 1000 ve inflect_names: true. pg_graphql varsayılan olarak koleksiyon başına 10.000 satırla sınırlanır — first: olmadan büyük bir tablo belleği doyurabilir. inflect_names, SQL tablolarının ham yılan_durumu yerine okunabilir tür adlarını verir.

#
Sınırlar

pg_graphql ne yapmaz (henüz)

Bu blogun ruhuna uygun olarak, saklanmak yerine belgelenmek.

  • Yerel GraphQL aboneliği yok. pg_graphql gerçek zamanlı değil, sorguları ve mutasyonları kapsar subscriptions — bu, Aurabase ihmali değil, uzantının kendisinin bir sınırlamasıdır. Gerçek zamanlı Aurabase mevcuttur, ancak GraphQL abonelik köprüsü değil, ayrı bir kanal (postgres_changes) aracılığıyla.
  • Hasura ile bildirime dayalı eylem yok. "GraphQL mutasyonuna bağlı iş web kancası" modelinin doğrudan bir eşdeğeri yoktur - Aurabase üzerinde bu mantık, özel bir GraphQL yapılandırması aracılığıyla değil, bir Postgres işlevi veya bir Edge İşlevi aracılığıyla gider.
  • Postgres motoru için ayrılmıştır. Bir MongoDB projesi bunu etkinleştiremez; herhangi bir geçici çözüm amaçlanmamıştır.
Bilgi

Etkinleştirme neden varsayılan yerine isteğe bağlı olarak kalıyor: Kiracı veritabanının GRANT/Roller alanında belgelenmiş bir gerileme geçmişi vardır. Bu, daha geniş bir kusuru değerlendirmeden önce, proje proje açık doğrulama olmadan hiçbir işlevin ona dokunmadığını haklı çıkarmak için yeterlidir.

#
Karar

Aurabase, Hasura veya PostGraphile: bağlamınıza bağlı olarak

Her üç seçenek de meşrudur; doğru seçim, halihazırda sahip olduğunuz şeye ve neyden kaçınmak istediğinize bağlıdır.

  • pg_graphql Aurabase üzerinde — RLS veritabanınız ve politikalarınız zaten Aurabase üzerinde yayınlanıyorsa ve izlenecek ek hizmetler olmadan onu sorgulamanın ikinci bir yolunu istiyorsanız.
  • Hasura — birden fazla veri kaynağını (yalnızca Postgres değil) tek bir GraphQL şeması arkasında birleştirirseniz veya PromptQL ve AI aracısı yaklaşımı yol haritanıza uyuyorsa.
  • PostGraphile v5 — eklenti sistemi aracılığıyla oluşturulan şema üzerinde hassas kontrol istiyorsanız ve onu entegre edebileceğiniz bir Node.js sunucusunu zaten çalıştırıyorsanız.

Tam sorgu söz dizimi için — sütun türüne göre filtreler, orderBysıralama, imlece göre sayfalandırma, insertInto<Table>Collection mutasyonlar — resmi pg_graphqlbelgelerine bakın. Aşağıdaki Aurabase GraphQL belgeleri de tüm döngünün ayrıntılarını vermektedir.

DAĞITILMAYA HAZIR MISINIZ?

Beş dakika içinde arka ucunuz.

Kredi kartı gerekmez · 500 MB ücretsiz · 50.000 MAU