`sqlite3` --- رابط DB-API 2.0 برای پایگاه‌های داده SQLite¶

کد منبع: Lib/sqlite3/

SQLite کتابخانه‌ای به زبان C است که پایگاه داده‌ای سبک و مبتنی بر دیسک فراهم می‌کند که به فرایند سرور جداگانه‌ای نیاز ندارد و امکان دسترسی به پایگاه داده را با استفاده از گونه‌ای غیراستاندارد از زبان پرس‌وجوی SQL می‌دهد. برخی برنامه‌ها می‌توانند از SQLite برای ذخیره‌سازی داخلی داده‌ها استفاده کنند. همچنین می‌توان پیش‌نمونه‌ای از یک برنامه را با استفاده از SQLite ساخت و سپس کد را به پایگاه داده‌ی بزرگ‌تری مانند PostgreSQL یا Oracle منتقل کرد.

ماژول sqlite3 توسط Gerhard Häring نوشته شده است. این ماژول یک رابط SQL سازگار با مشخصات DB-API 2.0 ارائه می‌کند که در PEP 249 توصیف شده است، و به کتابخانه‌ی شخص ثالث SQLite نیاز دارد.

این یک ماژول اختیاری است. اگر در نسخه CPython شما وجود ندارد، برای مستندات به توزیع‌کننده خود مراجعه کنید (یعنی هر کسی که پایتون را در اختیار شما قرار داده است). اگر شما توزیع‌کننده هستید، نیازمندی‌های ماژول‌های اختیاری را ببینید.

این سند شامل چهار بخش اصلی است:

آموزش چگونگی استفاده از ماژول sqlite3 را آموزش می‌دهد.
مرجع کلاس‌ها و توابعی را که این ماژول تعریف می‌کند، شرح می‌دهد.
راهنماهای چگونگی جزئیات چگونگی انجام وظایف خاص را شرح می‌دهد.
توضیح پیش‌زمینه‌ای عمیق درباره‌ی کنترل تراکنش ارائه می‌دهد.

همچنین ملاحظه نمائید

https://www.sqlite.org: صفحه‌ی وب SQLite؛ مستندات، سینتکس و انواع داده‌های موجود برای گویش SQL پشتیبانی‌شده را توضیح می‌دهد.
https://www.w3schools.com/sql/: آموزش، مرجع و مثال‌هایی برای یادگیری سینتکس SQL.
PEP 249 - مشخصات API پایگاه داده 2.0: PEP نوشته‌شده توسط Marc-André Lemburg.

آموزش¶

در این آموزش، شما پایگاه داده‌ای از فیلم‌های مانتی پایتون را با استفاده از قابلیت‌های پایه sqlite3 ایجاد خواهید کرد. این آموزش فرض می‌کند که شما درک بنیادی از مفاهیم پایگاه داده، از جمله cursors و transactions دارید.

نخست، باید یک پایگاه داده جدید ایجاد کنیم و یک اتصال به پایگاه داده باز کنیم تا sqlite3 بتواند با آن کار کند. برای ایجاد اتصال به پایگاه داده‌ی tutorial.db در پوشه کاری فعلی، sqlite3.connect() را فراخوانی کنید؛ اگر این پایگاه داده وجود نداشته باشد، به‌طور ضمنی ایجاد می‌شود:

import sqlite3
con = sqlite3.connect("tutorial.db")

شیء Connection بازگردانده‌شده con، نشان‌دهنده‌ی اتصال به پایگاه داده‌ی روی دیسک است.

برای اجرای دستورات SQL و واکشی نتایج از پرس‌وجوهای SQL، باید از یک نشانگر پایگاه داده استفاده کنیم. برای ایجاد Cursor، con.cursor() را فراخوانی کنید:

cur = con.cursor()

اکنون که یک اتصال به پایگاه داده و یک نشانگر داریم، می‌توانیم یک جدول پایگاه داده به نام movie با ستون‌هایی برای عنوان، سال انتشار و امتیاز نقد ایجاد کنیم. برای سادگی، می‌توانیم فقط از نام ستون‌ها در تعریف جدول استفاده کنیم — به‌لطف قابلیت flexible typing در SQLite، تعیین نوع‌های داده اختیاری است. دستور CREATE TABLE را با فراخوانی cur.execute(...) اجرا کنید:

cur.execute("CREATE TABLE movie(title, year, score)")

می‌توانیم با پرس‌وجوی جدول sqlite_master توکار در SQLite، تأیید کنیم که جدول جدید ایجاد شده است؛ این جدول اکنون باید شامل ورودی‌ای برای تعریف جدول movie باشد (برای جزئیات The Schema Table را ببینید). آن پرس‌وجو را با فراخوانی cur.execute(...) اجرا کنید، نتیجه را به res اختصاص دهید و برای واکشی ردیف حاصل res.fetchone() را فراخوانی کنید:

>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

می‌توانیم ببینیم که جدول ایجاد شده است، زیرا پرس‌وجو یک tuple برمی‌گرداند که شامل نام جدول است. اگر sqlite_master را برای جدولی به نام spam که وجود ندارد پرس‌وجو کنیم، res.fetchone() None را برمی‌گرداند:

>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

اکنون، با اجرای یک دستور INSERT، دو ردیف داده را که به‌صورت مقادیر لفظی SQL ارائه شده‌اند، بار دیگر با فراخوانی cur.execute(...) اضافه کنید:

cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

دستور INSERT به‌طور ضمنی یک تراکنش را باز می‌کند، که باید پیش از ذخیره شدن تغییرات در پایگاه داده، ثبت (commit) شود (برای جزئیات کنترل تراکنش را ببینید). برای ثبت تراکنش، con.commit() را روی شیء اتصال فراخوانی کنید:

con.commit()

می‌توانیم با اجرای یک پرس‌وجوی SELECT تأیید کنیم که داده‌ها به‌درستی درج شده‌اند. از cur.execute(...) که اکنون برایتان آشناست، برای اختصاص نتیجه به res استفاده کنید و res.fetchall() را فراخوانی کنید تا تمام ردیف‌های حاصل را برگرداند:

>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

نتیجه یک list شامل دو tuple است، یکی به‌ازای هر ردیف، که هر یک حاوی مقدار score آن ردیف است.

اکنون، ۳ ردیف دیگر را با فراخوانی cur.executemany(...) درج کنید:

data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # Remember to commit the transaction after executing INSERT.

توجه داشته باشید که از جای‌نگهدارهای ? برای مقید کردن data به پرس‌وجو استفاده می‌شود. همیشه برای مقید کردن مقادیر پایتون به دستورهای SQL، به‌جای قالب‌بندی رشته از جای‌نگهدارها استفاده کنید تا از SQL injection attacks جلوگیری شود (برای جزئیات بیشتر چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم را ببینید).

می‌توانیم با اجرای یک پرس‌وجوی SELECT تأیید کنیم که ردیف‌های جدید درج شده‌اند؛ این بار با پیمایش روی نتایج پرس‌وجو:

>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")

هر ردیف یک tuple دو آیتمی از (year, title) است که با ستون‌های انتخاب‌شده در پرس‌وجو مطابقت دارد.

در نهایت، با فراخوانی con.close() برای بستن اتصال موجود، باز کردن یک اتصال جدید، ایجاد یک نشانگر جدید و سپس پرس‌وجو از پایگاه داده، تأیید کنید که پایگاه داده روی دیسک نوشته شده است:

>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()

اکنون با استفاده از ماژول sqlite3 یک پایگاه داده SQLite ایجاد کرده‌اید، داده‌ها را درج کرده‌اید و مقادیر را به روش‌های متعدد از آن بازیابی کرده‌اید.

همچنین ملاحظه نمائید

راهنماهای چگونگی برای مطالعه بیشتر:
توضیح برای پیش‌زمینه‌ی تفصیلی درباره‌ی کنترل تراکنش.

مرجع¶

توابع ماژول¶

sqlite3.connect(database, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, *, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)¶

باز کردن اتصال به یک پایگاه داده‌ی SQLite.

پارامترها:

database (path-like object) -- مسیر پرونده پایگاه داده‌ای که باید باز شود. می‌توانید ":memory:" را برای ایجاد یک پایگاه داده SQLite که فقط در حافظه وجود دارد و باز کردن اتصالی به آن ارسال کنید.
timeout (float) -- تعداد ثانیه‌هایی که اتصال باید هنگام قفل بودن یک جدول، پیش از پرتاب OperationalError منتظر بماند. اگر اتصال دیگری تراکنشی را برای تغییر یک جدول آغاز کند، آن جدول تا زمانی که تراکنش ثبت نهایی (commit) شود، قفل خواهد بود. پیش‌فرض پنج ثانیه است.
detect_types (int) -- کنترل کنید که آیا و چگونه انواع داده‌ای که به‌صورت بومی توسط SQLite پشتیبانی نمی‌شوند، جستجو می‌شوند تا با استفاده از مبدل‌های ثبت‌شده با register_converter() به نوع‌های پایتون تبدیل شوند. برای فعال‌سازی این مورد، آن را روی هر ترکیبی از PARSE_DECLTYPES و PARSE_COLNAMES (با استفاده از |، یای بیتی) تنظیم کنید. اگر هر دو پرچم تنظیم شده باشند، نام ستون‌ها بر نوع‌های اعلام‌شده اولویت دارند. به‌طور پیش‌فرض (0)، تشخیص نوع غیرفعال است.
isolation_level (str | None) -- رفتار مدیریت تراکنش‌ها به روش قدیمی را کنترل می‌کند. برای اطلاعات بیشتر Connection.isolation_level و کنترل تراکنش از طریق ویژگی isolation_level را ببینید. می‌تواند "DEFERRED" (پیش‌فرض)، "EXCLUSIVE" یا "IMMEDIATE" باشد؛ یا برای غیرفعال کردن باز شدن تراکنش‌ها به‌صورت ضمنی، None باشد. هیچ تأثیری ندارد مگر اینکه Connection.autocommit روی LEGACY_TRANSACTION_CONTROL (پیش‌فرض) تنظیم شده باشد.
check_same_thread (bool) -- اگر True (پیش‌فرض) باشد، در صورتی که از اتصال پایگاه داده در نخی غیر از نخی که آن را ایجاد کرده است استفاده شود، ProgrammingError پرتاب می‌شود. اگر False باشد، ممکن است اتصال در چندین نخ مورد دسترسی قرار گیرد؛ ممکن است لازم باشد کاربر برای جلوگیری از خرابی داده‌ها، عملیات نوشتن را به‌صورت متوالی اجرا کند. برای اطلاعات بیشتر threadsafety را ببینید.
factory (Connection) -- یک زیرکلاس سفارشی از Connection برای ایجاد اتصال با آن، اگر کلاس پیش‌فرض Connection نباشد.
cached_statements (int) -- تعداد دستورهایی که sqlite3 باید برای این اتصال به‌صورت داخلی در نهانگاه ذخیره کند، تا از سربار تجزیه جلوگیری شود. به‌طور پیش‌فرض، ۱۲۸ دستور.
uri (bool) -- اگر روی True تنظیم شود، database به‌عنوان یک URI با یک مسیر پرونده و یک رشته‌ی پرس‌وجوی اختیاری تفسیر می‌شود. بخش طرح‌واره باید "file:" باشد، و مسیر می‌تواند نسبی یا مطلق باشد. رشته‌ی پرس‌وجو امکان ارسال پارامترها به SQLite را فراهم می‌کند و ترفندهای گوناگون نحوه کار با URIهای SQLite را ممکن می‌سازد.
autocommit (bool) -- رفتار مدیریت تراکنش PEP 249 را کنترل می‌کند. برای اطلاعات بیشتر، Connection.autocommit و کنترل تراکنش از طریق ویژگی autocommit را ببینید. مقدار پیش‌فرض autocommit در حال حاضر LEGACY_TRANSACTION_CONTROL است. این مقدار پیش‌فرض در یکی از نسخه‌های آینده پایتون به False تغییر خواهد کرد.

نوع برگشتی:

Connection

یک رویداد حسابرسی sqlite3.connect را با آرگومان database پرتاب می‌کند.

یک رویداد حسابرسی sqlite3.connect/handle را با آرگومان connection_handle پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.4: پارامتر uri اضافه شد.

تغییر یافته در نسخه‌ی 3.7: database اکنون می‌تواند یک path-like object نیز باشد، نه فقط یک رشته.

تغییر یافته در نسخه‌ی 3.10: رویداد حسابرسی sqlite3.connect/handle افزوده شد.

تغییر یافته در نسخه‌ی 3.12: پارامتر autocommit افزوده شد.

تغییر یافته در نسخه‌ی 3.13: استفاده‌ی جایگاهی از پارامترهای timeout، detect_types، isolation_level، check_same_thread، factory، cached_statements و uri منسوخ شده است. این پارامترها در پایتون 3.15 به پارامترهای فقط کلیدواژه‌ای تبدیل خواهند شد.

sqlite3.complete_statement(statement)¶

اگر به نظر برسد که رشته‌ی statement حاوی یک یا چند دستور کامل SQL باشد، True را برمی‌گرداند. هیچ‌گونه صحت‌سنجی سینتکسی یا تجزیه‌ای از هیچ نوع انجام نمی‌شود، به‌جز بررسی اینکه هیچ لفظی رشته‌ای بسته‌نشده‌ای وجود نداشته باشد و دستور با نقطه‌ویرگول پایان یافته باشد.

برای مثال:

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False

این تابع ممکن است در حین ورودی از خط فرمان برای تشخیص این‌که آیا به نظر می‌رسد متن واردشده یک دستور SQL کامل را تشکیل می‌دهد، یا پیش از فراخوانی execute() به ورودی بیشتری نیاز است، مفید باشد.

برای استفاده در دنیای واقعی، runsource() را در Lib/sqlite3/__main__.py ببینید.

sqlite3.enable_callback_tracebacks(flag, /)¶: فعال یا غیرفعال کردن ردگیری‌های پشته‌ی کال‌بک‌ها. به‌طور پیش‌فرض، هیچ ردگیری پشته‌ای در توابع تعریف‌شده توسط کاربر، تجمیع‌ها، مبدل‌ها، کال‌بک‌های مجوزدهنده و غیره دریافت نخواهید کرد. اگر می‌خواهید آن‌ها را اشکال‌زدایی کنید، می‌توانید این تابع را با flag برابر True فراخوانی کنید. پس از آن، ردگیری‌های پشته‌ی کال‌بک‌ها را در sys.stderr دریافت خواهید کرد. برای غیرفعال کردن مجدد این قابلیت، از False استفاده کنید.

توجه

خطاهای کال‌بک‌های تابعی تعریف‌شده توسط کاربر به‌عنوان استثناهای غیرقابل‌پرتاب ثبت می‌شوند. برای درون‌نگری کال‌بک ناموفق، از یک unraisable hook handler استفاده کنید.

sqlite3.register_adapter(type, adapter, /)¶: یک adapter callable برای تبدیل نوع پایتون type به یک نوع SQLite ثبت کنید. این آداپتور با یک شیء پایتون از نوع type به‌عنوان تنها آرگومان خود فراخوانی می‌شود و باید مقداری از نوعی که SQLite به‌صورت بومی آن را می‌شناسد برگرداند.

sqlite3.register_converter(typename, converter, /)¶

برای تبدیل اشیای SQLite از نوع typename به یک شیء پایتون از نوع مشخص، converter callable را ثبت کنید. مبدل برای همه مقادیر SQLite از نوع typename فراخوانی می‌شود؛ یک شیء bytes به آن داده می‌شود و باید یک شیء از نوع پایتون دلخواه را برگرداند. برای آگاهی از چگونگی کارکرد تشخیص نوع، به پارامتر detect_types در connect() مراجعه کنید.

توجه: typename و نام نوع در پرس‌وجوی شما، بدون حساسیت به بزرگی و کوچکی حروف تطبیق داده می‌شوند.

ثابت‌های ماژول¶

sqlite3.LEGACY_TRANSACTION_CONTROL¶: برای انتخاب رفتار کنترل تراکنش به سبک قدیمی (پیش از Python 3.12)، autocommit را روی این ثابت تنظیم کنید. برای اطلاعات بیشتر کنترل تراکنش از طریق ویژگی isolation_level را ببینید.

sqlite3.PARSE_DECLTYPES¶

مقدار این پرچم را به پارامتر detect_types در connect() بدهید تا با استفاده از انواع اعلام‌شده برای هر ستون، یک تابع تبدیل‌کننده جست‌وجو شود. این انواع هنگام ایجاد جدول پایگاه داده اعلام می‌شوند. sqlite3 یک تابع تبدیل‌کننده را با استفاده از نخستین واژه‌ی نوع اعلام‌شده به‌عنوان کلید دیکشنری مبدل جست‌وجو می‌کند. برای مثال:

CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )

این پرچم را می‌توان با استفاده از عملگر | (یا بیت‌به‌بیت) با PARSE_COLNAMES ترکیب کرد.

توجه

فیلدهای تولیدشده (برای مثال MAX(p)) به‌صورت str برگردانده می‌شوند. برای اعمال نوع‌ها در چنین پرس‌وجوهایی از PARSE_COLNAMES استفاده کنید.

sqlite3.PARSE_COLNAMES¶

این مقدار پرچم را به پارامتر detect_types از connect() بدهید تا با استفاده از نام نوع، که از نام ستون پرس‌وجو تجزیه می‌شود، به‌عنوان کلید دیکشنری مبدل، یک تابع مبدل را جستجو کنید. نام ستون پرس‌وجو باید داخل علامت نقل‌قول دوتایی (") و نام نوع باید داخل کروشه ([]) قرار گیرد.

SELECT MAX(p) as "p [point]" FROM test;  ! will look up converter "point"

می‌توان این پرچم را با PARSE_DECLTYPES با استفاده از عملگر | (یای بیتی) ترکیب کرد.

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

پرچم‌هایی که باید توسط authorizer_callback callable ارسال‌شده به Connection.set_authorizer() بازگردانده شوند، تا نشان دهند که آیا:

دسترسی مجاز است (SQLITE_OK)،
دستور SQL باید با یک خطا متوقف شود (SQLITE_DENY)
این ستون باید به‌عنوان یک مقدار NULL در نظر گرفته شود (SQLITE_IGNORE)

sqlite3.apilevel¶: ثابت رشته‌ای که سطح DB-API پشتیبانی‌شده را اعلام می‌کند. مورد نیاز DB-API است. به‌صورت سخت‌کد (hard-coded) برابر با "2.0" است.

sqlite3.paramstyle¶: ثابت رشته‌ای که نوع قالب‌بندی نشانگر پارامتر مورد انتظار ماژول sqlite3 را مشخص می‌کند. این ثابت توسط DB-API الزامی شده و به‌صورت سخت‌کد به "qmark" تنظیم شده است.

توجه

سبک پارامتر named در DB-API نیز پشتیبانی می‌شود.

sqlite3.sqlite_version¶: شماره‌ی نسخه‌ی کتابخانه‌ی SQLite ران‌تایم به‌صورت یک string.

sqlite3.sqlite_version_info¶: شماره نسخه کتابخانه SQLite در ران‌تایم به‌صورت یک tuple از اعداد صحیح.

sqlite3.threadsafety¶

ثابت عدد صحیح مورد نیاز DB-API 2.0، که سطح ایمنی نخی را که ماژول sqlite3 پشتیبانی می‌کند، مشخص می‌کند. این ویژگی بر اساس حالت نخی (threading mode) پیش‌فرضی تنظیم می‌شود که کتابخانه زیربنایی SQLite با آن کامپایل شده است. حالت‌های نخی SQLite عبارتند از:

تک‌نخی: در این حالت، همه قفل‌های متقابل غیرفعال هستند و استفاده از SQLite در بیش از یک نخ به‌طور همزمان ایمن نیست.
چندنخی: در این حالت، می‌توان از SQLite به‌طور امن در چندین نخ استفاده کرد، مشروط بر اینکه هیچ اتصال پایگاه داده‌ای به‌طور همزمان در دو یا چند نخ استفاده نشود.
سریال‌شده: در حالت سریال‌شده، می‌توان از SQLite به‌صورت ایمن توسط چندین نخ بدون هیچ‌گونه محدودیتی استفاده کرد.

نگاشت حالت‌های نخی SQLite به سطوح ایمنی نخی DB-API 2.0 به شرح زیر است:

حالت نخ‌بندی SQLite	threadsafety	SQLITE_THREADSAFE	معنای DB-API 2.0
تک‌نخی	0	0	نخ‌ها نمی‌توانند ماژول را به اشتراک بگذارند
چندنخی	1	۲	نخ‌ها می‌توانند ماژول را به اشتراک بگذارند، اما اتصال‌ها را نه
سریال‌شده	۳	1	نخ‌ها می‌توانند ماژول، اتصال‌ها و نشانگرها را به اشتراک بگذارند

تغییر یافته در نسخه‌ی 3.11: به‌جای سخت‌کد کردن آن روی 1، threadsafety را به‌صورت پویا تنظیم کنید.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE¶

sqlite3.SQLITE_DBCONFIG_DQS_DDL¶

sqlite3.SQLITE_DBCONFIG_DQS_DML¶

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY¶

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER¶

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION¶

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG¶

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER¶

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW¶

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE¶

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT¶

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE¶

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE¶

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP¶

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA¶

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA¶

این ثابت‌ها برای متدهای Connection.setconfig() و getconfig() استفاده می‌شوند.

دسترس‌پذیری این ثابت‌ها بسته به نسخه‌ی SQLite که پایتون با آن کامپایل شده است، متفاوت است.

اضافه شده در نسخه‌ی 3.12.

همچنین ملاحظه نمائید

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html: مستندات SQLite: گزینه‌های پیکربندی اتصال پایگاه داده

منسوخ شده از نسخه‌ی 3.12، در نسخه‌ی 3.14 حذف شده است: ثابت‌های version و version_info.

اشیای اتصال¶

class sqlite3.Connection¶

هر پایگاه داده‌ی باز SQLite با یک شیء Connection نمایش داده می‌شود، که با استفاده از sqlite3.connect() ایجاد می‌شود. هدف اصلی آن‌ها ایجاد اشیای Cursor و کنترل تراکنش است.

همچنین ملاحظه نمائید

نحوه استفاده از متدهای میان‌بر اتصال
نحوه استفاده از مدیر زمینه اتصال

تغییر یافته در نسخه‌ی 3.13: اگر close() پیش از حذف یک شیء Connection فراخوانی نشود، یک ResourceWarning نشان داده می‌شود.

اتصال پایگاه داده‌ی SQLite دارای ویژگی‌ها و متدهای زیر است:

cursor(factory=Cursor)¶: یک شیء Cursor را ایجاد کرده و برمی‌گرداند. متد cursor یک پارامتر اختیاری واحد به نام factory می‌پذیرد. در صورت ارائه، این باید یک callable باشد که نمونه‌ای از Cursor یا زیرکلاس‌های آن را برمی‌گرداند.

blobopen(table, column, rowid, /, *, readonly=False, name='main')¶

یک دسته‌ی Blob به یک BLOB موجود باز کنید.

پارامترها:

table (str) -- نام جدولی که blob در آن قرار دارد.
column (str) -- نام ستونی که blob در آن قرار دارد.
rowid (int) -- شناسه‌ی ردیفی که blob در آن قرار دارد.
readonly (bool) -- اگر قرار باشد blob بدون اجازه‌های نوشتن باز شود، روی True تنظیم شود. پیش‌فرض آن False است.
name (str) -- نام پایگاه داده‌ای که بلاب (blob) در آن قرار دارد. به‌طور پیش‌فرض "main" است.

برانگیختن:

OperationalError -- هنگام تلاش برای باز کردن یک بلاب در جدول WITHOUT ROWID.

نوع برگشتی:

Blob

توجه

اندازه‌ی blob را نمی‌توان با استفاده از کلاس Blob تغییر داد. برای ایجاد یک blob با اندازه‌ی ثابت، از تابع SQL zeroblob استفاده کنید.

اضافه شده در نسخه‌ی 3.11.

commit()¶: هر تراکنش در انتظار را در پایگاه داده ثبت می‌کند. اگر autocommit برابر True باشد، یا هیچ تراکنش بازی وجود نداشته باشد، این متد هیچ کاری انجام نمی‌دهد. اگر autocommit برابر False باشد، چنانچه تراکنش در انتظاری توسط این متد ثبت شود، تراکنش جدیدی به‌طور ضمنی باز می‌شود.

rollback()¶: به آغاز هر تراکنش در حال انتظار عقب‌گرد می‌کند. اگر autocommit برابر True باشد، یا هیچ تراکنش بازی وجود نداشته باشد، این متد هیچ کاری انجام نمی‌دهد. اگر autocommit برابر False باشد، در صورتی که یک تراکنش در حال انتظار توسط این متد عقب‌گرد شده باشد، تراکنش جدیدی به‌طور ضمنی باز می‌شود.

close()¶: اتصال به پایگاه داده را ببندید. اگر autocommit برابر False باشد، هر تراکنش در انتظاری به‌صورت ضمنی بازگردانده می‌شود. اگر autocommit برابر True یا LEGACY_TRANSACTION_CONTROL باشد، هیچ کنترل تراکنشی به‌صورت ضمنی اعمال نمی‌شود. برای جلوگیری از دست رفتن تغییرات در انتظار، اطمینان حاصل کنید که پیش از بستن، commit() را فراخوانی کنید.

execute(sql, parameters=(), /)¶: یک شیء Cursor جدید ایجاد می‌کند و execute() را با sql و parameters داده‌شده روی آن فراخوانی می‌کند. شیء نشانگر جدید را برمی‌گرداند.

executemany(sql, parameters, /)¶: یک شیء Cursor جدید ایجاد کنید و executemany() را با sql و parameters داده‌شده روی آن فراخوانی کنید. شیء نشانگر جدید را برگردانید.

executescript(sql_script, /)¶: یک شیء Cursor جدید ایجاد می‌کند و executescript() را با sql_script داده‌شده روی آن فراخوانی می‌کند. شیء نشانگر جدید را برمی‌گرداند.

create_function(name, narg, func, *, deterministic=False)¶

ایجاد یا حذف یک تابع SQL تعریف‌شده توسط کاربر.

پارامترها:

name (str) -- نام تابع SQL.
narg (int) -- تعداد آرگومان‌هایی که تابع SQL می‌تواند بپذیرد. اگر -1 باشد، می‌تواند هر تعداد آرگومان بگیرد.
func (callback | None) -- یک فراخوانی‌پذیر است که هنگام فراخوانی تابع SQL فراخوانده می‌شود. این فراخوانی‌پذیر باید نوعی که SQLite به‌صورت بومی از آن پشتیبانی می‌کند را برگرداند. برای حذف یک تابع SQL موجود، آن را روی None تنظیم کنید.
deterministic (bool) -- اگر True باشد، تابع SQL ایجادشده به‌عنوان قطعی (deterministic) علامت‌گذاری می‌شود، که به SQLite امکان می‌دهد بهینه‌سازی‌های بیشتری انجام دهد.

تغییر یافته در نسخه‌ی 3.8: پارامتر deterministic افزوده شد.

مثال:

>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()

تغییر یافته در نسخه‌ی 3.13: ارسال name، narg و func به‌صورت آرگومان‌های کلیدواژه‌ای منسوخ شده است. این پارامترها در پایتون 3.15 فقط جایگاهی خواهند شد.

create_aggregate(name, n_arg, aggregate_class)¶

ایجاد یا حذف یک تابع تجمیعی SQL تعریف‌شده توسط کاربر.

پارامترها:

name (str) -- نام تابع تجمعی SQL.
n_arg (int) -- تعداد آرگومان‌هایی که تابع تجمیعی SQL می‌تواند بپذیرد. اگر -1 باشد، ممکن است هر تعداد آرگومان را بپذیرد.
aggregate_class (class | None) -- یک کلاس باید متدهای زیر را پیاده‌سازی کند: * step(): یک ردیف را به تجمیع اضافه می‌کند. * finalize(): نتیجه نهایی تجمیع را به‌عنوان نوعی که به‌صورت بومی توسط SQLite پشتیبانی می‌شود برمی‌گرداند. تعداد آرگومان‌هایی که متد step() باید بپذیرد، با n_arg کنترل می‌شود. برای حذف یک تابع تجمیعی SQL موجود، آن را روی None تنظیم کنید.

مثال:

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])

