BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/server-database.mdx
View on GitHub---
title: "قاعدة البيانات"
description: "وصّل PostgreSQL بتطبيق Agent-Native الخاص بك: مساعدات المخطط، والترحيلات، وPGlite المحلي أو Postgres المستضاف."
---
# قاعدة البيانات
يخزّن كل تطبيق أصلي للوكيل حالته في PostgreSQL. تقرأ واجهة المستخدم والوكيل الجداول نفسها وتكتبان إليها عبر Actions نفسها، باستخدام عميل [Drizzle ORM](https://orm.drizzle.team) نفسه. تستخدم المزامنة الحية SSE مع الاستطلاع كخيار احتياطي، لذلك تظهر التغييرات في السطح الآخر دون تحديث يدوي.
<Diagram id="doc-block-9mtx2f" title="كيف تتدفق البيانات إلى قاعدة البيانات" summary="تصل كل من واجهة المستخدم والوكيل إلى قاعدة البيانات عبر طبقة Actions نفسها. يستخدم كلا المستدعيين عميل getDb() نفسه وجداول PostgreSQL نفسها. لا توجد خلفية منفصلة لكل منهما.">
```html
<div class="diagram-dbr">
<div class="diagram-col">
<div class="diagram-node">المتصفح / واجهة المستخدم</div>
<div class="diagram-node">حلقة الوكيل</div>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel" data-rough>
<strong>Actions</strong>
<small class="diagram-muted">defineAction</small>
<small class="diagram-muted">getDb() · Drizzle ORM</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-box" data-rough>
قاعدة بيانات PostgreSQL<br /><small class="diagram-muted"
>PostgreSQL من DATABASE_URL</small
>
</div>
</div>
```
```css
.diagram-dbr {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.diagram-dbr .diagram-col {
display: flex;
flex-direction: column;
gap: 10px;
}
.diagram-dbr .diagram-panel {
display: flex;
flex-direction: column;
gap: 4px;
padding: 12px 16px;
}
.diagram-dbr .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
## خيارات الاستضافة {#hosting}
يستخدم التطبيق PostgreSQL. وعند عدم ضبط `DATABASE_URL`، يستخدم PGlite المحلي لتتمكن من البدء دون إعداد.
### الافتراضي: ملف PGlite {#default-pglite}
عند عدم ضبط `DATABASE_URL`، ينشئ التطبيق قاعدة بيانات PGlite في `data/pglite`. لا يتطلب أي تكوين. شغّل خادم التطوير وسيُنشأ الملف عند أول تشغيل.
هذا مخصص للتطوير المحلي فقط. قد تعيد الحاويات، والوظائف بدون خادم، وبيئات المعاينة ضبط نظام الملفات الخاص بها بين عمليات إعادة التشغيل، مما يعني أن ملف PGlite المحلي يمكن أن يختفي. اضبط `DATABASE_URL` على قاعدة PostgreSQL مستضافة ومستمرة قبل النشر.
### Postgres محلي: PGlite {#local-pglite}
للتطوير محليًا باستخدام PostgreSQL دون Docker أو قاعدة بيانات مستضافة، ثبّت حزمة PGlite الاختيارية واضبط `DATABASE_URL`:
```bash
pnpm add @electric-sql/pglite@^0.5.8
```
```bash
DATABASE_URL=pglite:./data/pglite
```
يُشغّل [PGlite](https://pglite.dev/) قاعدة بيانات Postgres مبنية بتقنية WASM داخل العملية نفسها. يتيح لك اكتشاف مشكلات المخطط الخاصة بـ Postgres فقط قبل النشر، مع إبقاء الإعداد بسيطًا مثل الإعداد الافتراضي لـ PGlite. وهو، مثل PGlite، تخزين محلي فقط. لا تستخدمه في الإنتاج أو البيئات المشتركة.
### قاعدة بيانات الإنتاج {#production}
اضبط `DATABASE_URL` في ملف `.env` الخاص بك أو في بيئة موفر النشر للاتصال بقاعدة PostgreSQL مستضافة. تشمل الخيارات المُدارة الشائعة [Neon](/docs/neon) و[Supabase](/docs/supabase) و[Amazon RDS for PostgreSQL](/docs/aws-rds) و[Cloud SQL for PostgreSQL](/docs/cloud-sql) و[Azure Database for PostgreSQL](/docs/azure-postgresql). استخدم دليل [Plain Postgres](/docs/postgres) للخدمات المُدارة الأخرى وخوادم PostgreSQL ذاتية الاستضافة:
```bash
# Neon Postgres
DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
# Supabase Postgres
DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
# Plain Postgres
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
DATABASE_URL=pglite:./data/pglite
```
يهيئ إطار العمل Drizzle لـ PostgreSQL باستخدام `DATABASE_URL`.
يحدّ إطار العمل الاتصالات في كل تجمّع. القيم الافتراضية هي 20 لعمليات Node.js طويلة العمر، و2 لوظائف serverless الأمامية، و4 لوظائف serverless الخلفية، و1 للعاملين المجدولين منخفضي الاتصال. عيّن `AGENT_NATIVE_DB_POOL_MAX` لتجاوز حدّ كل تجمّع في عملاء Neon وPostgreSQL القياسيين. قدّر إجمالي الاتصالات عبر مثيلات الوظائف النشطة وعمليات Node.js والتطبيقات وعناوين قواعد البيانات المختلفة. لكل عملية تجمّعاتها الخاصة. أبقِ المجموع دون حد قاعدة البيانات أو مجمّع الاتصالات، مع ترك سعة للترحيلات والإدارة والعملاء الآخرين. استخدم عنوان المجمّع الذي يوفّره المزود عند توفره. للتطبيقات ذات العمليات الكثيرة على PostgreSQL ذاتي الاستضافة، فكّر في PgBouncer بوضع تجميع المعاملات.
### قاعدة بيانات مُدارة من Builder.io {#builder-managed}
_مخطط له (غير متاح بعد):_ عند الاتصال بـ Builder.io، سيتمكن تطبيقك من استخدام قاعدة بيانات مُدارة يتم توفيرها تلقائيًا، دون الحاجة إلى سلاسل اتصال.
## إعداد قاعدة البيانات {#setup}
يحتاج التطبيق الذي يستخدم قاعدة البيانات إلى ثلاثة ملفات:
- `server/db/schema.ts`: تعريفات الجداول
- `server/db/index.ts`: مثيل عميل قاعدة البيانات الوحيد المكتوب (typed singleton)
- `server/plugins/db.ts`: ترحيلات التطبيق الخاصة ببدء التشغيل المحلي
### 1. عرّف مخططك {#schema}
استورد مساعدات المخطط من `@agent-native/core/db/schema`. تنتج مساعدات الإطار تعريفات خاصة بـ PostgreSQL وPGlite.
```ts filename="server/db/schema.ts"
import { sql } from "drizzle-orm";
import { boolean, integer, pgTable, text } from "drizzle-orm/pg-core";
export const tasks = pgTable("tasks", {
id: text("id").primaryKey(),
title: text("title").notNull(),
priority: integer("priority").notNull().default(0),
done: boolean("done").notNull().default(false),
ownerEmail: text("owner_email").notNull(),
createdAt: text("created_at")
.notNull()
.default(sql`now()`),
});
```
| المساعد | الغرض |
| ----------------- | ----------------------------------- |
| `pgTable` | تحديد جدول؛ يستخدم مساعد PostgreSQL |
| `text` | عمود نصي، يدعم `{ enum: [...] }` |
| `integer` | عمود صحيح |
| `boolean` | عمود منطقي |
| `doublePrecision` | عمود عائم مزدوج الدقة |
| `sql` | تعبير SQL مثل `now()` |
<DataModel
id="doc-block-3hbven"
title="جدول tasks"
summary={
"يُعرَّف مرة واحدة باستخدام مساعدات إطار العمل لـ PostgreSQL وPGlite المحلي."
}
entities={[
{
id: "tasks",
name: "tasks",
note: "جدول نطاق. أضف owner_email (أو ...ownableColumns()) حتى يتمكن تحديد النطاق على مستوى SQL من تصفية الصفوف للمستخدم المصادق عليه.",
fields: [
{
name: "id",
type: "text",
pk: true,
nullable: false,
},
{
name: "title",
type: "text",
nullable: false,
},
{
name: "priority",
type: "integer",
nullable: false,
note: "القيمة الافتراضية 0",
},
{
name: "done",
type: "boolean",
nullable: false,
note: "القيمة الافتراضية false؛ تُعيَّن إلى قيمة منطقية في Postgres",
},
{
name: "owner_email",
type: "text",
nullable: false,
note: "يفعّل تحديد نطاق البيانات",
},
{
name: "created_at",
type: "text",
nullable: false,
note: "القيمة الافتراضية now()",
},
],
},
]}
/>
يجب أن تتضمن الجداول التي تخزّن بيانات خاصة بكل مستخدم عمود `owner_email` حتى يتمكن إطار العمل من تصفية الصفوف للمستخدم المصادق عليه. أما الجداول التي تدعم أيضًا المشاركة مع مستخدمين أو مؤسسات أخرى فينبغي أن تنشر `...ownableColumns()` بدلاً من ذلك، والتي تضيف `owner_email`، و`org_id`، و`visibility` في استدعاء واحد. راجع [تحديد نطاق البيانات للمستخدمين](#scoping) أدناه.
### 2. أنشئ عميل قاعدة البيانات {#db-client}
ينشئ كل تطبيق عميل Drizzle كسولًا ومفردًا (singleton) عن طريق استدعاء `createGetDb(schema)`. الموقع الأساسي هو `server/db/index.ts`:
```ts filename="server/db/index.ts"
import { createGetDb } from "@agent-native/core/db";
import * as schema from "./schema.js";
export const getDb = createGetDb(schema);
```
يُرجع `createGetDb` دالة `getDb()` تفتح اتصال PostgreSQL عند أول استدعاء، وتُرجع نفس مثيل Drizzle المكتوب في الاستدعاءات اللاحقة. وهي تقرأ `DATABASE_URL` للاتصال بـ PostgreSQL المستضاف أو PGlite المحلي.
استورد `getDb` من هذا المسار المحلي للقالب في actions والمسارات. لا تستورد مباشرةً من `@agent-native/core`. التصدير الأساسي (core) غير مكتوب النوع؛ بينما يحمل التصدير المحلي أنواع مخططك.
### 3. اكتب الترحيلات {#migrations}
أثناء التطوير المحلي، يمكن تطبيق تغييرات المخطط عبر إضافة Nitro في
`server/plugins/db.ts`. في الإنتاج أو البيئات الخالية من الخادم، شغّل الترحيلات
في خطوة إصدار أو نشر بدلاً من الطلب الأول. استخدم `runMigrations` من
`@agent-native/core/db`:
<AnnotatedCode
id="doc-block-7qwlpz"
title="إضافة ترحيل عند بدء التشغيل"
filename="server/plugins/db.ts"
language="ts"
code={
'import { runMigrations } from "@agent-native/core/db";\n\nexport default runMigrations(\n [\n {\n version: 1,\n sql: `CREATE TABLE IF NOT EXISTS tasks (\n id TEXT PRIMARY KEY,\n title TEXT NOT NULL,\n done BOOLEAN NOT NULL DEFAULT false,\n owner_email TEXT NOT NULL,\n created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP\n )`,\n },\n {\n version: 2,\n sql: `ALTER TABLE tasks ADD COLUMN IF NOT EXISTS priority INTEGER NOT NULL DEFAULT 0`,\n },\n {\n version: 3,\n sql: `ALTER TABLE tasks ADD COLUMN IF NOT EXISTS tsv tsvector`,\n },\n ],\n { table: "my_app_migrations" },\n);'
}
annotations={[
{
lines: "6",
label: "جدول إصدارات لكل تطبيق",
note: "يتتبع كل تطبيق إصداراته المطبَّقة الخاصة به في جدول منفصل. استخدم اسمًا فريدًا لتطبيقك حتى لا يتعارض مع ترحيلات إطار العمل أو تطبيقات أخرى تشارك قاعدة البيانات نفسها.",
},
{
lines: "7",
label: "إنشاء الجدول الأولي",
note: "يُعد `CREATE TABLE IF NOT EXISTS` آمنًا لإعادة التشغيل في كل مرة. ضع تعريف الجدول الكامل في الإصدار 1.",
},
{
lines: "17",
label: "إضافات أعمدة تراكمية",
note: "يُعد `ADD COLUMN IF NOT EXISTS` الطريقة الآمنة لإضافة أعمدة بعد الإنشاء الأولي. لا تقم أبدًا بحذف الأعمدة أو إعادة تسميتها.",
},
{
lines: "22-25",
label: "SQL لـ PostgreSQL",
note: "تستخدم الترحيلات SQL الخاص بـ PostgreSQL مباشرةً وتُطبّق بترتيب الإصدار.",
},
]}
/>
يشغّل `runMigrations` كل إدخال معلق بالترتيب مرة واحدة، ويسجله كمطبق، ثم
يتخطاه في عمليات التشغيل اللاحقة. امنح الإدخالات الجديدة اسماً ثابتاً؛ إذ تتبع
الترحيلات المسماة بشكل مستقل عن رقم الإصدار.
منذ الإصدار 0.177.0، يجب أن تكون تعليمة SQL للترحيل صالحة في PostgreSQL. هذا
تغيير غير متوافق مع الترحيلات القديمة بأسلوب SQLite. يرسل `runMigrations()`
تعليمات SQL كما كُتبت دون إعادة صياغتها. راجع الأنواع والتعبيرات المقصودة في
كل ترحيل بدلاً من إجراء استبدالات شاملة. في المخططات الجديدة، استخدم `BIGINT`
لمللي ثانية منذ بداية العصر و`INTEGER` للقيم العادية مثل الأولويات. استخدم
`CURRENT_TIMESTAMP` لعمود زمني بدلاً من `datetime('now')`، وصيغة الهوية في
PostgreSQL بدلاً من `AUTOINCREMENT`. هذا المثال لمخطط جديد وليس بديلاً لمخطط موجود:
```sql
CREATE TABLE task_events (
id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
priority INTEGER NOT NULL DEFAULT 0,
occurred_at_ms BIGINT NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```
تُتخطى إدخالات الترحيل القديمة المطبقة إذا بقيت معرّفات الاسم أو الإصدار الأصلية
دون تغيير. قد تؤدي إضافة `name` إلى إصدار قديم بلا اسم إلى إعادة تشغيله. احتفظ
بسلسلة الترحيلات الأصلية ومعرّفاتها لقواعد البيانات الموجودة، ولا تعدّل سجل
الترحيلات بصمت.
افحص المخطط الفعلي وأنواع الأعمدة في كل قاعدة بيانات موجودة قبل التخطيط للترقية.
كان المحوّل القديم قد يوسّع حتى أعمدة `INTEGER` العادية إلى `BIGINT`، لذا لا تفترض
أن مثال المخطط الجديد يطابقها. في قاعدة بيانات جديدة، قد يفشل ترحيل قديم غير صالح
قبل تشغيل إصلاح أُضيف لاحقاً. ضمن استراتيجية خاصة بالنشر ومخطط لها ومراجَعة بعناية،
أنشئ واختبر خط أساس PostgreSQL لقواعد البيانات الجديدة يعيد إنتاج المخطط والأنواع
المفحوصة في القواعد الموجودة وبيانات التهيئة المطلوبة وآثار دوال الاستدعاء للترحيلات
التي يحل محلها. تأكد من أن سجل ترحيلات خط الأساس يمثل الترحيلات المستبدلة بشكل صحيح.
تحتاج الترحيلات المسماة إلى أسماء مطابقة في السجل، ولا يكفي حد الإصدار وحده.
نفّذ واختبر اختيار خط الأساس وتجهيزه للتثبيتات الجديدة في شيفرة نشر التطبيق قبل
تشغيل الترحيلات الأحدث. احتفظ بمسار الترحيل الأصلي لقواعد البيانات الموجودة.
لا يختار المشغّل خط أساس تلقائياً.
<Callout tone="warning">
يوفر قالب Chat الأمر `pnpm migrate:production` لتشغيل الترحيلات كجزء من
الإصدار.
</Callout>
### إنشاء ترحيلات التطبيق الجديدة باستخدام Drizzle Kit {#drizzle-migrations}
بالنسبة إلى تغييرات مخطط التطبيق الجديدة، استخدم `pnpm db:generate` لإنشاء SQL
قابل للمراجعة. ينشئ ذلك `server/db/migrations/<id_name>.sql`، ويحمّل
`runDrizzleMigrations` هذه الملفات إلى مشغّل Agent-Native المشترك في بيئات Node.js
وبيئات serverless المستندة إلى Node. تبقى خطوة الإصدار هي المسؤولة عن تغييرات
الإنتاج. احتفظ بـ `runMigrations()` لجداول PostgreSQL، وعمليات ملء
البيانات، وخطوات JavaScript المؤجلة.
لا يتوفر محمّل نظام الملفات في Cloudflare Workers/Pages أو بيئات edge الأخرى
التي لا توفر نظام ملفات. استخدم `runMigrations()` هناك مع إدخالات SQL الخاصة بـ PostgreSQL المضمّنة
في حزمة العامل. أنشئ الترحيلات لـ PostgreSQL ولا تبدّل مجلدًا واحدًا بين
PGlite وPostgreSQL.
<Callout tone="risk">
لا تقم أبدًا بتشغيل `drizzle-kit push` مقابل قاعدة بيانات إنتاج. تُعرّف مخططات
القالب جداول التطبيق الخاصة فقط؛ ولا تتضمن جداول إطار العمل المركزية (`user`،
و`session`، و`application_state`، وغيرها). سيؤدي تشغيل `drizzle-kit push`
مقابل الإنتاج إلى اكتشاف تلك الجداول كجداول غير معروفة ومحاولة حذفها، مما
يتسبب في فقدان فوري للبيانات.
</Callout>
يهيئ `drizzle.config.ts` الموجود في جذر كل تطبيق drizzle-kit لفحص مخطط PostgreSQL أثناء التطوير المحلي. اضبط قاعدة PostgreSQL صراحةً، مثل `createDrizzleConfig({ dialect: "postgresql" })`:
```ts filename="drizzle.config.ts"
import { createDrizzleConfig } from "@agent-native/core/db/drizzle-config";
export default createDrizzleConfig();
```
استخدم `pnpm db:generate` لفحص مخططك، و`pnpm db:push` مقابل قاعدة بيانات محلية فقط.
### 4. استعلم داخل actions {#querying}
استدعِ `getDb()` من actions الخاصة بك للحصول على عميل Drizzle المكتوب. استخدم منشئ الاستعلامات في Drizzle والمشغلات المحمولة من `drizzle-orm`:
```ts
import { and, desc, eq } from "drizzle-orm";
import { getDb } from "../server/db/index.js";
import * as schema from "../server/db/schema.js";
const db = getDb();
const openTasks = await db
.select()
.from(schema.tasks)
.where(
and(eq(schema.tasks.ownerEmail, userEmail), eq(schema.tasks.done, false)),
)
.orderBy(desc(schema.tasks.createdAt));
await db
.update(schema.tasks)
.set({ done: true })
.where(eq(schema.tasks.id, taskId));
```
## تحديد نطاق البيانات للمستخدمين {#scoping}
يجب تحديد نطاق جميع عمليات القراءة والكتابة على الجداول التي تواجه المستخدم بحيث تقتصر على المستخدم المصادق عليه. يوفر إطار العمل نمطين حسب ما إذا كانت البيانات خاصة أو قابلة للمشاركة.
**البيانات الخاصة:** الجداول التي تخص مستخدمًا واحدًا. أضف `ownerEmail: text("owner_email").notNull()` إلى المخطط وأدرج `eq(table.ownerEmail, userEmail)` في كل استعلام:
```ts
.where(eq(schema.tasks.ownerEmail, userEmail))
```
**الموارد القابلة للمشاركة:** الجداول التي يمكن مشاركتها مع مستخدمين أو مؤسسات أخرى. انشر `...ownableColumns()` في المخطط بدلاً من `owner_email` مجردة. يضيف هذا `owner_email`، و`org_id`، و`visibility` في استدعاء واحد، وينشئ جدول مشاركات مرافقًا باستخدام `createSharesTable`:
```ts filename="server/db/schema.ts"
import {
table,
text,
ownableColumns,
createSharesTable,
} from "@agent-native/core/db/schema";
export const decks = table("decks", {
id: text("id").primaryKey(),
title: text("title").notNull(),
...ownableColumns(),
});
export const deckShares = createSharesTable("deck_shares");
```
ثم استخدم `accessFilter` من `@agent-native/core/sharing` في استعلامات القوائم بدلاً من فحص `eq` يدوي:
```ts
import { accessFilter } from "@agent-native/core/sharing";
const rows = await db
.select()
.from(schema.decks)
.where(accessFilter(schema.decks, schema.deckShares));
```
يبني `accessFilter` استعلامًا يسمح بالصفوف التي يملكها المستدعي، والصفوف المشتركة مع مؤسسته، والصفوف المشتركة معه صراحةً. ولا يكشف عن صفوف تخص مستخدمين آخرين.
راجع [الأمان — تحديد نطاق البيانات](/docs/security#data-scoping) و[المشاركة](/docs/sharing#building) للاطلاع على النموذج الكامل.
## المزامنة المدعومة بـ PostgreSQL {#sync}
لا يعتمد Agent-Native على مراقبي نظام الملفات أو الحالة اللاصقة في الذاكرة. فعندما يكتب action إلى قاعدة البيانات، يزداد إصدار المزامنة. يستطلع خطاف العميل `useDbSync()` نقطة النهاية `/_agent-native/poll` ويُبطل ذاكرات React Query المؤقتة عندما يرى إصدارًا أعلى.
يعمل هذا عبر عمليات النشر بدون خادم ومتعددة المثيلات لأن قاعدة البيانات هي نقطة التنسيق. إذا كتبت عمليات تغيير مخصصة خارج actions، استخدم مساعدات إطار العمل أو أصدر إبطال المزامنة المناسب حتى تتحدث واجهات المستخدم المفتوحة.
<Diagram id="doc-block-qhkdv8" title="حلقة المزامنة المدعومة بـ PostgreSQL" summary="لا مراقبون، ولا حالة لاصقة. تؤدي عملية الكتابة إلى زيادة إصدار في PostgreSQL؛ ويستطلع كل عميل الإصدار ويعيد الجلب.">
```html
<div class="diagram-db-sync">
<div class="diagram-box" data-rough>
Action / مساعد<br /><small class="diagram-muted">يُغيّر البيانات</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">→</div>
<div class="diagram-panel" data-rough>
<strong>قاعدة بيانات PostgreSQL</strong
><small class="diagram-muted">يزداد إصدار المزامنة</small>
</div>
<div class="diagram-arrow diagram-muted" aria-hidden="true">←</div>
<div class="diagram-col">
<div class="diagram-node">
useDbSync()<br /><small class="diagram-muted"
>يستطلع /_agent-native/poll</small
>
</div>
<div class="diagram-pill ok">
إبطال الذاكرات المؤقتة → تحديث واجهة المستخدم
</div>
</div>
</div>
```
```css
.diagram-db-sync {
display: flex;
align-items: center;
gap: 14px;
flex-wrap: wrap;
}
.diagram-db-sync .diagram-col {
display: flex;
flex-direction: column;
gap: 8px;
align-items: flex-start;
}
.diagram-db-sync .diagram-arrow {
font-size: 22px;
line-height: 1;
}
```
</Diagram>
<Endpoint id="doc-block-1s11d2e" title="نقطة نهاية الاستطلاع" method="GET" path="/_agent-native/poll" summary="إرجاع إصدارات مزامنة قاعدة البيانات الحالية لكل مصدر حتى يتمكن العميل من اكتشاف التغييرات." auth="ملف تعريف ارتباط الجلسة (هوية محددة النطاق للطلب)" responses={[
{
"status": "200",
"description": "إصدارات المزامنة الحالية مفهرسة حسب المصدر."
}
]}>
يستدعي `useDbSync()` هذه النقطة على فترات، ويعود إليها عندما يكون SSE غير متاح. وعندما يكون الإصدار المُرجَع أعلى من آخر قيمة رآها العميل، تُبطَل ذاكرات React Query المطابقة ويُعاد جلبها.
</Endpoint>
## PostgreSQL الخام {#raw-sql}
بالنسبة للاستعلامات المتقدمة، أو فحوصات السلامة، أو الصيانة لمرة واحدة التي لا يمكن لمنشئ استعلامات Drizzle التعبير عنها، استخدم `getDbExec` من `@agent-native/core/db`:
```ts
import { getDbExec } from "@agent-native/core/db";
const { rows } = await getDbExec().execute({
sql: `SELECT id, title FROM tasks WHERE owner_email = ? LIMIT ?`,
args: [userEmail, 50],
});
```
يحوّل `getDbExec` تلقائيًا معلمات `?` إلى `$1`، و`$2`، وهكذا بالنسبة إلى Postgres. يُفضّل استخدام منشئ استعلامات Drizzle لعمليات القراءة والكتابة العادية. يتجاوز SQL الخام أمان الأنواع (type safety) ويصعب صيانته.
## متغيرات البيئة {#environment-variables}
| المتغير | الغرض |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | سلسلة اتصال PostgreSQL مستمرة (غير مضبوط = PGlite محلي؛ `pglite:./data/pglite` = تفعيل اختياري لـ Postgres محلي) |
## ما هي الخطوة التالية {#whats-next}
- [**الأمان — تحديد نطاق البيانات**](/docs/security#data-scoping): كيف يحدّ `owner_email` ومساعدات الوصول نطاق القراءات والكتابات
- [**المشاركة**](/docs/sharing#building): `ownableColumns()` ونموذج الرؤية للموارد المشتركة
- [**الإضافات**](/docs/server-plugins): دورة حياة إضافة بدء التشغيل حيث تعمل الترحيلات
- [**Actions**](/docs/actions-overview): السطح الذي تستدعي فيه actions دالة `getDb()` لقراءة البيانات وكتابتها
- [**النشر**](/docs/deployment#persistent-database): توصيل قاعدة بيانات مستمرة لكل وجهة نشر
- [**المزامنة الفورية**](/docs/key-concepts#polling-sync): `useDbSync()` والنموذج الكامل للمزامنة من جانب العميل
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |