Методы объекта Cursor SQLite3

Объекта Cursor можно получить в результате вызова метода получения курсора connect.cursor().

Синтаксис:

import sqlite3

connect = sqlite3.connect("example.sqlite3")
cursor = connect.cursor()

В разделе рассмотрены методы объекта Cursor модуля sqlite3 с подробным описанием и примерами.

Содержание:

Выполнить команду SQL cursor.execute(),
Выполнить команду SQL для списка параметров cursor.executemany(),
Выполнить несколько операторов SQL cursor.executescript(),
Получить одну строку с результатом запроса cursor.fetchone(),
Получить список из нескольких строк с результатом запроса cursor.fetchmany(),
Получить список всех строк с результатом запроса cursor.fetchall(),
Получить ID последней измененной строки cursor.lastrowid,
Получить имена столбцов последнего запроса cursor.description,
Получить количество выбранных строк cursor.rowcount,
Закрыть курсор cursor.close(),
Получить/установить количество строк для метода cursor.fetchmany() cursor.arraysize,
Получить объект соединения с базой cursor.connection,

A Cursor instance has the following attributes and methods.

`cursor.execute(sql, parameters=(), /)`:

Метод cursor.execute() выполняет команду SQL. Команды SQL могут быть параметризованными, то есть передаются заполнители вместо литералов SQL.

Аргумент parameters значения Python для привязки к заполнителям в sql запросе. Представляет собой словарь dict, если используются именованные заполнители и последовательность, если используются вопросительные знаки '?'.

Если используются именованные заполнители, а параметры представляют собой последовательность, а не словарь то с версии Python 3.12 выдается DeprecationWarning. Начиная с версии Python 3.14, вместо этого будет выдаваться ProgrammingError.

Пример использования обоих стилей:

Модуль sqlite3 поддерживает два вида заполнителей: вопросительные знаки '?' - стиль qmark и именованные заполнители.

import sqlite3

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

sql = "create table people (name_last, age)"
cur.execute(sql)

who = "Yeltsin"
age = 72

# стиль qmark:
sql = "insert into people values (?, ?)"
cur.execute(sql, (who, age))

# именованный стиль:
sql = "select * from people where name_last=:who and age=:age"
cur.execute(sql, {"who": who, "age": age})

print(cur.fetchone())

con.close()

Метод cursor.execute() будет выполнять только один оператор SQL. Если попытаться выполнить более одного оператора, появится предупреждение Warning. если нужно выполнить несколько операторов SQL одним вызовом то нужно использовать метод cursor.executescript().

`cursor.executemany(sql, parameters, /)`:

Метод cursor.executemany() выполняет команду sql для всех элементов последовательности seq_of_parameters, которые содержат параметры запроса или словари именованных параметров.

Аргумент parameters - это значения Python для привязки к заполнителям в sql запросе. Представляет собой словарь dict, если используются именованные заполнители и последовательность, если используются вопросительные знаки '?'.

Если используются именованные заполнители, а параметры представляют собой последовательность, а не словарь то с версии Python 3.12 выдается DeprecationWarning. Начиная с версии Python 3.14, вместо этого будет выдаваться ProgrammingError.

Абстрактный пример:

rows = [
    ("row1",),
    ("row2",),
]

cur.executemany("INSERT INTO data VALUES(?)", rows)

Модуль sqlite3 также позволяет использовать итератор, который выдает параметры.

Пример использования итератора:

import sqlite3

class IterChars:
    def __init__(self):
        self.count = ord('a')

    def __iter__(self):
        return self

    def __next__(self):
        if self.count > ord('z'):
            raise StopIteration
        self.count += 1
        # это кортеж
        return (chr(self.count - 1),)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

theIter = IterChars()
cur.executemany("insert into characters(c) values (?)", theIter)

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

Пример использования генератора:

import sqlite3
import string

def char_generator():
    for c in string.ascii_lowercase:
        yield (c,)

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.execute("create table characters(c)")

cur.executemany("insert into characters(c) values (?)", char_generator())

cur.execute("select c from characters")
print(cur.fetchall())

con.close()

`cursor.executescript(sql_script)`:

Нестандартный удобный метод cursor.executescript() для одновременного выполнения нескольких операторов SQL. Аргумент sql_script может быть экземпляром str.

Сначала он выдает оператор COMMIT, а затем выполняет сценарий SQL, полученный в качестве параметра.

Пример использования:

import sqlite3

