Методы БД
После открытия БД с помощью sqlite3.open или sqlite3.open_memory возвращенный объект БД должен использоваться для всех вызовов методов этой БД. Объект открытой БД поддерживает следующие методы.
db:busy_handler([func[,udata]])
Задает или удаляет дескриптор занятости БД. func – или функция Lua, которая встраивает дескриптор занятости, или nil для удаления ранее заданного дескриптора. Данная функция ничего не возвращает.
Функция дескриптора вызывается с двумя параметрами: udata и числом попыток для незаконченных транзакций. Функция вернет nil, FALSE или 0, если транзакция должна быть прервана. Любые другие значения означают следующую попытку выполнить транзакцию (см. советы по написанию дескрипторов занятости в документации SQLite).
db:busy_timeout(t)
Задает дескриптор занятости, который ждет t миллисекунд, если транзакция не может быть продолжена. Вызов этой функции удаляет любой дескриптор занятости, заданный с помощью db:busy_handler ; вызов этой функции с аргументом, меньшим или равным 0, выключает все дескрипторы занятости.
db:changes()
Эта функция возвращает число строк ДБ, измененных, вставленных или удаленных последним оператором SQL. Подсчитываются только изменения, которые непосредственно заданы операторами INSERT, UPDATE или DELETE. Другие изменения, обусловленные триггерами, не учитываются. Используйте db:total_changes , чтобы найти общее число изменений.
db:close()
Закрывает БД. Все операторы SQL, подготовленные с помощью db:prepare , должны быть завершены перед вызовом этой функции. Функция возвращает sqlite3.OK в случае успешного закрытия БД, в противном случае возвращается код ошибки (см. список в разделе Результирующие коды и коды ошибок ).
db:close_vm(temponly)
Завершает все операторы, которые не завершены явно. Если temponly – TRUE, завершаются только внутренние, временные операторы. Эта функция ничего не возвращает.
db:create_aggregate(name,nargs,step,final)
Эта функция создает агрегатную функцию обратного вызова. Агрегатные функции выполняют операцию над всеми строками в запросе. name – строка с именем агрегатной функции как задано в операторе SQL; nargs – число аргументов в вызове. step – реальная функция Lua, которая вызывается однократно для каждой строки; она примет контекст функции (см. Методы контекстов обратного вызова ) плюс такое же число параметров, как задано nargs. final – функция, которая вызывается однократно после того, как все строки обработаны; она получает один аргумент (контекст функции).
Контекст функции может быть использован внутри двух функций обратного вызова для взаимодействия с SQLite3. Простой пример:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
local num_sum=0
local function oneRow(context,num) -- добавить один столбец во все строки
num_sum=num_sum+num
end
local function afterLast(context) -- возвратить сумму после того, как обработана последняя строка
context:result_number(num_sum)
num_sum=0
end
db:create_aggregate("do_the_sums",1,oneRow,afterLast)
for sum in db:urows('SELECT do_the_sums(num1) FROM numbers') do print("Sum of col 1:",sum) end
for sum in db:urows('SELECT do_the_sums(num2) FROM numbers') do print("Sum of col 2:",sum) end
Этот код печатает следующее:
Sum of col 1: 6
Sum of col 2: 66
db:create_collation(name,func)
Создает сравнительный обратный вызов. Сравнительный обратный вызов используется для установки порядка – в основном, для целей сравнения строк и сортировки. name – строка с именем сопоставления, которое должно быть создано; func – функция, принимает два строковых аргумента, сравнивает их и возвращает 0, если строки идентичны, -1, если первый аргумент расположен в порядке ниже, чем второй, и 1, если первый аргумент расположен в порядке выше, чем второй. Простой пример:
local function collate(s1,s2)
s1=s1:lower()
s2=s2:lower()
if s1==s2 then return 0
elseif s1<s2 then return -1
else return 1 end
end
db:exec[=[
CREATE TABLE test(id INTEGER PRIMARY KEY,content COLLATE CINSENS);
INSERT INTO test VALUES(NULL,'hello world');
INSERT INTO test VALUES(NULL,'Buenos dias');
INSERT INTO test VALUES(NULL,'HELLO WORLD');
]=]
db:create_collation('CINSENS',collate)
for row in db:nrows('SELECT * FROM test') do print(row.id,row.content) end
db:create_function(name,nargs,func)
Эта функция создает функцию обратного вызова. Функции обратного вызова вызываются SQLite3 один раз для каждой строки в запросе. name – строка с именем функции обратного вызова как указано в операторе SQL; nargs – число аргументов в вызове. func – реальная функция Lua, которая вызывается один раз для каждой строки, она примет контекст функции (см. Методы контекстов обратного вызова ) плюс такое же количество параметров, как задано nargs. Пример:
db:exec'CREATE TABLE test(col1,col2,col3)'
db:exec'INSERT INTO test VALUES(1,2,4)'
db:exec'INSERT INTO test VALUES(2,4,9)'
db:exec'INSERT INTO test VALUES(3,6,16)'
db:create_function('sum_cols',3,function(ctx,a,b,c)
ctx:result_number(a+b+c)
end))
for col1,col2,col3,sum in db:urows('SELECT *,sum_cols(col1,col2,col3) FROM test') do
util.printf('%2i+%2i+%2i=%2i\n',col1,col2,col3,sum)
end
db:errcode()
db:error_code()
Возвращает числовой результирующий код (или расширенный результирующий код) для последнего неудачного обращения, относящегося к базе данных db (см.. Результирующие коды и коды ошибок ).
db:errmsg()
db:error_message()
Возвращает строку, которая содержит сообщение об ошибке для последнего неудачного обращения, относящегося к базе данных db.
См. db:errcode .
См. db:errmsg .
db:exec(sql[,func[,udata]])
db:execute(sql[,func[,udata]])
Компилирует и выполняет SQL-операторы, заданные в строке sql. Операторы просто выполняются один за другим и не сохраняются. Функция возвращает sqlite3.OK при удачном выполнении или числовой код ошибки в противном случае (см. Результирующие коды и коды ошибок ).
Если один или несколько SQL-операторов – это запросы, функция обратного вызова, указанная в func, вызывается один раз для каждой строки результата запроса (если func = nil, обратный вызов не вызывается). Обратный вызов получает 4 аргумента: udata (третий аргумент db:exec()), число столбцов в строке, таблицу значений столбцов и таблицу имен столбцов. Функция обратного вызова вернет 0. Если обратный вызов возвращает ненулевое значение, запрос прерывается, все последующие SQL-операторы пропускаются, и db:exec() возвращает sqlite3.ABORT. Простой пример:
sql=[=[
CREATE TABLE numbers(num1,num2,str);
INSERT INTO numbers VALUES(1,11,"ABC");
INSERT INTO numbers VALUES(2,22,"DEF");
INSERT INTO numbers VALUES(3,33,"UVW");
INSERT INTO numbers VALUES(4,44,"XYZ");
SELECT * FROM numbers;
]=]
function showrow(udata,cols,values,names)
assert(udata=='test_udata')
print('exec:')
for i=1,cols do print('',names[i],values[i]) end
return 0
end
db:exec(sql,showrow,'test_udata')
См. db:exec .
db:interrupt()
Эта функция принуждает любую незаконченную операцию с БД прерваться и вернуть при первой возможности. Функция ничего не возвращает.
db:isopen()
Возвращает TRUE, если база данных db открыта, и FALSE в противном случае.
db:last_insert_rowid()
Эта функция возвращает rowid последней вставки в БД. Если вставки не было, возвращается 0. (Каждая строка в таблице SQLite имеет уникальный 64-разрядный целый знаковый ключ, называемый ’rowid’. Этот ID всегда доступен как недекларируемый столбец с именем ROWID, OID или _ROWID_. Если таблица содержит столбец типа INTEGER PRIMARY KEY, то этот столбец есть еще один псевдоним для rowid).
Если вставка происходит из триггера, rowid вставленной строки возвращается до тех пор, пока триггер работает. Как только триггер останавливается, возвращается значение, предшествующее запуску триггера.
db:nrows(sql)
Создает итератор, который возвращает успешные строки, выбранные SQL-оператором, который задан в строке sql. Каждое обращение к итератору возвращает таблицу, в которой именованные поля соответствуют столбцам БД. Пример:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
for a in db:nrows('SELECT * FROM numbers') do table.print(a) end
Этот скрипт печатает следующее:
num2: 11
num1: 1
num2: 22
num1: 2
num2: 33
num1: 3
db:prepare(sql)
Эта функция компилирует SQL-оператор (запрос), заданный в строке sql, во внутреннее представление и возвращает этот объект внутреннего представления как userdata. Возвращаемый объект должен использоваться для всех последующих обращений к методам этого SQL-оператора (см. Методы подготовленных операторов ).
db:progress_handler(n,func,udata)
Эта функция устанавливает функцию обратного вызова func, которая периодически (через каждые n внутренних операций) вызывается в течение длительно исполняемых обращений к db:exec или stmt:step (n – первый аргумент функции db:progress_handler). udata передается в func при каждом вызове func. Если обращение к db:exec() или stmt:step() приводит к меньшему, чем n, числу исполняемых операций, func никогда не вызывается. Только одна периодически вызываемая функция обратного вызова может быть задана для каждой открытой БД, и обращение к такой функции перезаписывает любую ранее заданную функцию обратного вызова. Для удаления периодически вызываемой функции обратного вызова нужно передать nil в качестве второго аргумента.
Если периодически вызываемая функция обратного вызова возвращает ненулевое значение, текущий запрос немедленно прерывается, отменяются все изменения в БД, а содержащая функция db:exec() или stmt:step() возвращает sqlite3.INTERRUPT. Это свойство может быть использовано для отмены длительно исполняемых запросов.
db:rows(sql)
Создает итератор, который возвращает успешные строки, выбранные с помощью SQL-оператора (запроса), который задан в строке sql. Каждое обращение к итератору возвращает таблицу, в которой числовые индексы от 1 до n соответствуют выбранным столбцам от 1 до n в БД. Пример:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
for a in db:rows('SELECT * FROM numbers') do table.print(a) end
Это скрипт печатает следующее:
1: 1
2: 11
1: 2
2: 22
1: 3
2: 33
db:total_changes()
Эта функция возвращает число строк БД, которые были добавлены, изменены или удалены с помощью операторов INSERT, UPDATE или DELETE с момента открытия БД. В это число входят также изменения, выполненные с помощью операторов UPDATE, INSERT и DELETE из триггерных программ. Все изменения подсчитываются как только оператор, выполняющий эти изменения, завершается вызовом stmt:reset или stmt:finalize .
db:trace(func,udata)
Устанавливает трассирующую функцию обратного вызова и возвращает ее дескриптор. func – это функция Lua, которая вызывается SQLite3 непосредственно перед выполнением оператора SQL. Трассировщик получает два аргумента: первый, udata, используется при установке функции, второй – это строка, содержащая SQL-оператор, который должен быть выполнен.
db:urows(sql)
Создает итератор, который возвращает успешные строки, выбранные с помощью SQL-оператора, заданного в строке sql. Каждое обращение к итератору возвращает значения, соответствующие столбцам в текущей выбранной строке. Пример:
db:exec[=[
CREATE TABLE numbers(num1,num2);
INSERT INTO numbers VALUES(1,11);
INSERT INTO numbers VALUES(2,22);
INSERT INTO numbers VALUES(3,33);
]=]
for num1,num2 in db:urows('SELECT * FROM numbers') do print(num1,num2) end
Этот скрипт печатает следующее:
1 11
2 22
3 33