انتقل إلى المحتوى
شعار أوراباسي
aurabase

الاستعلام عن قاعدة البيانات الخاصة بك باستخدام JavaScript SDK

التدفقات اليومية لـ aura.db والقواعد التي ترفض المكالمات غير الآمنة وكيفية حماية الجدول بأمان على مستوى الصف.

دليل عملي9 د قراءةالمستوى وسيطةتمت المراجعة في 12‏/10‏/2026

تمت ترجمة هذه الصفحة تلقائيًا. النسخة الإنجليزية موثوقة.

قراءة الصفوف#

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') هو النموذج المستخدم في هذه الوثائق (وهو اختصار لـ aura.db.from('todos')، نفس المكالمة). تعود كل مكالمة { data, error } وأبدا يلقي، انظر خيارات العميل والأخطاء.

سلسلة الفلاتر: eq, neq, gt, gte, lt, lte, like, ilike, in, is, والمرشحات الأخرى المدرجة في مرجع قاعدة البيانات. بالنسبة لصفحة الصفوف، استخدم range(from, to).

إدراج وتحديث وحذف#

write.tstypescript
// قم بإدراج صف واحد، أو مجموعة من الصفوف، واستعادتها
const { data } = await aura.from('todos').insert({ title: 'Write the docs' }).select()

// منزعج
await aura.from('todos').upsert({ id, title: 'Renamed' }).select()

// التحديث والحذف يحتاج إلى مرشح
await aura.from('todos').update({ done: true }).eq('id', id)
await aura.from('todos').delete().eq('id', id)

لا تُرجع الكتابة شيئًا (data is null) إلا إذا قمت بالتسلسل .select(): إدراج 10000 صف لا يؤدي إلى إرسال 10000 صف مرة أخرى. مع .select() تعود الصفوف، وPATCH أو POST التي لا تتطابق مع أي صف توضح السبب في meta.hint.

قاعدتان تحميك من الأخطاء:

  • يحتاج إدراج الدُفعة إلى نفس المفاتيح في كل صف. الصفوف ذات المفاتيح المختلفة ترجع 400 مع All object keys must match. املأ المفاتيح المفقودة بـ null.
  • يتم رفض update() وdelete() بدون مرشح من قبل العميل برمز الخطأ UNFILTERED_MUTATION، قبل إرسال أي طلب. لتغيير كل صف عن قصد، قم بتشغيل SQL من الخادم.

صف واحد، عدة صفوف، مهم#

count.tstypescript
// صف واحد بالضبط: خطأ إذا لم يكن هناك أي صف أو عدة صف
const one = await aura.from('todos').select('*').eq('id', id).single()
// → error.status 406 عندما يتطابق الفلتر مع صفر أو عدة صفوف

// صفر أو صف واحد: تكون البيانات فارغة عندما لا يتطابق أي شيء
const maybe = await aura.from('todos').select('*').eq('id', id).maybeSingle()

// الصفوف ومجموعها
const page = await aura.from('todos').select('*', { count: 'exact' }).range(0, 9)
// page.count هو الإجمالي، مهما كان النطاق

// المجموع فقط، لا توجد صفوف
const { count } = await aura.from('todos').select('*', { count: 'exact', head: true })

count: 'exact' يحسب كل صف مطابق. 'planned' و'estimated' أسرع على الجداول الكبيرة جدًا وتقريبية.

حماية الطاولة#

يتم تمكين RLS افتراضيًا من خلال Aurabase، أضف سياسات لمنح الوصول

الجداول التي تم إنشاؤها من خلال Aurabase (db.sql() أو عمليات الترحيل أو الاستوديو أو واجهة برمجة تطبيقات الجدول) تحصل تلقائيًا على ENABLE وFORCE ROW LEVEL SECURITY (ما لم تقم بتضمين DISABLE ROW LEVEL SECURITY بشكل صريح في مجموعة DDL الخاصة بك). مع عدم وجود سياسات حتى الآن، يرى المتصلون anon وauthenticated []. تحتاج الجداول التي تم إنشاؤها عبر اتصال مباشر Postgres إلى enable row level security بشكل صريح. أضف السياسات التي تحتاجها:

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

