الفرق بين المراجعتين لصفحة: «Python/sqlite3/connect»
أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الدالة <code>sqlite3.connect()</code> في بايثون}}</noinclude> تفتح هذه الدالة اتصالًا مع قاعدة ب...' |
|||
| (2 مراجعات متوسطة بواسطة نفس المستخدم غير معروضة) | |||
| سطر 8: | سطر 8: | ||
sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri]) | sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri]) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== المعاملات == | == المعاملات == | ||
=== database === | === <code>database</code> === | ||
كائن شبيه بالمسار path-like يمثّل مسار ملف قاعدة البيانات (المسار المطلق أو النسبي للمجلد الحالي) الذي سيتم الاتصال به. يمكن استخدام القيمة ":memory:" لفتح اتصال مع قاعدة بيانات تخزّن في ذاكرة الوصول العشوائي RAM بدلًا من القرص الصلب. | كائن شبيه بالمسار path-like يمثّل مسار ملف قاعدة البيانات (المسار المطلق أو النسبي للمجلد الحالي) الذي سيتم الاتصال به. يمكن استخدام القيمة <code>":memory:"</code> لفتح اتصال مع قاعدة بيانات تخزّن في ذاكرة الوصول العشوائي RAM بدلًا من القرص الصلب. | ||
إذا أجريت عدة اتصالات بقاعدة بيانات واحدة، وأجرى أحد هذه الاتصالات تعديلًا على قاعدة البيانات، فإنّ الأخيرة تقفل إلى حين إكمال الإجراء وحفظه. | إذا أجريت عدة اتصالات بقاعدة بيانات واحدة، وأجرى أحد هذه الاتصالات تعديلًا على قاعدة البيانات، فإنّ الأخيرة تقفل إلى حين إكمال الإجراء وحفظه. | ||
=== timeout === | === <code>timeout</code> === | ||
يحدّد هذا المعامل فترة انتظار الاتصال لرفع القفل عن قاعدة البيانات قبل إطلاق استثناء. القيمة الافتراضية لهذا المعامل هي 5.0 (خمس ثوانٍ). | يحدّد هذا المعامل فترة انتظار الاتصال لرفع القفل عن قاعدة البيانات قبل إطلاق استثناء. القيمة الافتراضية لهذا المعامل هي <code>5.0</code> (خمس ثوانٍ). | ||
=== isolation_level === | === <code>isolation_level</code> === | ||
راجع خاصية isolation_level في كائنات الاتصال. | راجع خاصية <code>isolation_level</code> في كائنات الاتصال. | ||
=== detect_types === | === <code>detect_types</code> === | ||
تدعم قواعد بيانات SQLite الأنواع TEXT و INTEGER و REAL و BLOB و | تدعم قواعد بيانات SQLite الأنواع <code>TEXT</code> و <code>INTEGER</code> و <code>REAL</code> و <code>BLOB</code> و <code>NULL</code>، وإذا أردت إضافة الدعم لأنواع أخرى فعليك القيام بذلك بنفسك، ويجعل المعامل <code>detect_types</code> -إلى جانب المحوّلات المسجّلة بواسطة الدالة <code>[[Python/sqlite3/register converter|register_converter()]]</code> - هذه العملية يسيرة للغاية. | ||
يأخذ المعامل detect_types القيمة الافتراضية 0 (أي لن يجري الكشف عن أي نوع)، ويمكن تعيين أي مجموعة من قيم PARSE_DECLTYPES و PARSE_COLNAMES لتشغيل عملية الكشف عن الأنواع. | يأخذ المعامل <code>detect_types</code> القيمة الافتراضية <code>0</code> (أي لن يجري الكشف عن أي نوع)، ويمكن تعيين أي مجموعة من قيم <code>PARSE_DECLTYPES</code> و <code>PARSE_COLNAMES</code> لتشغيل عملية الكشف عن الأنواع. | ||
=== check_same_thread === | === <code>check_same_thread</code> === | ||
يأخذ هذا المعامل - | يأخذ هذا المعامل -افتراضيًا- القيمة <code>True</code> وحينها لا يمكن لأي خيط أن يستخدم الاتصال سوى سوى الخيط المسؤول عن إنشائه. أما إن أخذ المعامل القيمة <code>False</code> فسيكون حينئذ بالإمكان استخدام الاتصال من قبل خيوط متعددة، ويجب على المستخدم في مثل هذه الحالة أن يسلسل serialize عمليات الكتابة لتجنب تلف البيانات. | ||
=== factory === | === <code>factory</code> === | ||
تستخدم وحدة sqlite3 كائن الاتصال لإجراء عملية الاتصال، ولكن يمكن تفريع صنف الاتصال ودفع الدالة connect() إلى استخدام الصنف الخاص بالمستخدم وذلك بتقديمه كقيمة للمعامل factory. | تستخدم وحدة <code>sqlite3</code> كائن الاتصال لإجراء عملية الاتصال، ولكن يمكن تفريع صنف الاتصال ودفع الدالة <code>connect()</code> إلى استخدام الصنف الخاص بالمستخدم وذلك بتقديمه كقيمة للمعامل factory. | ||
راجع قسم SQLite وأنواع بايثون في هذا الدليل للاطلاع على المزيد من التفاصيل. | راجع قسم SQLite وأنواع بايثون في هذا الدليل للاطلاع على المزيد من التفاصيل. | ||
=== cached_statement === | === <code>cached_statement</code> === | ||
تستخدم وحدة sqlite3 ذاكرة مخبئية داخلية لتقليل عمليات تفسير عبارات SQL قدر الإمكان. يمكن استخدام المعامل cached_statement لتحديد عدد العبارات التي ستخزّن في الذاكرة المخبئية لاتصال معين، وتخزّن الوحدة بصورة افتراضية 100 عبارة لكل اتصال. | تستخدم وحدة <code>sqlite3</code> ذاكرة مخبئية داخلية لتقليل عمليات تفسير عبارات [[SQL]] قدر الإمكان. يمكن استخدام المعامل <code>cached_statement</code> لتحديد عدد العبارات التي ستخزّن في الذاكرة المخبئية لاتصال معين، وتخزّن الوحدة بصورة افتراضية <code>100</code> عبارة لكل اتصال. | ||
=== uri === | === <code>uri</code> === | ||
إن كان المعامل uri يحمل القيمة True فستفسّر قاعدة البيانات الحالية | إن كان المعامل <code>uri</code> يحمل القيمة <code>True</code> فستفسّر قاعدة البيانات الحالية كمعرف موارد موحد <code>URI</code>، ويسمح هذا بتحديد بعض الخيارات الإضافية. فيمكن مثلًا فتح قاعدة البيانات للقراءة فقط، وذلك بالطريقة التالية:<syntaxhighlight lang="python3"> | ||
db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) | db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) | ||
</syntaxhighlight> | |||
يمكن الاطلاع على المزيد من المعلومات حول هذه الخاصية، إضافة إلى قائمة بالخيارات المتاحة، في توثيق SQLite URI. | يمكن الاطلاع على المزيد من المعلومات حول هذه الخاصية، إضافة إلى قائمة بالخيارات المتاحة، في توثيق SQLite URI. | ||
ملاحظة: أضيف المعامل uri في الإصدار 3.4 من اللغة. | '''ملاحظة:''' أضيف المعامل <code>uri</code> في الإصدار 3.4 من اللغة. | ||
ملاحظة: في الإصدار 3.7 أصبح بالإمكان استخدام الكائنات الشبيهة بالمسارات path-like objects لتمثيل قاعدة البيانات إلى جانب السلاسل النصية. | '''ملاحظة:''' في الإصدار 3.7 أصبح بالإمكان استخدام الكائنات الشبيهة بالمسارات path-like objects لتمثيل قاعدة البيانات إلى جانب [[Python/str|السلاسل النصية]]. | ||
== القيمة المعادة == | == القيمة المعادة == | ||
تعيد الدالة افتراضيًا كائن اتصال ما لم تُحدّد قيمة خاصة للمعامل factory. | تعيد الدالة افتراضيًا [[Python/sqlite3/connection|كائن اتصال]] ما لم تُحدّد قيمة خاصة للمعامل factory. | ||
== أمثلة == | == أمثلة == | ||
| سطر 60: | سطر 61: | ||
== انظر أيضًا == | == انظر أيضًا == | ||
* كائنات الاتصال. | * [[Python/sqlite3/connection|كائنات الاتصال في بايثون.]] | ||
* كائنات المؤشر. | * [[Python/sqlite3/cursor|كائنات المؤشر في بايثون.]] | ||
== مصادر == | == مصادر == | ||
المراجعة الحالية بتاريخ 16:40، 16 سبتمبر 2018
تفتح هذه الدالة اتصالًا مع قاعدة بيانات SQLite عبر الملف المعطى، وتعيد افتراضيًا كائن اتصال ما لم تحدد قيمة أخرى في المعاملات.
البنية العامة
sqlite3.connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri])
المعاملات
database
كائن شبيه بالمسار path-like يمثّل مسار ملف قاعدة البيانات (المسار المطلق أو النسبي للمجلد الحالي) الذي سيتم الاتصال به. يمكن استخدام القيمة ":memory:" لفتح اتصال مع قاعدة بيانات تخزّن في ذاكرة الوصول العشوائي RAM بدلًا من القرص الصلب.
إذا أجريت عدة اتصالات بقاعدة بيانات واحدة، وأجرى أحد هذه الاتصالات تعديلًا على قاعدة البيانات، فإنّ الأخيرة تقفل إلى حين إكمال الإجراء وحفظه.
timeout
يحدّد هذا المعامل فترة انتظار الاتصال لرفع القفل عن قاعدة البيانات قبل إطلاق استثناء. القيمة الافتراضية لهذا المعامل هي 5.0 (خمس ثوانٍ).
isolation_level
راجع خاصية isolation_level في كائنات الاتصال.
detect_types
تدعم قواعد بيانات SQLite الأنواع TEXT و INTEGER و REAL و BLOB و NULL، وإذا أردت إضافة الدعم لأنواع أخرى فعليك القيام بذلك بنفسك، ويجعل المعامل detect_types -إلى جانب المحوّلات المسجّلة بواسطة الدالة register_converter() - هذه العملية يسيرة للغاية.
يأخذ المعامل detect_types القيمة الافتراضية 0 (أي لن يجري الكشف عن أي نوع)، ويمكن تعيين أي مجموعة من قيم PARSE_DECLTYPES و PARSE_COLNAMES لتشغيل عملية الكشف عن الأنواع.
check_same_thread
يأخذ هذا المعامل -افتراضيًا- القيمة True وحينها لا يمكن لأي خيط أن يستخدم الاتصال سوى سوى الخيط المسؤول عن إنشائه. أما إن أخذ المعامل القيمة False فسيكون حينئذ بالإمكان استخدام الاتصال من قبل خيوط متعددة، ويجب على المستخدم في مثل هذه الحالة أن يسلسل serialize عمليات الكتابة لتجنب تلف البيانات.
factory
تستخدم وحدة sqlite3 كائن الاتصال لإجراء عملية الاتصال، ولكن يمكن تفريع صنف الاتصال ودفع الدالة connect() إلى استخدام الصنف الخاص بالمستخدم وذلك بتقديمه كقيمة للمعامل factory.
راجع قسم SQLite وأنواع بايثون في هذا الدليل للاطلاع على المزيد من التفاصيل.
cached_statement
تستخدم وحدة sqlite3 ذاكرة مخبئية داخلية لتقليل عمليات تفسير عبارات SQL قدر الإمكان. يمكن استخدام المعامل cached_statement لتحديد عدد العبارات التي ستخزّن في الذاكرة المخبئية لاتصال معين، وتخزّن الوحدة بصورة افتراضية 100 عبارة لكل اتصال.
uri
إن كان المعامل uri يحمل القيمة True فستفسّر قاعدة البيانات الحالية كمعرف موارد موحد URI، ويسمح هذا بتحديد بعض الخيارات الإضافية. فيمكن مثلًا فتح قاعدة البيانات للقراءة فقط، وذلك بالطريقة التالية:
db = sqlite3.connect('file:path/to/database?mode=ro', uri=True)
يمكن الاطلاع على المزيد من المعلومات حول هذه الخاصية، إضافة إلى قائمة بالخيارات المتاحة، في توثيق SQLite URI.
ملاحظة: أضيف المعامل uri في الإصدار 3.4 من اللغة.
ملاحظة: في الإصدار 3.7 أصبح بالإمكان استخدام الكائنات الشبيهة بالمسارات path-like objects لتمثيل قاعدة البيانات إلى جانب السلاسل النصية.
القيمة المعادة
تعيد الدالة افتراضيًا كائن اتصال ما لم تُحدّد قيمة خاصة للمعامل factory.
أمثلة
يبين المثال التالي آلية عمل التابع:
import sqlite3
conn = sqlite3.connect('example.db')
انظر أيضًا
مصادر
صفحة DB-API 2.0 interface for SQLite databases في توثيق بايثون الرسمي.