con = sqlite3.connect(":memory:")
cur = con.cursor()
cur.executescript("""
    create table person(
        firstname,
        lastname,
        age
    );

    create table book(
        title,
        author,
        published
    );

    insert into book(title, author, published)
    values (
        'Dirk Gently''s Holistic Detective Agency',
        'Douglas Adams',
        1987
    );
    """)
con.close()

`cursor.fetchone()`:

Метод cursor.fetchone() извлекает следующую строку из набора результатов запроса, возвращая одну последовательность или None, если больше нет доступных данных.

`cursor.fetchmany(size=cursor.arraysize)`:

Метод cursor.fetchmany() извлекает следующий набор строк результата запроса, возвращая список. Возвращает пустой список , когда больше нет доступных строк.

Количество строк, извлекаемых за вызов, определяется аргументом size. Если он не задан, то количество строк, которые нужно извлечь определяет атрибут cursor.arraysize().

Метод должен попытаться извлечь столько строк, сколько указано параметром size. Если это невозможно из-за недоступности указанного количества строк, может быть возвращено меньшее количество строк.

Обратите внимание, что с аргументом size связаны соображения производительности. Для оптимальной производительности обычно лучше использовать атрибут cursor.arraysize(). Если используется аргумент size, то лучше всего сохранить то же значение от одного вызова cursor.fetchmany() до следующего.

`cursor.fetchall()`:

Метод cursor.fetchall() выбирает все оставшиеся строки результата запроса, возвращая список.

Обратите внимание, что атрибут cursor.arraysize() курсора может повлиять на производительность этой операции. Метод возвращает пустой список, когда нет доступных строк.

`cursor.close()`:

Метод cursor.close() закрывает курсор сейчас, а не всякий раз, когда вызывается метод __del__.

С этого момента курсор будет непригодным для использования. Возникнет исключение ProgrammingError, если с закрытом курсором будет предпринята какая-либо операция.

`cursor.rowcount`:

Хотя класс Cursor модуля sqlite3 реализует атрибут cursor.rowcount, собственная поддержка ядром SQLite определения "затронутых строк"/"выбранных строк" в запросе является странной.

Для операторов метода cursor.executemany() количество модификаций суммируется в cursor.rowcount.

В соответствии со спецификацией API-интерфейса DB Python атрибут cursor.rowcount равен -1, если для курсора не выполняется любой из методов execute*() или количество строк последней операции не определяется интерфейсом. Это включает операторы SELECT, потому что нельзя определить количество строк результата запроса, пока все строки не будут выбраны самим запросом.

В версиях SQLite до 3.6.5 rowcount устанавливается в 0, если выполнить запрос DELETE FROM table без каких-либо условий WHERE.

`cursor.lastrowid`:

Атрибут cursor.lastrowid только для чтения, предоставляет идентификатор последней измененной строки в базе данных.

Атрибут cursor.lastrowid устанавливается только в том случае, если выполняется оператор INSERT или REPLACE с помощью метода cursor.execute(). Для операций, отличных от INSERT или REPLACE, или когда вызывается метод cursor.executemany(), cursor.lastrowid имеет значение None.

Атрибут cursor.lastrowid будет возвращен, если оператору INSERT или REPLACE не удалось успешно вставить предыдущий идентификатор строки.

`cursor.arraysize`:

Атрибут cursor.arraysize для чтения и записи. Управляет количеством строк, возвращаемых методом cursor.fetchmany().

Значение по умолчанию равно 1, что означает, что для каждого вызова будет выбрана одна строка.

`cursor.description`:

Атрибут cursor.description только для чтения. Предоставляет имена столбцов последнего запроса. Чтобы оставаться совместимым с API-интерфейсом Python DB, он возвращает кортеж из 7 элементов для каждого столбца, где последние шесть элементов каждого кортежа равны None.

Он также устанавливается для операторов SELECT без соответствующих строк.

`cursor.connection`:

Атрибут cursor.connection только для чтения. Обеспечивает соединение базы данных SQLite, используемое объектом Cursor.

Объект Cursor, созданный путем вызова connect.cursor(), будет иметь атрибут подключения, который ссылается на connect:

>>> import sqlite3
>>> connect = sqlite3.connect(":memory:")
>>> connect = con.cursor()
>>> connect.connection == connect
# True

Методы объекта Cursor SQLite3

Синтаксис:

Содержание:

cursor.execute(sql, parameters=(), /):

cursor.executemany(sql, parameters, /):

cursor.executescript(sql_script):

cursor.fetchone():

cursor.fetchmany(size=cursor.arraysize):

cursor.fetchall():

cursor.close():

cursor.rowcount:

cursor.lastrowid:

cursor.arraysize:

cursor.description:

cursor.connection: