İçeriğe geç
Aurabase Logosu
aura tabanı

Veritabanınızı JavaScript SDK'sıyla sorgulayın

aura.db günlük akışları, güvenli olmayan çağrıları reddeden kurallar ve bir tablonun satır düzeyinde güvenlikle nasıl korunacağı.

Nasıl yapılır kılavuzu9 dk. okuSeviye orta düzey12 Eki 2026 tarihinde revize edildi

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

Satırları oku#

read.tstypescript
const { data, error } = await aura
  .from('todos')
  .select('id, title, done')
  .eq('done', false)
  .order('created_at', { ascending: false })
  .limit(20)

aura.from('todos') bu belge boyunca kullanılan formdur (aynı çağrı olan aura.db.from('todos') için bir kısayoldur). Her çağrı { data, error } değerini döndürür ve hiçbir zaman fırlatmaz; bkz. istemci seçenekleri ve hataları.

Filtre zinciri: eq, neq, gt, gte, lt, lte, like, ilike, in, is ve listede listelenen diğerleri veritabanı referansı. Satırlardan oluşan bir sayfa için range(from, to) kullanın.

Ekle, güncelle ve sil#

write.tstypescript
// Bir satır veya bir dizi satır ekleyin ve bunları geri alın
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// Yukarı
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// Güncelleme ve silme filtreye ihtiyaç duyar
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

.select() zincirleme yapmadığınız sürece yazma hiçbir şey döndürmez (data null'dir): 10.000 satır eklemek 10.000 satırı geri göndermez. .select() ile satırlar geri gelir ve hiçbir satırla eşleşmeyen PATCH veya POST, nedenini meta.hint içinde belirtir.

İki kural sizi hatalardan korur:

  • Bir toplu eklemenin her satırda aynı anahtarlara ihtiyacı vardır. Farklı anahtarlara sahip satırlar, All object keys must match ile 400 değerini döndürür. Eksik anahtarları null ile doldurun.
  • Filtresiz update() ve delete(), herhangi bir istek gönderilmeden önce istemcisi tarafından UNFILTERED_MUTATION hata koduyla reddedilir. Her satırı bilerek değiştirmek için SQL'i bir sunucudan çalıştırın.

Bir satır, birçok satır, önemli#

count.tstypescript
// Tam olarak bir satır: hiç veya birkaç tane varsa hata
const one = await aura.from('todos').select('*').eq('id', id).single()
// → filtre sıfır veya birkaç satırla eşleştiğinde error.status 406

// Sıfır veya bir satır: hiçbir şey eşleşmediğinde veriler boştur
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// Satırlar ve toplamları
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count aralık ne olursa olsun toplamdır

// Yalnızca toplam, satır yok
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' eşleşen her satırı sayar. 'planned' ve 'estimated' çok büyük tablolarda daha hızlıdır ve yaklaşıktır.

Bir masayı koruyun#

RLS varsayılan olarak Aurabase aracılığıyla etkindir, erişim izni vermek için politikalar ekleyin

Aurabase (db.sql(), geçişler, Studio veya tablo API'si) aracılığıyla oluşturulan tablolar otomatik olarak ENABLE ve FORCE ROW LEVEL SECURITY alır (DISABLE ROW LEVEL SECURITY'yi DDL grubunuza açıkça dahil etmediğiniz sürece). Henüz politika yokken, anon ve authenticated arayanlar [] öğesini görür. Doğrudan Postgres bağlantısıyla oluşturulan tabloların açıkça enable row level security olması gerekir. İhtiyacınız olan politikaları ekleyin:

SQLsql
create policy todos_own_read on todos
  for select to aura_authenticated
  using (auth.uid() = owner);

Kurallı veritabanı rolleri aura_anon, aura_authenticated ve aura_service_role'dir (grup takma adları anon, authenticated, service_role ayrıca yönetilen kümelerde bunlarla eşleşir). auth.uid(), ortak anahtar için NULL ve oturum açmış bir kullanıcının kullanıcı kimliğidir. Satır Düzeyi Güvenliği konusuna bakın.

Bir service_role anahtarı, tasarım gereği RLS anahtarını atlar: onu sunucunuzda tutun.

SQL işlevleri ve rpc#

Bir sunucudan bir işlev oluşturun, ardından onu herhangi bir yerden rpc() ile çağırın:

server/setup.tstypescript
await admin.db.createFunction({
  name: 'add',
  args: [
    { name: 'a', data_type: 'int', mode: 'IN' },
    { name: 'b', data_type: 'int', mode: 'IN' },
  ],
  returns: 'int',
  language: 'sql',
  body: 'SELECT a + b',
  grant_execute_to: ['anon', 'authenticated'],
})
client.tstypescript
const { data } = await aura.rpc('add', { a: 1, b: 2 }) // → 3
  • grant_execute_to onu çağırmak için gereklidir. Bu olmadan hiç kimse işlevi yürütemez. Listelenmeyen bir rol 403 permission denied for function alır. Hem authenticated hem de aura_authenticated kabul edilir. Bu aynı zamanda db.sql() ile oluşturduğunuz işlevler veya bu değişiklikten sonra oluşturulan projelerdeki geçiş için de geçerlidir (PUBLIC'nin varsayılan EXECUTE ayrıcalığı iptal edilmiştir): grant execute on function hello(text) to aura_authenticated;'yi kendiniz ekleyin.
  • Yeni bir işlev birkaç saniye sonra çağrılabilir. API şemasını yeniden yükleyene kadar rpc(), 404 Could not find the function değerini döndürür.
  • SQL aracılığıyla işlevler (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION'ye SECURITY INVOKER modunda izin verilir (varsayılan); SECURITY DEFINER, /raw üzerinde reddedilir ve createFunction (POST /v1/db/{project_id}/functions) veya açık grant_execute_to içeren CLI/geçişler yoluyla oluşturulmalıdır.

SQL'i bir sunucudan çalıştırın#

server/migrate.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

await admin.db.sql(`
  create table if not exists todos (
    id uuid primary key default gen_random_uuid(),
    title text not null,
    done boolean not null default false,
    owner uuid,
    created_at timestamptz not null default now()
  )
`)

db.sql() bir service_role anahtarına ihtiyaç duyar. DELETE olmadan WHERE öğesini reddeder ve pg_class veya pg_roles gibi sistem kataloglarını okumaz. Tablolarınızı listelemek için admin.db.schema() kullanın.

Sayfalandırma, satır sınırı ve tam sayılar

  • Bir okuma en fazla 1.000 satır döndürür — istediğiniz limit() veya range() ne olursa olsun, varsayılan ve sabit tavan. Daha fazla satır eşleştiğinde meta.has_more true olur; count: 'exact' öğesinin ayrıca meta.total almasını isteyin.
  • Anahtar seti sayfalandırması olan büyük bir tablo boyunca sayfa, bu da milyonuncu sayfada aynı maliyete sahiptir: aura.from('events').select('id,label').limit(1000).after('id', lastId) (bu .order('id').gt('id', lastId)). .cursor() yalnızca MongoDB'dir; offset derine indikçe yavaşlar.
  • JavaScript'in 2^53'ünün ötesindeki sayılar. 9,007,199,254,740,991'in üzerindeki bir bigint, JS numarası olarak ayrıştırıldığında son rakamlarını kaybeder: bu değerleri dize olarak almak için { parseBigIntAsString: true } ile istemci oluşturun. Bir numeric tam olarak temsil edilebilir olduğunda bir JSON numarası olarak, aksi halde tam bir ondalık dize olarak döndürülür (12345678901234567890.123456789 gibi uzun değerler).
  • count: 'planned' ve 'estimated' yalnızca tahmindir. Bunlar, yeni yüklenen bir tabloda boş olan PostgreSQL istatistiklerinden gelir (60 satırlık bir tablo 430'u rapor edebilir). Sayı önemli olduğunda count: 'exact' kullanın.
  • Bir vector sütunu, "[0.1,0.2,0.3]" gibi bir dizesi olarak geri gelir: number[] elde etmek için onu JSON.parse ile ayrıştırın.
  • Bir görünüm ayrıcalıklarınızla okunur. Oluşturduğunuz görünümler (SQL, geçiş) security_invoker = true değerini alır, böylece temel tabloların politikaları okuyucuya uygulanır. with (security_invoker = false) yalnızca görünümün gerçekten RLS atlanmasını istiyorsanız açıkça yazın.
  • db.sql(), Retry-After gecikmesinden sonra 429'yi yeniden dener (reddedilen istek hiçbir zaman çalıştırılmaz). /raw proje başına sınırlıdır; toplu yüklemeler için yazılan insert() dizisini kullanın.