الوحدة sqlite3 في بايثون
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 عبر الملف database، وتعيد افتراضيًا كائن اتصال.
الدالة sqlite3.register_converter()
تسجّل الدالة كائنًا قابلًا للاستدعاء callable لتحويل سلسلة بايتات نصية من قاعدة البيانات إلى نوع خاص من أنواع بيانات بايثون.
الدالة sqlite3.register_adapter()
تسجّل الدالة كائنًا قابلًا للاستدعاء لتحويل نوع بيانات بايثون المعطى إلى إحدى الأنواع التي تدعمها قواعد بيانات SQLite.
الدالة sqlite3.complete_statement()
تعيد الدالة القيمة True إن كانت السلسلة النصية المعطاة تتضمن جملة SQL واحدة أو أكثر تنتهي بالفاصلة المنقوطة.
الدالة sqlite3.enable_callback_tracebacks()
تتيح هذه الدالة عرض الأخطاء tracebacks الناتجة عن الدوال والمجاميع aggregates والمحوّلات converters والاستدعاءات الخلفية authorizer callbacks المفوِّضة المعرّفة من قبل المستخدم.
كائنات الاتصال Connection
تمتلك كائنات الاتصال بقواعد البيانات SQLite الخصائص والتوابع التالية:
الخاصية isolation_level
يمكن استخدام هذه الخاصية لمعرفة مستوى العزل الافتراضي الحالي أو تعيينه. تأخذ الخاصية القيمة None لنمط الحفظ التلقائي autocommit أو إحدى القيم "DEFERRED" أو "IMMEDIATE" أو "EXCLUSIVE". راجع قسم التحكم بالإجراءات للمزيد من المعلومات.
الخاصية in_transaction
تأخذ الخاصية القيمة True إن كان الإجراء فعّالًا (أي في حال وجود تعديلات غير محفوظة) وتأخذ القيمة False فيما عدا ذلك. هذه الخاصية للقراءة فقط.
التابع 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
كائنات الصف row
قواعد بيانات SQLite وأنواع بيانات بايثون
الاستثناءات في وحدة 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() والذي يعدّ استدعاؤه من خيط آخر أمرًا منطقيًا.