sqlite3, RusHub | Библиотека базы данных sqlite

Описание функций библиотеки:


Методы объекта среды разработки (env):

env:complete(sql)
В случае верного синтаксиса SQL команды возвращает true, иначе возвращает false.


env:open(filename) или env:connect(filename)
Открывает (или создаёт, если не создана) SQLite базу с именем filename и возвращает её хендл, который имеет lua тип userdata (возвращаемый данной функцией объект в дальнейшем используется для вызовов всех методов для данного соединения с базой данных). Пример:



В случае ошибки, функция возвращает nil, код ошибки и сообщение об ошибке.


env:open_memory()
Открывает временную базу данных (в памяти) и возвращает хендл, который имеет lua тип userdata. В случае ошибки, функция возвращает nil, код ошибки и сообщение об ошибке. (В памяти база данных изменяется, но никогда не сохраняется на диск.)


env:close()
Закрывает текущую среду разработки (env).


env._VERSION
Возвращает строку с информацией о версии SQLite (в формате "x.y[.z]").



Методы объекта соединения (con):
После открытия базы данных при помощи метода env:open() или env:open_memory() возвращается хендл этой базы. Открытые базы данных поддерживают следующие методы:


con:busy_handler([func [, udata]])
Этот вызов позволяет указать lua функцию-обработчик, которая будет вызываться в случае, если файл базы данных был заблокирован другим процессом или потоком. Если func равен nil, то удаляется ранее установленная функция и любой вызов метода exec вернет состояние занятости env.BUSY немедленно при доступе к заблокированной таблице. Если функция-обработчик указана, то она вызовется с двумя аргументами. Первый аргумент - это указанный в методе busy_handler аргумент udata. Второй аргумент – предыдущее количество вызовов обработчика, при доступе к заблокированному ресурсу. Если обработчик вернул nil, false или 0, то метод exec вернет env.BUSY, в противном случае, метод exec будет пытаться открыть в цикле выполнить свой запрос.
По умолчанию обработчика нету.
Sqlite реентерабельна, и в обработчике возможно выполнять запросы. Не совсем понятно, зачем это может пригодиться, но в теории это возможно. Обработчик не должен закрывать файл базы данных. Закрытие базы из обработчика вызовет удаление структур вышестоящего запроса и может привести к аварийному завершению.


con:busy_timeout(t)
Этот вызов позволяет установить время t в миллисекундах, которое нужно подождать в случае если транзакция не была завершена (файл базы данных был заблокирован другим процессом или потоком). Вызов этого метода удалит все функции-обработчики, установленные методом busy_handler. Вызов этого метода с аргументом меньше либо равном 0 отключит все функции-обработчики.


con:close()
Закрывает базу данных. Все sql запросы, использующие con:prepare() завершаются при вызове данного метода. Метод возвращает env.OK в случае успеха, и числовой код ошибки в случае неудачи.


con:create_aggregate(name, nargs, step, final)
Этот метод создаёт функцию обратного вызова. Функция вызывается для каждой строки запроса. Аргумент name - это строка, которая содержит имя создаваемой sql функции. Аргумент nargs - это число аргументов у sql функции. Аргумент step - это непосредственно lua функция, которая будет выполняться для каждой строки запроса, эта функция вызывается с аргументом context и аргументами sql функции. Аргумент final - это функция, которая будет вызываться один раз в самом конце запроса, эта функция вызывается с один аргументом - context.

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



В результате на экране увидим следующее:


con:create_collation(name, func)
Этот метод создают сортирующую функцию обратного вызова. Функция обратного вызова нужна для установки порядка сортировки, по большей части за счёт сравнения строк. Аргумент name - это строка, содержащая имя sql сортировки. Аргумент func - это непосредственно lua функция сортировки, принимающая 2 строковых аргумента и возвращающая 0, если строковые аргументы равны, -1 - если первый аргумент "меньше" второго, и 1 - если первый аргумент "больше" второго.

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




con:create_function(name, nargs, func)
Этот метод создаёт функцию обратного вызова. Функция вызывается для каждой строки запроса. Аргумент name - это строка, которая содержит имя создаваемой sql функции. Аргумент nargs - это число аргументов у sql функции. Аргумент func - это непосредственно lua функция, которая будет выполняться для каждой строки запроса, эта функция вызывается с аргументом context и аргументами sql функции.

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




con:errcode() или con:error_code()
Возвращает числовой код (или расширенный код) для недавнего неудавшегося вызова метода базы данных.


con:errmsg() или con:error_message()
Возвращает сообщение с ошибкой для недавнего неудавшегося вызова метода базы данных.


con:exec(sql [, func [, udata]]) или con:execute(sql [, func [, udata]]) или con:query(sql [, func [, udata]])
Составляет и выполняет sql запрос, указанный в первом аргументе этого метода. Запросы просто выполняются друг за другом не сохраняясь. Функция возвращает env.OK в случае успеха и числовой код ошибки в случае неудачи.

Если один или несколько утверждений являются запросами, и если во втором параметре данного метода указана функция func, то эта функция выполнится для каждой строки результатов запроса. Эта функция будет вызываться с 4 аргументами: udata (третий аргумент метода exec), числом колонок в строке(cols), таблицей (values), содержащей все данные всех колонок, и другой таблицей (names), содержащей имена всех колонок. Эта функция должна возвратить 0. Если она вернёт не 0, то запрос будет считаться прерванным. Все последующие запросы не будут выполняться, а метод exec вернёт код env.ABORT.

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




con:interrupt()
Этот метод прерывает выполнение операции базы данных. Метод ничего не возвращает.


con:isopen() или con:isconnect()
Этот метод возвращает true, если база открыта, иначе возвращает false.


con:last_insert_rowid()
Этот метод возвращает идентификатор строки последнего INSERT запроса. Если INSERT запрос никогда не выполнялся, то метод возвращает 0. Каждая строка в SQLite таблице имеет уникальный 64-битный целочисленный ключ 'rowid'. Этот идентификатор всегда доступен по имени ROWID, OID, или _ROWID_. Если таблица имеет поле с типом INTEGER PRIMARY KEY, то эта колонка является псевонимом для 'rowid'.
Если INSERT выполняется внутри триггера, то идентификатор rowid вносимой строки будет возвращаться так долго, как долго будет работать тригер. Как только триггер завершит свою работу вернётся то значение, которое было до работы триггера.


con:nrows(sql)
Метод создаёт итератор, который возвращает последующие строки, выбирая их из запроса sql. Каждый вызов итератора возвращает таблицу, ключами которой являются поля таблицы, а значениями - значения этих полей.

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



Результаты работы:




con:prepare(sql)
Данный метод компилирует sql утверждение во внутренне представление и возвращает cur объект (курсор) типа userdata для дальнейших операций.


con:progress_handler(n, func, udata)
Этот метод устанавливает функцию обратного вызова func, которая выполняется периодически в течение длинных вызовов метода con:exec() или cur:step(). Вызов функции происходит каждые n операций, где n передаётся в качестве первого аргумента в указанную функцию. udata передаётся в качестве второго аргумента. Если действий в методе con:exec() или cur:step() меньше n, то функция обратного вызова не будет выполняться. Только одна функция обратного вызова может быть зарегистрирована для каждой открытой базы данных. Повторный вызов данного метода перезапишет прежде установленную функцию. Для того, чтобы удалить функцию обратного вызова, достаточно в методе вторым аргументом указать nil.
Если функция обратного вызова возвращает значение, отличное от 0, то текущий запрос незамедлительно прерывается и база данных откатывается назад, а метод con:exec() или cur:step() вернёт число env.INTERRUPT. Данный метод может быть использован для отмены длительных запросов.


con:rows(sql)
Метод создаёт итератор, который возвращает последующие строки, выбирая их из запроса sql. Каждый вызов итератора возвращает таблицу, ключами которой являются номера полей таблицы, а значениями - значения этих полей.

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



Результаты работы:




con:total_changes()
Этот метод возвращает общее число строк, которое было модифицировано при помощи INSERT, UPDATE или DELETE, за всё время, в течение которого база была открытой. Сюда также включаются операции в триггерах. Изменения записываются как только выполняется любой из вызовов cur:reset() или cur:finalize().


con:trace(func, udata)
Этот метод устанавливает функцию трассировки. func - это lua функция, которую вызывает SQLite до разбора sql утверждения. В эту функцию передаются 2 аргумента. Первый - это аргумент udata, второй - это строка с sql утверждением.


con:urows(sql)
Метод создаёт итератор, который возвращает последующие строки, выбирая их из запроса sql. Каждый вызов итератора возвращает значения всех полей данной строки.

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



Результаты работы:




con:commit()
Метод выполнения (завершения) текущей транзакции. Возвращает true в случае успеха, nil и сообщение ошибки - в случае, когда транзакция не может быть завершина или база данных не поддерживает транзакции.


con:rollback()
Метод отката на предыдущую транзакцию. Возвращает true в случае успеха, nil и сообщение ошибки - в случае, когда операция не может быть выполнена или база данных не поддерживает транзакции.


con:setautocommit(boolean)
Метод включения/отключения автоматических транзакций. Эта функция не может работать в базах, на которых не осуществляются транзакции. В базах данных, на которых нет понятия режима автоматических транзакций, этот механизм осуществляется драйвером. Метод возвращает true в случае успеха, и вызывает ошибку - в случае невыполнимости или неосуществимости.



Методы объекта курсор (cur):
После создания подзапроса при помощи метода con:prepare(), к этому подзапросу можно применять следующие методы:


cur:bind(n [, value])
Связывает данные value с переменной n в запросе. Если тип данных value является строкой или числом, то эти данные связываются как text или double соответственно. Если типом данных переменной value является тип boolean или эта переменная равна nil или вовсе отсутствует missing, то предыдущая связь удаляется. Данный метод возвращает env.OK в случае успеха или численный код ошибки в случае неудачи.


cur:bind_blob(n, blob)
Связывает строку blob (которая может быть бинарной строкой) с параметром n. Данный метод возвращает env.OK в случае успеха или численный код ошибки в случае неудачи.


cur:bind_names(nametable)
Связывает параметры запроса с данными таблицы nametable. Если есть параметры запроса вида ":AAA" или "$AAA", то ищутся соответствующие поля таблицы, если параметры в запросе не именованные, то ищутся числовые поля таблицы nametable. Данный метод возвращает env.OK в случае успеха или численный код ошибки в случае неудачи.


cur:bind_parameter_count()
Возвращает максимальный индекс подзапроса. Если параметры подзапроса имеют вид ":AAA" или вид "?", то назначается последовательно увеличивающееся число, начинающиеся с 1, так что возвращаемая величина является количеством параметров. Тем не менее если одно и тоже имя используется в подзапросе несколько раз, то все повторные имена не считаются, то есть возвращается величина, являющаяся числом уникальных параметров в подзапросе.
Если какой-либо параметр подзапроса имеет вид "?NNN" (где NNN - целое число), то могут быть промежутки в нумерации и возвращаемая величина будет равна индексу параметра подзапроса с самой большой индексной величиной.


cur:bind_parameter_name(n)
Возвращает имя n-го параметра подзапроса stmt. Параметры ":AAA", "@AAA", "$VVV" будут иметь имена ":AAA", "@AAA", "$VVV", соответственно. Другими словами, символы ":", "$" и "@" включаются в имя. Параметры "?" и "?NNN" не имеют имени. Первый связанный параметр имеет индекс 1. Если величина n за допустимыми рамками, или если n-ый параметр не имеет имени, то возвращается nil. Данный метод возвращает env.OK в случае успеха или численный код ошибки в случае неудачи.


cur:bind_values(value1, value2, ..., valueN)
Связывает указанные данные с параметрами подзапроса. Данный метод возвращает env.OK в случае успеха или численный код ошибки в случае неудачи.


cur:columns() или cur:numcols()
Возвращает количество колонок в результатах запроса, или 0, если подзапрос не возвращает ничего.


cur:finalize()
Эта функция завершает подзапрос. Если поздапрос выполнился успешно или не выполнился, то функция возвращает env.OK, в случае неудачи возвращает численный код ошибки.


cur:get_name(n) или cur:getcolname(n)
Возвращает имя n-ого столбца в результатах подзапроа (номер самого левого столбца - 0).


cur:get_named_types() или cur:getcolntypes()
Возвращает таблицу с именами и типами всех столбцов подзапроса.


cur:get_named_values() или cur:getcolnvalues()
Возвращает таблицу с именами и данными текущей строки результатов подзапроса.


cur:get_names() или cur:getcolnames()
Возвращает массив с именами всех столбцов в результатах подзапроса.


cur:get_type(n) или cur:getcoltype(n)
Возвращает тип n-ого столбца подзапроса (номер самого левого столбца - 0).


cur:get_types() или cur:getcoltypes()
Возвращает массив с типами всех столбцов подзапроса.


cur:get_unames() или cur:getcolunames()
Возвращает имена всех столбцов подзапроса.


cur:get_utypes() или cur:getcolutypes()
Возвращает типы всех столбцов подзапроса.


cur:get_uvalues() или cur:getcoluvalues()
Возвращает данные всех столбцов текущей сроки подзапроса.


cur:get_value(n) или cur:getcolvalue(n)
Возвращает данные n-ого столбца подзапроса (номер самого левого столбца - 0).


cur:get_values() или cur:getcolvalues()
Возвращает массив данных всех столбцов подзапроса.


cur:isopen() или cur:isconnect()
Возвращает true, если запрос ещё открыт (не заверщён при помощи метода finalize), иначе возвращает false.


cur:close()
Закрывает текущий курсор (cur).


cur:nrows()
Возвращает итератор, который возвращает последующие строки, выбирая их из подзапроса. Каждый вызов итератора возвращает таблицу, ключами которой являются поля таблицы, а значениями - значения этих полей.


cur:reset()
Этот метод восстанавливает подзапрос, для того чтобы он был выполнен. Переменные, которые были связаны при помощи методов cur:bind*() сохраняют свои значения.


cur:rows()
Возвращает итератор, который возвращает последующие строки, выбирая их из подзапроса. Каждый вызов итератора возвращает таблицу, ключами которой являются номера полей таблицы, а значениями - значения этих полей.


cur:step()
Этот метод должен быть вызван для того чтобы оценить следующую итерацию подзапроса. Она возвращает одо из следующих значений:

env.BUSY: база данных была занята. Если подзапрос подтверждён (COMMIT), то вы можете повторить запрос, в противном случае можно откатиться на предыдущую транзакцию.

env.DONE: подзапрос успешно завершил работу (finalize). Метод cur:step() не должен вызываться заново, без вызова метода cur:reset(), который сбросит всё на начальное состояние.

env.ROW: возвращается всякий раз, когда новая строка с данными готова для обработки вызывающим оператором. Данные могут быть доступны использованием функций доступа к строкам. cur:step(), может вызываться снова, чтобы извлекать следующую строку с данными.

env.ERROR: ошибка во время выполнения (например, нарушение ограничений). Метод cur:step() не должен вызываться снова. Более детальную информацию можно посмотреть, вызвав метод con:errmsg(). Более специфический код ошибки может быть получен при вызове метода cur:reset().

env.MISUSE: вызвана неподходящая функция. Такое возможно если предыдущий подзапрос завершил работу (finalize), или предыдущий вызов метода cur:step() вернул env.ERROR или env.DONE.


cur:urows()
Возвращает итератор, который возвращает последующие строки, выбирая их из подзапроса. Каждый вызов итератора возвращает значения всех полей данной строки.



Методы объекта context функций обратного вызова:
Объекта context доступен как параметр в функциях обратного вызова методов con:create_aggregate() и con:create_function(). Этот объект обладает следующими методами:


ctx:aggregate_count()
Метод возвращает число вызовов функции обратного вызова.


ctx:get_aggregate_data()
Возвращает данные определенного пользователем поля.


ctx:set_aggregate_data(udata)
Устанавливает данные для определённого пользователем поля.


ctx:result(res)
Устанавливает результат функции обратного вызова в res. Тип результата зависит от типа res и является числом, или строкой или nil. Все другие величины поднимают сообщение ошибки.


ctx:result_null()
Устанавливает результат функции обратного вызова в nil. Метод ничего не возвращает.


ctx:result_number(number) или ctx:result_double(number)
Устанавливает результат функции обратного вызова как число number. Метод ничего не возвращает.


ctx:result_int(number)
Устанавливает результат функции обратного вызова как целое число number. Метод ничего не возвращает.


ctx:result_text(str)
Устанавливает результат функции обратного вызова как строку str. Метод ничего не возвращает.


ctx:result_blob(blob)
Устанавливает результат функции обратного вызова как бинарную строку blob. Метод ничего не возвращает.


ctx:result_error(err)
Устанавливает результат функции обратного вызова как ошибку err. Метод ничего не возвращает.


ctx:user_data()
Возвращает userdata параметр поступивший при вызове, чтобы устанавливать функцию возврата (см. описания методов con:create_aggregate() и con:create_function()).


В заключении приведу числовые коды ошибок: