عن المشروع

QueryAPIGate هي خدمة Flask ذاتية الاستضافة تعمل كخدمة واحدة، وتنفذ SQL ضد قواعد بياناتك وتعيد النتائج بصيغ JSON أو NDJSON أو XML أو YAML أو CSV أو TSV أو Excel. احفظ استعلامًا مرة واحدة ليصبح نقطة نهاية REST مُرقّمة بمعلمات مكتوبة وآمنة من الحقن، مع سجل تشغيل، دون الحاجة لكتابة وحدات تحكم أو طبقات مستودع أو ترقيم صفحات أو مصادقة أو تسلسل. يدعم الخدمة قواعد بيانات متعددة مع برامج تشغيل أصلية لـ MySQL وPostgreSQL وClickHouse وSQLite وH2 وDuckDB، بالإضافة إلى JDBC عام لأي قاعدة بيانات تحتوي على ملف برنامج تشغيل (مثل Oracle وSQL Server وDB2 وSnowflake). تنطبق نفس حماية SQL والتجميع وربط المعلمات وصيغ الإخراج بغض النظر عن قاعدة البيانات الأساسية. ميزات الأمان والتحكم في الوصول: - مصادقة بمفاتيح API مع تخزين المفاتيح بتجزئة SHA-256. - تشفير كلمات مرور اتصالات قاعدة البيانات في وضع السكون عبر QUERYAPIGATE_SECRET_KEY، وفك تشفيرها فقط في الذاكرة عند فتح الاتصال. - مفاتيح API محددة النطاق: تقييد المفتاح باتصالات محددة و/أو قائمة مسموح بها من الاستعلامات المحفوظة؛ الوصول للكتابة معطل ما لم يُفعَّل صراحةً. - المجموعات: تجميع الاستعلامات المحفوظة ومنح المفتاح مجموعة كاملة؛ نقل استعلام يعرض معاينة للمفاتيح التي ستكسب أو تفقد الوصول. - أدوار الأذونات المسماة: قوالب قابلة لإعادة الاستخدام تُنسخ على المفتاح عند الإنشاء. - انتهاء صلاحية مفتاح API، والإلغاء، وتحديد المعدل لكل مفتاح، وقائمة السماح بعناوين IP (نطاقات CIDR). - حماية SQL تسمح فقط بجمل SELECT/WITH/SHOW/DESCRIBE/EXPLAIN المفردة افتراضيًا، مع معلمات :name مرتبطة. الاستعلامات المحفوظة مُرقّمة—الحفظ تحت نفس الاسم ينشئ إصدارًا جديدًا بدلاً من الكتابة فوقه، و?version=1 لا يزال يشغل الإصدار السابق. يمكن للمعلمات الإعلان عن النوع، والقيمة الافتراضية، والإلزامية/الاختيارية، والعداد، والنطاق الرقمي، والطول، والنمط؛ يتم رفض الإدخال غير الصالح برمز 400 حقلًا بحقل قبل الوصول إلى قاعدة البيانات. صيغ الاستجابة (JSON، NDJSON، XML، YAML، CSV، TSV، XLSX) قابلة للتحديد لكل طلب عبر ?format=. يستخدم الترقيم ?page و?page_size مع رأس X-Has-More. للتصدير الكامل، ?stream=true يدفق النتيجة الكاملة من مؤشر قاعدة البيانات بدلاً من التخزين المؤقت—تم التحقق مع نتائج 1,000,000 صف وذاكرة خادم ثابتة على MySQL وPostgreSQL وClickHouse. أمر CLI (queryapigate export) يغلف نفس مسار التدفق لاستخدام cron/systemd/Kubernetes CronJob. يدعم التخزين المؤقت للاستعلامات cache_ttl وCache-Control وETag والطلبات الشرطية و304 Not Modified ورأس X-Cache HIT/MISS؛ لا يُطبق أبدًا على عمليات الكتابة. يجمع تحديد المعدل حدًا عامًا على مستوى الخادم مرتبطًا بعنوان IP مع حد اختياري مستقل لكل مفتاح. تشمل المراقبة سجلات JSON منظمة موسومة بمعرفات الطلبات، وتوقيت تنفيذ كل استعلام، وتحذيرات الاستعلامات البطيئة، ومقاييس Prometheus في /metrics تغطي أعداد الطلبات/الاستعلامات، وزمن الاستجابة، وإشغال تجمع الاتصالات، ورفض تحديد المعدل. تتوفر لوحة Grafana مدمجة للمقاييس التاريخية. يتم توليد OpenAPI 3.0 في /openapi.json (تم التحقق منه في CI مقابل المدقق الرسمي) مع كل استعلام محفوظ كنقطة نهاية مكتوبة؛ /docs يخدم Swagger UI، مُصفىً بما يمكن لكل مفتاح الوصول إليه. واجهة الإدارة المدمجة في /ui تغطي إدارة الاتصالات، ومحرر SQL مع تمييز الصيغة وتصفح المخطط، وتنفيذ/معاينة الاستعلام، وEXPLAIN، وإدارة الاستعلامات والإصدارات المحفوظة، وإدارة مفاتيح API، وسجل تدقيق للتغييرات الإدارية، وسجل تنفيذ لكل استعلام، وفحص الاستجابات مع أشجار JSON قابلة للطي، ومخططات شريطية سريعة للنتائج الرقمية، ونقرة واحدة لـ"نسخ كـ curl"/"نسخ كـ TSV". شاشة الإعدادات للقراءة فقط تعرض كل متغير بيئة وقيمته الفعلية، مع الإبلاغ عن الأسرار فقط كمُهيأة أو لا. التثبيت عبر pip مع إضافات برامج تشغيل اختيارية (mysql، postgres، clickhouse، h2، duckdb، all، encryption). لا يتطلب SQLite وDuckDB وقت تشغيل خارجي؛ يتطلب H2 وJDBC العام وقت تشغيل Java. يدعم أيضًا Docker. الأمر `queryapigate examples load` يثبت أربعة سيناريوهات أمثلة عملية (واجهة برمجة تقارير، بيانات لوحة معلومات، تصدير تدفق، تكامل شريك) كمجموعات واستعلامات وأدوار ومفاتيح API جاهزة للاستخدام. يشمل الاختبار اختبارات الوحدة، واختبارات التكامل ضد خوادم MySQL وPostgreSQL وClickHouse وH2 الحقيقية في CI، واختبارات تكامل DuckDB، واختبارات ضبابية لحماية SQL مع Hypothesis، وفحص النوع الثابت mypy، وتدقيق ruff، وCI عند كل دفع. المشروع مرخص بموجب FSL-1.1-MIT ويتطلب Python 3.9+.