con.close()

تغییر یافته در نسخه‌ی 3.13: ارسال name، n_arg و aggregate_class به‌صورت آرگومان‌های کلیدواژه‌ای منسوخ شده است. این پارامترها در پایتون 3.15 فقط جایگاهی خواهند شد.

create_window_function(name, num_params, aggregate_class, /)¶

ایجاد یا حذف یک تابع پنجره‌ای تجمیعی تعریف‌شده توسط کاربر.

پارامترها:

name (str) -- نام تابع پنجره‌ای تجمیعی SQL برای ایجاد یا حذف.
num_params (int) -- تعداد آرگومان‌هایی که تابع تجمیعی پنجره‌ای SQL می‌تواند بپذیرد. اگر -1 باشد، می‌تواند هر تعداد آرگومان بگیرد.
aggregate_class (class | None) -- کلاسی که باید متدهای زیر را پیاده‌سازی کند: * step(): افزودن یک ردیف به پنجره جاری. * value(): برگرداندن مقدار فعلی تجمیع. * inverse(): حذف یک ردیف از پنجره جاری. * finalize(): برگرداندن نتیجه نهایی تجمیع به‌عنوان نوعی که SQLite به‌صورت بومی از آن پشتیبانی می‌کند. تعداد آرگومان‌هایی که متدهای step() و value() باید بپذیرند، با num_params کنترل می‌شود. برای حذف یک تابع پنجره‌ای تجمیعی SQL موجود، آن را روی None تنظیم کنید.

برانگیختن:

NotSupportedError -- اگر با نسخه‌ای از SQLite قدیمی‌تر از 3.25.0 استفاده شود، که از توابع پنجره‌ای تجمیعی پشتیبانی نمی‌کند.

اضافه شده در نسخه‌ی 3.11.

مثال:

# Example taken from https://www.sqlite.org/windowfunctions.html#udfwinfunc
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """Add a row to the current window."""
        self.count += value

    def value(self):
        """Return the current value of the aggregate."""
        return self.count

    def inverse(self, value):
        """Remove a row from the current window."""
        self.count -= value

    def finalize(self):
        """Return the final value of the aggregate.

        Any clean-up actions should be placed here.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()

create_collation(name, callable, /)¶

یک ترتیب‌گذاری (collation) به نام name با استفاده از تابع مقایسه‌کننده callable ایجاد کنید. callable دو آرگومان از نوع رشته دریافت می‌کند و باید یک عدد صحیح برگرداند:

1 اگر مورد اول بالاتر از مورد دوم مرتب شده باشد
-1 اگر اولی از نظر ترتیب، پایین‌تر از دومی باشد
0 اگر از نظر ترتیب برابر باشند

مثال زیر یک ترتیب‌گذاری (collation) مرتب‌سازی معکوس را نشان می‌دهد:

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()

برای حذف یک تابع ترتیب‌گذاری (collation)، callable را روی None تنظیم کنید.

تغییر یافته در نسخه‌ی 3.11: نام ترتیب‌گذاری (collation) می‌تواند شامل هر نویسه‌ای از Unicode باشد. پیش‌تر، فقط نویسه‌های ASCII مجاز بودند.

interrupt()¶: این متد را از یک نخ دیگر فراخوانی کنید تا هر پرس‌وجویی که ممکن است روی اتصال در حال اجرا باشد، لغو شود. پرس‌وجوهای لغوشده یک OperationalError پرتاب خواهند کرد.

set_authorizer(authorizer_callback)¶

authorizer_callback، یک فراخوانی‌پذیر، را ثبت کنید تا برای هر تلاش برای دسترسی به یک ستون از یک جدول در پایگاه داده فراخوانی شود. این کال‌بک باید یکی از SQLITE_OK، SQLITE_DENY یا SQLITE_IGNORE را برگرداند تا مشخص کند دسترسی به ستون باید توسط کتابخانه زیربنایی SQLite چگونه مدیریت شود.

نخستین آرگومان کال‌بک نشان می‌دهد که چه نوع عملیاتی باید مجاز شود. آرگومان دوم و سوم، بسته به آرگومان نخست، یا آرگومان‌هایی خواهند بود یا None. آرگومان چهارم در صورت لزوم، نام پایگاه داده ("main"، "temp" و غیره) است. آرگومان پنجم نام درونی‌ترین تریگر یا ویویی است که مسئول تلاش برای دسترسی است، یا None اگر این تلاش برای دسترسی مستقیماً از کد SQL ورودی باشد.

لطفاً مستندات SQLite را درباره‌ی مقادیر ممکن برای آرگومان اول و معنی آرگومان دوم و سوم، بسته به آرگومان اول، ببینید. همه‌ی ثابت‌های مورد نیاز در ماژول sqlite3 در دسترس هستند.

با ارسال None به‌عنوان authorizer_callback، تأییدکننده‌ی دسترسی غیرفعال می‌شود.

تغییر یافته در نسخه‌ی 3.11: پشتیبانی از غیرفعال‌سازی مجوزدهنده (authorizer) با استفاده از None افزوده شد.

تغییر یافته در نسخه‌ی 3.13: ارسال authorizer_callback به‌عنوان آرگومان کلیدواژه‌ای منسوخ شده است. این پارامتر در پایتون 3.15 فقط جایگاهی خواهد شد.

set_progress_handler(progress_handler, n)¶

callable progress_handler را ثبت کنید تا به ازای هر n دستورالعملِ ماشین مجازی SQLite فراخوانی شود. این قابلیت زمانی مفید است که بخواهید در حین عملیات‌های طولانی‌مدت از SQLite فراخوانی شوید، برای مثال برای به‌روزرسانی رابط کاربری گرافیکی (GUI).

اگر می‌خواهید هر مدیر پیشرفت (progress handler) نصب‌شده‌ی قبلی را پاک کنید، متد را با None برای progress_handler فراخوانی کنید.

بازگرداندن یک مقدار غیرصفر از تابع هندلر، پرس‌وجوی در حال اجرا را خاتمه می‌دهد و باعث می‌شود که یک استثنا DatabaseError پرتاب شود.

تغییر یافته در نسخه‌ی 3.13: ارسال progress_handler به‌عنوان آرگومان کلیدواژه‌ای منسوخ شده است. این پارامتر در Python 3.15 فقط جایگاهی خواهد شد.

set_trace_callback(trace_callback)¶

یک callable به نام trace_callback را ثبت کنید تا برای هر دستور SQL که به‌طور واقعی توسط بک‌اند SQLite اجرا می‌شود، فراخوانی شود.

تنها آرگومانی که به کال‌بک داده می‌شود، دستور در حال اجرا (به‌صورت str) است. مقدار بازگشتی کال‌بک نادیده گرفته می‌شود. توجه داشته باشید که بک‌اند تنها دستورهایی را که به متدهای Cursor.execute() داده‌شده‌اند، اجرا نمی‌کند. منابع دیگر شامل مدیریت تراکنش ماژول sqlite3 و اجرای ماشه‌های تعریف‌شده در پایگاه داده‌ی جاری هستند.

با ارسال None به‌عنوان trace_callback، کال‌بک ردگیری غیرفعال می‌شود.

توجه

استثناهای پرتاب‌شده در کال‌بک ردگیری منتشر نمی‌شوند. به‌عنوان کمکی برای توسعه و اشکال‌زدایی، از enable_callback_tracebacks() برای فعال کردن چاپ ردگیری‌های پشته‌ی استثناهای پرتاب‌شده در کال‌بک ردگیری استفاده کنید.

اضافه شده در نسخه‌ی 3.3.

تغییر یافته در نسخه‌ی 3.13: ارسال trace_callback به‌عنوان آرگومان کلیدواژه‌ای منسوخ شده است. این پارامتر در پایتون 3.15 فقط جایگاهی خواهد شد.

enable_load_extension(enabled, /)¶

اگر enabled برابر True باشد، به موتور SQLite اجازه می‌دهد تا افزونه‌های SQLite را از کتابخانه‌های مشترک بارگذاری کند؛ در غیر این صورت، بارگذاری افزونه‌های SQLite را مجاز نمی‌داند. افزونه‌های SQLite می‌توانند توابع جدید، تجمیع‌ها یا پیاده‌سازی‌های کاملاً جدید جدول مجازی را تعریف کنند. یکی از افزونه‌های شناخته‌شده، افزونه جستجوی تمام‌متنی (fulltext-search) است که همراه SQLite توزیع شده است.

توجه

ماژول sqlite3 به‌طور پیش‌فرض با پشتیبانی از افزونه‌های قابل بارگذاری ساخته نمی‌شود، زیرا برخی سکوها (به‌ویژه macOS) کتابخانه‌های SQLite دارند که بدون این قابلیت کامپایل شده‌اند. برای بهره‌مندی از پشتیبانی از افزونه‌های قابل بارگذاری، باید گزینه‌ی --enable-loadable-sqlite-extensions را به configure بدهید.

یک رویداد حسابرسی sqlite3.enable_load_extension را با آرگومان‌های connection و enabled پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.10: رویداد حسابرسی sqlite3.enable_load_extension اضافه شد.

con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)

load_extension(path, /, *, entrypoint=None)¶

یک افزونه‌ی SQLite را از یک کتابخانه مشترک بارگذاری کنید. پیش از فراخوانی این متد، بارگذاری افزونه را با enable_load_extension() فعال کنید.

پارامترها:

path (str) -- مسیر افزونه‌ی SQLite.
entrypoint (str | None) -- نام نقطه ورود. اگر None (پیش‌فرض) باشد، SQLite نام نقطه ورود خاص خود را انتخاب می‌کند؛ برای جزئیات، مستندات SQLite با عنوان Loading an Extension را ببینید.

یک رویداد حسابرسی sqlite3.load_extension را با آرگومان‌های connection و path پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.10: رویداد حسابرسی sqlite3.load_extension افزوده شد.

تغییر یافته در نسخه‌ی 3.12: پارامتر entrypoint اضافه شد.

iterdump(*, filter=None)¶

یک iterator برای برون‌ریزی پایگاه داده به‌صورت کد منبع SQL برمی‌گرداند. هنگام ذخیره‌ی یک پایگاه داده‌ی درون‌حافظه‌ای برای بازیابی بعدی مفید است. مشابه دستور .dump در پوسته‌ی sqlite3 است.

پارامترها:: filter (str | None) -- یک الگوی LIKE اختیاری برای اشیای پایگاه داده‌ای که باید برون‌ریزی شوند، به‌عنوان مثال prefix_%. اگر None (پیش‌فرض) باشد، تمام اشیای پایگاه داده گنجانده می‌شوند.

مثال:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
con.close()

همچنین ملاحظه نمائید

نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8

تغییر یافته در نسخه‌ی 3.13: پارامتر filter اضافه شد.

backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)¶

یک نسخه پشتیبان از پایگاه‌داده SQLite ایجاد کنید.

حتی اگر پایگاه داده توسط کلاینت‌های دیگر یا به‌صورت همزمان توسط همان اتصال در حال دسترسی باشد، باز هم کار می‌کند.

پارامترها:

target (Connection) -- اتصال پایگاه داده‌ای که نسخه پشتیبان در آن ذخیره می‌شود.
pages (int) -- تعداد صفحه‌هایی که در هر نوبت کپی می‌شوند. اگر برابر یا کمتر از 0 باشد، کل پایگاه داده در یک مرحله کپی می‌شود. مقدار پیش‌فرض آن -1 است.
progress (callback | None) -- اگر به یک callable تنظیم شود، در هر تکرار پشتیبان‌گیری با سه آرگومان عدد صحیحی فراخوانی می‌شود: وضعیت آخرین تکرار، تعداد صفحات باقی‌مانده که هنوز باید کپی شوند و تعداد کل صفحات. مقدار پیش‌فرض آن None است.
name (str) -- نام پایگاه داده‌ای که از آن پشتیبان‌گیری می‌شود. یا "main" (پیش‌فرض) برای پایگاه داده اصلی، "temp" برای پایگاه داده موقت، یا نام یک پایگاه داده سفارشی که با دستور SQL ATTACH DATABASE متصل شده است.
sleep (float) -- تعداد ثانیه‌های توقف بین تلاش‌های متوالی برای پشتیبان‌گیری صفحه‌های باقی‌مانده.

مثال ۱، کپی کردن یک پایگاه داده‌ی موجود به پایگاه داده‌ای دیگر:

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

مثال ۲، کپی یک پایگاه داده‌ی موجود به یک کپی گذرا:

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

اضافه شده در نسخه‌ی 3.7.

همچنین ملاحظه نمائید

نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8

getlimit(category, /)¶

محدودیت ران‌تایم یک اتصال را دریافت کنید.

پارامترها:: category (int) -- SQLite limit category که باید پرس‌وجو شود.
نوع برگشتی:: int
برانگیختن:: ProgrammingError -- اگر category توسط کتابخانه SQLite زیربنایی شناسایی نشود.

مثال، حداکثر طول یک دستور SQL را برای Connection con پرس‌وجو کنید (مقدار پیش‌فرض ۱۰۰۰۰۰۰۰۰۰ است):

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

اضافه شده در نسخه‌ی 3.11.

setlimit(category, limit, /)¶

یک محدودیت ران‌تایم اتصال را تنظیم می‌کند. اگر تلاش شود محدودیتی به بالاتر از کران بالایی سخت خود افزایش یابد، بدون هیچ پیامی به کران بالایی سخت تقلیل می‌یابد. صرف‌نظر از اینکه محدودیت تغییر کرده باشد یا خیر، مقدار پیشین محدودیت برگردانده می‌شود.

پارامترها:

category (int) -- SQLite limit category که باید تنظیم شود.
limit (int) -- مقدار محدودیت جدید. اگر منفی باشد، محدودیت فعلی بدون تغییر می‌ماند.

نوع برگشتی:

int

برانگیختن:

ProgrammingError -- اگر category توسط کتابخانه SQLite زیربنایی شناسایی نشود.

مثال، تعداد پایگاه‌های داده‌ی پیوست‌شده را برای Connection con به ۱ محدود کنید (محدودیت پیش‌فرض ۱۰ است):

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

اضافه شده در نسخه‌ی 3.11.

getconfig(op, /)¶

یک گزینه‌ی پیکربندی اتصال بولی را پرس‌وجو کنید.

پارامترها:: op (int) -- یک کد SQLITE_DBCONFIG.
نوع برگشتی:: bool

اضافه شده در نسخه‌ی 3.12.

setconfig(op, enable=True, /)¶

یک گزینه‌ی پیکربندی اتصال از نوع بولی را تنظیم کنید.

پارامترها:

op (int) -- یک کد SQLITE_DBCONFIG.
enable (bool) -- True اگر گزینه‌ی پیکربندی باید فعال باشد (پیش‌فرض)؛ False اگر باید غیرفعال باشد.

اضافه شده در نسخه‌ی 3.12.

serialize(*, name='main')¶

یک پایگاه داده را به یک شیء bytes سریال‌سازی می‌کند. برای یک پرونده پایگاه داده‌ی معمولی روی دیسک، سریال‌سازی صرفاً رونوشتی از پرونده دیسک است. برای یک پایگاه داده‌ی درون‌حافظه‌ای یا یک پایگاه داده‌ی "temp"، سریال‌سازی همان دنباله‌ای از بایت‌ها است که اگر آن پایگاه داده روی دیسک پشتیبان‌گیری می‌شد، روی دیسک نوشته می‌شد.

پارامترها:: name (str) -- نام پایگاه داده‌ای که باید سریال‌سازی شود. پیش‌فرض "main" است.
نوع برگشتی:: bytes

توجه

این متد فقط در صورتی در دسترس است که کتابخانه SQLite زیرین، دارای API سریال‌سازی (serialize) باشد.

اضافه شده در نسخه‌ی 3.11.

deserialize(data, /, *, name='main')¶

یک پایگاه داده‌ی سریال‌سازی‌شده را به یک Connection از سریال‌سازی خارج کنید. این متد موجب می‌شود اتصال پایگاه داده از پایگاه داده‌ی name قطع شود و name به‌عنوان یک پایگاه داده‌ی درون‌حافظه‌ای بر اساس سریال‌سازی موجود در data بازگشایی شود.

پارامترها:

data (bytes) -- یک پایگاه داده سریال‌سازی‌شده.
name (str) -- نام پایگاه داده مقصد برای سریال‌زدایی کردن (deserialize). پیش‌فرض آن "main" است.

برانگیختن:

OperationalError -- اگر اتصال پایگاه داده در حال حاضر درگیر یک تراکنش خواندن یا یک عملیات پشتیبان‌گیری باشد.
DatabaseError -- اگر data شامل یک پایگاه داده SQLite معتبر نباشد.
OverflowError -- اگر len(data) بزرگ‌تر از 2**63 - 1 باشد.

توجه

این متد تنها در صورتی در دسترس است که کتابخانه SQLite زیرین دارای API سریال‌زدایی کردن (deserialize) باشد.

اضافه شده در نسخه‌ی 3.11.

autocommit¶

این ویژگی رفتار تراکنش مطابق با PEP 249 را کنترل می‌کند. autocommit سه مقدار مجاز دارد:

False: رفتار تراکنشی مطابق PEP 249 را انتخاب می‌کند، به این معنا که sqlite3 تضمین می‌کند یک تراکنش همیشه باز است. برای بستن تراکنش‌ها از commit() و rollback() استفاده کنید.

این مقدار توصیه‌شده برای autocommit است.
True: از autocommit mode SQLite استفاده کنید. در این حالت، commit() و rollback() هیچ تأثیری ندارند.
LEGACY_TRANSACTION_CONTROL: کنترل تراکنش پیش از پایتون 3.12 (ناسازگار با PEP 249). برای جزئیات بیشتر isolation_level را ببینید.

این در حال حاضر مقدار پیش‌فرض autocommit است.

تغییر autocommit به False یک تراکنش جدید را باز می‌کند، و تغییر آن به True هر تراکنش در انتظار را ثبت (commit) می‌کند.

برای جزئیات بیشتر به کنترل تراکنش از طریق ویژگی autocommit مراجعه کنید.

توجه

ویژگی isolation_level تأثیری ندارد، مگر اینکه autocommit برابر LEGACY_TRANSACTION_CONTROL باشد.

اضافه شده در نسخه‌ی 3.12.

in_transaction¶

این ویژگی فقط‌خواندنی، متناظر با حالت autocommit mode سطح پایین در SQLite است.

اگر یک تراکنش فعال باشد (تغییرات ثبت‌نشده‌ای وجود داشته باشد)، True و در غیر این صورت False است.

اضافه شده در نسخه‌ی 3.2.

isolation_level¶

حالت مدیریت تراکنش قدیمی در sqlite3 را کنترل می‌کند. اگر روی None تنظیم شود، تراکنش‌ها هرگز به‌صورت ضمنی باز نمی‌شوند. اگر روی یکی از "DEFERRED"، "IMMEDIATE" یا "EXCLUSIVE" تنظیم شود، مطابق با SQLite transaction behaviour زیربنایی، مدیریت ضمنی تراکنش انجام می‌شود.

اگر پارامتر isolation_level در connect() آن را بازنویسی نکند، مقدار پیش‌فرض "" است که نام مستعاری برای "DEFERRED" محسوب می‌شود.

توجه

استفاده از autocommit برای کنترل مدیریت تراکنش، به‌جای استفاده از isolation_level توصیه می‌شود. isolation_level هیچ تأثیری ندارد، مگر اینکه autocommit روی LEGACY_TRANSACTION_CONTROL (پیش‌فرض) تنظیم شده باشد.

row_factory¶

row_factory اولیه برای اشیای Cursor ایجادشده از این اتصال. انتساب به این ویژگی بر row_factory نشانگرهای موجود متعلق به این اتصال تأثیری نمی‌گذارد و فقط نشانگرهای جدید را تحت تأثیر قرار می‌دهد. به‌طور پیش‌فرض None است، به این معنا که هر ردیف به‌صورت یک tuple بازگردانده می‌شود.

برای جزئیات بیشتر نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories) را ببینید.

تغییر یافته در نسخه‌ی 3.14.6: حذف ویژگی row_factory دیگر مجاز نیست.

text_factory¶

یک callable که یک پارامتر از نوع bytes را می‌پذیرد و یک نمایش متنی از آن را برمی‌گرداند. این callable برای مقادیر SQLite با نوع داده TEXT فراخوانی می‌شود. به‌طور پیش‌فرض، این ویژگی روی str تنظیم شده است.

برای جزئیات بیشتر نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8 را ببینید.

تغییر یافته در نسخه‌ی 3.14.6: حذف ویژگی text_factory دیگر مجاز نیست.

total_changes¶: تعداد کل ردیف‌های پایگاه داده را که از زمان باز شدن اتصال پایگاه داده تغییریافته، درج‌شده یا حذف‌شده‌اند، برمی‌گرداند.

اشیای نشانگر¶

یک شیء Cursor نشان‌دهنده‌ی یک database cursor است که برای اجرای دستورات SQL و مدیریت زمینه‌ی یک عملیات واکشی استفاده می‌شود. نشانگرها با استفاده از Connection.cursor()، یا با استفاده از هر یک از متدهای میان‌بر اتصال ایجاد می‌شوند.

اشیاء Cursor از نوع پیمایش‌گر هستند، به این معنا که اگر یک پرس‌وجوی SELECT را execute() کنید، می‌توانید برای واکشی ردیف‌های حاصل، به‌سادگی روی نشانگر پیمایش کنید:
for row in cur.execute("SELECT t FROM data"):
    print(row)

class sqlite3.Cursor¶

یک نمونه Cursor دارای ویژگی‌ها و متدهای زیر است.

execute(sql, parameters=(), /)¶

یک دستور SQL واحد را اجرا کنید و به‌صورت اختیاری مقادیر پایتون را با استفاده از جای‌نگهدارها مقید کنید.

پارامترها:

sql (str) -- یک دستور SQL واحد.
parameters (dict | sequence) -- مقادیر پایتون برای مقیدسازی به جای‌نگهدارها در sql. در صورت استفاده از جای‌نگهدارهای نام‌دار، یک dict. در صورت استفاده از جای‌نگهدارهای بی‌نام، یک sequence. چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم را ببینید.

برانگیختن:

ProgrammingError -- هنگامی که sql شامل بیش از یک دستور SQL باشد. هنگامی که از جای‌نگهدارهای نام‌گذاری‌شده استفاده می‌شود و parameters به‌جای یک dict یک دنباله باشد.

اگر autocommit برابر LEGACY_TRANSACTION_CONTROL باشد، isolation_level برابر None نباشد، sql یک دستور INSERT، UPDATE، DELETE یا REPLACE باشد و هیچ تراکنش بازی وجود نداشته باشد، پیش از اجرای sql، یک تراکنش به‌طور ضمنی باز می‌شود.

تغییر یافته در نسخه‌ی 3.14: ProgrammingError پرتاب می‌شود، اگر از جای‌نگهدارهای نام‌دار استفاده شود و parameters به‌جای یک dict یک دنباله باشد.

برای اجرای چندین دستور SQL از executescript() استفاده کنید.

executemany(sql, parameters, /)¶

به ازای هر آیتم در parameters، دستور SQL DML (زبان دست‌کاری داده‌ها) <DML (Data Manipulation Language)> پارامتریزه sql را به‌طور مکرر اجرا کنید.

از همان مدیریت تراکنش ضمنیِ execute() استفاده می‌کند.

پارامترها:

sql (str) -- یک دستور SQL DML.
parameters (iterable) -- یک iterable از پارامترها برای مقیدسازی با جای‌نگهدارها در sql. چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم را ببینید.

برانگیختن:

ProgrammingError -- هنگامی که sql شامل بیش از یک دستور SQL باشد یا یک دستور DML نباشد، هنگامی که از جای‌نگهدارهای نام‌گذاری‌شده استفاده شود و آیتم‌های parameters به جای dicts دنباله باشند.

مثال:

rows = [
    ("row1",),
    ("row2",),
]
# cur is an sqlite3.Cursor object
cur.executemany("INSERT INTO data VALUES(?)", rows)

توجه

هر ردیف حاصل دور ریخته می‌شود، از جمله در دستورات DML با RETURNING clauses.

تغییر یافته در نسخه‌ی 3.14: اگر از جای‌نگهدارهای نام‌دار استفاده شود و آیتم‌های درون parameters به‌جای dicts دنباله باشند، ProgrammingError پرتاب می‌شود.

executescript(sql_script, /)¶

دستورات SQL موجود در sql_script را اجرا کنید. اگر autocommit برابر LEGACY_TRANSACTION_CONTROL باشد و یک تراکنش در انتظار وجود داشته باشد، ابتدا یک دستور COMMIT ضمنی اجرا می‌شود. هیچ‌گونه کنترل تراکنش ضمنی دیگری انجام نمی‌شود؛ هرگونه کنترل تراکنش باید به sql_script اضافه شود.

sql_script باید یک رشته باشد.

مثال:

# cur is an sqlite3.Cursor object
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()¶: اگر row_factory None باشد، ردیف بعدی از مجموعه‌ی نتایج پرس‌وجو را به‌صورت یک tuple برمی‌گرداند. در غیر این صورت، آن را به کارخانه‌ی ردیف (row factory) می‌دهد و نتیجه‌ی آن را برمی‌گرداند. اگر داده‌ی بیشتری در دسترس نباشد، None را برمی‌گرداند.

fetchmany(size=cursor.arraysize)¶

برگرداندن دسته‌ی بعدی از ردیف‌های نتیجه‌ی یک پرس‌وجو به‌عنوان یک list. اگر دیگر ردیفی در دسترس نباشد، یک فهرست خالی برمی‌گرداند.

تعداد ردیفهایی که در هر فراخوانی واکشی می‌شوند، با پارامتر size مشخص می‌شود. اگر size داده نشود، arraysize تعداد ردیفهای واکشی‌شده را تعیین می‌کند. اگر کمتر از size ردیف در دسترس باشد، هر تعداد ردیفی که در دسترس باشد بازگردانده می‌شود.

توجه داشته باشید که ملاحظات عملکردی مرتبط با پارامتر size وجود دارد. برای عملکرد بهینه، معمولاً بهتر است از ویژگی arraysize استفاده کنید. اگر از پارامتر size استفاده می‌شود، بهتر است مقدار آن از یک فراخوانی fetchmany() تا فراخوانی بعدی ثابت بماند.

تغییر یافته در نسخه‌ی 3.14.1: مقادیر منفی size با پرتاب ValueError رد می‌شوند.

fetchall()¶: تمام ردیف‌های (باقی‌مانده) نتیجه‌ی پرس‌وجو را به‌صورت یک list برمی‌گرداند. اگر هیچ ردیفی موجود نباشد، یک فهرست خالی برمی‌گرداند. توجه داشته باشید که ویژگی arraysize می‌تواند بر عملکرد این عملیات تأثیر بگذارد.

close()¶

اکنون نشانگر را ببندید (نه هر زمان که __del__ فراخوانی می‌شود).

از این نقطه به بعد، نشانگر غیرقابل استفاده خواهد بود؛ در صورت تلاش برای انجام هر عملیاتی با نشانگر، استثنای ProgrammingError پرتاب خواهد شد.

setinputsizes(sizes, /)¶: مورد نیاز DB-API است. در sqlite3 هیچ کاری انجام نمی‌دهد.

setoutputsize(size, column=None, /)¶: مورد نیاز DB-API است. در sqlite3 هیچ کاری انجام نمی‌دهد.

arraysize¶: ویژگی خواندنی/نوشتنی که تعداد ردیف‌های بازگردانده‌شده توسط fetchmany() را کنترل می‌کند. مقدار پیش‌فرض ۱ است، یعنی در هر فراخوانی یک ردیف واکشی می‌شود.

تغییر یافته در نسخه‌ی 3.14.1: مقادیر منفی با پرتاب ValueError رد می‌شوند.

connection¶

ویژگی فقط‌خواندنی که Connection پایگاه داده‌ی SQLite متعلق به نشانگر را فراهم می‌کند. یک شیء Cursor که با فراخوانی con.cursor() ایجاد شده باشد، ویژگی connection خواهد داشت که به con ارجاع می‌دهد:

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()

description¶

ویژگی فقط‌خواندنی که نام ستون‌های آخرین پرس‌وجو را ارائه می‌دهد. برای حفظ سازگاری با Python DB API، برای هر ستون یک تاپل ۷تایی بازمی‌گرداند که شش آیتم پایانی هر تاپل None هستند.

این ویژگی برای دستورهای SELECT که هیچ ردیف منطبقی ندارند نیز تنظیم می‌شود.

lastrowid¶: ویژگی فقط‌خواندنی که شناسه‌ی آخرین ردیف درج‌شده را فراهم می‌کند. این ویژگی فقط پس از دستورهای موفق INSERT یا REPLACE با استفاده از متد execute() به‌روزرسانی می‌شود. برای دستورهای دیگر، پس از executemany() یا executescript()، یا اگر درج ناموفق باشد، مقدار lastrowid بدون تغییر باقی می‌ماند. مقدار اولیه‌ی lastrowid برابر None است.

توجه

درج‌ها در جدول‌های WITHOUT ROWID ثبت نمی‌شوند.

تغییر یافته در نسخه‌ی 3.6: پشتیبانی از دستور REPLACE افزوده شد.

rowcount¶: ویژگی فقط‌خواندنی که تعداد ردیفهای تغییرکرده توسط دستورهای INSERT، UPDATE، DELETE و REPLACE را ارائه می‌دهد؛ برای سایر دستورها، از جمله پرس‌وجوهای CTE، -1 است. این ویژگی فقط توسط متدهای execute() و executemany()، پس از اجرای کامل دستور به‌روزرسانی می‌شود. این بدان معناست که برای به‌روزرسانی rowcount باید همه ردیفهای حاصل واکشی شوند.

row_factory¶

چگونگی بازنمایی ردیفی را که از این Cursor واکشی می‌شود، کنترل می‌کند. اگر None باشد، یک ردیف به‌صورت یک tuple بازنمایی می‌شود. می‌توان آن را روی sqlite3.Row ارائه‌شده تنظیم کرد؛ یا روی یک callable که دو آرگومان می‌پذیرد، یک شیء Cursor و tuple مقدارهای ردیف، و یک شیء سفارشی را بازمی‌گرداند که یک ردیف SQLite را بازنمایی می‌کند.

به‌طور پیش‌فرض برابر مقداری است که Connection.row_factory هنگام ایجاد Cursor روی آن تنظیم شده است. انتساب به این ویژگی بر Connection.row_factory اتصال والد تأثیری نمی‌گذارد.

برای جزئیات بیشتر نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories) را ببینید.

تغییر یافته در نسخه‌ی 3.14.6: حذف ویژگی row_factory دیگر مجاز نیست.

اشیای Row¶

class sqlite3.Row¶

نمونه‌ای از Row به‌عنوان یک row_factory بسیار بهینه‌شده برای اشیای Connection عمل می‌کند. این نمونه از تکرار، آزمون برابری، len() و دسترسی به‌صورت mapping از طریق نام و اندیس ستون پشتیبانی می‌کند.

دو شیء Row زمانی برابر مقایسه می‌شوند که نام‌ها و مقادیر ستون‌های یکسانی داشته باشند.

برای جزئیات بیشتر نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories) را ببینید.

keys()¶: یک list از نام ستون‌ها به‌صورت strings برمی‌گرداند. بلافاصله پس از یک پرس‌وجو، اولین عضو هر تاپل در Cursor.description است.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از اسلایس افزوده شد.

اشیای Blob¶

class sqlite3.Blob¶

اضافه شده در نسخه‌ی 3.11.

یک نمونه از Blob یک شیء شبه‌پرونده است که می‌تواند داده‌ها را در یک BLOB مربوط به SQLite بخواند و بنویسد. برای دریافت اندازه‌ی blob (یعنی تعداد بایت‌های آن)، len(blob) را فراخوانی کنید. برای دسترسی مستقیم به داده‌های blob، از اندیس‌ها و اسلایس‌ها استفاده کنید.

از Blob به‌عنوان یک context manager استفاده کنید تا اطمینان حاصل شود که دسته‌ی blob پس از استفاده بسته می‌شود.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# Write to our blob, using two write operations:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # Modify the first and last bytes of our blob
    blob[0] = ord("H")
    blob[-1] = ord("!")

# Read the contents of our blob
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # outputs "b'Hello, world!'"
con.close()

close()¶

بلاب را ببندید.

این blob از این نقطه به بعد غیرقابل استفاده خواهد بود. در صورت تلاش برای انجام هر عملیات دیگری با blob، یک استثنای Error (یا زیرکلاس آن) پرتاب خواهد شد.

read(length=-1, /)¶: length بایت داده از بلاب در موقعیت فعلی آفست خوانده می‌شود. اگر به انتهای بلاب رسیده شود، داده تا EOF بازگردانده می‌شود. هنگامی که length مشخص نشده باشد یا منفی باشد، read() تا انتهای بلاب می‌خواند.

write(data, /)¶: data را در آفست فعلی بلاب بنویسید. این تابع نمی‌تواند طول بلاب را تغییر دهد. نوشتن فراتر از انتهای بلاب باعث پرتاب ValueError می‌شود.

tell()¶: موقعیت دسترسی جاری بلاب را برمی‌گرداند.

seek(offset, origin=os.SEEK_SET, /)¶: موقعیت دسترسی فعلی بلاب را روی offset تنظیم می‌کند. آرگومان origin به‌طور پیش‌فرض os.SEEK_SET (موقعیت‌دهی مطلق بلاب) است. مقادیر دیگر برای origin عبارت‌اند از os.SEEK_CUR (جابه‌جایی نسبت به موقعیت فعلی) و os.SEEK_END (جابه‌جایی نسبت به انتهای بلاب).

اشیای PrepareProtocol¶

class sqlite3.PrepareProtocol¶: تنها هدف نوع PrepareProtocol این است که به‌عنوان یک پروتکل تطبیق به سبک PEP 246 برای اشیایی عمل کند که می‌توانند خود را وفق دهند به انواع ذاتی SQLite.

استثناها¶

سلسله‌مراتب استثنا توسط DB-API 2.0 تعریف شده است (PEP 249).

exception sqlite3.Warning¶: این استثنا در حال حاضر توسط ماژول sqlite3 پرتاب نمی‌شود، اما ممکن است توسط برنامه‌هایی که از sqlite3 استفاده می‌کنند پرتاب شود، برای مثال اگر یک تابع تعریف‌شده توسط کاربر هنگام درج، داده‌ها را کوتاه کند. Warning زیرکلاسی از Exception است.

exception sqlite3.Error¶

کلاس پایه‌ی سایر استثناهای این ماژول. از این برای گرفتن همه‌ی خطاها با یک دستور except واحد استفاده کنید. Error یک زیرکلاس از Exception است.

اگر استثنا از درون کتابخانه SQLite سرچشمه گرفته باشد، دو ویژگی زیر به استثنا اضافه می‌شوند:

sqlite_errorcode¶: کد خطای عددی از SQLite API

اضافه شده در نسخه‌ی 3.11.

sqlite_errorname¶: نام نمادینِ کد خطای عددی از SQLite API

اضافه شده در نسخه‌ی 3.11.

exception sqlite3.InterfaceError¶: استثنایی که برای استفاده‌ی نادرست از API سطح پایین C در SQLite پرتاب می‌شود. به عبارت دیگر، اگر این استثنا پرتاب شد، احتمالاً نشان‌دهنده‌ی یک خطا در ماژول sqlite3 است. InterfaceError زیرکلاسی از Error است.

exception sqlite3.DatabaseError¶: استثنایی که برای خطاهای مرتبط با پایگاه داده پرتاب می‌شود. این استثنا به‌عنوان استثنای پایه برای چندین نوع از خطاهای پایگاه داده عمل می‌کند. این استثنا تنها به‌طور ضمنی از طریق زیرکلاس‌های تخصصی پرتاب می‌شود. DatabaseError یک زیرکلاس از Error است.

exception sqlite3.DataError¶: استثنایی که برای خطاهای ناشی از مشکلات در داده‌های پردازش‌شده، مانند مقادیر عددی خارج از محدوده و رشته‌هایی که بیش از حد طولانی هستند، پرتاب می‌شود. DataError زیرکلاسی از DatabaseError است.

exception sqlite3.OperationalError¶: استثنایی که برای خطاهایی پرتاب می‌شود که به عملیات پایگاه داده مرتبط هستند و لزوماً تحت کنترل برنامه‌نویس نیستند. برای مثال، مسیر پایگاه داده پیدا نشود یا تراکنشی قابل پردازش نباشد. OperationalError زیرکلاسی از DatabaseError است.

exception sqlite3.IntegrityError¶: استثنایی که هنگامی پرتاب می‌شود که یکپارچگی رابطه‌ای پایگاه داده تحت تأثیر قرار بگیرد، برای مثال وقتی بررسی کلید خارجی ناموفق باشد. این استثنا یک زیرکلاس از DatabaseError است.

exception sqlite3.InternalError¶: استثنایی که هنگام بروز خطای داخلی در SQLite پرتاب می‌شود. اگر این استثنا پرتاب شود، ممکن است نشان‌دهنده‌ی وجود مشکل در کتابخانه‌ی ران‌تایم SQLite باشد. InternalError زیرکلاسی از DatabaseError است.

exception sqlite3.ProgrammingError¶: استثنایی که برای خطاهای برنامه‌نویسی در API sqlite3 پرتاب می‌شود، برای مثال ارائه تعداد نادرست مقیدسازی‌ها به یک کوئری، یا تلاش برای انجام عملیات روی یک Connection بسته. ProgrammingError زیرکلاسی از DatabaseError است.

exception sqlite3.NotSupportedError¶: استثنایی که در صورتی پرتاب می‌شود که یک متد یا API پایگاه داده توسط کتابخانه SQLite زیرین پشتیبانی نشود. برای مثال، تنظیم deterministic روی True در create_function()، در صورتی که کتابخانه SQLite زیرین از توابع قطعی پشتیبانی نکند. NotSupportedError زیرکلاسی از DatabaseError است.

نوع‌های SQLite و پایتون¶

SQLite به‌صورت بومی از انواع زیر پشتیبانی می‌کند: NULL، INTEGER، REAL، TEXT، BLOB.

بنابراین می‌توان انواع پایتون زیر را بدون هیچ مشکلی به SQLite ارسال کرد:

نوع پایتون	نوع SQLite
`None`	`NULL`
`int`	`INTEGER`
`float`	`REAL`
`str`	`TEXT`
`bytes`	`BLOB`

انواع SQLite به‌صورت پیش‌فرض این‌گونه به انواع پایتون تبدیل می‌شوند:

نوع SQLite	نوع پایتون
`NULL`	`None`
`INTEGER`	`int`
`REAL`	`float`
`TEXT`	به `text_factory` بستگی دارد، به‌طور پیش‌فرض `str`
`BLOB`	`bytes`

سیستم نوع ماژول sqlite3 به ۲ روش قابل‌گسترش است: شما می‌توانید انواع اضافی پایتون را از طریق آداپتورهای شیء (object adapters) در یک پایگاه‌داده‌ی SQLite ذخیره کنید، و می‌توانید به ماژول sqlite3 اجازه دهید تا انواع SQLite را از طریق مبدل‌ها (converters) به انواع پایتون تبدیل کند.

سازگارکننده‌ها و مبدل‌های پیش‌فرض (منسوخ)¶

توجه

آداپتورها و مبدل‌های پیش‌فرض از پایتون 3.12 منسوخ شده‌اند. در عوض، از دستورپخت‌های آداپتور و مبدل استفاده کنید و آن‌ها را متناسب با نیازهای خود تنظیم کنید.

آداپتورها و مبدل‌های پیش‌فرض منسوخ‌شده عبارت‌اند از:

آداپتوری برای تبدیل اشیای datetime.date به strings در قالب ISO 8601.
یک آداپتور (adapter) برای تبدیل اشیای datetime.datetime به رشته‌هایی در قالب ISO 8601.
مبدلی برای تبدیل انواع "date" اعلام‌شده به اشیای datetime.date.
مبدلی برای تبدیل انواع «timestamp» اعلام‌شده به اشیای datetime.datetime. بخش‌های کسری به ۶ رقم کوتاه می‌شوند (دقت میکروثانیه).

توجه

مبدل پیش‌فرض "timestamp" انحراف‌های UTC را در پایگاه داده نادیده می‌گیرد و همیشه یک شیء datetime.datetime ساده برمی‌گرداند. برای حفظ انحراف‌های UTC در timestampها، یا مبدل‌ها را غیرفعال نگه دارید، یا یک مبدل آگاه از انحراف را با register_converter() ثبت کنید.

منسوخ شده از نسخه‌ی 3.12.

رابط خط فرمان¶

می‌توان ماژول sqlite3 را به‌عنوان یک اسکریپت، با استفاده از سوییچ -m مفسر، فراخوانی کرد تا یک پوسته ساده SQLite فراهم شود. امضای آرگومان به صورت زیر است:

python -m sqlite3 [-h] [-v] [filename] [sql]

برای خروج از پوسته، .quit یا CTRL-D را وارد کنید.

-h, --help¶: چاپ راهنمای CLI.

-v, --version¶: نسخه‌ی کتابخانه‌ی SQLite زیرین را چاپ می‌کند.

اضافه شده در نسخه‌ی 3.12.

راهنماهای چگونگی¶

چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم¶

عملیات‌های SQL معمولاً به استفاده از مقادیر متغیرهای پایتون نیاز دارند. با این حال، از استفاده از عملیات رشته‌ای پایتون برای ساخت پرس‌وجوها برحذر باشید، زیرا در برابر حملات تزریق SQL آسیب‌پذیرند. برای مثال، یک مهاجم می‌تواند به‌سادگی علامت نقل‌قول تکی را ببندد و OR TRUE را تزریق کند تا تمام ردیف‌ها انتخاب شوند:

>>> # Never do this -- insecure!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --'
>>> cur.execute(sql)

در عوض، از جای‌گزینی پارامترِ DB-API استفاده کنید. برای درج یک متغیر در رشته‌ی پرس‌وجو، از یک جای‌نگهدار در رشته استفاده کنید و مقادیر واقعی را با ارائه آن‌ها به‌صورت یک tuple از مقادیر به آرگومان دوم متد execute() نشانگر، در پرس‌وجو جای‌گزین کنید.

یک دستور SQL ممکن است از یکی از دو نوع جای‌نگهدار استفاده کند: علامت‌های سؤال (سبک qmark) یا جای‌نگهدارهای نام‌دار (سبک named). برای سبک qmark، parameters باید یک sequence باشد که طول آن باید با تعداد جای‌نگهدارها برابر باشد، در غیر این صورت یک ProgrammingError پرتاب می‌شود. برای سبک named، parameters باید نمونه‌ای از dict (یا یک زیرکلاس) باشد که باید شامل کلیدهایی برای همه‌ی پارامترهای نام‌دار باشد؛ هر آیتم اضافی نادیده گرفته می‌شود. در ادامه مثالی از هر دو سبک آمده است:

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# This is the named style used with executemany():
data = (
    {"name": "C", "year": 1972},
    {"name": "Fortran", "year": 1957},
    {"name": "Python", "year": 1991},
    {"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# This is the qmark style used in a SELECT query:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

توجه

از جای‌نگه‌دارهای عددی PEP 249 پشتیبانی نمی‌شود. در صورت استفاده، به‌عنوان جای‌نگه‌دارهای نام‌دار تفسیر خواهند شد.

چگونگی تطبیق انواع سفارشی پایتون با مقادیر SQLite¶

SQLite تنها از مجموعه‌ای محدود از انواع داده به‌صورت بومی پشتیبانی می‌کند. برای ذخیره‌ی انواع پایتونی سفارشی در پایگاه‌های داده‌ی SQLite، آن‌ها را با یکی از انواع پایتونی که SQLite به‌صورت بومی می‌شناسد سازگار کنید.

دو روش برای تطبیق اشیای پایتون با انواع SQLite وجود دارد: اینکه بگذارید شیء شما خودش را تطبیق دهد، یا استفاده از یک فراخوانی‌پذیر تطبیق‌دهنده (adapter callable). دومی بر اولی تقدم خواهد داشت. برای کتابخانه‌ای که یک نوع سفارشی اکسپورت می‌کند، ممکن است منطقی باشد که آن نوع بتواند خودش را تطبیق دهد. به‌عنوان توسعه‌دهنده‌ی برنامه‌ی کاربردی، ممکن است منطقی‌تر باشد که با ثبت توابع تطبیق‌دهنده‌ی سفارشی، کنترل مستقیم را در دست بگیرید.

چگونه اشیای سازگارپذیر بنویسیم¶

فرض کنید یک کلاس Point داریم که یک جفت مختصات، x و y، را در یک دستگاه مختصات دکارتی نشان می‌دهد. جفت مختصات به‌صورت یک رشته متنی در پایگاه داده ذخیره خواهد شد و برای جداسازی مختصات از نقطه‌ویرگول استفاده می‌شود. این کار را می‌توان با افزودن یک متد __conform__(self, protocol) پیاده‌سازی کرد که مقدار تطبیق‌یافته را برمی‌گرداند. شیء منتقل‌شده به protocol از نوع PrepareProtocol خواهد بود.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"{self.x};{self.y}"

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()

چگونه موارد فراخوانی‌پذیر آداپتور را ثبت کنید¶

امکان دیگر، ساخت تابعی است که شیء پایتون را به نوعی سازگار با SQLite تبدیل می‌کند. سپس می‌توانید این تابع را با استفاده از register_adapter() ثبت کنید.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

چگونه مقادیر SQLite را به انواع سفارشی پایتون تبدیل کنیم¶

نوشتن یک آداپتور امکان تبدیل از انواع سفارشی پایتون به مقادیر SQLite را به شما می‌دهد. برای توانایی تبدیل از مقادیر SQLite به انواع سفارشی پایتون، از مبدل‌ها استفاده می‌کنیم.

بیایید به کلاس Point بازگردیم. ما مختصات x و y را به‌صورت رشته‌هایی که با نقطه‌ویرگول از یکدیگر جدا شده‌اند، در SQLite ذخیره کردیم.

ابتدا، یک تابع تبدیل‌کننده تعریف می‌کنیم که رشته را به‌عنوان پارامتر می‌پذیرد و از روی آن یک شیء Point می‌سازد.

توجه

توابع مبدل همیشه یک شیء bytes دریافت می‌کنند، صرف‌نظر از نوع داده‌ی زیرین SQLite.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

اکنون باید به sqlite3 بگوییم که چه زمانی باید یک مقدار SQLite مشخص را تبدیل کند. این کار هنگام اتصال به یک پایگاه داده، با استفاده از پارامتر detect_types تابع connect() انجام می‌شود. سه گزینه وجود دارد:

ضمنی: detect_types را روی PARSE_DECLTYPES تنظیم کنید
صریح: detect_types را روی PARSE_COLNAMES تنظیم کنید
هر دو: detect_types را روی sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES تنظیم کنید. نام ستون‌ها بر انواع اعلام‌شده اولویت دارند.

مثال زیر رویکردهای ضمنی و صریح را نشان می‌دهد:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

دستورپخت‌های آداپتور و مبدل¶

این بخش دستورالعمل‌هایی برای آداپتورها و مبدل‌های رایج ارائه می‌دهد.

import datetime as dt
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.replace(tzinfo=None).isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(dt.date, adapt_date_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return dt.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return dt.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return dt.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

نحوه استفاده از متدهای میان‌بر اتصال¶

با استفاده از متدهای execute()، executemany() و executescript() کلاس Connection، می‌توانید کد خود را مختصرتر بنویسید، زیرا نیازی نیست اشیای Cursor را (که اغلب غیرضروری هستند) به‌صورت صریح ایجاد کنید. در عوض، اشیای Cursor به‌صورت ضمنی ایجاد می‌شوند و این متدهای میان‌بر اشیای cursor را برمی‌گردانند. به این ترتیب، می‌توانید یک دستور SELECT را اجرا کرده و تنها با یک فراخوانی روی شیء Connection، مستقیماً آن را پیمایش کنید.

# Create and fill the table.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# Print the table contents
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# close() is not a shortcut method and it's not called automatically;
# the connection object should be closed manually
con.close()

نحوه استفاده از مدیر زمینه اتصال¶

یک شیء Connection می‌تواند به‌عنوان یک مدیر زمینه استفاده شود که هنگام خروج از بدنه‌ی مدیر زمینه، تراکنش‌های باز را به‌طور خودکار ثبت یا بازگردانی می‌کند. اگر بدنه‌ی دستور with بدون استثنا به پایان برسد، تراکنش ثبت می‌شود. اگر این ثبت ناموفق باشد، یا اگر بدنه‌ی دستور with یک استثنای گرفته‌نشده پرتاب کند، تراکنش بازگردانی می‌شود. اگر autocommit برابر False باشد، پس از ثبت یا بازگردانی، یک تراکنش جدید به‌طور ضمنی باز می‌شود.

اگر هنگام خروج از بدنه‌ی دستور with هیچ تراکنش بازی وجود نداشته باشد، یا اگر autocommit برابر True باشد، مدیر زمینه هیچ کاری انجام نمی‌دهد.

توجه

این مدیر زمینه نه به‌طور ضمنی تراکنش جدیدی را باز می‌کند و نه اتصال را می‌بندد. اگر به یک مدیر زمینه برای بستن نیاز دارید، استفاده از contextlib.closing() را در نظر بگیرید.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# Successful, con.commit() is called automatically afterwards
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# con.rollback() is called after the with block finishes with an exception,
# the exception is still raised and must be caught
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# Connection object used as context manager only commits or rollbacks transactions,
# so the connection object should be closed manually
con.close()

نحوه کار با URIهای SQLite¶

برخی ترفندهای مفید URI عبارتند از:

باز کردن یک پایگاه داده در حالت فقط‌خواندنی:

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database
>>> con.close()

اگر پرونده پایگاه داده جدید از قبل وجود نداشته باشد، به‌طور ضمنی یک پرونده پایگاه داده جدید ایجاد نمی‌شود؛ اگر امکان ایجاد پرونده جدید وجود نداشته باشد، OperationalError پرتاب می‌شود:

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

ایجاد یک پایگاه داده‌ی درون‌حافظه‌ای نام‌دار مشترک:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()

اطلاعات بیشتر درباره این قابلیت، از جمله فهرستی از پارامترها، در SQLite URI documentation یافت می‌شود.

نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories)¶

به‌طور پیش‌فرض، sqlite3 هر ردیف را به‌صورت یک tuple نمایش می‌دهد. اگر یک tuple نیاز شما را برآورده نمی‌کند، می‌توانید از کلاس sqlite3.Row یا یک row_factory سفارشی استفاده کنید.

اگرچه row_factory به‌عنوان یک ویژگی هم در Cursor و هم در Connection وجود دارد، توصیه می‌شود Connection.row_factory را تنظیم کنید تا تمام نشانگرهایی که از اتصال ایجاد می‌شوند از همان کارخانه‌ی ردیف (row factory) استفاده کنند.

Row دسترسی اندیسی و دسترسی نامی بدون حساسیت به بزرگی و کوچکی حروف به ستون‌ها را با حداقل سربار حافظه و تأثیر بر عملکرد نسبت به یک tuple فراهم می‌کند. برای استفاده از Row به‌عنوان کارخانه‌ی ردیف (row factory)، آن را به ویژگی row_factory انتساب دهید:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row

پرس‌وجوها اکنون اشیای Row را برمی‌گردانند:

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # Access by index.
'Earth'
>>> row["name"]    # Access by name.
'Earth'
>>> row["RADIUS"]  # Column names are case-insensitive.
6378
>>> con.close()

توجه

می‌توان بند FROM را در دستور SELECT حذف کرد، همان‌طور که در مثال بالا آمده است. در این موارد، SQLite یک ردیف واحد با ستون‌های تعریف‌شده توسط عبارت‌ها، برای مثال مقادیر لفظی، با نام‌های مستعار داده‌شده به صورت expr AS alias برمی‌گرداند.

شما می‌توانید یک row_factory سفارشی ایجاد کنید که هر ردیف را به‌صورت یک dict برمی‌گرداند، به‌طوری که نام ستون‌ها به مقادیر نگاشته شده‌اند:

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

با استفاده از آن، پرس‌وجوها اکنون یک dict به‌جای یک tuple برمی‌گردانند:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}
>>> con.close()

کارخانه ردیف (row factory) زیر یک named tuple برمی‌گرداند:

from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)

می‌توان از namedtuple_factory() به‌صورت زیر استفاده کرد:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # Indexed access.
1
>>> row.b   # Attribute access.
2
>>> con.close()

با برخی تنظیمات، می‌توان دستور بالا را برای استفاده از یک dataclass یا هر کلاس سفارشی دیگری، به‌جای یک namedtuple تطبیق داد.

نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8¶

به‌طور پیش‌فرض، sqlite3 از str برای تطبیق مقادیر SQLite با نوع داده TEXT استفاده می‌کند. این روش برای متن‌های کدگذاری‌شده با UTF-8 به‌خوبی کار می‌کند، اما ممکن است برای کدگذاری‌های دیگر و UTF-8 نامعتبر شکست بخورد. می‌توانید از یک text_factory سفارشی برای رسیدگی به چنین مواردی استفاده کنید.

به دلیل flexible typing در SQLite، مواجه شدن با ستون‌های جدول با نوع داده TEXT که شامل کدگذاری‌های غیر UTF-8 یا حتی داده‌های دلخواه هستند، چندان غیرمعمول نیست. برای نمایش، فرض کنیم پایگاه داده‌ای با متن کدگذاری‌شده به‌صورت ISO-8859-2 (Latin-2) داریم، برای مثال جدولی از ورودی‌های فرهنگ لغت چکی-انگلیسی. با فرض اینکه اکنون یک نمونه Connection به نام con داریم که به این پایگاه داده متصل است، می‌توانیم متن کدگذاری‌شده با Latin-2 را با استفاده از این text_factory کدگشایی کنیم:

con.text_factory = lambda data: str(data, encoding="latin2")

برای UTF-8 نامعتبر یا داده‌های دلخواه ذخیره‌شده در ستون‌های جدول TEXT، می‌توانید از روش زیر استفاده کنید، که از راهنمای عملی یونیکد وام گرفته شده است:

con.text_factory = lambda data: str(data, errors="surrogateescape")

توجه

API ماژول sqlite3 از رشته‌های حاوی نویسه‌های جانشین (surrogates) پشتیبانی نمی‌کند.

همچنین ملاحظه نمائید

راهنمای عملی یونیکد

توضیح¶

کنترل تراکنش¶

sqlite3 روش‌های متعددی برای کنترل این‌که آیا، چه زمانی و چگونه تراکنش‌های پایگاه داده باز و بسته می‌شوند، ارائه می‌دهد. کنترل تراکنش از طریق ویژگی autocommit توصیه می‌شود، در حالی که کنترل تراکنش از طریق ویژگی isolation_level رفتار پیش از Python 3.12 را حفظ می‌کند.

کنترل تراکنش از طریق ویژگی `autocommit`¶

روش توصیه‌شده برای کنترل رفتار تراکنش، از طریق ویژگی Connection.autocommit است که بهتر است با پارامتر autocommit در connect() تنظیم شود.

پیشنهاد می‌شود autocommit را روی False تنظیم کنید، که به معنای کنترل تراکنش مطابق PEP 249 است. این یعنی:

sqlite3 تضمین می‌کند که یک تراکنش همیشه باز است، بنابراین connect()، Connection.commit() و Connection.rollback() به‌طور ضمنی یک تراکنش جدید باز می‌کنند (بلافاصله پس از بستن تراکنش در انتظار، برای دو مورد آخر). sqlite3 هنگام باز کردن تراکنش‌ها از دستورات BEGIN DEFERRED استفاده می‌کند.
تراکنش‌ها باید به‌صورت صریح با استفاده از commit() کامیت شوند.
تراکنش‌ها باید به‌صراحت با استفاده از rollback() بازگردانی شوند.
اگر پایگاه داده در حالی که تغییرات در انتظار دارد با close() بسته شود، یک بازگردانی (rollback) ضمنی انجام می‌شود.

برای فعال‌سازی autocommit mode در SQLite، autocommit را روی True تنظیم کنید. در این حالت، Connection.commit() و Connection.rollback() هیچ اثری ندارند. توجه داشته باشید که حالت autocommit در SQLite از ویژگی Connection.autocommit سازگار با PEP 249 متمایز است؛ برای پرس‌وجوی حالت autocommit سطح پایین SQLite از Connection.in_transaction استفاده کنید.

برای اینکه رفتار کنترل تراکنش به ویژگی Connection.isolation_level واگذار شود، autocommit را روی LEGACY_TRANSACTION_CONTROL تنظیم کنید. برای اطلاعات بیشتر کنترل تراکنش از طریق ویژگی isolation_level را ببینید.

کنترل تراکنش از طریق ویژگی `isolation_level`¶

توجه

روش توصیه‌شده برای کنترل تراکنش‌ها، استفاده از ویژگی autocommit است. کنترل تراکنش از طریق ویژگی autocommit را ببینید.

اگر Connection.autocommit روی LEGACY_TRANSACTION_CONTROL (پیش‌فرض) تنظیم شده باشد، رفتار تراکنش با استفاده از ویژگی Connection.isolation_level کنترل می‌شود. در غیر این صورت، isolation_level اثری ندارد.

اگر ویژگی اتصال isolation_level برابر None نباشد، پیش از اجرای دستورات INSERT، UPDATE، DELETE یا REPLACE توسط execute() و executemany()، تراکنش‌های جدید به‌طور ضمنی باز می‌شوند؛ برای سایر دستورات، هیچ مدیریت تراکنش ضمنی‌ای انجام نمی‌شود. از متدهای commit() و rollback() به‌ترتیب برای ثبت (commit) و بازگرداندن (rollback) تراکنش‌های در انتظار استفاده کنید. شما می‌توانید رفتار زیربنایی SQLite transaction behaviour — یعنی اینکه آیا و چه نوع دستورات BEGIN توسط sqlite3 به‌طور ضمنی اجرا می‌شوند – را از طریق ویژگی isolation_level انتخاب کنید.

اگر isolation_level روی None تنظیم شده باشد، اصلاً هیچ تراکنشی به‌طور ضمنی باز نمی‌شود. این امر باعث می‌شود کتابخانه SQLite زیرین در autocommit mode باقی بماند، اما همچنین به کاربر اجازه می‌دهد مدیریت تراکنش خود را با استفاده از دستورات صریح SQL انجام دهد. حالت کامیت خودکار کتابخانه SQLite زیرین را می‌توان از طریق ویژگی in_transaction پرس‌وجو کرد.

متد executescript() به‌طور ضمنی هر تراکنش در حال انتظاری را پیش از اجرای اسکریپت SQL داده‌شده، صرف‌نظر از مقدار isolation_level، ثبت (commit) می‌کند.

تغییر یافته در نسخه‌ی 3.6: sqlite3 پیش‌تر یک تراکنش باز را پیش از دستورات DDL به‌صورت ضمنی ثبت (commit) می‌کرد. این موضوع دیگر صدق نمی‌کند.

تغییر یافته در نسخه‌ی 3.12: روش توصیه‌شده برای کنترل تراکنش‌ها اکنون از طریق ویژگی autocommit است.

`sqlite3` --- رابط DB-API 2.0 برای پایگاه‌های داده SQLite¶

آموزش¶

مرجع¶

توابع ماژول¶

ثابت‌های ماژول¶

اشیای اتصال¶

اشیای نشانگر¶

اشیای Row¶

اشیای Blob¶

اشیای PrepareProtocol¶

استثناها¶

نوع‌های SQLite و پایتون¶

سازگارکننده‌ها و مبدل‌های پیش‌فرض (منسوخ)¶

رابط خط فرمان¶

راهنماهای چگونگی¶

چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم¶

چگونگی تطبیق انواع سفارشی پایتون با مقادیر SQLite¶

چگونه اشیای سازگارپذیر بنویسیم¶

چگونه موارد فراخوانی‌پذیر آداپتور را ثبت کنید¶

چگونه مقادیر SQLite را به انواع سفارشی پایتون تبدیل کنیم¶

دستورپخت‌های آداپتور و مبدل¶

نحوه استفاده از متدهای میان‌بر اتصال¶

نحوه استفاده از مدیر زمینه اتصال¶

نحوه کار با URIهای SQLite¶

نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories)¶

نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8¶

توضیح¶

کنترل تراکنش¶

کنترل تراکنش از طریق ویژگی `autocommit`¶

کنترل تراکنش از طریق ویژگی `isolation_level`¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

sqlite3 --- رابط DB-API 2.0 برای پایگاه‌های داده SQLite¶

آموزش¶

مرجع¶

توابع ماژول¶

ثابت‌های ماژول¶

اشیای اتصال¶

اشیای نشانگر¶

اشیای Row¶

اشیای Blob¶

اشیای PrepareProtocol¶

استثناها¶

نوع‌های SQLite و پایتون¶

سازگارکننده‌ها و مبدل‌های پیش‌فرض (منسوخ)¶

رابط خط فرمان¶

راهنماهای چگونگی¶

چگونه از جای‌نگهدارها (placeholders) برای مقیدسازی مقادیر در پرس‌وجوهای SQL استفاده کنیم¶

چگونگی تطبیق انواع سفارشی پایتون با مقادیر SQLite¶

چگونه اشیای سازگارپذیر بنویسیم¶

چگونه موارد فراخوانی‌پذیر آداپتور را ثبت کنید¶

چگونه مقادیر SQLite را به انواع سفارشی پایتون تبدیل کنیم¶

دستورپخت‌های آداپتور و مبدل¶

نحوه استفاده از متدهای میان‌بر اتصال¶

نحوه استفاده از مدیر زمینه اتصال¶

نحوه کار با URIهای SQLite¶

نحوه‌ی ایجاد و استفاده از کارخانه‌های ردیف (row factories)¶

نحوه‌ی مدیریت کدگذاری‌های متن غیر UTF-8¶

توضیح¶

کنترل تراکنش¶

کنترل تراکنش از طریق ویژگی autocommit¶

کنترل تراکنش از طریق ویژگی isolation_level¶

`sqlite3` --- رابط DB-API 2.0 برای پایگاه‌های داده SQLite¶

کنترل تراکنش از طریق ویژگی `autocommit`¶

کنترل تراکنش از طریق ویژگی `isolation_level`¶