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

بداية سريعة

من الصفر إلى واجهة برمجة التطبيقات القابلة للاستعلام: قاعدة بيانات Postgres مخصصة، وأمان على مستوى الصف، وفي الوقت الفعلي وإنشاء النوع TypeScript - لا يلزم وجود بطاقة ائتمان.

درس تعليمي5 د قراءةالمستوى مبتدئتمت المراجعة في 21‏/10‏/2026

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

موجّه لوكيل البرمجة الخاص بك

Set up Aurabase in this app by following this page: https://aurabase.cloud/en/docs/getting-started.md

Documentation: read https://aurabase.cloud/llms.txt first. Every docs page is also available as Markdown: add .md to its URL, for example (the same works for every page): https://aurabase.cloud/en/docs/getting-started.md

Client: install @aurabase/aurabase-js and create the client with createClient(NEXT_PUBLIC_AURABASE_URL, NEXT_PUBLIC_AURABASE_ANON_KEY). Keep AURABASE_SERVICE_ROLE_KEY on the server: never put it in client code.

Project access: to read the schema and run SQL, start the Aurabase MCP server over stdio (82 tools with a project key):
npx -y -p @aurabase/mcp-server aurabase-mcp --url https://<slug>.aurabase.cloud --project-id <project-id> --service-role-key aura_sk_…
The project id is in Studio › Settings › General. The service role key is shown once when the project is created; regenerate it in Studio › Settings › Connection if you lost it.

بداية سريعة#

قم بتثبيت SDK، وقم بإنشاء العميل وقراءة الصفوف الأولى.

1. قم بتثبيت SDK#

أضف SDK إلى مشروعك. تقوم علامة التبويب Rust بتثبيت الصندوق aurabase؛ تتحقق علامة التبويب cURL من استجابة عنوان URL لمشروعك.

bash
pnpm add @aurabase/aurabase-js

2. إنشاء العميل#

أنشئ العميل باستخدام عنوان URL لمشروعك ومفتاح التشغيل، وكلاهما في الاستوديو > الإعدادات > الاتصال. احتفظ بمفتاح دور الخدمة على الخادم.

typescript
import { createClient } from '@aurabase/aurabase-js'

const aura = createClient(
  process.env.NEXT_PUBLIC_AURABASE_URL!,
  process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)

3. الاستعلام عن قاعدة البيانات#

اقرأ ما يصل إلى 10 صفوف من todos. يتم إنشاء الجدول في قسم "إنشاء جدول" أدناه؛ حتى يتم العثور عليه، يتم تعيين error.

typescript
// تم إنشاء "المهام" في "إنشاء جدول" أدناه
const { data, error } = await aura
  .from('todos')
  .select('id, title, done')
  .limit(10)

console.log(data, error)

المتطلبات الأساسية#

نحن نفترض أنه تم تثبيت Node.js ≥ 20 وأن محطة POSIX موجودة ضمن النطاق. ليست هناك حاجة إلى قاعدة بيانات محلية: Aurabase توفر قاعدة بيانات Postgres مخصصة لكل مشروع.

معلومات

هل أنت قادم من Supabase أو Firebase؟ معظم المفاهيم قابلة للنقل. انظر دليل الهجرة.

تثبيت SDK#

يكشف SDK الرسمي عن عميل مكتوب لـ CRUD والمصادقة والوقت الفعلي والتخزين. إنه يعمل بنفس الطريقة في Next.js أو React أو Node أو Bun أو Deno.

terminalbash
# موصى به
pnpm add @aurabase/aurabase-js

يتضمن اسم الحزمة النطاق @aurabase/. الحزمة aurabase-js بدون نطاق لا تتم صيانتها بواسطة Aurabase: لا تقم بتثبيتها.

نصيحة

تتضمن SDK مباشرةً تصدير @aurabase/aurabase-js/ssr (createServerClient) لـ Next.js (جهاز توجيه التطبيقات، وإجراءات الخادم، والبرامج الوسيطة)، وRemix، وNuxt، وSvelteKit مع إدارة ملفات تعريف الارتباط للجلسة تلقائيًا وتقطيع مضاد للاقتطاع.

إنشاء مشروع#

إنشاء مشروع من الاستوديو. عندما يصبح نشطًا، يعرض الاستوديو لوحة انسخ مفاتيحك الآن مع لوحة .env.local جاهزة للاستخدام (انسخها أو قم بتنزيلها): يظهر مفتاح service_role هناك مرة واحدة، ويتم الاحتفاظ فقط بالتجزئة الخاصة به بعد ذلك. الإعدادات › الاتصال يُظهر لاحقًا عنوان URL للمشروع ومفتاح Anon العام؛ إذا فقدت المفتاح service_role، فأعد إنشائه هناك (تم إبطال المفتاح السابق). يمكن نشر NEXT_PUBLIC_AURABASE_URL وNEXT_PUBLIC_AURABASE_ANON_KEY على جانب العميل؛ AURABASE_SERVICE_ROLE_KEY يبقى بشكل صارم على جانب الخادم.

.env.localbash
NEXT_PUBLIC_AURABASE_URL=https://<slug>.aurabase.cloud
NEXT_PUBLIC_AURABASE_ANON_KEY=aura_anon_…
AURABASE_SERVICE_ROLE_KEY=aura_sk_…
المخططالوصوليحتوي على
project_{uuid}أنتجداول التطبيقات الخاصة بك
project_{uuid}_authالنظامusers, sessions, oauth_accounts, mfa
project_{uuid}_storageالنظامbuckets, objects, rls_policies
project_{uuid}_platformالنظامfunctions, jobs, cron_jobs, api_keys
تفضل المحطة؟

يعمل المسار بالكامل أيضًا من واجهة سطر الأوامر (راجع CLI للتثبيت): aura projects create ينتظر حتى يصبح المشروع جاهزًا ويطبع عنوان URL والمفاتيح مرة واحدة.

terminalbash
aura login
aura projects create todos-app --json > project.json    # ينتظر حتى يصبح المشروع نشطا
aura link --project-id "$(jq -r .id project.json)"
export NEXT_PUBLIC_AURABASE_URL="$(jq -r .url project.json)"
export AURABASE_SERVICE_ROLE_KEY="$(jq -r .service_role_key project.json)"
aura db raw "create table todos (id bigint generated always as identity primary key, title text not null, done boolean not null default false, user_id uuid not null default auth.uid(), created_at timestamptz not null default now())"
aura db raw "create policy todos_own_read on todos for select to aura_authenticated using (auth.uid() = user_id)"
aura db raw "create policy todos_own_insert on todos for insert to aura_authenticated with check (auth.uid() = user_id)"
aura db table realtime todos on
aura db raw "select count(*) from todos" --as authenticated --user <a user id>   # انظر ما يراه هذا المستخدم
مفتاح دور الخدمة

لا تقم مطلقًا بتضمين AURABASE_SERVICE_ROLE_KEY في حزمة العميل. يتجاوز جميع سياسات RLS، وترفضه واجهة برمجة التطبيقات (API) من المتصفح (401 SECRET_KEY_IN_BROWSER). قم بحجزه لاستدعاءات الخادم (معالجات المسار وإجراءات الخادم والوظائف).

إنشاء جدول#

يفتح قاعدة البيانات في الاستوديو، انقر فوق محرر SQL (الرابط الموجود أسفل لوحة الجداول) وقم بتشغيل هذا البرنامج النصي. يتم تمكين الأمان على مستوى الصف في كل جدول: تسمح السياستان الأوليتان لكل مستخدم قام بتسجيل الدخول بقراءة وإنشاء الصفوف الخاصة به، أما السياسة الثالثة فهي عبارة عن مثال يتيح للزائرين قراءة الجدول حتى تتمكن من رؤية الصفوف الأولى دون تسجيل الدخول. تستهدف السياسات aura_authenticated دور (aura_anon للزوار).

todos.sqlsql
create table todos (
  id bigint generated always as identity primary key,
  title text not null,
  done boolean not null default false,
  user_id uuid not null default auth.uid(),
  created_at timestamptz not null default now()
);
create policy "todos_own_read" on todos for select to aura_authenticated using (auth.uid() = user_id);
create policy "todos_own_insert" on todos for insert to aura_authenticated with check (auth.uid() = user_id);
-- مثال فقط: يمكن لأي زائر قراءة كل ما يجب عمله. أسقطه قبل الإنتاج:
--   إسقاط السياسة "todos_public_read" على جميع المهام؛
create policy "todos_public_read" on todos for select to aura_anon using (true);

ثم قم بإنشاء أنواع TypeScript لمخططك (يقرأ الأمر .env.local):

terminalbash
npx @aurabase/gen --out lib/aurabase.types.ts

المكالمة الأولى#

قم بإنشاء عميل Aurabase قابل لإعادة الاستخدام من خلال قراءة المفاتيح من متغيرات البيئة، ثم الاستعلام عن الجدول الأول الخاص بك. المسارات أدناه مرتبطة بجذر تطبيقك: إذا كان مشروعك يستخدم دليل src/، فضع lib/ و components/ و app/ بداخله، بحيث يتم حل الاسم المستعار للاستيراد @/.

lib/aurabase.tstypescript
import { createClient } from '@aurabase/aurabase-js'
import type { Database } from './aurabase.types'

export const aura = createClient<Database>(
  process.env.NEXT_PUBLIC_AURABASE_URL!,
  process.env.NEXT_PUBLIC_AURABASE_ANON_KEY!,
)

ثم، في معالج المسار أو مكون الخادم:

app/api/todos/route.tstypescript
import { aura } from '@/lib/aurabase'

export async function GET() {
  const { data, error } = await aura
    .from('todos')
    .select('id, title, done')
    .order('created_at', { ascending: false })
    .limit(10)

  if (error) throw error
  return Response.json(data)
}
نصيحة

يؤدي ذلك إلى إرجاع صفوف الجدول، بما في ذلك صفوف الجدول التي لم يتم تسجيل دخولها، وذلك بفضل سياسة المثال todos_public_read. بدونها (بمجرد إسقاطها، كما ينبغي قبل الإنتاج) يحصل الزائر على []: السياسات الأخرى تفتح الصفوف فقط إلى aura_authenticated، لذا قم بتسجيل دخول المستخدم أولاً باستخدام aura.auth.signInWithPassword({ email, password }) (راجع صفحات تسجيل الدخول الجاهزة لـ Next.js). قم بإعادة إنشاء أنواع Database باستخدام npx @aurabase/gen بعد كل تغيير في المخطط.

لإدراج صف أول، قم بتسجيل دخول المستخدم لأعلى ثم قم بإدراجه. العمود user_id الافتراضي هو auth.uid():

scripts/first-row.tstypescript
import { aura } from '../lib/aurabase'

async function main() {
  const email = 'you@example.com'
  const password = 'a-strong-password'

  await aura.auth.signUp({ email, password })
  await aura.auth.signInWithPassword({ email, password })

  const { data, error } = await aura.from('todos').insert({ title: 'First todo' }).select()
  console.log(data, error)
}

main().catch((err) => {
  console.error(err)
  process.exit(1)
})

قم بتشغيله باستخدام tsx، الذي يحل مشكلة الاستيراد بدون امتداد ويقرأ .env.local:

terminalbash
pnpm add -D tsx
pnpm approve-builds   # pnpm 10+: اسمح للبرنامج النصي لتثبيت esbuild، ثم قم بتشغيل:
pnpm exec tsx --env-file=.env.local scripts/first-row.ts
يقوم npm 11 بحظر البرنامج النصي لتثبيت esbuild

مع npm 11 أو الأحدث، يفشل npx tsx مع «لقد قمت بتثبيت esbuild لنظام أساسي آخر» لأن البرنامج النصي لتثبيت esbuild محظور افتراضيًا. استخدم pnpm كما هو مذكور أعلاه، أو قم بتخطي tsx وقم بتشغيل البرنامج النصي مع تجريد النوع المدمج في Node (Node 22.6+) بعد كتابة الاستيرادين بامتدادهما ('../lib/aurabase.ts', './aurabase.types.ts'): node --env-file=.env.local --experimental-strip-types scripts/first-row.ts.

تأكيد البريد الإلكتروني معطل بشكل افتراضي

بالنسبة لمستخدمي مشروعك، يعمل signUp متبوعًا بـ signInWithPassword على الفور: تأكيد البريد الإلكتروني هو متوقف عن العمل حتى تقوم بتشغيله في الاستوديو › المصادقة › التكوين (يحتاج إلى خادم بريد). يمكن لأي شخص بعد ذلك التسجيل باستخدام أي عنوان، لذا قم بتشغيله قبل الإنتاج.

انتبه

لا يحتوي المفتاح service_role على مستخدم قام بتسجيل الدخول، لذا فإن auth.uid() هو NULL ويفشل الإدخال الذي يعتمد على الإعداد الافتراضي مع NOT_NULL_VIOLATION. من الخادم، قم بتمرير user_id بشكل صريح.

ربط الوقت الحقيقي#

ثلاث عمليات نقل يتم التفاوض عليها تلقائيًا: WebSocket وSSE وNATS. يختار العميل الخيار الأفضل استنادًا إلى الشبكة — ولا يلزم إجراء أي تكوين.

تمكين الوقت الفعلي على الطاولة مرة واحدة، باستخدام واجهة سطر الأوامر:

terminalbash
aura db table realtime todos on

أو باستخدام HTTP API، من الخادم (القيم من .env.local):

terminalbash
curl -X PUT "$NEXT_PUBLIC_AURABASE_URL/v1/db/schema/tables/todos/realtime" \
  -H "apikey: $AURABASE_SERVICE_ROLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

ثم الاشتراك في التغييرات. يتلقى المستخدم الذي قام بتسجيل الدخول الصفوف التي تسمح له سياسات RLS بقراءتها، بما في ذلك وقت فتح القناة قبل تسجيل الدخول (تتم إعادة المصادقة عليها تلقائيًا)؛ تقارير الاشتراك المرفوضة CHANNEL_ERROR مع السبب.

components/LiveTodos.tsxtypescript
'use client'
import { aura } from '@/lib/aurabase'
import { useEffect } from 'react'

export function LiveTodos() {
  useEffect(() => {
    const channel = aura.realtime
      .channel('todos')
      .on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (change) =>
        console.log(change.eventType, change.new),
      )
      .subscribe((status, err) => {
        // أثناء التطوير، يقوم React StrictMode بتركيب المكون وإلغاء تحميله وإعادة تثبيته:
        // يأتي الإغلاق الأول من عملية التنظيف تلك وهو متوقع.
        if (status === 'SUBSCRIBED') console.log('realtime connected')
        if (status === 'CHANNEL_ERROR') console.error('realtime refused:', err?.message)
      })

    return () => {
      void channel.unsubscribe()
    }
  }, [])
  return null
}
نصيحة

يتم مضاعفة الاشتراكات عبر اتصال TCP واحد. افتح العدد الذي تحتاجه - دون أي تكاليف إضافية للشبكة.

للذهاب أبعد من ذلك#