الأدوات

يوفر الخادم 63 أداة: خمس أدوات جلسة، وثلاث أدوات قراءة، و54 أداة تحرير، واحدة لكل عملية تحرير، وerd_batch التي تشغّل عدة أدوات تحرير بوصفها تعديلًا واحدًا.

تأخذ كل أداة باستثناء erd_list_documents مسار المستند path بوصفه وسيطتها الأولى، وتُغفله الجداول أدناه. الوسيطة التي تحمل العلامة ? اختيارية.

أدوات الجلسة

الأداة	الوسائط	ما تفعله
erd_list_documents		تسرد مستندات ERD مع path وopen وactive وdirty وreadonly: مستندات المحرر الذي يخدم مجلد العمل، وتشمل في بيئة تطوير JetBrains كل مشروع مفتوح، وإلا فملفات ERD الموجودة ضمن مجلد العمل.
erd_open_document	create?	تفتح مستندًا للتحرير، في ERD Editor التابع للمحرر الذي يخدمه، إن وُجد. مع create تنشئ الملف أولًا إن لم يكن موجودًا، ويُضاف .erd.json إلى الاسم الذي لا امتداد له.
erd_save		تحفظ مستندًا يحتفظ به محرر. يُبقي VS Code تعديلات الوكيل غير محفوظة إلى أن تُستدعى هذه الأداة؛ أما Obsidian وبيئة تطوير JetBrains فيحفظانها كما يحفظان تعديلاتك، وتكتبها هذه الأداة فورًا. في الوضع بدون واجهة، يكون كل تعديل مكتوبًا بالفعل ولا تفعل هذه الأداة شيئًا.
erd_undo		تتراجع عن آخر تعديل أجراه هذا الوكيل، ولا تتراجع أبدًا عن تعديلاتك. تتخطى الاستدعاءات التي لم تُنشئ إدخال تراجع وتذكر أسماءها.
erd_redo		تعيد تطبيق التعديل الذي تراجعت عنه erd_undo آخر مرة.

لمعرفة ما يفعله الحفظ والتراجع في كل وضع، راجع الوضع المباشر والوضع بدون واجهة.

قراءة مستند

الأداة	الوسائط	ما تفعله
erd_list	query?, offset?, limit?, namesOnly?	الإعدادات والأعداد، ثم صفحة من الجداول مع فهارسها وعلاقاتها، وكل جدول بمعرّفه وموضعه وحجمه على لوحة الرسم وعدد أعمدته ومجموعة الجداول التي ينتمي إليها إن كان في إحداها. ما لم تُجرِ بحثًا، تأتي بعد الجداول مجموعاتُ الجداول ثم الملاحظات.
erd_get	tableIds?, tableNames?, relationshipIds?, indexIds?, memoIds?, tableGroupIds?	الكيانات المسمّاة كاملةً: الجداول مع أعمدتها ومجموعة جداولها، والعلاقات مع أعمدتها وقيمتي onDelete وonUpdate الخاصتين بها، والفهارس مع أعمدتها، والملاحظات مع نصوصها، ومجموعات الجداول مع جداولها.
erd_read	format, vendor?, statements?, header?, tableIds?, tableNames?, groupNames?	المستند كله مرة واحدة بأحد أربعة تنسيقات، أو DDL بعض الجداول أو مجموعات الجداول فقط.

يعثر الوكيل على المعرّفات باستخدام erd_list، ويقرأ الأعمدة والتفاصيل الأخرى باستخدام erd_get، ثم يمرّر تلك المعرّفات إلى أدوات التحرير. حجم الجدول في erd_list هو المربع الذي يشغله على لوحة الرسم: الارتفاع دقيق والعرض تقريبي. تُسرد مجموعة الجداول بالمستطيل الذي تخزنه، مع اسمها ولونها وعدد الجداول التي تضمها. تُسرد كل علاقة مرة واحدة، مع أحد جدوليها. الإعدادات التي تُبلغ عنها erd_list وerd_read هي تلك التي يحفظها الملف، راجع الإعدادات.

تأخذ erd_read أحد أربعة تنسيقات:

format	ما تُرجعه
snapshot	JSON مضغوط يضم كل كيان ومعرّفه، بما في ذلك مجموعات الجداول، والإعدادات مع سكربتات مخطط SQL. يستبعد ما يختلف من مشاهد إلى آخر: عروض الجداول المقيسة وترتيب التراص والعرض وعلامة التبويب. يكون كبيرًا في المخططات الكبيرة.
sql	DDL لإحدى قواعد البيانات الثماني، Databricks أو MariaDB أو MSSQL أو MySQL أو Oracle أو PostgreSQL أو Snowflake أو SQLite. القيمة الافتراضية للوسيطة vendor هي قاعدة البيانات المضبوط عليها المستند. يتضمن DDL المستند كله سكربتاته قبل الجداول وبعدها. مع tableIds أو tableNames أو groupNames، تلك الجداول فقط، مع المفاتيح الخارجية التي تحملها، ودون سكربتات. تحمل المفاتيح الخارجية إجراءات ON DELETE وON UPDATE الخاصة بها، باستثناء ما تستبعده قاعدة البيانات المستهدفة، راجع ON DELETE وON UPDATE.
json	المستند كله تمامًا كما يكتب الحفظ الملف، بما في ذلك أي تعديلات لم يحفظها المحرر بعد، راجع صيغة التخزين وقيمة وقت التشغيل.
scripts	سكربتات المستند قبل الجداول وبعدها وحدها، بالشكل {"before":"…","after":"…"}، وكلٌّ منها فارغ إن لم يُضبط، مهما كان حجم المخطط.

لا يأخذ vendor وstatements وheader وtableIds وtableNames وgroupNames إلا التنسيق sql، ويرفضها أي تنسيق آخر.

• statements: create، وهي القيمة الافتراضية؛ أو ifNotExists، التي تكتب CREATE TABLE IF NOT EXISTS في MySQL وMariaDB وPostgreSQL وSQLite وDatabricks وعبارة CREATE TABLE العادية في البقية؛ أو recreate، التي تحذف الجداول قبل إنشائها، وفيها يكتب Snowflake بدلًا من ذلك CREATE OR REPLACE TABLE.
• header: none، وهي القيمة الافتراضية؛ أو use، التي تحدد قاعدة البيانات أو المخطط المسمّى باسم قاعدة البيانات في المستند؛ أو createAndUse، التي تنشئه أولًا. ليس لدى Oracle سوى use، لذا تكتب createAndUse فيه use، وليس لدى PostgreSQL سوى createAndUse، لذا لا تكتب use فيه أي ترويسة. لا يكتب SQLite أي ترويسة، ولا تكتب أي قاعدة بيانات ترويسة ما دام اسم قاعدة البيانات فارغًا أو ليس معرّفًا بسيطًا.
• groupNames: جداول مجموعات الجداول المسمّاة، بالاسم دون مراعاة حالة الأحرف، مضمومةً إلى tableIds وtableNames. يُرفض الاسم الذي لا يطابق أي مجموعة بالرمز notFound. لا تضيف المجموعة التي لا تضم أي جدول شيئًا، والقراءة التي لا يتبقى فيها أي جدول على الإطلاق، كما حين تكون كل المجموعات المسمّاة فارغة ولا يُسمّى أي جدول، تُرفض بالرمز invalidArgs.

تنطبق الوسيطتان statements وheader على DDL بعض الجداول أيضًا. وتعملان كالخيارين Statements وHeader في علامة تبويب مخطط SQL في المحرر، وإن كانت علامة التبويب تبدأ على القيمتين If not exists وCREATE + USE. تُحاط الأسماء بنوع علامات الاقتباس الذي يحفظه الملف، أي النوع المقفل ما دام Bracket Type مقفلًا، راجع القفل.

المخططات الكبيرة

تعمل المخططات التي تضم مئات الجداول أو آلافها أيضًا. تُرجع القراءة 40,000 حرف على الأكثر، دون الحد الذي يضع عنده Claude Code نتيجة الأداة جانبًا في ملف.

• تُرجع erd_list صفحة من 100 عنصر افتراضيًا، الجداول أولًا، ثم مجموعات الجداول، ثم الملاحظات، وتذكر أين تبدأ الصفحة التالية عبر nextOffset وnote. مرّر قيمة nextOffset تلك بوصفها offset، مع قيمة query نفسها.
• تعثر query على الجداول بكلمات في اسم جدول أو عمود أو تعليقه، دون مراعاة حالة الأحرف. تأتي أولًا الجداول التي تحوي أسماؤها عددًا أكبر من الكلمات. لا يسرد البحث أي مجموعات جداول أو ملاحظات.
• تسرد namesOnly أسماء الجداول وحدها، نحو 2,000 اسم قصير في استجابة واحدة.
• تأخذ erd_get وerd_read الوسيطة tableNames إلى جانب المعرّفات، وتأخذ erd_read الوسيطة groupNames، لذا فالوكيل الذي يُطلب منه استعلام SQL على مخطط كبير يقرأ DDL الجداول التي يحتاجها فقط.
• تسرد erd_get المعرّفات والأسماء التي لا تشير إلى شيء ضمن missing، والمعرّفات التي لا تتسع لها استجابة واحدة ضمن notReturned، لطلبها مرة أخرى.
• تُرفض القراءة الأكبر من أن تتسع لها استجابة واحدة بالرمز tooLarge، مع بيان كيفية تضييقها.

أدوات التحرير

تأتي المعرّفات من erd_list وerd_get، أو من createdIds في الاستدعاء الذي أنشأ الكيان. يتكوّن المعرّف الجديد من 25 خانة من الأحرف الصغيرة والأرقام، مثل 03h17be2plxpj5n59tqag7ogj، بينما يحتفظ المعرّف الموجود في المستند مسبقًا بشكله، فلا تستنتج شيئًا من شكل المعرّف. x وy هما الحافتان اليسرى والعليا على لوحة الرسم، بالبكسل، واللون هو لون CSS سداسي عشري مثل #3b82f6، أو سلسلة نصية فارغة تزيل اللون.

الجداول

الأداة	الوسائط	ما تفعله
erd_add_table		تضيف جدولًا فارغًا في موضع شاغر وتُرجع معرّفه في createdIds.
erd_remove_table	tableId	تزيل جدولًا مع أعمدته وفهارسه وكل علاقة تتصل به.
erd_change_table_name	tableId, value	تعيد تسمية جدول.
erd_change_table_comment	tableId, value	تضبط تعليق جدول. السلسلة النصية الفارغة تمسحه.
erd_change_table_color	tableId, color	تضبط لون جدول.
erd_move_table	tableId, x, y	تنقل جدولًا إلى موضع على لوحة الرسم.
erd_move_tables	positions	تنقل عدة جداول في تعديل واحد، يتراجع عنه استدعاء erd_undo واحد. تحمل positions القيمة { tableId, x, y } لكل جدول، وكل جدول مرة واحدة على الأكثر.
erd_sort_tables		ترتّب كل الجداول في صفوف عبر لوحة الرسم، الأقل أعمدةً أولًا، كما ترتّبها erd_import_sql وerd_import_graphql وerd_import_dbml وerd_import_aml. تبقى جداول مجموعة الجداول معًا، ويُضبط مربع كل مجموعة ليحيط بها.

الأعمدة

الأداة	الوسائط	ما تفعله
erd_add_column	tableId	تضيف عمودًا فارغًا إلى جدول وتُرجع معرّفه في createdIds.
erd_remove_columns	tableId, columnIds	تزيل أعمدةً من جدول واحد، مع العلاقات وإدخالات الفهارس التي تستخدمها.
erd_change_column_name	tableId, columnId, value	تعيد تسمية عمود.
erd_change_column_data_type	tableId, columnId, value	تضبط نوع البيانات، مثل INT أو VARCHAR(255). ما دامت مزامنة نوع البيانات عبر العلاقات مفعّلة، يتبع التغيير العلاقات في الاتجاهين، كما يحدث في المحرر: يصل النوع serial إلى المفاتيح الخارجية بوصفه نوع العدد الصحيح الذي يخزنه، كما تنسخه erd_add_relationship، ويحتفظ مفتاح serial بنوعه حين يتغير أحد مفاتيحه الخارجية، فيتوقف التغيير عنده. تفعيل المزامنة أو تعطيلها متروك للمستخدم، وتُبلغ عنها erd_list بالاسم relationshipDataTypeSync.
erd_change_column_default	tableId, columnId, value	تضبط القيمة الافتراضية، بوصفها نص SQL. السلسلة النصية الفارغة تمسحها.
erd_change_column_comment	tableId, columnId, value	تضبط التعليق. السلسلة النصية الفارغة تمسحه.
erd_set_column_primary_key	tableId, columnId, value	القيمة true تجعل العمود جزءًا من المفتاح الأساسي، والقيمة false تُخرجه منه.
erd_set_column_unique	tableId, columnId, value	تضبط ما إذا كان العمود فريدًا.
erd_set_column_not_null	tableId, columnId, value	تضبط ما إذا كان العمود NOT NULL.
erd_set_column_auto_increment	tableId, columnId, value	تضبط ما إذا كان العمود يتزايد تلقائيًا.
erd_move_column	tableId, columnId, targetColumnId	تنقل عمودًا داخل جدوله إلى موضع عمود آخر.

العلاقات

تمثّل relationshipType التعددية عند طرف الجدول الفرعي: ZeroOne أو ZeroN أو OneOnly أو OneN. جدول البداية هو الجدول الأصل، أي الجانب المُشار إليه الذي يحمل المفتاح الأساسي، وجدول النهاية هو الجدول الفرعي. تمثّل onDelete وonUpdate إجراءي ON DELETE وON UPDATE للمفتاح الخارجي: none أو noAction أو cascade أو setNull أو setDefault أو restrict. لا تكتب القيمة none أي بند، فيُطبَّق السلوك الافتراضي لقاعدة البيانات، راجع ON DELETE وON UPDATE. الإجراء الذي لا يُذكر في erd_add_relationship أو erd_link_columns تكون قيمته none.

الأداة	الوسائط	ما تفعله
erd_add_relationship	startTableId, endTableId, relationshipType, onDelete?, onUpdate?	تربط جدولين بعلاقة. تنسخ المفتاح الأساسي للجدول الأصل إلى الجدول الفرعي بوصفه أعمدة مفتاح خارجي، وتنشئ عمود مفتاح أساسي أولًا إن لم يكن للجدول الأصل مفتاح أساسي. يُسمّى كل عمود مفتاح خارجي بالطريقة التي يسمّيه بها رسم علاقة في المحرر: المفتاح id في الجدول users يعطي users_id، ويحتفظ مفتاح مثل member_id باسمه، راجع أسماء أعمدة المفاتيح الخارجية. ينسخ كل منها نوع بيانات مفتاحه، إلا أن مفتاح serial يعطي نوع العدد الصحيح الذي يخزنه، مثل integer للنوع serial4، ويبقى النوع serial المجرد serial خارج PostgreSQL وMySQL وMariaDB، راجع العلاقات المُعرِّفة. تحمل createdIds عمود المفتاح الجديد ذاك إن أُنشئ، وأعمدة المفتاح الخارجي، ومعرّف العلاقة في الأخير.
erd_link_columns	startTableId, startColumnIds, endTableId, endColumnIds, relationshipType, onDelete?, onUpdate?	ترسم علاقة بين أعمدة موجودة بالفعل، فتقرن أعمدة البداية بأعمدة النهاية حسب موضعها. لا تعيد تسمية أي عمود ولا تغيّر أي نوع بيانات.
erd_remove_relationship	relationshipId	تزيل خط ربط علاقة. تبقى أعمدة المفتاح الخارجي الخاصة بها في الجدول.
erd_change_relationship_type	relationshipId, relationshipType	تغيّر تعددية علاقة.
erd_change_relationship_on_delete	relationshipId, onDelete	تضبط إجراء ON DELETE لعلاقة: ما يُحدثه حذف صف أصل في صفوفه الفرعية.
erd_change_relationship_on_update	relationshipId, onUpdate	تضبط إجراء ON UPDATE لعلاقة: ما يُحدثه تغيير مفتاح أصل في صفوفه الفرعية.

تسمّي erd_add_relationship أعمدة المفتاح الخارجي لحظة تشغيلها، لذا سمِّ الجدول الأصل ومفتاحه الأساسي أولًا.

لا توجد أداة تغيّر أعمدة علاقة قائمة كما يفعل تعيين الأعمدة في المحرر. لتعيين علاقة على أعمدة أخرى، شغّل erd_remove_relationship، التي تُبقي أعمدة المفتاح الخارجي الخاصة بها في الجدول، وerd_link_columns مع الأعمدة المطلوبة، في دفعة erd_batch واحدة، يتراجع عنها استدعاء erd_undo واحد.

الفهارس

معرّف عمود الفهرس هو إدخال في قائمة أعمدة الفهرس التي تعطيها erd_get، وليس معرّف عمود الجدول.

الأداة	الوسائط	ما تفعله
erd_add_index	tableId	تضيف فهرسًا فارغًا إلى جدول وتُرجع معرّفه في createdIds.
erd_remove_index	indexId	تزيل فهرسًا.
erd_change_index_name	indexId, value	تعيد تسمية فهرس.
erd_set_index_unique	indexId, value	تضبط ما إذا كان الفهرس فريدًا.
erd_add_index_column	indexId, columnId	تضيف عمودًا من جدول الفهرس وتُرجع معرّف عمود الفهرس الجديد. العمود الموجود في الفهرس بالفعل يُترك كما هو.
erd_remove_index_column	indexId, indexColumnId	تزيل عمودًا واحدًا من فهرس.
erd_move_index_column	indexId, indexColumnId, targetIndexColumnId	تنقل عمودًا داخل فهرس إلى موضع عمود آخر من أعمدته.
erd_set_index_column_order	indexId, indexColumnId, orderType	تضبط ترتيب الفرز لعمود واحد في فهرس، ASC أو DESC.

الملاحظات

الأداة	الوسائط	ما تفعله
erd_add_memo		تضيف ملاحظة فارغة في موضع شاغر وتُرجع معرّفها في createdIds.
erd_remove_memo	memoId	تزيل ملاحظة.
erd_change_memo_value	memoId, value	تستبدل نص ملاحظة.
erd_change_memo_color	memoId, color	تضبط لون ملاحظة.
erd_move_memo	memoId, x, y	تنقل ملاحظة إلى موضع على لوحة الرسم.
erd_resize_memo	memoId, width, height	تغيّر حجم ملاحظة. يجب أن يكون العرض نحو 116 بكسل على الأقل والارتفاع 100 على الأقل. لا تُنشئ إدخال تراجع، لأن المحرر لا يسجّل تغيير حجم الملاحظة إلا من السحب.

أثناء إخفاء الملاحظات عبر View Option → Memos، تضيف erd_add_memo ملاحظةً رغم ذلك، وتبقى مخفيةً حتى تُظهَر الملاحظات من جديد. تسرد erd_list وerd_get الملاحظات المخفية أيضًا.

مجموعات الجداول

مجموعة الجداول مربع مسمّى يُرسم خلف جداولها، ويظهر لونها على المربع وعبر رؤوس جداولها، راجع مجموعات الجداول. ينتمي الجدول إلى مجموعة واحدة على الأكثر. لا تغيّر erd_move_table وerd_move_tables وerd_move_table_group أبدًا الجداول التي تضمها المجموعة، أينما وضعت جدولًا، بينما في المحرر ينضم الجدول إلى مجموعة أو يغادرها حيث يُفلَت، راجع إضافة الجداول وإزالتها. تضع erd_add_table_group وerd_set_table_group الجداول في مجموعة، وتترك erd_remove_table_group جداولها خارج أي مجموعة. تخزن المجموعة مستطيلًا لا يقل عرضه عن 160 بكسل وارتفاعه عن 100، بما في ذلك شريط العنوان، ويرسم المحرر المربع موسّعًا ليتسع لكل جدول من جداولها.

الأداة	الوسائط	ما تفعله
erd_add_table_group	name, color?, x?, y?, width?, height?, tableIds?	تضيف مجموعة وتُرجع معرّفها في createdIds. مرّر إما tableIds وإما مستطيلًا، أي x وy وwidth وheight معًا. مع tableIds، يغادر كل جدول أي مجموعة كان فيها، ويُضبط المستطيل ليحيط بها كما يضبطه تجميع الجداول المحددة. يضم المستطيل كل جدول لا ينتمي إلى أي مجموعة ويقع مركزه داخله، كما يفعل رسم مجموعة. إذا كانت name فارغة، تبقى المجموعة بلا اسم. استدعاء erd_undo واحد يزيل المجموعة ويعيد كل جدول إلى المجموعة التي كان فيها.
erd_remove_table_group	groupId	تزيل مجموعة. تبقى جداولها في أماكنها، خارج أي مجموعة.
erd_change_table_group_name	groupId, value	تعيد تسمية مجموعة. السلسلة النصية الفارغة تتركها بلا اسم.
erd_change_table_group_color	groupId, color	تضبط لون مجموعة.
erd_move_table_group	groupId, x, y	تنقل مجموعة بحيث يبدأ مستطيلها عند تلك النقطة، مع جداولها بالمقدار نفسه، كما يفعل سحب شريط عنوانها. النقل الذي يقل عن 20 بكسلًا، بجمع الإزاحتين الأفقية والرأسية، لا يُنشئ إدخال تراجع.
erd_resize_table_group	groupId, x?, y?, width, height	تضبط مستطيل مجموعة، وتبقى جداولها في أماكنها. إغفال x وy يُبقي زاويتها. يُرفض المستطيل الذي لا يتسع لجداول المجموعة مع هوامشها الداخلية، مع رسالة تحدد المربع الذي يجب أن يتسع له.
erd_set_table_group	tableIds, groupId	تضع جداول في مجموعة، فيغادر كل منها أي مجموعة كان فيها. القيمة null أو السلسلة النصية الفارغة في groupId تُخرج الجداول من كل المجموعات.

أثناء إخفاء المجموعات عبر View Option → Table Groups، تضيف هذه الأدوات المجموعات وتغيّرها رغم ذلك، وتبقى المجموعات مخفيةً حتى تُظهَر، راجع إخفاء المجموعات. تُبقي erd_sort_tables جداول كل مجموعة معًا، وتجلب erd_import_dbml وerd_import_json المجموعات — راجع الاستيراد — وتكتب erd_read نص DDL لمجموعات مختارة باستخدام groupNames. يُسقط أي إصدار من ERD Editor يسبق ظهور مجموعات الجداول مجموعاتِ الملف عند حفظه، كما تفعل إضافة VS Code قبل الإصدار 4.0.0 ومكوّنا Obsidian وJetBrains الإضافيان قبل الإصدار 1.0.0، راجع التحديث.

الإعدادات

يضبط الوكيل إعدادات المخطط نفسه: قاعدة البيانات واسمها وسكربتات مخطط SQL. أما كل إعداد آخر يخزنه المستند فضبطه متروك للمستخدم في المحرر: مفاتيح تبديل خيارات العرض، وخيارات علامة تبويب الإعدادات، ولغة منشئ التعليمات البرمجية وأنماط التسمية فيه، ونوع علامات الاقتباس، والأقفال. لا تغيّرها أي أداة، باستثناء أدوات الاستيراد في الوضع replace: تجلب erd_import_json إعدادات المستند الذي تحمّله وأقفاله، وتعيد الأدوات الأربع الأخرى العرض إلى بداية لوحة الرسم، راجع الاستيراد. أزال الإصدار 1.0.0 من الخادم الأدوات التي كانت تضبطها: erd_set_language وerd_set_table_name_case وerd_set_column_name_case وerd_set_bracket_type وerd_set_relationship_data_type_sync وerd_set_relationship_optimization وerd_set_column_order وerd_set_max_width_comment وerd_set_ignore_save_settings وerd_set_show.

تُبلغ erd_list والتنسيق snapshot في erd_read عن الإعدادات كما يحفظها الملف، وتحمل lockSettings علامة واحدة لكل قفل: viewport وcanvasType وlanguage وtableNameCase وcolumnNameCase وbracketType. يُبلَّغ عن اللغة أو نمط التسمية أو نوع علامات الاقتباس المقفل بقيمته المقفلة، وهي القيمة التي يحتفظ بها الملف ويُفتح عليها كل محرر، أيًّا كان ما تعرضه شاشة المحرر. ولا يُبلَّغ عن العرض وعلامة التبويب.

تُنشئ erd_set_ddl_script إدخال تراجع. أما erd_set_database وerd_set_database_name فلا تُنشئان أي إدخال، لذا لا تستطيع erd_undo التراجع عنهما.

الأداة	الوسائط	ما تفعله
erd_set_database	value	تضبط قاعدة البيانات: MariaDB أو MSSQL أو MySQL أو Oracle أو PostgreSQL أو SQLite أو Databricks أو Snowflake. ويحدد ذلك أنواع بيانات قاعدة البيانات، ونص DDL الذي تكتبه erd_read حين لا تُعطى vendor.
erd_set_database_name	value	تضبط اسم قاعدة البيانات، الذي تذكره الترويستان use وcreateAndUse في erd_read.
erd_set_ddl_script	position, sql	تضبط أحد السكربتين اللذين يُكتبان حول الجداول، راجع السكربتات قبل الجداول وبعدها. قيمة position إما before، أي السكربت المكتوب قبل الجداول، مثل CREATE EXTENSION أو CREATE SCHEMA، وإما after، أي السكربت المكتوب بعدها، مثل GRANT أو CREATE VIEW. تستبدل sql السكربت كله، بحد أقصى 10,000 حرف، وتزيله السلسلة النصية الفارغة. اقرأ السكربت الحالي أولًا باستخدام التنسيق scripts في erd_read.

يدخل السكربت كما هو في DDL كل قاعدة بيانات، لذا اكتبه لقاعدة بيانات المستند. في MSSQL، يُضاف سطر GO بعد السكربت الذي لا يكون سطره الأخير GO. يُسقط أي إصدار من ERD Editor يسبق ظهور هذه السكربتات سكربتاتِ الملف عند حفظه، كما تفعل إضافة VS Code قبل الإصدار 4.0.0 ومكوّنا Obsidian وJetBrains الإضافيان قبل الإصدار 1.0.0، راجع التحديث.

الاستيراد

تقرأ هذه الأدوات المخطط بالطريقة التي تقرؤه بها قائمة الاستيراد في المحرر، راجع استيراد الملفات وتصديرها. تأخذ كل منها النص في value، وmode: replace، وهي القيمة الافتراضية، أو append.

الأداة	الوسائط	ما تفعله
erd_import_sql	value, mode?	تحمّل DDL بلغة SQL، كعبارات CREATE TABLE وما شابهها.
erd_import_graphql	value, mode?	تحمّل SDL بلغة GraphQL.
erd_import_dbml	value, mode?	تحمّل DBML. يصبح كل TableGroup مجموعةَ جداول تضم الجداول التي يسمّيها، راجع DBML.
erd_import_aml	value, mode?	تحمّل AML.
erd_import_json	value, mode?	تحمّل مستند JSON من erd-editor، مثل ملف .erd.json آخر.

يستبدل الوضع replace المستند، وتستعيد erd_undo المستند الذي كان قبله:

• تستبدل erd_import_sql وerd_import_graphql وerd_import_dbml وerd_import_aml كل جدول وعلاقة وفهرس وملاحظة ومجموعة جداول. وتُبقي إعدادات المستند، بما فيها أقفاله، باستثناء العرض الذي يعود إلى بداية لوحة الرسم بمستوى تكبير 100%.
• تستبدل erd_import_json المستند كله، بما في ذلك إعداداته: تحل إعدادات JSON وأقفاله محل ما في هذا المستند، وملف JSON الذي لا يسجّل أي أقفال يفعّل كل الأقفال ويضع العرض عند بداية لوحة الرسم. للإبقاء على إعدادات هذا المستند، ابدأ من النص الذي يعطيه التنسيق json في erd_read. النص الفارغ يعطي مستندًا جديدًا، مثل الذي تنشئه erd_open_document مع create.

يضيف الوضع append ما يُستورد إلى المستند، كما يفعل استيراد وإضافة في المحرر، ويزيل استدعاء erd_undo واحد الإضافة كلها:

