mcp-dbutils

<div dir="rtl"> # دليل الاستخدام *[English](../en/usage.md) | [中文](../zh/usage.md) | [Français](../fr/usage.md) | [Español](../es/usage.md) | العربية | [Русский](../ru/usage.md)* يقدم هذا المستند تعليمات مفصلة لاستخدام MCP Database Utilities، مما يساعدك على الاستفادة الكاملة من قدراتها لتحليل البيانات باستخدام الذكاء الاصطناعي. ## سير العمل الأساسي سير العمل الأساسي لاستخدام MCP Database Utilities هو كما يلي: 1. **تكوين اتصالات قاعدة البيانات**: حدد اتصالات قاعدة البيانات الخاصة بك في ملف `config.yaml` 2. **بدء خدمة MCP**: قم بتشغيل الخدمة من خلال تكوين عميل الذكاء الاصطناعي الخاص بك 3. **التفاعل مع الذكاء الاصطناعي**: اطرح أسئلة حول قواعد البيانات الخاصة بك باستخدام اللغة الطبيعية 4. **عرض النتائج**: سينفذ الذكاء الاصطناعي الاستعلامات اللازمة ويقدم النتائج بتنسيق سهل الفهم ## الأدوات المتاحة توفر MCP Database Utilities عدة أدوات يمكن للذكاء الاصطناعي الخاص بك استخدامها: ### dbutils-list-connections يسرد جميع اتصالات قاعدة البيانات المتاحة مع معلومات مفصلة تشمل نوع قاعدة البيانات والمضيف والمنفذ واسم قاعدة البيانات، مع إخفاء المعلومات الحساسة مثل كلمات المرور. المعلمة الاختيارية check_status تسمح بالتحقق مما إذا كان كل اتصال متاحًا، على الرغم من أن هذا قد يزيد من وقت الاستجابة. استخدم هذه الأداة عندما تحتاج إلى فهم موارد قاعدة البيانات المتاحة أو تشخيص مشكلات الاتصال. **مثال على التفاعل**: **أنت**: "ما هي اتصالات قاعدة البيانات المتاحة لدي؟" **الذكاء الاصطناعي**: "سأتحقق من اتصالات قاعدة البيانات المتاحة لديك. إليك ما وجدته: 1. **postgres-db** - النوع: PostgreSQL - المضيف: localhost - قاعدة البيانات: analytics - المستخدم: analyst 2. **sqlite-db** - النوع: SQLite - المسار: /path/to/database.db 3. **mysql-db** - النوع: MySQL - المضيف: db.example.com - قاعدة البيانات: customer_data - المستخدم: reader" ### dbutils-list-tables يسرد جميع الجداول في اتصال قاعدة البيانات المحدد مع أسماء الجداول وعناوين URI والأوصاف المتاحة، مجمعة حسب نوع قاعدة البيانات لسهولة التعرف عليها. هذه الأداة مفيدة لاستكشاف بنية قاعدة البيانات وفهم الجداول المتاحة للتحليل. **مثال على التفاعل**: **أنت**: "قم بسرد جميع الجداول في قاعدة بيانات postgres الخاصة بي." **الذكاء الاصطناعي**: "سأتحقق من ذلك لك. إليك الجداول في قاعدة بيانات postgres الخاصة بك: - العملاء - المنتجات - الطلبات - المخزون - الموظفون" ### dbutils-run-query ينفذ استعلامات SQL للقراءة فقط (SELECT فقط) على قاعدة البيانات المحددة، مع دعم للاستعلامات المعقدة، بما في ذلك JOIN وGROUP BY ووظائف التجميع، مع إرجاع نتائج منظمة تتضمن أسماء الأعمدة وصفوف البيانات. هذه الأداة ضرورية لاستخراج معلومات محددة من قواعد البيانات وإجراء تحليلات مخصصة. **مثال على التفاعل**: **أنت**: "استعلم عن عدد العملاء الذين سجلوا في آخر 30 يومًا." **الذكاء الاصطناعي**: "سأتحقق من ذلك لك. وفقًا للبيانات، كان هناك 42 تسجيلًا جديدًا للعملاء في آخر 30 يومًا." ### dbutils-describe-table يوفر معلومات مفصلة عن بنية الجدول، بما في ذلك أسماء الأعمدة وأنواع البيانات وإمكانية الخلو والقيم الافتراضية والتعليقات بتنسيق سهل القراءة. هذه الأداة مفيدة بشكل خاص لفهم مخطط الجدول قبل تنفيذ الاستعلامات أو تحليل البيانات. **مثال على التفاعل**: **أنت**: "صف بنية جدول العملاء." **الذكاء الاصطناعي**: "إليك بنية جدول العملاء: | العمود | النوع | قابل للخلو | افتراضي | الوصف | |---------|------|----------|--------|-------------| | id | INTEGER | لا | NULL | معرف فريد للعميل | | name | VARCHAR(100) | لا | NULL | الاسم الكامل للعميل | | email | VARCHAR(100) | لا | NULL | عنوان البريد الإلكتروني (فريد) | | registration_date | DATE | لا | CURRENT_DATE | تاريخ التسجيل | | last_login | TIMESTAMP | نعم | NULL | الطابع الزمني لآخر تسجيل دخول | | status | ENUM | لا | 'نشط' | حالة الحساب (نشط، غير نشط، معلق) |" ### dbutils-get-ddl يسترجع بيان DDL (لغة تعريف البيانات) الكامل لإنشاء الجدول المحدد، بما في ذلك جميع تعريفات الأعمدة والقيود والفهارس. هذه الأداة مفيدة لفهم التعريف الدقيق للجدول أو لإعادة إنشاء بنية جدول مماثلة في بيئة أخرى. **مثال على التفاعل**: **أنت**: "أظهر لي DDL لجدول الطلبات." **الذكاء الاصطناعي**: "إليك بيان DDL لجدول الطلبات: ```sql CREATE TABLE orders ( order_id INT PRIMARY KEY AUTO_INCREMENT, customer_id INT NOT NULL, order_date DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, total_amount DECIMAL(10,2) NOT NULL CHECK (total_amount > 0), status VARCHAR(20) NOT NULL DEFAULT 'pending', FOREIGN KEY (customer_id) REFERENCES customers(id) ); CREATE INDEX idx_order_date ON orders(order_date); CREATE INDEX idx_customer_id ON orders(customer_id); ```" ### dbutils-list-indexes يسرد جميع الفهارس على الجدول المحدد، بما في ذلك أسماء الفهارس والأنواع (فريد/غير فريد) وطرق الفهرسة والأعمدة المضمنة، مجمعة حسب اسم الفهرس. هذه الأداة مفيدة لفهم كيفية فهرسة الجدول، مما يمكن أن يساعد في تحسين الاستعلامات وتحسين الأداء. **مثال على التفاعل**: **أنت**: "ما هي الفهارس الموجودة على جدول المنتجات؟" **الذكاء الاصطناعي**: "إليك الفهارس على جدول المنتجات: 1. **pk_product_id** (أساسي) - الأعمدة: product_id - النوع: B-tree - فريد: نعم 2. **idx_category** (ثانوي) - الأعمدة: category_id - النوع: B-tree - فريد: لا 3. **idx_product_name** (ثانوي) - الأعمدة: name - النوع: B-tree - فريد: لا 4. **idx_price_category** (ثانوي) - الأعمدة: price, category_id - النوع: B-tree - فريد: لا" ### dbutils-get-stats يسترجع معلومات إحصائية عن الجدول، بما في ذلك العدد التقديري للصفوف ومتوسط طول الصف وحجم البيانات وحجم الفهرس. هذه الإحصائيات مفيدة لفهم حجم البيانات وتخطيط تحسينات الأداء. **مثال على التفاعل**: **أنت**: "احصل على إحصائيات لجدول المنتجات." **الذكاء الاصطناعي**: "إليك إحصائيات جدول المنتجات: - إجمالي الصفوف: 1,245 - حجم الجدول: 2.3 ميجابايت - إحصائيات العمود: * product_id: 1,245 قيمة فريدة * الفئة: 8 فئات مختلفة * السعر: متوسط $45.99، الحد الأدنى $5.99، الحد الأقصى $299.99" ### dbutils-list-constraints يسرد جميع القيود على الجدول، بما في ذلك المفاتيح الأساسية والمفاتيح الخارجية والقيود الفريدة وقيود التحقق، مع الجداول والأعمدة المرجعية للمفاتيح الخارجية. هذه الأداة مفيدة لفهم العلاقات بين الجداول وقواعد سلامة البيانات. **مثال على التفاعل**: **أنت**: "أظهر القيود لجدول الطلبات." **الذكاء الاصطناعي**: "جدول الطلبات له القيود التالية: - المفتاح الأساسي: order_id - المفتاح الخارجي: customer_id يشير إلى العملاء(id) - المفتاح الخارجي: product_id يشير إلى المنتجات(id) - قيد التحقق: order_amount > 0" ### dbutils-explain-query يوفر خطة تنفيذ لاستعلام SQL، موضحًا كيف سيعالج محرك قاعدة البيانات الاستعلام، بما في ذلك طرق الوصول وأنواع الربط والتكاليف المقدرة. هذه الأداة ضرورية لفهم وتحسين أداء الاستعلامات المعقدة. **مثال على التفاعل**: **أنت**: "اشرح خطة التنفيذ لهذا الاستعلام: SELECT * FROM orders WHERE customer_id = 123" **الذكاء الاصطناعي**: "خطة التنفيذ لهذا الاستعلام هي: 1. فحص الفهرس: باستخدام فهرس customer_id_idx 2. التكلفة المقدرة: 12.5 3. الصفوف المقدرة: 8 4. شرط التصفية: customer_id = 123" ### dbutils-get-performance يسترجع مقاييس الأداء لاتصال قاعدة البيانات، بما في ذلك عدد الاستعلامات ومتوسط وقت التنفيذ واستخدام الذاكرة وإحصاءات الأخطاء. هذه المعلومات قيمة لمراقبة صحة قاعدة البيانات وتحديد نقاط الاختناق المحتملة. **مثال على التفاعل**: **أنت**: "احصل على مقاييس الأداء لقاعدة البيانات." **الذكاء الاصطناعي**: "مقاييس أداء قاعدة البيانات الحالية: - وقت تنفيذ الاستعلام: متوسط 45 مللي ثانية - معدل إصابة ذاكرة التخزين المؤقت: 87% - الاتصالات النشطة: 3 - معدل الخطأ الأخير: 0.2%" ### dbutils-analyze-query يحلل خصائص أداء استعلام SQL، مع توفير خطة التنفيذ ووقت التنفيذ الفعلي وتوصيات محددة للتحسين. تتجاوز هذه الأداة التفسير البسيط من خلال تحديد المشكلات المحتملة واقتراح تحسينات ملموسة لتسريع تنفيذ الاستعلامات. **مثال على التفاعل**: **أنت**: "حلل هذا الاستعلام: SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id WHERE order_date > '2023-01-01'" **الذكاء الاصطناعي**: "نتائج تحليل الاستعلام: 1. مشكلة الأداء: استخدام SELECT * يسترجع أعمدة غير ضرورية 2. فهرس مفقود: لا يوجد فهرس على عمود order_date 3. اقتراحات التحسين: - حدد فقط الأعمدة المطلوبة - أضف فهرسًا على عمود order_date - فكر في إضافة عبارة LIMIT لتقييد عدد النتائج" ## سيناريوهات الاستخدام الشائعة ### 1. استكشاف البيانات **أنت**: "أريد فهم بنية قاعدة البيانات الخاصة بي." **الذكاء الاصطناعي**: "يمكنني مساعدتك في استكشاف بنية قاعدة البيانات الخاصة بك. دعني أسرد جميع الجداول، ثم يمكنك اختيار واحد لمعرفة المزيد عن بنيته." **أنت**: "حسنًا، قم بسرد جميع الجداول." **الذكاء الاصطناعي**: "تحتوي قاعدة البيانات الخاصة بك على الجداول التالية: - العملاء - المنتجات - الطلبات - المخزون - الموظفون عن أي جدول ترغب في معرفة المزيد؟" **أنت**: "أخبرني عن بنية جدول العملاء." **الذكاء الاصطناعي**: "جدول العملاء له البنية التالية: - id (عدد صحيح، مفتاح أساسي) - name (varchar(100)، غير فارغ) - email (varchar(100)، فريد، غير فارغ) - registration_date (تاريخ، غير فارغ) - last_login (طابع زمني) - status (تعداد: 'نشط'، 'غير نشط'، 'معلق')" ### 2. تحليل البيانات **أنت**: "حلل اتجاهات المبيعات على مدار الأشهر الستة الماضية." **الذكاء الاصطناعي**: "سأحلل اتجاهات المبيعات على مدار الأشهر الستة الماضية. دعني أنفذ بعض الاستعلامات..." [ينفذ الذكاء الاصطناعي استعلامات متعددة، ويحلل بيانات المبيعات] **الذكاء الاصطناعي**: "بناءً على تحليل الأشهر الستة الماضية: 1. إجمالي المبيعات: $1,245,678، بزيادة 15% عن الأشهر الستة السابقة 2. المنتج الأكثر مبيعًا: المنتج X، يمثل 23% من إجمالي المبيعات 3. فترات ذروة المبيعات: أيام الجمعة والسبت، تمثل 45% من إجمالي المبيعات 4. معدل الاحتفاظ بالعملاء: 78%، بزيادة 5% عن الأشهر الستة السابقة" ### 3. تحليل عبر قواعد البيانات **أنت**: "قارن بنية جدول المستخدمين بين قواعد بيانات الإنتاج والاختبار." **الذكاء الاصطناعي**: "سأقارن بنية جدول المستخدمين بين قاعدتي البيانات..." [يستعلم الذكاء الاصطناعي عن بنية الجداول في كلتا قاعدتي البيانات] **الذكاء الاصطناعي**: "الاختلافات في بنية جدول المستخدمين بين قواعد بيانات الإنتاج والاختبار: 1. الإنتاج لديه عمود إضافي 'last_login_ip' (varchar(45)) 2. عمود 'email' في قاعدة بيانات الاختبار ليس له قيد فريد 3. الإنتاج لديه فهرس إضافي: idx_user_status 4. قاعدة بيانات الاختبار تفتقر إلى قيد المفتاح الخارجي: fk_user_role" ## أفضل الممارسات ### تحسين الاستعلام 1. **تحديد حجم مجموعة النتائج**: استخدم عبارات LIMIT لتقييد عدد الصفوف المرجعة 2. **تحديد الأعمدة الضرورية فقط**: تجنب استخدام SELECT * 3. **استخدام الأعمدة المفهرسة**: استخدم الأعمدة ذات الفهارس في عبارات WHERE 4. **تجنب العمليات الحسابية المعقدة**: انقل العمليات الحسابية المعقدة إلى طبقة التطبيق ### توصيات الأمان 1. **استخدام حسابات للقراءة فقط**: قم بإنشاء حسابات قاعدة بيانات مخصصة للقراءة فقط لوصول الذكاء الاصطناعي 2. **تقييد الوصول إلى الجداول**: امنح الوصول فقط إلى الجداول الضرورية 3. **استخدام SSL/TLS**: قم بتمكين التشفير لاتصالات قاعدة البيانات عن بُعد 4. **تدوير كلمات المرور بانتظام**: قم بتغيير كلمات مرور قاعدة البيانات بشكل دوري ### تحسين الأداء 1. **تكوين مجمع الاتصال**: اضبط حجم مجمع الاتصال بناءً على استخدامك 2. **إعدادات مهلة الاستعلام**: قم بتعيين مدة مهلة معقولة للاستعلام 3. **تخزين النتائج مؤقتًا**: فكر في التخزين المؤقت للبيانات التي يتم الاستعلام عنها بشكل متكرر 4. **مراقبة الأداء**: تحقق بانتظام من مقاييس الأداء لتحديد المشكلات المحتملة ## استكشاف الأخطاء وإصلاحها إذا واجهت مشكلات أثناء الاستخدام، راجع قسم استكشاف الأخطاء وإصلاحها في [دليل التثبيت](installation.md) أو راجع [الوثائق التقنية](technical/architecture.md) للحصول على معلومات أكثر تفصيلاً. </div>