الفرق بين المراجعتين لصفحة: «Python/sqlite3»
لا ملخص تعديل |
|||
سطر 6: | سطر 6: | ||
كُتبت وحدة <code>sqlite3</code> من قبل Gerhard Häring، وتقدّم واجهة [[SQL]] متوافقة مع معايير DB-API 2.0 الموصوفة في [https://www.python.org/dev/peps/pep-0249 PEP 249]. | كُتبت وحدة <code>sqlite3</code> من قبل Gerhard Häring، وتقدّم واجهة [[SQL]] متوافقة مع معايير DB-API 2.0 الموصوفة في [https://www.python.org/dev/peps/pep-0249 PEP 249]. | ||
==الاتصال بقاعدة بيانات SQLite== | |||
== الاتصال بقاعدة بيانات SQLite == | لاستخدام هذه الوحدة يجب إنشاء كائن اتصال <code>Connection</code> يمثّل قاعدة البيانات. يبين المثال التالي طريقة استخدام الوحدة مع افتراض أن البيانات مخزّنة في ملف باسم <code>example.db</code>.<syntaxhighlight lang="python3"> | ||
لاستخدام هذه الوحدة يجب إنشاء كائن اتصال <code>Connection</code> يمثّل قاعدة البيانات. يبين المثال التالي طريقة استخدام الوحدة مع افتراض أن البيانات مخزّنة في ملف باسم <code>example.db</code>. | |||
<syntaxhighlight lang="python3"> | |||
import sqlite3 | import sqlite3 | ||
conn = sqlite3.connect('example.db') | conn = sqlite3.connect('example.db') | ||
</syntaxhighlight> | </syntaxhighlight>يمكن كذلك استخدام الاسم الخاص <code>:memory:</code> لإنشاء قاعدة البيانات في ذاكرة الوصول العشوائي RAM. | ||
بعد إجراء الاتصال مع قاعدة البيانات يمكن إنشاء كائن مؤشر <code>Cursor</code> واستدعاء التابع <code>[[Python/Cursor/execute|execute()]]</code> لتنفيذ أوامر [[SQL]]:<syntaxhighlight lang="python3"> | |||
بعد إجراء الاتصال مع قاعدة البيانات يمكن إنشاء كائن مؤشر <code>Cursor</code> واستدعاء التابع <code>[[Python/ | |||
<syntaxhighlight lang="python3"> | |||
c = conn.cursor() | c = conn.cursor() | ||
سطر 41: | سطر 34: | ||
</syntaxhighlight>ستحتاج في العادة إلى استخدام القيم المخزّنة في متغيرات بايثون لإجراء [[SQL|عمليات SQL]]، ولكن عليك أن تتجنب استخدام [[Python/str|سلاسل بايثون النصية]] لإنشاء أوامر الاستعلام عن البيانات لأنّ ذلك غير آمن، إذ يكون برنامجك عرضة لهجمات حقن SQL. | </syntaxhighlight>ستحتاج في العادة إلى استخدام القيم المخزّنة في متغيرات بايثون لإجراء [[SQL|عمليات SQL]]، ولكن عليك أن تتجنب استخدام [[Python/str|سلاسل بايثون النصية]] لإنشاء أوامر الاستعلام عن البيانات لأنّ ذلك غير آمن، إذ يكون برنامجك عرضة لهجمات حقن SQL. | ||
ينصح باستخدام معامل الاستبدال الخاصّ بواجهة DB-API، حيث يوضع الرمز <code>?</code> عوضًا عن القيم التي تريد إدراجها في جملة الاستعلام، ثم تزويد تابع <code>execute()</code> بمعامل ثانٍ يكون على هيئة [[Python/tuple|صفّ tuple]] يتضمّن تلك القيم حسب ترتيبها في جملة الاستعلام. (قد تستخدم وحدات قواعد البيانات الأخرى رموز مختلفة، مثل <code>%s</code> أو <code>:1</code>). فعلى سبيل المثال: | ينصح باستخدام معامل الاستبدال الخاصّ بواجهة DB-API، حيث يوضع الرمز <code>?</code> عوضًا عن القيم التي تريد إدراجها في جملة الاستعلام، ثم تزويد تابع [[Python/Cursor/execute|<code>execute()</code>]]<code></code> بمعامل ثانٍ يكون على هيئة [[Python/tuple|صفّ tuple]] يتضمّن تلك القيم حسب ترتيبها في جملة الاستعلام. (قد تستخدم وحدات قواعد البيانات الأخرى رموز مختلفة، مثل <code>%s</code> أو <code>:1</code>). فعلى سبيل المثال:<syntaxhighlight lang="python3"> | ||
<syntaxhighlight lang="python3"> | |||
# لا تقم بهذا - هذا خطر. | # لا تقم بهذا - هذا خطر. | ||
symbol = 'RHAT' | symbol = 'RHAT' | ||
سطر 59: | سطر 50: | ||
] | ] | ||
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases) | c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases) | ||
</syntaxhighlight> | </syntaxhighlight>بعد تنفيذ جملة الاستعلام [[SQL/select|SELECT]] يمكن استرجاع البيانات إمّا عن طريق التعامل مع المؤشر كمكرِّر iterator، أو استدعاء التابع <code>[[Python/Cursor/fetchone|fetchone()]]</code> لاسترجاع صفّ row واحد فقط، أو استدعاء التابع <code>[[Python/Cursor/fetchall|fetchall()]]</code> للحصول على قائمة بالصفوف rows المطابقة. | ||
بعد تنفيذ جملة الاستعلام [[SQL/select|SELECT]] يمكن استرجاع البيانات إمّا عن طريق التعامل مع المؤشر كمكرِّر iterator، أو استدعاء التابع <code>fetchone()</code> لاسترجاع صفّ row واحد فقط، أو استدعاء التابع <code>fetchall()</code> للحصول على قائمة بالصفوف rows المطابقة. | |||
يستخدم المثال التالي طريقة المكرِّر: | يستخدم المثال التالي طريقة المكرِّر:<syntaxhighlight lang="python3"> | ||
<syntaxhighlight lang="python3"> | |||
>>> for row in c.execute('SELECT * FROM stocks ORDER BY price'): | >>> for row in c.execute('SELECT * FROM stocks ORDER BY price'): | ||
print(row) | print(row) | ||
سطر 74: | سطر 61: | ||
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0) | ('2006-04-05', 'BUY', 'MSFT', 1000, 72.0) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==ثوابت الوحدة sqlite== | |||
== ثوابت الوحدة sqlite == | |||
تقدّم وحدة <code>sqlite</code> الثوابت التالية: | تقدّم وحدة <code>sqlite</code> الثوابت التالية: | ||
===الثابت <code>sqlite3.version</code>=== | |||
=== الثابت <code>sqlite3.version</code> === | |||
رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة سلسلة نصية. | رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة سلسلة نصية. | ||
===الثابت <code>sqlite3.version_info</code>=== | |||
=== الثابت <code>sqlite3.version_info</code> === | |||
رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة صفّ من الأعداد الصحيحة. | رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة صفّ من الأعداد الصحيحة. | ||
===الثابت <code>sqlite3.sqlite_version</code>=== | |||
=== الثابت <code>sqlite3.sqlite_version</code> === | |||
رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة سلسلة نصية. | رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة سلسلة نصية. | ||
===الثابت <code>sqlite3.sqlite_version_info</code>=== | |||
=== الثابت <code>sqlite3.sqlite_version_info</code> === | |||
رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة صفّ من الأعداد الصحيحة. | رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة صفّ من الأعداد الصحيحة. | ||
===الثابت <code>sqlite3.PARSE_DECLTYPES</code>=== | |||
=== الثابت <code>sqlite3.PARSE_DECLTYPES</code> === | يستخدم هذا الثابت مع معامل <code>detect_types</code> في دالة <code>[[Python/sqlite3/connect|connect()]]</code>. | ||
يستخدم هذا الثابت مع معامل <code>detect_types</code> في دالة <code>connect()</code>. | |||
تفسر وحدة <code>sqlite3</code> -عند تعيين قيمة لهذا الثابت- الأنواع المصرّح عنها لكل عمود تعيده. تفسّر الوحدة أول كلمة في النوع المصرّح عنه، أي تفسر النوع <code>"integer primary key"</code> إلى <code>"integer"</code>، والنوع <code>"number(10)"</code> إلى <code>"number"</code>. ثم تبحث الوحدة في قاموس المحوّلات عن الدالة المحوّلة المسجَّلة لذلك النوع. | تفسر وحدة <code>sqlite3</code> -عند تعيين قيمة لهذا الثابت- الأنواع المصرّح عنها لكل عمود تعيده. تفسّر الوحدة أول كلمة في النوع المصرّح عنه، أي تفسر النوع <code>"integer primary key"</code> إلى <code>"integer"</code>، والنوع <code>"number(10)"</code> إلى <code>"number"</code>. ثم تبحث الوحدة في قاموس المحوّلات عن الدالة المحوّلة المسجَّلة لذلك النوع. | ||
===الثابت <code>sqlite3.PARSE_COLNAMES</code>=== | |||
يستخدم هذا الثابت مع معامل <code>detect_types</code> في دالة <code>[[Python/sqlite3/connect|connect()]]</code>. | |||
تفسّر واجهة SQLite -عند تعيين قيمة لهذا الثابت- اسم العمود لكل عمود تعيده. | |||
ستبحث الواجهة عن سلسلة نصية بهيئة <code>[mytype]</code> في جملة الاستعلام لتقرّر أن العمود هو من نوع <code>'mytype'</code>. ستحاول الواجهة البحث عن مدخل من نوع <code>'mytype'</code> في قاموس المحوّلات ثم تستخدم الدالة المحوّلة التي تجدها لإعادة القيمة. | |||
يكون اسم العمود الموجود في الخاصية <code>[[Python/sqlite3#.D8.A7.D9.84.D8.AE.D8.A7.D8.B5.D9.8A.D8.A9 description|Cursor.description]]</code> مقصورًا على الكلمة الأولى من اسم العمود، بمعنى أنّه لو استخدمت مثلًا العبارة <code>'as "x [datetime]"'</code> في [[SQL]]، فإنّها ستفسّر إلى حين الوصول إلى أول فراغ في اسم العمود، وبهذا يصبح اسم العمود هو <code>"x"</code> فقط. | |||
==دوال وحدة sqlite3== | |||
يكون اسم العمود الموجود في <code>Cursor.description</code> مقصورًا على الكلمة الأولى من اسم العمود، بمعنى أنّه لو استخدمت مثلًا العبارة <code>'as "x [datetime]"'</code> في [[SQL]]، فإنّها ستفسّر إلى حين الوصول إلى أول فراغ في اسم العمود، وبهذا يصبح اسم العمود هو <code>"x"</code> فقط. | ===الدالة <code>[[Python/sqlite3/connect|sqlite3.connect()]]</code>=== | ||
تفتح هذه الدالة اتصالًا مع قاعدة بيانات SQLite عبر الملف المعطى، وتعيد افتراضيًا كائن اتصال. | |||
== دوال وحدة sqlite3 == | ===الدالة <code>[[Python/sqlite3/register converter|sqlite3.register_converter()]]</code>=== | ||
تسجّل الدالة كائنًا قابلًا للاستدعاء <code>callable</code> لتحويل سلسلة بايتات نصية من قاعدة البيانات إلى نوع خاص من أنواع بيانات بايثون. | |||
=== الدالة <code>[[Python/sqlite3/connect|sqlite3.connect()]]</code> === | ===الدالة <code>[[Python/sqlite3/register adapter|sqlite3.register_adapter()]]</code>=== | ||
تفتح هذه الدالة اتصالًا مع قاعدة بيانات SQLite عبر الملف | |||
=== الدالة <code>[[Python/sqlite3/register converter|sqlite3.register_converter()]]</code> === | |||
تسجّل الدالة كائنًا قابلًا للاستدعاء callable لتحويل سلسلة بايتات نصية من قاعدة البيانات إلى نوع خاص من أنواع بيانات بايثون. | |||
=== الدالة <code>[[Python/sqlite3/register adapter|sqlite3.register_adapter()]]</code> === | |||
تسجّل الدالة كائنًا قابلًا للاستدعاء لتحويل نوع بيانات بايثون المعطى إلى إحدى الأنواع التي تدعمها قواعد بيانات SQLite. | تسجّل الدالة كائنًا قابلًا للاستدعاء لتحويل نوع بيانات بايثون المعطى إلى إحدى الأنواع التي تدعمها قواعد بيانات SQLite. | ||
===الدالة <code>[[Python/sqlite3/complete statement|sqlite3.complete_statement()]]</code>=== | |||
=== الدالة <code>[[Python/sqlite3/complete statement|sqlite3.complete_statement()]]</code> === | تختبر الدالة ما إذا كانت السلسلة النصية المعطاة تتضمن جملة [[SQL]] واحدة أو أكثر تنتهي بالفاصلة المنقوطة. | ||
===الدالة <code>[[Python/sqlite3/enable callback tracebacks|sqlite3.enable_callback_tracebacks()]]</code>=== | |||
=== الدالة <code>[[Python/sqlite3/enable callback tracebacks|sqlite3.enable_callback_tracebacks()]]</code> === | |||
تتيح هذه الدالة عرض الأخطاء tracebacks الناتجة عن الدوال والمجاميع aggregates والمحوّلات converters والاستدعاءات الخلفية authorizer callbacks المفوِّضة المعرّفة من قبل المستخدم. | تتيح هذه الدالة عرض الأخطاء tracebacks الناتجة عن الدوال والمجاميع aggregates والمحوّلات converters والاستدعاءات الخلفية authorizer callbacks المفوِّضة المعرّفة من قبل المستخدم. | ||
==كائنات الاتصال Connection== | |||
== كائنات الاتصال Connection == | |||
تمتلك كائنات الاتصال بقواعد البيانات SQLite الخصائص والتوابع التالية: | تمتلك كائنات الاتصال بقواعد البيانات SQLite الخصائص والتوابع التالية: | ||
===الخاصية <code>isolation_level</code>=== | |||
=== الخاصية <code>isolation_level</code> === | |||
يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة <code>None</code> لنمط الحفظ التلقائي <code>autocommit</code> أو إحدى القيم <code>"DEFERRED"</code> أو <code>"IMMEDIATE"</code> أو <code>"EXCLUSIVE"</code>. راجع قسم التحكم بالإجراءات للمزيد من المعلومات. | يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة <code>None</code> لنمط الحفظ التلقائي <code>autocommit</code> أو إحدى القيم <code>"DEFERRED"</code> أو <code>"IMMEDIATE"</code> أو <code>"EXCLUSIVE"</code>. راجع قسم التحكم بالإجراءات للمزيد من المعلومات. | ||
===الخاصية <code>in_transaction</code>=== | |||
=== الخاصية <code>in_transaction</code> === | |||
تأخذ الخاصية القيمة <code>True</code> إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة <code>False</code> فيما عدا ذلك. هذه الخاصية للقراءة فقط. | تأخذ الخاصية القيمة <code>True</code> إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة <code>False</code> فيما عدا ذلك. هذه الخاصية للقراءة فقط. | ||
===الخاصية <code>row_factory</code>=== | |||
=== الخاصية <code>row_factory</code> === | |||
يمكن تبديل هذه الخاصية إلى كائن قابل للاستدعاء يستقبل كائن المؤشّر والصفّ row الأصلي على هيئة [[Python/tuples|صفّ <code>tuple</code>]] وسيعيد النتيجة الحقيقية للصف row. يمكن بهذه الطريقة تطبيق طرق متقدّمة لإعادة النتائج، مثل إعادة كائن بمقدوره الوصول إلى الأعمدة عن طريق أسمائها، مثال:<syntaxhighlight lang="python3"> | يمكن تبديل هذه الخاصية إلى كائن قابل للاستدعاء يستقبل كائن المؤشّر والصفّ row الأصلي على هيئة [[Python/tuples|صفّ <code>tuple</code>]] وسيعيد النتيجة الحقيقية للصف row. يمكن بهذه الطريقة تطبيق طرق متقدّمة لإعادة النتائج، مثل إعادة كائن بمقدوره الوصول إلى الأعمدة عن طريق أسمائها، مثال:<syntaxhighlight lang="python3"> | ||
import sqlite3 | import sqlite3 | ||
سطر 146: | سطر 115: | ||
cur.execute("select 1 as a") | cur.execute("select 1 as a") | ||
print(cur.fetchone()["a"]) | print(cur.fetchone()["a"]) | ||
</syntaxhighlight>إن لم يكن [[Python/type|الصف <code>tuple</code>]] كافيًا، وكنت ترغب في الوصول إلى الأعمدة بواسطة أسمائها، فيمكنك تعيين النوع <code>sqlite3.Row</code> إلى هذه الخاصية. يتيح النوع <code>Row</code> الوصول إلى الأعمدة عن طريق أرقامها وعن طريق أسمائها دون تحسّس حالة الأحرف ودون استهلاك الكثير من الذاكرة. وقد يكون هذا النوع خيارًا أفضل من استخدام [[Python/dict|القواميس]] للوصول إلى الأعمدة، أو أفضل حتى من استخدام <code>db_row</code>. | </syntaxhighlight>إن لم يكن [[Python/type|الصف <code>tuple</code>]] كافيًا، وكنت ترغب في الوصول إلى الأعمدة بواسطة أسمائها، فيمكنك تعيين النوع <code>sqlite3.Row</code> إلى هذه الخاصية. يتيح [[Python/sqlite3#.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B5.D9.81 Row|النوع <code>Row</code>]] الوصول إلى الأعمدة عن طريق أرقامها وعن طريق أسمائها دون تحسّس حالة الأحرف ودون استهلاك الكثير من الذاكرة. وقد يكون هذا النوع خيارًا أفضل من استخدام [[Python/dict|القواميس]] للوصول إلى الأعمدة، أو أفضل حتى من استخدام <code>db_row</code>. | ||
===الخاصية <code>text_factory</code>=== | |||
=== الخاصية <code>text_factory</code> === | |||
يمكن عن طريق هذه الخاصية التحكم في طبيعة الكائنات المعادة لأنواع البيانات النصية <code>TEXT</code>. القيمة الافتراضية لهذه الخاصية هي <code>str</code> وتعيد وحدة <code>sqlite3</code> كائنات Unicode للأعمدة النصية. يمكن تعيين القيمة <code>bytes</code> لهذه الخاصية إن كان المطلوب إعادة سلاسل بايتات نصية <code>bytestrings</code>. | يمكن عن طريق هذه الخاصية التحكم في طبيعة الكائنات المعادة لأنواع البيانات النصية <code>TEXT</code>. القيمة الافتراضية لهذه الخاصية هي <code>str</code> وتعيد وحدة <code>sqlite3</code> كائنات Unicode للأعمدة النصية. يمكن تعيين القيمة <code>bytes</code> لهذه الخاصية إن كان المطلوب إعادة سلاسل بايتات نصية <code>bytestrings</code>. | ||
سطر 183: | سطر 151: | ||
assert row[0] == "barfoo" | assert row[0] == "barfoo" | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===الخاصية <code>total_changes</code>=== | |||
=== الخاصية <code>total_changes</code> === | |||
تعيد الخاصية العدد الإجمالي للصفوف الخاضعة للتعديلات، أو المدرجة أو المحذوفة من قاعدة البيانات منذ إجراء الاتصال مع قاعدة البيانات. | تعيد الخاصية العدد الإجمالي للصفوف الخاضعة للتعديلات، أو المدرجة أو المحذوفة من قاعدة البيانات منذ إجراء الاتصال مع قاعدة البيانات. | ||
===التابع [[Python/Connectin/cursor|<code>cursor()</code>]]=== | |||
=== التابع [[Python/Connectin/cursor|<code>cursor()</code>]] === | يعيد التابع نسخة من صنف <code>Cursor</code> أو أحد أصنافه الفرعية. | ||
يعيد التابع نسخة من صنف | ===التابع [[Python/Connection/commit|<code>commit()</code>]]=== | ||
=== التابع [[Python/Connection/commit|<code>commit()</code>]] === | |||
يحفظ التابع الإجراء الحالي. | يحفظ التابع الإجراء الحالي. | ||
=== التابع [[Python/Connection/rollback|<code>rollback()</code>]] === | ===التابع [[Python/Connection/rollback|<code>rollback()</code>]]=== | ||
يلغي التابع جميع التعديلات التي أجريت على قاعدة البيانات بعد آخر استدعاء للتابع [[Python/Connection/commit|<code>commit()</code>]]. | يلغي التابع جميع التعديلات التي أجريت على قاعدة البيانات بعد آخر استدعاء للتابع [[Python/Connection/commit|<code>commit()</code>]]. | ||
=== التابع [[Python/Connection/close|<code>close()</code>]] === | ===التابع [[Python/Connection/close|<code>close()</code>]]=== | ||
يغلق التابع الاتصال بقاعدة البيانات. | يغلق التابع الاتصال بقاعدة البيانات. | ||
=== التابع [[Python/Connection/execute|<code>execute()</code>]] === | ===التابع [[Python/Connection/execute|<code>execute()</code>]]=== | ||
يستدعي التابع [[Python/Cursor/execute|<code>execute()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | يستدعي التابع [[Python/Cursor/execute|<code>execute()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | ||
=== التابع [[Python/Connection/excutemany|<code>excutemany()</code>]] === | ===التابع [[Python/Connection/excutemany|<code>excutemany()</code>]]=== | ||
يستدعي التابع [[Python/Cursor/executemany|<code>executemany()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | يستدعي التابع [[Python/Cursor/executemany|<code>executemany()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | ||
=== التابع [[Python/Connection/executescript|<code>executescript()</code>]] === | ===التابع [[Python/Connection/executescript|<code>executescript()</code>]]=== | ||
يستدعي التابع [[Python/Cursor/executescript|<code>executescript()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | يستدعي التابع [[Python/Cursor/executescript|<code>executescript()</code>]] في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/create function|<code>create_function()</code>]]=== | ||
ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل [[ | ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل [[SQL]]. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/create aggregate|<code>create_aggregate()</code>]]=== | ||
ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم. | ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/create collation|<code>create_collation()</code>]]=== | ||
ينشئ التابع | ينشئ التابع مقارنة collation تحمل الاسم المعطى مع الكائن القابل للاستدعاء المعطى. | ||
=== التابع [[Python/Connection/interrupt|<code>interrupt()</code>]] === | ===التابع [[Python/Connection/interrupt|<code>interrupt()</code>]]=== | ||
يمكن استدعاء هذا التابع من خيط آخر لتجاهل أي استعلامات قد تكون قيد التنفيذ عبر الاتصال الحالي. | يمكن استدعاء هذا التابع من خيط آخر لتجاهل أي استعلامات قد تكون قيد التنفيذ عبر الاتصال الحالي. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/set authorizer|<code>set_authorizer()</code>]]=== | ||
يسجّل هذا التابع كائن استدعاء خلفيٍّ، وينفّذ هذا الكائن في كل | يسجّل هذا التابع كائن استدعاء خلفيٍّ، وينفّذ هذا الكائن في كل محاولة للوصول إلى عمود في جدول ضمن قاعدة البيانات. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/set progress handler|<code>set_progress_handler()</code>]]=== | ||
يسجّل هذا التابع استدعاءً خلفيًا يجري تنفيذه لكل n من تعليمات SQLite في الجهاز الافتراضي virtual machine. | يسجّل هذا التابع استدعاءً خلفيًا يجري تنفيذه لكل <code>n</code> من تعليمات SQLite في الجهاز الافتراضي virtual machine. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/set trace callback|<code>set_trace_callback()</code>]]=== | ||
يسجل التابع trace_callback يجري استدعاؤه لكل جملة SQL تنفّذ بواسطة SQLite. | يسجل التابع كائن استدعاء خلفي للأخطاء trace_callback يجري استدعاؤه لكل جملة [[SQL]] تنفّذ بواسطة SQLite. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/enable load extension|<code>enable_load_extension()</code>]]=== | ||
يحدّد هذا التابع ما إذا كان بإمكان محرّك SQLite من تحميل الملحقات من المكتبات المشتركة. | يحدّد هذا التابع ما إذا كان بإمكان محرّك SQLite من تحميل الملحقات من المكتبات المشتركة. | ||
=== التابع [[Python/Connection/ | ===التابع [[Python/Connection/load extension|<code>load_extension()</code>]]=== | ||
يحمل هذا التابع إحدى ملحقات SQlite من المكتبة المشتركة. | يحمل هذا التابع إحدى ملحقات SQlite من المكتبة المشتركة. | ||
=== التابع [[Python/Connection/iterdump|<code>iterdump()</code>]] === | ===التابع [[Python/Connection/iterdump|<code>iterdump()</code>]]=== | ||
يعيد التابع مكرِّرًا iterator يمكن استخدامه لعرض dump قاعدة البيانات بصيغة SQL النصية. | يعيد التابع مكرِّرًا iterator يمكن استخدامه لعرض dump قاعدة البيانات بصيغة [[SQL]] النصية. | ||
=== التابع [[Python/Connection/backup|<code>backup()</code>]] === | ===التابع [[Python/Connection/backup|<code>backup()</code>]]=== | ||
ينشئ هذا التابع نسخة احتياطية من قاعدة بيانات SQLite. | ينشئ هذا التابع نسخة احتياطية من قاعدة بيانات SQLite. | ||
'''ملاحظة:''' هذه الخاصية جديدة في الإصدار 3.2. | '''ملاحظة:''' هذه الخاصية جديدة في الإصدار 3.2. | ||
==كائنات المؤشر <code>Cursor</code>== | |||
== كائنات المؤشر <code>Cursor</code> == | |||
يمتلك كائن المؤشر الخصائص والتوابع التالية: | يمتلك كائن المؤشر الخصائص والتوابع التالية: | ||
===الخاصية <code>rowcount</code>=== | |||
=== الخاصية <code>rowcount</code> === | |||
بالرغم من أنّ صنف <code>Cursor</code> في وحدة <code>sqlite3</code> يتضمّن هذه الخاصية، إلا أنّ الدعم الذي يقدّمه محرّك SQLite لتحديد "عدد الصفوف المتأثرة"/"عدد الصفوف المحدّدة" جيّد أيضًا. | بالرغم من أنّ صنف <code>Cursor</code> في وحدة <code>sqlite3</code> يتضمّن هذه الخاصية، إلا أنّ الدعم الذي يقدّمه محرّك SQLite لتحديد "عدد الصفوف المتأثرة"/"عدد الصفوف المحدّدة" جيّد أيضًا. | ||
سطر 237: | سطر 201: | ||
في الإصدارات السابقة للإصدار 3.6.5 من SQLite، تعين القيمة <code>0</code> للخاصية <code>rowcount</code> في حال تنفيذ عبارة <code>[[SQL/delete|DELETE FROM table]]</code> دون وضع أي شروط. | في الإصدارات السابقة للإصدار 3.6.5 من SQLite، تعين القيمة <code>0</code> للخاصية <code>rowcount</code> في حال تنفيذ عبارة <code>[[SQL/delete|DELETE FROM table]]</code> دون وضع أي شروط. | ||
===الخاصية <code>lastrowid</code>=== | |||
=== الخاصية <code>lastrowid</code> === | |||
خاصية للقراءة فقط تقدّم معرّف الصف <code>rowid</code> لآخر صفّ جرى تعديله. لا تأخذ هذه الخاصية أيّ قيمة إلا عند تنفيذ جمل <code>[[SQL/insert|INSERT]]</code> أو <code>[[SQL/replace|REPLACE]]</code> باستخدام التابع <code>[[Python/Cursor/execute|execute()]]</code>. أما عند تنفيذ جمل أخرى غير الجملتين السابقتين، أو عند استدعاء التابع <code>[[Python/Cursor/executemany|executemany()]]</code> فإنّ هذه الخاصية ستأخذ القيمة <code>None</code>. | خاصية للقراءة فقط تقدّم معرّف الصف <code>rowid</code> لآخر صفّ جرى تعديله. لا تأخذ هذه الخاصية أيّ قيمة إلا عند تنفيذ جمل <code>[[SQL/insert|INSERT]]</code> أو <code>[[SQL/replace|REPLACE]]</code> باستخدام التابع <code>[[Python/Cursor/execute|execute()]]</code>. أما عند تنفيذ جمل أخرى غير الجملتين السابقتين، أو عند استدعاء التابع <code>[[Python/Cursor/executemany|executemany()]]</code> فإنّ هذه الخاصية ستأخذ القيمة <code>None</code>. | ||
سطر 244: | سطر 207: | ||
ملاحظة: أضيف دعم جملة <code>[[SQL/replace|REPLACE]]</code> في الإصدار 3.6 من اللغة. | ملاحظة: أضيف دعم جملة <code>[[SQL/replace|REPLACE]]</code> في الإصدار 3.6 من اللغة. | ||
===الخاصية <code>arraysize</code>=== | |||
=== الخاصية <code>arraysize</code> === | |||
خاصية للقراءة والكتابة تتحكم في عدد الصفوف المعادة بواسطة التابع <code>[[Python/Cursor/fetchmany|fetchmany()]]</code>. القيمة الافتراضية لهذه الخاصية هي <code>1</code> ويعني ذلك أنّ استدعاء التابع سيؤدي إلى جلب صفٍّ واحدٍ فقط. | خاصية للقراءة والكتابة تتحكم في عدد الصفوف المعادة بواسطة التابع <code>[[Python/Cursor/fetchmany|fetchmany()]]</code>. القيمة الافتراضية لهذه الخاصية هي <code>1</code> ويعني ذلك أنّ استدعاء التابع سيؤدي إلى جلب صفٍّ واحدٍ فقط. | ||
===الخاصية <code>description</code>=== | |||
=== الخاصية <code>description</code> === | |||
خاصية للقراءة فقط، وتقدّم أسماء الأعمدة في آخر استعلام أجراه المستخدم. تعيد هذا الخاصية صفًّا يتضمن سبعة عناصر لكل عمود وتحمل آخر ستة عناصر في هذا الصف القيمة <code>None</code>، وذلك لتكون هذه الخاصية متوافقة مع واجهة بايثون لقواعد البيانات Python DB API. | خاصية للقراءة فقط، وتقدّم أسماء الأعمدة في آخر استعلام أجراه المستخدم. تعيد هذا الخاصية صفًّا يتضمن سبعة عناصر لكل عمود وتحمل آخر ستة عناصر في هذا الصف القيمة <code>None</code>، وذلك لتكون هذه الخاصية متوافقة مع واجهة بايثون لقواعد البيانات Python DB API. | ||
تأخذ هذه الخاصية القيمة نفسها لجمل <code>[[SQL/select|SELECT]]</code> التي لا تعيد أي صفّ من قاعدة البيانات. | تأخذ هذه الخاصية القيمة نفسها لجمل <code>[[SQL/select|SELECT]]</code> التي لا تعيد أي صفّ من قاعدة البيانات. | ||
===الخاصية <code>connection</code>=== | |||
=== الخاصية <code>connection</code> === | |||
خاصية للقراءة فقط، وتقدّم اسم الاتصال بقاعدة بيانات SQLite الذي يستخدمه كائن المؤشر. فعلى سبيل المثال، لو أنشئ كائن مؤشر باستدعاء التابع <code>[[Python/Connection/cursor|con.cursor()]]</code> فإنّ خاصية <code>connection</code> ستشير إلى الكائن <code>con</code>، كما هو مبين في المثال التالي:<syntaxhighlight lang="python3"> | خاصية للقراءة فقط، وتقدّم اسم الاتصال بقاعدة بيانات SQLite الذي يستخدمه كائن المؤشر. فعلى سبيل المثال، لو أنشئ كائن مؤشر باستدعاء التابع <code>[[Python/Connection/cursor|con.cursor()]]</code> فإنّ خاصية <code>connection</code> ستشير إلى الكائن <code>con</code>، كما هو مبين في المثال التالي:<syntaxhighlight lang="python3"> | ||
>>> con = sqlite3.connect(":memory:") | >>> con = sqlite3.connect(":memory:") | ||
سطر 261: | سطر 221: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===التابع [[Python/Cursor/execute|<code>execute()</code>]]=== | ===التابع [[Python/Cursor/execute|<code>execute()</code>]]=== | ||
ينفّذ التابع جملة [[SQL]] المعطاة. | ينفّذ التابع جملة [[SQL]] المعطاة. | ||
===التابع [[Python/Cursor/executemany|<code>executemany()</code>]]=== | ===التابع [[Python/Cursor/executemany|<code>executemany()</code>]]=== | ||
ينفّذ التابع أمر SQL على جميع تسلسلات المعاملات parameter sequences أو الروابط mappings الموجودة في تسلسل المعاملات المعطى. | ينفّذ التابع أمر SQL على جميع تسلسلات المعاملات parameter sequences أو الروابط mappings الموجودة في تسلسل المعاملات المعطى. | ||
===التابع [[Python/Cursor/executescript|<code>executescript()</code>]]=== | ===التابع [[Python/Cursor/executescript|<code>executescript()</code>]]=== | ||
هذا التابع من التوابع غير المعيارية والذي يسهل عملية تنفيذ جمل [[SQL]] متعددة دفعة واحدة. | هذا التابع من التوابع غير المعيارية والذي يسهل عملية تنفيذ جمل [[SQL]] متعددة دفعة واحدة. | ||
===التابع [[Python/Cursor/fetchone|<code>fetchone()</code>]]=== | ===التابع [[Python/Cursor/fetchone|<code>fetchone()</code>]]=== | ||
يجلب التابع الصفّ row التالي من نتيجة الاستعلام، ويعيد تسلسلًا واحدًا فقط. | يجلب التابع الصفّ row التالي من نتيجة الاستعلام، ويعيد تسلسلًا واحدًا فقط. | ||
===التابع [[Python/Cursor/fetchmany|<code>fetchmany()</code>]]=== | ===التابع [[Python/Cursor/fetchmany|<code>fetchmany()</code>]]=== | ||
يجلب التابع المجموعة اللاحقة من الصفوف rows في نتيجة الاستعلام. | يجلب التابع المجموعة اللاحقة من الصفوف rows في نتيجة الاستعلام. | ||
===التابع [[Python/Cursor/fetchall|<code>fetchall()</code>]]=== | ===التابع [[Python/Cursor/fetchall|<code>fetchall()</code>]]=== | ||
يجلب التابع جميع الصفوف (المتبقّية) في نتيجة الاستعلام، ويعيد النتيجة على هيئة [[Python/list|قائمة]]. | يجلب التابع جميع الصفوف (المتبقّية) في نتيجة الاستعلام، ويعيد النتيجة على هيئة [[Python/list|قائمة]]. | ||
===التابع [[Python/Cursor/close|<code>close()</code>]]=== | ===التابع [[Python/Cursor/close|<code>close()</code>]]=== | ||
يغلق التابع المؤشر الحالي. | يغلق التابع المؤشر الحالي. | ||
==كائنات الصف Row== | |||
== كائنات الصف Row == | |||
نسخة من الصنف <code>Row</code> وتعدّ صورة محسّنة من الخاصية <code>row_factory</code> في كائنات الاتصال. تحاول نسخة الصنف هذه محاكاة الصفوف <code>[[Python/tuples|tuples]]</code> في معظم خصائصها، وتدعم الوصول إلى العناصر بواسطة اسم العمود وموقعه، وتدعم كذلك المرور على العناصر، وتمثيلها، واختبار المساواة ومعرفة الطول بواسطة الدالة <code>[[Python/len|len()]]</code>. | نسخة من الصنف <code>Row</code> وتعدّ صورة محسّنة من الخاصية <code>row_factory</code> في كائنات الاتصال. تحاول نسخة الصنف هذه محاكاة الصفوف <code>[[Python/tuples|tuples]]</code> في معظم خصائصها، وتدعم الوصول إلى العناصر بواسطة اسم العمود وموقعه، وتدعم كذلك المرور على العناصر، وتمثيلها، واختبار المساواة ومعرفة الطول بواسطة الدالة <code>[[Python/len|len()]]</code>. | ||
إن امتلك كائنا <code>Row</code> نفس عدد الأعمدة وكان عدد العناصر فيهما متساويًا، فإنّ الكائنين متساويان. | إن امتلك كائنا <code>Row</code> نفس عدد الأعمدة وكان عدد العناصر فيهما متساويًا، فإنّ الكائنين متساويان. | ||
===التابع <code>[[Python/Row/keys|keys()]]</code>=== | |||
=== التابع <code>[[Python/Row/keys|keys()]]</code> === | |||
يعيد التابع قائمة بأسماء الأعمدة. | يعيد التابع قائمة بأسماء الأعمدة. | ||
==الاستثناءات في وحدة <code>sqlite3</code>== | |||
== الاستثناءات في وحدة <code>sqlite3</code> == | ===الاستثناء <code>sqlite3.Warning</code>=== | ||
=== الاستثناء <code>sqlite3.Warning</code> === | |||
صنف متفرّع من الصنف <code>[[Python/exceptions|Exception]]</code>. | صنف متفرّع من الصنف <code>[[Python/exceptions|Exception]]</code>. | ||
===الاستثناء <code>sqlite3.Error</code>=== | |||
=== الاستثناء <code>sqlite3.Error</code> === | |||
الصنف الأساسي لبقية الاستثناءات في هذه الوحدة، وهو صنف متفرّع من الصنف <code>[[Python/exceptions|Exception]]</code>. | الصنف الأساسي لبقية الاستثناءات في هذه الوحدة، وهو صنف متفرّع من الصنف <code>[[Python/exceptions|Exception]]</code>. | ||
===الاستثناء <code>sqlite3.DatabaseError</code>=== | |||
=== الاستثناء <code>sqlite3.DatabaseError</code> === | |||
يطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بقاعدة البيانات. | يطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بقاعدة البيانات. | ||
===الاستثناء <code>sqlite3.IntegrityError</code>=== | |||
=== الاستثناء <code>sqlite3.IntegrityError</code> === | |||
يطلق هذا الاستثناء عند حدوث خلل في العلاقات التي تربط بين جداول قاعدة البيانات، كحدوث خلل في المفتاح الخارجي foreign key. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | يطلق هذا الاستثناء عند حدوث خلل في العلاقات التي تربط بين جداول قاعدة البيانات، كحدوث خلل في المفتاح الخارجي foreign key. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | ||
===الاستثناء <code>sqlite3.ProgrammingError</code>=== | |||
=== الاستثناء <code>sqlite3.ProgrammingError</code> === | |||
يُطلق هذا الاستثناء عند حدوث أخطاء برمجية، مثل عدم العثور على الجدول المحدّد أو وجود الجدول المراد إنشاؤه أصلًا، أو وجود خلل في جمل [[SQL]]، أو تحديد عدد خاطئ من المعاملات... الخ. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | يُطلق هذا الاستثناء عند حدوث أخطاء برمجية، مثل عدم العثور على الجدول المحدّد أو وجود الجدول المراد إنشاؤه أصلًا، أو وجود خلل في جمل [[SQL]]، أو تحديد عدد خاطئ من المعاملات... الخ. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | ||
===الاستثناء <code>sqlite3.OperationalError</code>=== | |||
=== الاستثناء <code>sqlite3.OperationalError</code> === | |||
يُطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بالعمليات الخاصّة بقواعد البيانات والتي لا تكون بالضرورة تحت سيطرة المبرمج، مثل: انقطاع الاتصال بقاعدة البيانات على نحو مفاجئ، أو عدم العثور على اسم مصدر البيانات، أو تعذّر معالجة إجراء معيّن... الخ. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | يُطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بالعمليات الخاصّة بقواعد البيانات والتي لا تكون بالضرورة تحت سيطرة المبرمج، مثل: انقطاع الاتصال بقاعدة البيانات على نحو مفاجئ، أو عدم العثور على اسم مصدر البيانات، أو تعذّر معالجة إجراء معيّن... الخ. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | ||
===الاستثناء <code>sqlite3.NotSupportedError</code>=== | |||
=== الاستثناء <code>sqlite3.NotSupportedError</code> === | يُطلق هذا الاستثناء عند استخدام تابع أو واجهة برمجية لقواعد البيانات لا تدعمها قاعدة البيانات الحالية، مثل: استدعاء التابع <code>[[Python/Connection/rollback|rollback()]]</code> مع اتصال لا يدعم الإجراءات transaction أو أنّ الإجراءات تكون مغلقة. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | ||
يُطلق هذا الاستثناء عند استخدام تابع أو واجهة برمجية لقواعد البيانات لا تدعمها قاعدة البيانات الحالية، مثل: استدعاء التابع <code>rollback()</code> مع اتصال لا يدعم الإجراءات transaction أو أنّ الإجراءات تكون مغلقة. هذا الاستثناء متفرّع من الصنف <code>DatabaseError</code>. | ==التحكم بالإجراءات== | ||
== التحكم بالإجراءات == | |||
تعمل مكتبة <code>sqlite3</code> الداخلية افتراضيًا في وضع الحفظ التلقائي <code>autocommit</code>، ولكن وحدة <code>sqlite3</code> في بايثون ليست كذلك افتراضيًا. | تعمل مكتبة <code>sqlite3</code> الداخلية افتراضيًا في وضع الحفظ التلقائي <code>autocommit</code>، ولكن وحدة <code>sqlite3</code> في بايثون ليست كذلك افتراضيًا. | ||
سطر 321: | سطر 263: | ||
تطلق وحدة <code>sqlite3</code> في بايثون وعلى نحو تلقائي الجملة <code>[[SQL/begin|BEGIN]]</code> ضمنيًا قبل أي جملة تعديل للبيانات Data Modification Language (DML) (أي الجمل <code>[[SQL/insert|INSERT]]/[[SQL/update|UPDATE]]/[[SQL/delete|DELETE]]/[[SQL/replace|REPLACE]]</code>). | تطلق وحدة <code>sqlite3</code> في بايثون وعلى نحو تلقائي الجملة <code>[[SQL/begin|BEGIN]]</code> ضمنيًا قبل أي جملة تعديل للبيانات Data Modification Language (DML) (أي الجمل <code>[[SQL/insert|INSERT]]/[[SQL/update|UPDATE]]/[[SQL/delete|DELETE]]/[[SQL/replace|REPLACE]]</code>). | ||
يمكن التحكم في طبيعة جمل <code>[[SQL/begin|BEGIN]]</code> التي تنفّذها <code>sqlite3</code> ضمنيًا بواسطة المعامل <code>isolation_level</code> عند استدعاء الدالة <code>connect()</code>، أو عن طريق خاصية <code>isolation_level</code> في كائنات الاتصال. | يمكن التحكم في طبيعة جمل <code>[[SQL/begin|BEGIN]]</code> التي تنفّذها <code>sqlite3</code> ضمنيًا بواسطة المعامل <code>isolation_level</code> عند استدعاء الدالة <code>[[Python/sqlite3/connect|connect()]]</code>، أو عن طريق خاصية <code>[[isolation_level]]</code> في كائنات الاتصال. | ||
في حال عدم تعيين قيمة لمستوى العزل <code>isolation_level</code> فستستخدم <code>sqlite3</code> جملة <code>[[SQL/begin|BEGIN]]</code> صرفة، وهذا مكافئ لتعيين القيمة <code>DEFERRED</code>، وهناك قيم أخرى يمكن استخدامها وهي <code>IMMEDIATE</code> و <code>EXCLUSIVE</code>. | في حال عدم تعيين قيمة لمستوى العزل <code>isolation_level</code> فستستخدم <code>sqlite3</code> جملة <code>[[SQL/begin|BEGIN]]</code> صرفة، وهذا مكافئ لتعيين القيمة <code>DEFERRED</code>، وهناك قيم أخرى يمكن استخدامها وهي <code>IMMEDIATE</code> و <code>EXCLUSIVE</code>. | ||
يمكن تعطيل الآلية الضمنية للتحكم في الإجراءات في وحدة <code>sqlite3</code> عن طريق تعيين القيمة <code>None</code> للمعامل أو الخاصية <code>isolation_level</code>، وسيؤدي هذا إلى تحويل عمل مكتبة <code>sqlite3</code> الداخلية إلى وضع التخزين التلقائي، وعندها يمكنك التحكم في الإجراءات بصورة كاملة عن طريق استخدام جمل [[SQL/begin|<code>BEGIN</code>]] و [[SQL/rollback|<code>ROLLBACK</code>]] و [[SQL/savepoint|<code>SAVEPOINT</code>]] و [[SQL/release|<code>RELEASE</code>]] في شيفرتك. | يمكن تعطيل الآلية الضمنية للتحكم في الإجراءات في وحدة <code>sqlite3</code> عن طريق تعيين القيمة <code>None</code> للمعامل أو الخاصية <code>[[Python/sqlite3#.D8.A7.D9.84.D8.AE.D8.A7.D8.B5.D9.8A.D8.A9 isolation level|isolation_level]]</code>، وسيؤدي هذا إلى تحويل عمل مكتبة <code>sqlite3</code> الداخلية إلى وضع التخزين التلقائي، وعندها يمكنك التحكم في الإجراءات بصورة كاملة عن طريق استخدام جمل [[SQL/begin|<code>BEGIN</code>]] و [[SQL/rollback|<code>ROLLBACK</code>]] و [[SQL/savepoint|<code>SAVEPOINT</code>]] و [[SQL/release|<code>RELEASE</code>]] في شيفرتك. | ||
'''ملاحظة:''' تحفظ <code>sqlite3</code> الإجراءات المفتوحة ضمنيًا قبل جمل <code>DDL</code>. لم يعد هذا يحدث في الإصدار 3.6 من بايثون. | '''ملاحظة:''' تحفظ <code>sqlite3</code> الإجراءات المفتوحة ضمنيًا قبل جمل <code>DDL</code>. لم يعد هذا يحدث في الإصدار 3.6 من بايثون. | ||
== استخدام sqlite3 بكفاءة == | ==استخدام sqlite3 بكفاءة== | ||
===استخدام التوابع المختصرة=== | |||
=== استخدام التوابع المختصرة === | يؤدي استخدام التوابع غير المعيارية <code>[[Python/Connection/execute|execute()]]</code> و [[Python/Connection/executemany|<code>executemany()</code>]] و <code>[[Python/Connection/executescript|executescript()]]</code> في كائن <code>Connection</code> إلى اختصار الشيفرة البرمجية المكتوبة نظرًا لانتفاء الحاجة إلى إنشاء كائن المؤشر <code>Cursor</code> والذي يكون في كثير من الأحيان زائدًا عن الحاجة. | ||
يؤدي استخدام التوابع غير المعيارية <code>execute()</code> و <code>executemany()</code> و <code>executescript()</code> في كائن <code> | |||
عوضًا عن ذلك، يجري إنشاء كائن | عوضًا عن ذلك، يجري إنشاء كائن <code>Cursor</code> ضمنيًا وتعيد هذه التوابع المختصرة كائنات المؤشر، وهكذا يمكنك تنفيذ جملة <code>[[SQL/select|SELECT]]</code> والمرور على النتائج مباشرة وعن طريق تنفيذ استدعاء واحد فقط على كائن الاتصال.<syntaxhighlight lang="python3"> | ||
<syntaxhighlight lang="python3"> | |||
import sqlite3 | import sqlite3 | ||
سطر 358: | سطر 297: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===الوصول إلى الأعمدة عن طريق أسمائها عوضًا عن فهارسها=== | |||
الصنف الداخلي <code>[[Python/sqlite3#.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B5.D9.81 Row|sqlite3.Row]]</code> هو من الميزات المفيدة في وحدة <code>sqlite3</code>، وقد صمّم هذا الصنف لاستخدامه كمنتج للصفوف row factory. | |||
يمكن الوصول إلى الصفوف <code>rows</code> المغلّفة بهذا الصنف إما عن طريق الفهرس (مثل [[Python/tuples|الصفوف tuples]]) أو عن طريق الاسم دون تحسس حالة الأحرف:<syntaxhighlight lang="python3"> | |||
يمكن الوصول إلى الصفوف <code>rows</code> المغلّفة بهذا الصنف إما عن طريق الفهرس (مثل [[Python/tuples|الصفوف tuples]]) أو عن طريق الاسم دون تحسس حالة الأحرف: | |||
<syntaxhighlight lang="python3"> | |||
import sqlite3 | import sqlite3 | ||
سطر 380: | سطر 315: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
===استخدام الاتصال كمدير للسياق context manager=== | |||
=== استخدام الاتصال كمدير للسياق context manager === | يمكن استخدام كائنات الاتصال كمدراء للسياق يمكنها حفظ أو استرجاع الإجراءات على نحو تلقائي. في حال حدوث أي استثناء، يتم التراجع عن الإجراء، وفيما عدا ذلك يُحفظ الإجراء:<syntaxhighlight lang="python3"> | ||
يمكن استخدام كائنات الاتصال كمدراء للسياق يمكنها حفظ أو استرجاع الإجراءات على نحو تلقائي. في حال حدوث أي استثناء، يتم التراجع عن الإجراء، وفيما عدا ذلك يُحفظ الإجراء: | |||
<syntaxhighlight lang="python3"> | |||
import sqlite3 | import sqlite3 | ||
سطر 405: | سطر 336: | ||
print("couldn't add Joe twice") | print("couldn't add Joe twice") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==مشاكل شائعة== | |||
===تعدد الخيوط Multithreading=== | |||
تعاني إصدارات SQLite القديمة من مشاكل في مشاركة الاتصال بين خيوط متعددة، ولهذا السبب تمنع وحدة بايثون مشاركة الاتصالات والمؤشرات بين الخيوط، وتطلق اللغة استثناء في وقت التشغيل عند القيام بذلك. | |||
الاستثناء الوحيد هو في استدعاء التابع <code>[[Python/Connection/interrupt|interrupt()]]</code> والذي يعدّ استدعاؤه من خيط آخر أمرًا منطقيًا. | |||
== انظر أيضًا == | |||
* [[Python/dbm|وحدة <code>dbm</code>]]: تمثّل وحدة <code>dbm</code> واجهة عامّة للأشكال المختلفة من قواعد بيانات DBM، مثل <code>dbm.gnu</code> أو <code>dbm.ndbm</code>. | |||
== مصادر == | ==مصادر== | ||
* [https://docs.python.org/3/library/sqlite3.html#sqlite-and-python-types صفحة DB-API 2.0 interface for SQLite databases في توثيق بايثون الرسمي.] | * [https://docs.python.org/3/library/sqlite3.html#sqlite-and-python-types صفحة DB-API 2.0 interface for SQLite databases في توثيق بايثون الرسمي.] | ||
[[تصنيف:Python]] | [[تصنيف:Python]] | ||
[[تصنيف:Python Modules]] | [[تصنيف:Python Modules]] |
مراجعة 13:34، 19 سبتمبر 2018
SQLite هي مكتبة مكتوبة بلغة C تتيح إنشاء قواعد بيانات على القرص الصلب ولا تحتاج إلى خادوم خاص لمعالجتها، وتتيح الوصول إلى قاعدة البيانات باستخدام نسخة غير قياسية من لغة الاستعلام SQL.
تستخدم بعض التطبيقات والبرامج قاعدة بيانات SQLite لتخزين بياناتها الداخلية، ويمكن إنشاء نماذج أولية من التطبيق باستخدام SQLite ثم نقل الشيفرة إلى قواعد بيانات أكبر مثل PostgreSQL أو Oracle.
كُتبت وحدة sqlite3
من قبل Gerhard Häring، وتقدّم واجهة SQL متوافقة مع معايير DB-API 2.0 الموصوفة في PEP 249.
الاتصال بقاعدة بيانات SQLite
لاستخدام هذه الوحدة يجب إنشاء كائن اتصال Connection
يمثّل قاعدة البيانات. يبين المثال التالي طريقة استخدام الوحدة مع افتراض أن البيانات مخزّنة في ملف باسم example.db
.
import sqlite3
conn = sqlite3.connect('example.db')
يمكن كذلك استخدام الاسم الخاص :memory:
لإنشاء قاعدة البيانات في ذاكرة الوصول العشوائي RAM.
بعد إجراء الاتصال مع قاعدة البيانات يمكن إنشاء كائن مؤشر Cursor
واستدعاء التابع execute()
لتنفيذ أوامر SQL:
c = conn.cursor()
# إنشاء جدول
c.execute('''CREATE TABLE stocks
(date text, trans text, symbol text, qty real, price real)''')
# إدراج صف من البيانات
c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
# حفظ التعديلات
conn.commit()
# يمكن كذلك إغلاق الاتصال بعد الانتهاء
# ولكن يجب التأكد من حفظ جميع التعديلات تجنبًا لفقدانها كلّها
conn.close()
تكون البيانات المحفوظة من النوع المستمر persistent وهي متاحة للاستخدام في الجلسات اللاحقة:
import sqlite3
conn = sqlite3.connect('example.db')
c = conn.cursor()
ستحتاج في العادة إلى استخدام القيم المخزّنة في متغيرات بايثون لإجراء عمليات SQL، ولكن عليك أن تتجنب استخدام سلاسل بايثون النصية لإنشاء أوامر الاستعلام عن البيانات لأنّ ذلك غير آمن، إذ يكون برنامجك عرضة لهجمات حقن SQL.
ينصح باستخدام معامل الاستبدال الخاصّ بواجهة DB-API، حيث يوضع الرمز ?
عوضًا عن القيم التي تريد إدراجها في جملة الاستعلام، ثم تزويد تابع execute()
بمعامل ثانٍ يكون على هيئة صفّ tuple يتضمّن تلك القيم حسب ترتيبها في جملة الاستعلام. (قد تستخدم وحدات قواعد البيانات الأخرى رموز مختلفة، مثل %s
أو :1
). فعلى سبيل المثال:
# لا تقم بهذا - هذا خطر.
symbol = 'RHAT'
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)
# استخدم هذه الطريقة
t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)
print(c.fetchone())
# يبين المثال التالي طريقة إدراج عدد من القيم
purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
('2006-04-06', 'SELL', 'IBM', 500, 53.00),
]
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)
بعد تنفيذ جملة الاستعلام SELECT يمكن استرجاع البيانات إمّا عن طريق التعامل مع المؤشر كمكرِّر iterator، أو استدعاء التابع fetchone()
لاسترجاع صفّ row واحد فقط، أو استدعاء التابع fetchall()
للحصول على قائمة بالصفوف rows المطابقة.
يستخدم المثال التالي طريقة المكرِّر:
>>> for row in c.execute('SELECT * FROM stocks ORDER BY price'):
print(row)
('2006-01-05', 'BUY', 'RHAT', 100, 35.14)
('2006-03-28', 'BUY', 'IBM', 1000, 45.0)
('2006-04-06', 'SELL', 'IBM', 500, 53.0)
('2006-04-05', 'BUY', 'MSFT', 1000, 72.0)
ثوابت الوحدة sqlite
تقدّم وحدة sqlite
الثوابت التالية:
الثابت sqlite3.version
رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة سلسلة نصية.
الثابت sqlite3.version_info
رقم الإصدار الخاص بالوحدة -وليس مكتبة SQLite- على هيئة صفّ من الأعداد الصحيحة.
الثابت sqlite3.sqlite_version
رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة سلسلة نصية.
الثابت sqlite3.sqlite_version_info
رقم الإصدار الخاص بمكتبة SQLite في وقت التشغيل، على هيئة صفّ من الأعداد الصحيحة.
الثابت sqlite3.PARSE_DECLTYPES
يستخدم هذا الثابت مع معامل detect_types
في دالة connect()
.
تفسر وحدة sqlite3
-عند تعيين قيمة لهذا الثابت- الأنواع المصرّح عنها لكل عمود تعيده. تفسّر الوحدة أول كلمة في النوع المصرّح عنه، أي تفسر النوع "integer primary key"
إلى "integer"
، والنوع "number(10)"
إلى "number"
. ثم تبحث الوحدة في قاموس المحوّلات عن الدالة المحوّلة المسجَّلة لذلك النوع.
الثابت sqlite3.PARSE_COLNAMES
يستخدم هذا الثابت مع معامل detect_types
في دالة connect()
.
تفسّر واجهة SQLite -عند تعيين قيمة لهذا الثابت- اسم العمود لكل عمود تعيده.
ستبحث الواجهة عن سلسلة نصية بهيئة [mytype]
في جملة الاستعلام لتقرّر أن العمود هو من نوع 'mytype'
. ستحاول الواجهة البحث عن مدخل من نوع 'mytype'
في قاموس المحوّلات ثم تستخدم الدالة المحوّلة التي تجدها لإعادة القيمة.
يكون اسم العمود الموجود في الخاصية Cursor.description
مقصورًا على الكلمة الأولى من اسم العمود، بمعنى أنّه لو استخدمت مثلًا العبارة 'as "x [datetime]"'
في SQL، فإنّها ستفسّر إلى حين الوصول إلى أول فراغ في اسم العمود، وبهذا يصبح اسم العمود هو "x"
فقط.
دوال وحدة sqlite3
الدالة sqlite3.connect()
تفتح هذه الدالة اتصالًا مع قاعدة بيانات SQLite عبر الملف المعطى، وتعيد افتراضيًا كائن اتصال.
الدالة sqlite3.register_converter()
تسجّل الدالة كائنًا قابلًا للاستدعاء callable
لتحويل سلسلة بايتات نصية من قاعدة البيانات إلى نوع خاص من أنواع بيانات بايثون.
الدالة sqlite3.register_adapter()
تسجّل الدالة كائنًا قابلًا للاستدعاء لتحويل نوع بيانات بايثون المعطى إلى إحدى الأنواع التي تدعمها قواعد بيانات SQLite.
الدالة sqlite3.complete_statement()
تختبر الدالة ما إذا كانت السلسلة النصية المعطاة تتضمن جملة SQL واحدة أو أكثر تنتهي بالفاصلة المنقوطة.
الدالة sqlite3.enable_callback_tracebacks()
تتيح هذه الدالة عرض الأخطاء tracebacks الناتجة عن الدوال والمجاميع aggregates والمحوّلات converters والاستدعاءات الخلفية authorizer callbacks المفوِّضة المعرّفة من قبل المستخدم.
كائنات الاتصال Connection
تمتلك كائنات الاتصال بقواعد البيانات SQLite الخصائص والتوابع التالية:
الخاصية isolation_level
يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة None
لنمط الحفظ التلقائي autocommit
أو إحدى القيم "DEFERRED"
أو "IMMEDIATE"
أو "EXCLUSIVE"
. راجع قسم التحكم بالإجراءات للمزيد من المعلومات.
الخاصية in_transaction
تأخذ الخاصية القيمة True
إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة False
فيما عدا ذلك. هذه الخاصية للقراءة فقط.
الخاصية row_factory
يمكن تبديل هذه الخاصية إلى كائن قابل للاستدعاء يستقبل كائن المؤشّر والصفّ row الأصلي على هيئة صفّ tuple
وسيعيد النتيجة الحقيقية للصف row. يمكن بهذه الطريقة تطبيق طرق متقدّمة لإعادة النتائج، مثل إعادة كائن بمقدوره الوصول إلى الأعمدة عن طريق أسمائها، مثال:
import sqlite3
def dict_factory(cursor, row):
d = {}
for idx, col in enumerate(cursor.description):
d[col[0]] = row[idx]
return d
con = sqlite3.connect(":memory:")
con.row_factory = dict_factory
cur = con.cursor()
cur.execute("select 1 as a")
print(cur.fetchone()["a"])
إن لم يكن الصف tuple
كافيًا، وكنت ترغب في الوصول إلى الأعمدة بواسطة أسمائها، فيمكنك تعيين النوع sqlite3.Row
إلى هذه الخاصية. يتيح النوع Row
الوصول إلى الأعمدة عن طريق أرقامها وعن طريق أسمائها دون تحسّس حالة الأحرف ودون استهلاك الكثير من الذاكرة. وقد يكون هذا النوع خيارًا أفضل من استخدام القواميس للوصول إلى الأعمدة، أو أفضل حتى من استخدام db_row
.
الخاصية text_factory
يمكن عن طريق هذه الخاصية التحكم في طبيعة الكائنات المعادة لأنواع البيانات النصية TEXT
. القيمة الافتراضية لهذه الخاصية هي str
وتعيد وحدة sqlite3
كائنات Unicode للأعمدة النصية. يمكن تعيين القيمة bytes
لهذه الخاصية إن كان المطلوب إعادة سلاسل بايتات نصية bytestrings
.
يمكن كذلك تعيين أي قيمة قابلة للاستدعاء وتستقبل معامل واحدًا من نوع bytestring
وتعيد الكائن الناتج من الاستدعاء.
يبين المثال التالي طريقة عمل الخاصية:
import sqlite3
con = sqlite3.connect(":memory:")
cur = con.cursor()
AUSTRIA = "\xd6sterreich"
# تكون الصفوف المعادة بترميز يونيكود افتراضيًا
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert row[0] == AUSTRIA
# ولكن يمكن جعل وحدة sqlite3 تعيد سلاسل بايتات نصية دائمًا...
con.text_factory = bytes
cur.execute("select ?", (AUSTRIA,))
row = cur.fetchone()
assert type(row[0]) is bytes
# سترمّز سلاسل البايتات النصية بترميز UTF-8
assert row[0] == AUSTRIA.encode("utf-8")
# يمكننا كذلك تطبيق text_factory مخصّص
# هنا ستُلحق السلسلة "foo" بجميع السلاسل النصية
con.text_factory = lambda x: x.decode("utf-8") + "foo"
cur.execute("select ?", ("bar",))
row = cur.fetchone()
assert row[0] == "barfoo"
الخاصية total_changes
تعيد الخاصية العدد الإجمالي للصفوف الخاضعة للتعديلات، أو المدرجة أو المحذوفة من قاعدة البيانات منذ إجراء الاتصال مع قاعدة البيانات.
التابع cursor()
يعيد التابع نسخة من صنف Cursor
أو أحد أصنافه الفرعية.
التابع commit()
يحفظ التابع الإجراء الحالي.
التابع rollback()
يلغي التابع جميع التعديلات التي أجريت على قاعدة البيانات بعد آخر استدعاء للتابع commit()
.
التابع close()
يغلق التابع الاتصال بقاعدة البيانات.
التابع execute()
يستدعي التابع execute()
في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع excutemany()
يستدعي التابع executemany()
في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع executescript()
يستدعي التابع executescript()
في كائن المؤشر مع تمرير المعاملات المعطاة، ثم يعيد كائن المؤشر.
التابع create_function()
ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل SQL.
التابع create_aggregate()
ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم.
التابع create_collation()
ينشئ التابع مقارنة collation تحمل الاسم المعطى مع الكائن القابل للاستدعاء المعطى.
التابع interrupt()
يمكن استدعاء هذا التابع من خيط آخر لتجاهل أي استعلامات قد تكون قيد التنفيذ عبر الاتصال الحالي.
التابع set_authorizer()
يسجّل هذا التابع كائن استدعاء خلفيٍّ، وينفّذ هذا الكائن في كل محاولة للوصول إلى عمود في جدول ضمن قاعدة البيانات.
التابع set_progress_handler()
يسجّل هذا التابع استدعاءً خلفيًا يجري تنفيذه لكل n
من تعليمات SQLite في الجهاز الافتراضي virtual machine.
التابع set_trace_callback()
يسجل التابع كائن استدعاء خلفي للأخطاء trace_callback يجري استدعاؤه لكل جملة SQL تنفّذ بواسطة SQLite.
التابع enable_load_extension()
يحدّد هذا التابع ما إذا كان بإمكان محرّك SQLite من تحميل الملحقات من المكتبات المشتركة.
التابع load_extension()
يحمل هذا التابع إحدى ملحقات SQlite من المكتبة المشتركة.
التابع iterdump()
يعيد التابع مكرِّرًا iterator يمكن استخدامه لعرض dump قاعدة البيانات بصيغة SQL النصية.
التابع backup()
ينشئ هذا التابع نسخة احتياطية من قاعدة بيانات SQLite.
ملاحظة: هذه الخاصية جديدة في الإصدار 3.2.
كائنات المؤشر Cursor
يمتلك كائن المؤشر الخصائص والتوابع التالية:
الخاصية rowcount
بالرغم من أنّ صنف Cursor
في وحدة sqlite3
يتضمّن هذه الخاصية، إلا أنّ الدعم الذي يقدّمه محرّك SQLite لتحديد "عدد الصفوف المتأثرة"/"عدد الصفوف المحدّدة" جيّد أيضًا.
يُجمع عدد التعديلات في الخاصية rowcount
عند تنفيذ جمل الاستعلام بواسطة التابع executemany()
.
تتطلب معايير بايثون لواجهات قواعد البيانات البرمجية Python DB API أن تحمل الخاصية rowcount
"القيمة -1
في حال عدم تنفيذ أي تابع من توابع executeXX()
على المؤشر، أو عندما لا يكون بإمكان الواجهة البرمجية تحديد قيمة rowcount
لآخر عملية". ويتضمن هذا جمل SELECT
لأنّنا لا نستطيع تحديد عدد الصفوف الناتجة من استعلام معين إلا بعد جلب جميع الصفوف.
في الإصدارات السابقة للإصدار 3.6.5 من SQLite، تعين القيمة 0
للخاصية rowcount
في حال تنفيذ عبارة DELETE FROM table
دون وضع أي شروط.
الخاصية lastrowid
خاصية للقراءة فقط تقدّم معرّف الصف rowid
لآخر صفّ جرى تعديله. لا تأخذ هذه الخاصية أيّ قيمة إلا عند تنفيذ جمل INSERT
أو REPLACE
باستخدام التابع execute()
. أما عند تنفيذ جمل أخرى غير الجملتين السابقتين، أو عند استدعاء التابع executemany()
فإنّ هذه الخاصية ستأخذ القيمة None
.
في حال فشل تنفيذ جملة INSERT
أو REPLACE
في إدراج البيانات تأخذ هذه الخاصية قيمة آخر عملية إدراج ناجحة.
ملاحظة: أضيف دعم جملة REPLACE
في الإصدار 3.6 من اللغة.
الخاصية arraysize
خاصية للقراءة والكتابة تتحكم في عدد الصفوف المعادة بواسطة التابع fetchmany()
. القيمة الافتراضية لهذه الخاصية هي 1
ويعني ذلك أنّ استدعاء التابع سيؤدي إلى جلب صفٍّ واحدٍ فقط.
الخاصية description
خاصية للقراءة فقط، وتقدّم أسماء الأعمدة في آخر استعلام أجراه المستخدم. تعيد هذا الخاصية صفًّا يتضمن سبعة عناصر لكل عمود وتحمل آخر ستة عناصر في هذا الصف القيمة None
، وذلك لتكون هذه الخاصية متوافقة مع واجهة بايثون لقواعد البيانات Python DB API.
تأخذ هذه الخاصية القيمة نفسها لجمل SELECT
التي لا تعيد أي صفّ من قاعدة البيانات.
الخاصية connection
خاصية للقراءة فقط، وتقدّم اسم الاتصال بقاعدة بيانات SQLite الذي يستخدمه كائن المؤشر. فعلى سبيل المثال، لو أنشئ كائن مؤشر باستدعاء التابع con.cursor()
فإنّ خاصية connection
ستشير إلى الكائن con
، كما هو مبين في المثال التالي:
>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
التابع execute()
ينفّذ التابع جملة SQL المعطاة.
التابع executemany()
ينفّذ التابع أمر SQL على جميع تسلسلات المعاملات parameter sequences أو الروابط mappings الموجودة في تسلسل المعاملات المعطى.
التابع executescript()
هذا التابع من التوابع غير المعيارية والذي يسهل عملية تنفيذ جمل SQL متعددة دفعة واحدة.
التابع fetchone()
يجلب التابع الصفّ row التالي من نتيجة الاستعلام، ويعيد تسلسلًا واحدًا فقط.
التابع fetchmany()
يجلب التابع المجموعة اللاحقة من الصفوف rows في نتيجة الاستعلام.
التابع fetchall()
يجلب التابع جميع الصفوف (المتبقّية) في نتيجة الاستعلام، ويعيد النتيجة على هيئة قائمة.
التابع close()
يغلق التابع المؤشر الحالي.
كائنات الصف Row
نسخة من الصنف Row
وتعدّ صورة محسّنة من الخاصية row_factory
في كائنات الاتصال. تحاول نسخة الصنف هذه محاكاة الصفوف tuples
في معظم خصائصها، وتدعم الوصول إلى العناصر بواسطة اسم العمود وموقعه، وتدعم كذلك المرور على العناصر، وتمثيلها، واختبار المساواة ومعرفة الطول بواسطة الدالة len()
.
إن امتلك كائنا Row
نفس عدد الأعمدة وكان عدد العناصر فيهما متساويًا، فإنّ الكائنين متساويان.
التابع keys()
يعيد التابع قائمة بأسماء الأعمدة.
الاستثناءات في وحدة sqlite3
الاستثناء sqlite3.Warning
صنف متفرّع من الصنف Exception
.
الاستثناء sqlite3.Error
الصنف الأساسي لبقية الاستثناءات في هذه الوحدة، وهو صنف متفرّع من الصنف Exception
.
الاستثناء sqlite3.DatabaseError
يطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بقاعدة البيانات.
الاستثناء sqlite3.IntegrityError
يطلق هذا الاستثناء عند حدوث خلل في العلاقات التي تربط بين جداول قاعدة البيانات، كحدوث خلل في المفتاح الخارجي foreign key. هذا الاستثناء متفرّع من الصنف DatabaseError
.
الاستثناء sqlite3.ProgrammingError
يُطلق هذا الاستثناء عند حدوث أخطاء برمجية، مثل عدم العثور على الجدول المحدّد أو وجود الجدول المراد إنشاؤه أصلًا، أو وجود خلل في جمل SQL، أو تحديد عدد خاطئ من المعاملات... الخ. هذا الاستثناء متفرّع من الصنف DatabaseError
.
الاستثناء sqlite3.OperationalError
يُطلق هذا الاستثناء عند حدوث الأخطاء المتعلّقة بالعمليات الخاصّة بقواعد البيانات والتي لا تكون بالضرورة تحت سيطرة المبرمج، مثل: انقطاع الاتصال بقاعدة البيانات على نحو مفاجئ، أو عدم العثور على اسم مصدر البيانات، أو تعذّر معالجة إجراء معيّن... الخ. هذا الاستثناء متفرّع من الصنف DatabaseError
.
الاستثناء sqlite3.NotSupportedError
يُطلق هذا الاستثناء عند استخدام تابع أو واجهة برمجية لقواعد البيانات لا تدعمها قاعدة البيانات الحالية، مثل: استدعاء التابع rollback()
مع اتصال لا يدعم الإجراءات transaction أو أنّ الإجراءات تكون مغلقة. هذا الاستثناء متفرّع من الصنف DatabaseError
.
التحكم بالإجراءات
تعمل مكتبة sqlite3
الداخلية افتراضيًا في وضع الحفظ التلقائي autocommit
، ولكن وحدة sqlite3
في بايثون ليست كذلك افتراضيًا.
وضع الحفظ التلقائي يعني أنّ الجمل التي تعدّل قاعدة البيانات تأخذ مفعولها على نحو مباشر. تعطّل جملة BEGIN
أو SAVEPOINT
وضع الحفظ التلقائي، وتفعّل جملة COMMIT
أو ROLLBACK
أو RELEASE
والتي تنهي الإجراء الأخير، وضع الحفظ التلقائي مرة أخرى.
تطلق وحدة sqlite3
في بايثون وعلى نحو تلقائي الجملة BEGIN
ضمنيًا قبل أي جملة تعديل للبيانات Data Modification Language (DML) (أي الجمل INSERT/UPDATE/DELETE/REPLACE
).
يمكن التحكم في طبيعة جمل BEGIN
التي تنفّذها sqlite3
ضمنيًا بواسطة المعامل isolation_level
عند استدعاء الدالة connect()
، أو عن طريق خاصية isolation_level
في كائنات الاتصال.
في حال عدم تعيين قيمة لمستوى العزل isolation_level
فستستخدم sqlite3
جملة BEGIN
صرفة، وهذا مكافئ لتعيين القيمة DEFERRED
، وهناك قيم أخرى يمكن استخدامها وهي IMMEDIATE
و EXCLUSIVE
.
يمكن تعطيل الآلية الضمنية للتحكم في الإجراءات في وحدة sqlite3
عن طريق تعيين القيمة None
للمعامل أو الخاصية isolation_level
، وسيؤدي هذا إلى تحويل عمل مكتبة sqlite3
الداخلية إلى وضع التخزين التلقائي، وعندها يمكنك التحكم في الإجراءات بصورة كاملة عن طريق استخدام جمل BEGIN
و ROLLBACK
و SAVEPOINT
و RELEASE
في شيفرتك.
ملاحظة: تحفظ sqlite3
الإجراءات المفتوحة ضمنيًا قبل جمل DDL
. لم يعد هذا يحدث في الإصدار 3.6 من بايثون.
استخدام sqlite3 بكفاءة
استخدام التوابع المختصرة
يؤدي استخدام التوابع غير المعيارية execute()
و executemany()
و executescript()
في كائن Connection
إلى اختصار الشيفرة البرمجية المكتوبة نظرًا لانتفاء الحاجة إلى إنشاء كائن المؤشر Cursor
والذي يكون في كثير من الأحيان زائدًا عن الحاجة.
عوضًا عن ذلك، يجري إنشاء كائن Cursor
ضمنيًا وتعيد هذه التوابع المختصرة كائنات المؤشر، وهكذا يمكنك تنفيذ جملة SELECT
والمرور على النتائج مباشرة وعن طريق تنفيذ استدعاء واحد فقط على كائن الاتصال.
import sqlite3
persons = [
("Hugo", "Boss"),
("Calvin", "Klein")
]
con = sqlite3.connect(":memory:")
# إنشاء الجدول
con.execute("create table person(firstname, lastname)")
# تعبئة الجدول بالبيانات
con.executemany("insert into person(firstname, lastname) values (?, ?)", persons)
# طباعة محتويات الجدول
for row in con.execute("select firstname, lastname from person"):
print(row)
print("I just deleted", con.execute("delete from person").rowcount, "rows")
الوصول إلى الأعمدة عن طريق أسمائها عوضًا عن فهارسها
الصنف الداخلي sqlite3.Row
هو من الميزات المفيدة في وحدة sqlite3
، وقد صمّم هذا الصنف لاستخدامه كمنتج للصفوف row factory.
يمكن الوصول إلى الصفوف rows
المغلّفة بهذا الصنف إما عن طريق الفهرس (مثل الصفوف tuples) أو عن طريق الاسم دون تحسس حالة الأحرف:
import sqlite3
con = sqlite3.connect(":memory:")
con.row_factory = sqlite3.Row
cur = con.cursor()
cur.execute("select 'John' as name, 42 as age")
for row in cur:
assert row[0] == row["name"]
assert row["name"] == row["nAmE"]
assert row[1] == row["age"]
assert row[1] == row["AgE"]
استخدام الاتصال كمدير للسياق context manager
يمكن استخدام كائنات الاتصال كمدراء للسياق يمكنها حفظ أو استرجاع الإجراءات على نحو تلقائي. في حال حدوث أي استثناء، يتم التراجع عن الإجراء، وفيما عدا ذلك يُحفظ الإجراء:
import sqlite3
con = sqlite3.connect(":memory:")
con.execute("create table person (id integer primary key, firstname varchar unique)")
# يستدعى التابع con.commit() تلقائيًا بعد ذلك ودون حدوث أي مشاكل
with con:
con.execute("insert into person(firstname) values (?)", ("Joe",))
# يستدعى التابع con.rollback() بعد انتهاء الإجراء باستثناء، وسيبقى الاستثناء طليقًا ويجب الإمساك به.
try:
with con:
con.execute("insert into person(firstname) values (?)", ("Joe",))
except sqlite3.IntegrityError:
print("couldn't add Joe twice")
مشاكل شائعة
تعدد الخيوط Multithreading
تعاني إصدارات SQLite القديمة من مشاكل في مشاركة الاتصال بين خيوط متعددة، ولهذا السبب تمنع وحدة بايثون مشاركة الاتصالات والمؤشرات بين الخيوط، وتطلق اللغة استثناء في وقت التشغيل عند القيام بذلك.
الاستثناء الوحيد هو في استدعاء التابع interrupt()
والذي يعدّ استدعاؤه من خيط آخر أمرًا منطقيًا.
انظر أيضًا
- وحدة
dbm
: تمثّل وحدةdbm
واجهة عامّة للأشكال المختلفة من قواعد بيانات DBM، مثلdbm.gnu
أوdbm.ndbm
.