• يدخل ما يحتويه النص بوصفه كيانات جديدة بمعرّفات جديدة، في كتلة أسفل كل ما يحويه المستند، بما في ذلك الملاحظات المخفية ومجموعات الجداول، ومحاذيةً لحافته اليسرى. يبقى كل جدول وإعداد موجود بالفعل، بما في ذلك الجدول الذي يحمل الاسم نفسه: لا يُدمج شيء بالاسم.
• لا تأتي العلاقات والفهارس إلا بين الجداول التي يجلبها الاستيراد، لذا يُسقَط المفتاح الخارجي المشير إلى جدول لا يصرّح به النص.
• تضيف erd_import_sql وerd_import_graphql وerd_import_aml الجداول مع علاقاتها وفهارسها، وتضيف erd_import_dbml مجموعات الجداول أيضًا. تضيف erd_import_json الجداول والعلاقات والفهارس والملاحظات ومجموعات الجداول، ولا تضيف إعدادات JSON أبدًا، وترفض النص الفارغ.

يحتفظ مستند JSON بترتيبه الخاص، بما في ذلك مجموعات جداوله: حيث يضع جداوله مع replace، وداخل الكتلة المضافة مع append. تُرتَّب جداول SQL وGraphQL وDBML وAML في صفوف، الأقل أعمدةً أولًا مع إبقاء جداول كل مجموعة معًا، كما ترتّبها erd_sort_tables، ولا تُرتَّب أبدًا حسب Flow كما يرتّبها الاستيراد في المحرر نفسه حين يستطيع. ترفض هذه الأدوات الأربع النص الفارغ في كلا الوضعين.

erd_batch

تشغّل erd_batch عدة أدوات تحرير بالترتيب بوصفها تعديلًا واحدًا، كلها أو لا شيء.

• تحمل operations حتى 100 إدخال، كل منها { tool, as?, args? }، حيث args هي وسائط الأداة دون path.
• تُجرَّب العمليات على نسخة من المستند أولًا. تُذكر العملية المرفوضة باسمها، مثل operations[1] erd_remove_table: …، ولا يُطبَّق شيء.
• يتراجع استدعاء erd_undo واحد عن الدفعة كلها، باستثناء العمليات التي لا يستطيع التراجع عنها، والتي يذكرها undoNote في النتيجة: عمليات أداة لا تُنشئ إدخال تراجع، مثل erd_set_database، والعمليات التي غيّرت المستند دون إنشاء إدخال، مثل نقل قصير عبر erd_move_table_group. تتخطى erd_undo الدفعة التي لم تُنشئ أي إدخال تراجع على الإطلاق. يَعُدّ historyEntries في النتيجة إدخالات سجل المحرر داخل الدفعة، لا استدعاءات erd_undo.
• في الجلسة المباشرة، يقبل المحرر الدفعة كلها أو لا يقبل منها شيئًا.

لا يستطيع الوكيل معرفة المعرّفات التي تنشئها الدفعة قبل استدعائها، لذا تتيح العملية المسمّاة باستخدام as لعملية لاحقة الإشارة إليها: $name أو $name.0 لأول معرّف أنشأته، و$name.1 لثانيها، و$name.last لآخرها. يتكوّن الاسم من أحرف ASCII وأرقام وشرطات سفلية، ولا يبدأ برقم، ولا يسمّي إلا عملية واحدة. لا تُحَل الإشارة إلا حيث تأخذ الوسيطة معرّف كيان، لذا يبقى الاسم أو التعليق الذي نصه $x نصًا عاديًا.

جدول بأعمدته وعلاقة، في استدعاء واحد:

