تمت ترجمة هذه الوثائق تلقائيًا بواسطة الذكاء الاصطناعي.
تُعد Database أداة تفاعل مع قواعد البيانات يقدمها NocoBase، وتوفر إمكانيات مريحة للغاية للتفاعل مع قواعد البيانات لتطبيقات بلا تعليمات برمجية (no-code) وتطبيقات منخفضة التعليمات البرمجية (low-code). قواعد البيانات المدعومة حاليًا هي:
في دالة إنشاء الكائن (constructor) الخاصة بـ Database، يمكنك تهيئة الاتصال بقاعدة البيانات عن طريق تمرير المعامل options.
للاطلاع على معلمات التهيئة التفصيلية، يرجى الرجوع إلى دالة الإنشاء.
تُعرّف Database بنية قاعدة البيانات من خلال مجموعة (Collection). يمثل كائن مجموعة (Collection) جدولاً في قاعدة البيانات.
بعد الانتهاء من تعريف بنية قاعدة البيانات، يمكنك استخدام الدالة sync() لمزامنة بنية قاعدة البيانات.
لمزيد من التفاصيل حول استخدام مجموعة (Collection)، يرجى الرجوع إلى المجموعة.
تُجري Database عمليات على البيانات من خلال المستودع (Repository).
لمزيد من التفاصيل حول استخدام عمليات CRUD للبيانات، يرجى الرجوع إلى المستودع.
التوقيع
constructor(options: DatabaseOptions)تُنشئ نسخة من قاعدة البيانات.
المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options.host | string | 'localhost' | مضيف قاعدة البيانات |
options.port | number | - | منفذ خدمة قاعدة البيانات، مع منفذ افتراضي يتوافق مع قاعدة البيانات المستخدمة |
options.username | string | - | اسم مستخدم قاعدة البيانات |
options.password | string | - | كلمة مرور قاعدة البيانات |
options.database | string | - | اسم قاعدة البيانات |
options.dialect | string | 'mysql' | نوع قاعدة البيانات |
options.storage? | string | ':memory:' | وضع التخزين لـ SQLite |
options.logging? | boolean | false | هل يتم تمكين التسجيل (logging) |
options.define? | Object | {} | معلمات تعريف الجدول الافتراضية |
options.tablePrefix? | string | '' | امتداد NocoBase، بادئة اسم الجدول |
options.migrator? | UmzugOptions | {} | امتداد NocoBase، معلمات متعلقة بمدير الترحيل (migration manager)، راجع تطبيق Umzug |
addMigration()تُضيف ملف ترحيل واحد.
التوقيع
addMigration(options: MigrationItem)المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options.name | string | - | اسم ملف الترحيل |
options.context? | string | - | سياق ملف الترحيل |
options.migration? | typeof Migration | - | فئة مخصصة لملف الترحيل |
options.up | Function | - | دالة up لملف الترحيل |
options.down | Function | - | دالة down لملف الترحيل |
مثال
addMigrations()تُضيف ملفات الترحيل من دليل محدد.
التوقيع
addMigrations(options: AddMigrationsOptions): voidالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options.directory | string | '' | الدليل الذي توجد به ملفات الترحيل |
options.extensions | string[] | ['js', 'ts'] | امتدادات الملفات |
options.namespace? | string | '' | مساحة الاسم |
options.context? | Object | { db } | سياق ملف الترحيل |
مثال
inDialect()تتحقق مما إذا كان نوع قاعدة البيانات الحالي هو أحد الأنواع المحددة.
التوقيع
inDialect(dialect: string[]): booleanالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
dialect | string[] | - | نوع قاعدة البيانات، القيم المحتملة هي mysql/postgres/mariadb |
getTablePrefix()تُرجع بادئة اسم الجدول من التهيئة.
التوقيع
getTablePrefix(): stringcollection()تُعرّف مجموعة. هذه الدالة تشبه دالة define في Sequelize، حيث تُنشئ بنية الجدول في الذاكرة فقط. لجعلها دائمة في قاعدة البيانات، تحتاج إلى استدعاء دالة sync.
التوقيع
collection(options: CollectionOptions): Collectionالمعلمات
تتوافق جميع معلمات التهيئة الخاصة بـ options مع دالة الإنشاء لفئة مجموعة (Collection)، راجع المجموعة.
الأحداث
'beforeDefineCollection': يُطلق قبل تعريف المجموعة.'afterDefineCollection': يُطلق بعد تعريف المجموعة.مثال
getCollection()تُرجع مجموعة معرفة.
التوقيع
getCollection(name: string): Collectionالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
name | string | - | اسم المجموعة |
مثال
hasCollection()تتحقق مما إذا كانت مجموعة محددة قد تم تعريفها.
التوقيع
hasCollection(name: string): booleanالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
name | string | - | اسم المجموعة |
مثال
removeCollection()تُزيل مجموعة معرفة. يتم إزالتها من الذاكرة فقط؛ لجعل التغيير دائمًا، تحتاج إلى استدعاء دالة sync.
التوقيع
removeCollection(name: string): voidالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
name | string | - | اسم المجموعة |
الأحداث
'beforeRemoveCollection': يُطلق قبل إزالة المجموعة.'afterRemoveCollection': يُطلق بعد إزالة المجموعة.مثال
import()تستورد جميع الملفات في دليل كتهيئة للمجموعات إلى الذاكرة.
التوقيع
async import(options: { directory: string; extensions?: ImportFileExtension[] }): Promise<Map<string, Collection>>المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options.directory | string | - | مسار الدليل المراد استيراده |
options.extensions | string[] | ['ts', 'js'] | مسح الامتدادات المحددة |
مثال
المجموعة المعرفة في الملف ./collections/books.ts هي كما يلي:
استيراد التهيئة ذات الصلة عند تحميل الإضافة:
registerFieldTypes()تُسجل أنواع الحقول المخصصة.
التوقيع
registerFieldTypes(fieldTypes: MapOf<typeof Field>): voidالمعلمات
إن fieldTypes عبارة عن زوج من المفتاح والقيمة، حيث يكون المفتاح هو اسم نوع الحقل والقيمة هي فئة نوع الحقل.
مثال
registerModels()تُسجل فئات نماذج البيانات المخصصة.
التوقيع
registerModels(models: MapOf<ModelStatic<any>>): voidالمعلمات
إن models عبارة عن زوج من المفتاح والقيمة، حيث يكون المفتاح هو اسم نموذج البيانات والقيمة هي فئة نموذج البيانات.
مثال
registerRepositories()تُسجل فئات المستودعات المخصصة.
التوقيع
registerRepositories(repositories: MapOf<RepositoryType>): voidالمعلمات
إن repositories عبارة عن زوج من المفتاح والقيمة، حيث يكون المفتاح هو اسم المستودع والقيمة هي فئة المستودع.
مثال
registerOperators()تُسجل عوامل تشغيل استعلام البيانات المخصصة.
التوقيع
registerOperators(operators: MapOf<OperatorFunc>)المعلمات
إن operators عبارة عن زوج من المفتاح والقيمة، حيث يكون المفتاح هو اسم عامل التشغيل والقيمة هي الدالة التي تُنشئ عبارة المقارنة.
مثال
getModel()تُرجع فئة نموذج بيانات معرفة. إذا لم يتم تسجيل فئة نموذج مخصصة مسبقًا، فستُرجع فئة نموذج Sequelize الافتراضية. الاسم الافتراضي هو نفس اسم المجموعة المعرفة.
التوقيع
getModel(name: string): Modelالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
name | string | - | اسم النموذج المسجل |
مثال
ملاحظة: فئة النموذج التي يتم الحصول عليها من مجموعة ليست متطابقة تمامًا مع فئة النموذج المسجلة، بل ترث منها. نظرًا لأن خصائص فئة نموذج Sequelize يتم تعديلها أثناء عملية التهيئة، فإن NocoBase يتعامل تلقائيًا مع علاقة الوراثة هذه. باستثناء عدم تطابق الفئة، يمكن استخدام جميع التعريفات الأخرى بشكل طبيعي.
getRepository()تُرجع فئة المستودع المخصصة. إذا لم يتم تسجيل فئة مستودع مخصصة مسبقًا، فستُرجع فئة مستودع NocoBase الافتراضية. الاسم الافتراضي هو نفس اسم المجموعة المعرفة.
تُستخدم فئات المستودعات بشكل أساسي لعمليات CRUD (الإنشاء، القراءة، التحديث، الحذف) المستندة إلى نماذج البيانات، راجع المستودع.
التوقيع
getRepository(name: string): RepositorygetRepository(name: string, relationId?: string | number): Repositoryالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
name | string | - | اسم المستودع المسجل |
relationId | string | number | - | قيمة المفتاح الخارجي للبيانات العلائقية |
عندما يكون الاسم اسمًا مرتبطًا مثل 'tables.relations'، فإنه سيعيد فئة المستودع المرتبطة. إذا تم توفير المعلمة الثانية، فإن المستودع عند الاستخدام (الاستعلام، التحديث، إلخ) سيعتمد على قيمة المفتاح الخارجي للبيانات العلائقية.
مثال
لنفترض وجود مجموعتين، المقالات والمؤلفون، وأن مجموعة المقالات تحتوي على مفتاح خارجي يشير إلى مجموعة المؤلفين:
on()تستمع لأحداث قاعدة البيانات.
التوقيع
on(event: string, listener: (...args: any[]) => void | Promise<void>): voidالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
| event | string | - | اسم الحدث |
| listener | Function | - | مستمع الحدث |
تدعم أسماء الأحداث أحداث نموذج Sequelize بشكل افتراضي. بالنسبة للأحداث العامة، استمع باستخدام التنسيق <sequelize_model_global_event>، وبالنسبة لأحداث النموذج الفردي، استخدم التنسيق <model_name>.<sequelize_model_event>.
للحصول على وصف المعلمات وأمثلة تفصيلية لجميع أنواع الأحداث المضمنة، راجع قسم الأحداث المضمنة.
off()تُزيل دالة مستمع الحدث.
التوقيع
off(name: string, listener: Function)المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
| name | string | - | اسم الحدث |
| listener | Function | - | مستمع الحدث |
مثال
auth()مصادقة اتصال قاعدة البيانات. يمكن استخدامها للتأكد من أن التطبيق قد أقام اتصالاً بالبيانات.
التوقيع
auth(options: QueryOptions & { retry?: number } = {}): Promise<boolean>المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options? | Object | - | خيارات المصادقة |
options.retry? | number | 10 | عدد مرات إعادة المحاولة عند فشل المصادقة |
options.transaction? | Transaction | - | كائن المعاملة |
options.logging? | boolean | Function | false | هل يتم طباعة السجلات |
مثال
reconnect()تُعيد الاتصال بقاعدة البيانات.
مثال
closed()تتحقق مما إذا كان اتصال قاعدة البيانات مغلقًا.
التوقيع
closed(): booleanclose()تُغلق اتصال قاعدة البيانات. مكافئ لـ sequelize.close().
sync()تُزامن بنية مجموعة قاعدة البيانات. مكافئ لـ sequelize.sync()، للمعلومات حول المعلمات، راجع وثائق Sequelize.
clean()تُفرغ قاعدة البيانات، وستحذف جميع المجموعات.
التوقيع
clean(options: CleanOptions): Promise<void>المعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
options.drop | boolean | false | هل يتم إسقاط جميع المجموعات |
options.skip | string[] | - | تهيئة أسماء المجموعات المراد تخطيها |
options.transaction | Transaction | - | كائن المعاملة |
مثال
تُزيل جميع المجموعات باستثناء مجموعة users.
defineCollection()تُنشئ محتوى تهيئة لمجموعة.
التوقيع
defineCollection(name: string, config: CollectionOptions): CollectionOptionsالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
collectionOptions | CollectionOptions | - | نفس جميع معلمات db.collection() |
مثال
لملف تهيئة المجموعة المراد استيراده بواسطة db.import():
extendCollection()تُوسّع محتوى تهيئة بنية المجموعة الموجودة بالفعل في الذاكرة، وتُستخدم بشكل أساسي لمحتوى الملفات المستوردة بواسطة دالة import(). هذه الدالة هي دالة عليا يتم تصديرها بواسطة حزمة @nocobase/database ولا يتم استدعاؤها عبر نسخة db. يمكن أيضًا استخدام الاسم المستعار extend.
التوقيع
extendCollection(collectionOptions: CollectionOptions, mergeOptions?: MergeOptions): ExtendedCollectionOptionsالمعلمات
| اسم المعلمة | النوع | القيمة الافتراضية | الوصف |
|---|---|---|---|
collectionOptions | CollectionOptions | - | نفس جميع معلمات db.collection() |
mergeOptions? | MergeOptions | - | معلمات حزمة npm deepmerge |
مثال
تعريف مجموعة الكتب الأصلية (books.ts):
تعريف مجموعة الكتب الموسعة (books.extend.ts):
إذا تم استيراد الملفين أعلاه عند استدعاء import()، وبعد توسيعهما مرة أخرى باستخدام extend()، ستحتوي مجموعة الكتب على حقلي title و price.
تُعد هذه الدالة مفيدة جدًا عند توسيع هياكل المجموعات المعرفة بالفعل بواسطة الإضافات الموجودة.
تُطلق قاعدة البيانات الأحداث التالية في مراحل دورة حياتها المختلفة. يتيح الاشتراك في هذه الأحداث باستخدام دالة on() معالجة محددة لتلبية بعض الاحتياجات التجارية.
'beforeSync' / 'afterSync'يُطلق قبل وبعد مزامنة تهيئة بنية مجموعة جديدة (الحقول، الفهارس، إلخ) مع قاعدة البيانات. عادةً ما يُطلق عند تنفيذ collection.sync() (استدعاء داخلي) ويُستخدم بشكل عام لمعالجة منطق امتدادات الحقول الخاصة.
التوقيع
النوع
مثال
'beforeValidate' / 'afterValidate'قبل إنشاء أو تحديث البيانات، توجد عملية تحقق تستند إلى القواعد المعرفة في المجموعة. تُطلق الأحداث المقابلة قبل وبعد التحقق. يُطلق هذا عند استدعاء repository.create() أو repository.update().
التوقيع
النوع
مثال
'beforeCreate' / 'afterCreate'تُطلق الأحداث المقابلة قبل وبعد إنشاء سجل. يُطلق هذا عند استدعاء repository.create().
التوقيع
النوع
مثال
'beforeUpdate' / 'afterUpdate'تُطلق الأحداث المقابلة قبل وبعد تحديث سجل. يُطلق هذا عند استدعاء repository.update().
التوقيع
النوع
مثال
'beforeSave' / 'afterSave'تُطلق الأحداث المقابلة قبل وبعد إنشاء أو تحديث سجل. يُطلق هذا عند استدعاء repository.create() أو repository.update().
التوقيع
النوع
مثال
'beforeDestroy' / 'afterDestroy'تُطلق الأحداث المقابلة قبل وبعد حذف سجل. يُطلق هذا عند استدعاء repository.destroy().
التوقيع
النوع
مثال
'afterCreateWithAssociations'يُطلق هذا الحدث بعد إنشاء سجل يحتوي على بيانات ارتباط هرمية. يُطلق هذا عند استدعاء repository.create().
التوقيع
النوع
مثال
'afterUpdateWithAssociations'يُطلق هذا الحدث بعد تحديث سجل يحتوي على بيانات ارتباط هرمية. يُطلق هذا عند استدعاء repository.update().
التوقيع
النوع
مثال
'afterSaveWithAssociations'يُطلق هذا الحدث بعد إنشاء أو تحديث سجل يحتوي على بيانات ارتباط هرمية. يُطلق هذا عند استدعاء repository.create() أو repository.update().
التوقيع
النوع
مثال
'beforeDefineCollection'يُطلق قبل تعريف مجموعة، على سبيل المثال، عند استدعاء db.collection().
ملاحظة: هذا الحدث متزامن.
التوقيع
النوع
مثال
'afterDefineCollection'يُطلق بعد تعريف مجموعة، على سبيل المثال، عند استدعاء db.collection().
ملاحظة: هذا الحدث متزامن.
التوقيع
النوع
مثال
'beforeRemoveCollection' / 'afterRemoveCollection'يُطلق قبل وبعد إزالة مجموعة من الذاكرة، على سبيل المثال، عند استدعاء db.removeCollection().
ملاحظة: هذا الحدث متزامن.
التوقيع
النوع
مثال