أدوار قاعدة البيانات الأساسية هي aura_anon و aura_authenticated و aura_service_role (الأسماء المستعارة للمجموعة anon و authenticated و service_role يتم تعيينها أيضًا على المجموعات المُدارة). auth.uid() هو NULL للمفتاح العام ومعرف المستخدم للمستخدم الذي قام بتسجيل الدخول. راجع الأمان على مستوى الصف.

يتجاوز المفتاح service_role RLS حسب التصميم: احتفظ به على الخادم الخاص بك.

وظائف SQL وRPC#

أنشئ دالة من خادم، ثم اتصل بها من أي مكان باستخدام rpc():

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 مطلوب للاتصال به. بدونها، لا يمكن لأحد تنفيذ الوظيفة. يحصل الدور غير المدرج على 403 permission denied for function. يتم قبول كل من authenticated وaura_authenticated. ينطبق هذا أيضًا على الوظائف التي تنشئها باستخدام db.sql() أو الترحيل في المشاريع التي تم إنشاؤها بعد هذا التغيير (تم إبطال الامتياز الافتراضي EXECUTE لـ PUBLIC): أضف grant execute on function hello(text) to aura_authenticated; بنفسك.
  • يمكن استدعاء وظيفة جديدة بعد بضع ثوانٍ. حتى تقوم واجهة برمجة التطبيقات (API) بإعادة تحميل مخططها، تقوم rpc() بإرجاع 404 Could not find the function.
  • وظائف عبر SQL (db.sql()): CREATE FUNCTION / CREATE OR REPLACE FUNCTION مسموح بها في وضع SECURITY INVOKER (افتراضي)؛ تم رفض SECURITY DEFINER على /raw ويجب إنشاؤه من خلال createFunction (POST /v1/db/{project_id}/functions) أو CLI/الهجرة مع grant_execute_to صريح.

تشغيل SQL من الخادم#

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() يحتاج إلى مفتاح service_role. فهو يرفض DELETE بدون WHERE ولا يقرأ كتالوجات النظام مثل pg_class أو pg_roles. لسرد الجداول الخاصة بك، استخدم admin.db.schema().

ترقيم الصفحات وغطاء الصف والأرقام الدقيقة

  • تُرجع القراءة 1000 صف على الأكثر — الافتراضي والسقف الصلب، أيًا كان limit() أو range() الذي تطلبه. meta.has_more يصبح true عندما يتطابق المزيد من الصفوف؛ اطلب count: 'exact' لتحصل أيضًا على meta.total.
  • صفحة من خلال جدول كبير مع ترقيم الصفحات لمجموعة المفاتيح، والتي تكلف نفس التكلفة في الصفحة المليون: aura.from('events').select('id,label').limit(1000).after('id', lastId) (وهي .order('id').gt('id', lastId)). .cursor() هو MongoDB فقط؛ offset يصبح أبطأ كلما تعمقت.
  • أرقام تتجاوز 2^53 في JavaScript. يفقد bigint أعلى من 9,007,199,254,740,991 أرقامه الأخيرة عند تحليله كرقم JS: قم بإنشاء العميل باستخدام { parseBigIntAsString: true } لتلقي هذه القيم كسلاسل. يتم إرجاع numeric كرقم JSON عندما يكون قابلاً للتمثيل تمامًا، وكسلسلة عشرية دقيقة بخلاف ذلك (القيم الطويلة مثل 12345678901234567890.123456789).
  • count: 'planned' و'estimated' مجرد تقديرات. تأتي من إحصائيات PostgreSQL، وهي فارغة في جدول تم تحميله للتو (يمكن لجدول مكون من 60 صفًا الإبلاغ عن 430). استخدم count: 'exact' عندما يكون الرقم مهمًا.
  • يعود عمود vector كسلسلة مثل "[0.1,0.2,0.3]": قم بتحليله باستخدام JSON.parse للحصول على number[].
  • عرض يقرأ بامتيازاتك. تحصل العروض التي تقوم بإنشائها (SQL، الترحيل) على security_invoker = true، وبالتالي تنطبق سياسات الجداول الأساسية على القارئ. اكتب with (security_invoker = false) بشكل صريح فقط إذا كنت تريد حقًا أن يتجاوز العرض RLS.
  • db.sql() يعيد محاولة 429 بعد التأخير Retry-After (لم يتم تشغيل الطلب المرفوض مطلقًا). /raw محدود لكل مشروع؛ بالنسبة للأحمال المجمعة، استخدم insert() المكتوب مع مصفوفة.