{
  "path": "shop.erd.json",
  "operations": [
    { "tool": "erd_add_table", "as": "users" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$users", "value": "users" } },
    { "tool": "erd_add_column", "as": "uid", "args": { "tableId": "$users" } },
    { "tool": "erd_change_column_name", "args": { "tableId": "$users", "columnId": "$uid", "value": "id" } },
    { "tool": "erd_change_column_data_type", "args": { "tableId": "$users", "columnId": "$uid", "value": "BIGINT" } },
    { "tool": "erd_set_column_primary_key", "args": { "tableId": "$users", "columnId": "$uid", "value": true } },
    { "tool": "erd_add_table", "as": "orders" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$orders", "value": "orders" } },
    { "tool": "erd_add_relationship", "args": { "startTableId": "$users", "endTableId": "$orders", "relationshipType": "ZeroN", "onDelete": "cascade" } }
  ]
}

يُسمّى users ومفتاحه id قبل العلاقة، لذا يكون عمود المفتاح الخارجي الذي تضيفه العلاقة إلى orders هو users_id.

النتائج

يُرجع التعديل سطرًا واحدًا من JSON:

{"tool":"erd_add_table","mode":"live","createdIds":["03h17be2plxpj5n59tqag7ogj"],"batches":1,"historyEntries":1}

الحقل	المعنى
mode	live أو headless، راجع الوضع المباشر والوضع بدون واجهة.
createdIds	معرّفات ما أنشأه الاستدعاء، بالترتيب.
batches, historyEntries	عدد دفعات التغيير التي أرسلها الاستدعاء وعدد إدخالات سجل المحرر التي أنشأها.
undoable, undoNote	تكون قيمة undoable هي false حين ستتخطى erd_undo الاستدعاء، ويذكر undoNote السبب: الأداة لا تُنشئ إدخال تراجع، أو الاستدعاء غيّر المستند دون إنشاء إدخال، كما يفعل نقل عبر erd_move_table_group بأقل من 20 بكسلًا، أو المستند كان يحمل القيمة بالفعل. تحمل نتيجة erd_batch دائمًا undoNote. حين تُنشئ الدفعة إدخال تراجع، تذكر الملاحظة أن استدعاء erd_undo واحدًا يتراجع عن الدفعة وتسمّي أي عملية يتركها كما هي؛ وحين لا تُنشئ أي إدخال، تحمل النتيجة undoable: false وتذكر الملاحظة أن erd_undo تتخطاها.
mismatch	يظهر حين يُنشئ الاستدعاء عددًا من الدفعات أو إدخالات السجل يختلف عما تعلنه الأداة.
notes	يظهر حين يتغير شيء في الجلسة، مثل محرر أُغلق أو توقف عن خدمة المستند، أو ملف تغيّر على القرص.

الرفض نتيجة خطأ تحمل رمزًا ورسالةً تذكر ما يجب فعله:

{"error":{"code":"notFound","message":"tableId nope names no live table; read the document for current ids"}}

code	السبب
notFound	معرّف لا يشير إلى أي شيء موجود حاليًا، أو الملف غير موجود.
invalidArgs	وسيطة مفقودة أو ذات قيمة خاطئة.
invalidPath	المسار ليس مستند ERD. على Windows، يشمل أيضًا مسارًا فيه اسم لا يخزنه Windows كما كُتب، أو مسارًا يصل إلى مستند يحتفظ به محرر تحت مسار آخر، تذكره الرسالة.
invalidDocument	الملف ليس مستندًا يستطيع المحرر قراءته.
tooLarge	القراءة لا تتسع لها استجابة واحدة.
blocked	يحتفظ بالمستند محرر محوره معطّل. تذكر الرسالة كيفية تفعيله: في VS Code، ثق بمساحة العمل وفعّل dineug.erd-editor.agentHub.enabled، أو أعد تحميل النافذة؛ في Obsidian، فعّل Coding agents، أو أعد تحميل Obsidian؛ في بيئة تطوير JetBrains، فعّل Coding agents، أو أعد تشغيل بيئة التطوير إن كان مفعّلًا.
hubDisabled	لا تحتفظ بيئة تطوير JetBrains بالمستند إلا في مشروع لا تثق به. تظل القراءة ممكنة؛ ثق بالمشروع ليتمكن الوكيل من التحرير.
conflict	تغيّر الملف على القرص أثناء الاستدعاء. لم يُكتب شيء.
hubAppeared, hubGone	بدأ محرر يخدم مستندًا كان الوكيل يحرره على القرص، أو أن المحرر الذي كان يخدمه لا يزال يعمل لكن ملف القفل الخاص به واتصاله قد اختفيا. لم يُكتب شيء.
notSaved	لم تتمكن erd_save من حفظ مستند المحرر.
readonly	يحتفظ المحرر بالمستند للقراءة فقط، مثل ملف لا يستطيع الكتابة فيه أو لا يستطيع قراءته بوصفه مخططًا. في غياب المحرر، يكون الملف نفسه للقراءة فقط، مثل ملف Perforce أو TFVC لم يُسحب للتحرير. لم يُكتب شيء.
protocolMismatch	تستخدم إضافة ERD Editor أو مكوّنه الإضافي في المحرر والخادم إصدارين مختلفين من البروتوكول، مثل الخادم بالإصدار 1.0.0 مع إضافة VS Code بالإصدار 3.x. تُرفض القراءات أيضًا، وتذكر الرسالة الطرف الذي يجب تحديثه، راجع التحديث.
hubUnreachable, timeout, disconnected	لم يقبل محور المحرر الاتصال، أو لم يُجب خلال 30 ثانية، أو قطع الاتصال أثناء الاستدعاء. على Windows، يعني الرمز hubUnreachable أيضًا أن Windows منع الوكيل من الوصول إلى المحور: يعمل المحرر بصلاحيات أعلى من صلاحيات الوكيل، كأن يكون قد شُغّل بصفة مسؤول ولم يُشغَّل الوكيل كذلك، أو يعمل الوكيل في بيئة معزولة.

الرموز الأخرى أندر، وكل رفض يحمل رسالة تذكر ما حدث.

ترفض أدوات التحرير وerd_batch وأدوات القراءة الثلاث أي وسيطة لا تعلنها، أو وسيطة من نوع خاطئ، بخطأ الوسائط غير الصالحة في JSON-RPC (-32602) قبل المساس بالمستند، لذا لا تُسقَط أبدًا وسيطة مكتوبة خطأً دون تنبيه. تتجاهل أدوات الجلسة الخمس الوسائط التي لا تعرفها.