Интерфейс Tcl для библиотеки SQLite

Библиотека SQLite разработана для очень простого использования из скрипта Tcl или Tcl/Tk. SQLite изначально была расширением Tcl, а основной набор тестов для SQLite написан на TCL. SQLite может быть использована с любым языком программирования, но её связи с TCL очень глубоки.

Этот документ предоставляет обзор программного интерфейса Tcl для SQLite.

API

Интерфейс библиотеки SQLite состоит из единственной команды tcl под названием sqlite3. Поскольку существует только эта одна команда, интерфейс не размещается в отдельном пространстве имён.

Команда sqlite3 в основном используется следующим образом для открытия или создания базы данных:

 sqlite3 dbcmd ?database-name? ?options? 

Для получения только информации команда sqlite3 может быть вызвана ровно с одним аргументом, либо «-version», либо «-sourceid», либо «-has-codec», которые вернут указанные данные без других эффектов.

С другими аргументами команда sqlite3 открывает базу данных, имя которой указано во втором не опционном аргументе, или имя «» если такого нет. Если открытие прошло успешно, создаётся новая команда Tcl, имя которой передаётся в качестве первого аргумента, и возвращается «». (Этот подход аналогичен способу создания виджетов в Tk.) Если открытие завершилось ошибкой, генерируется ошибка без создания команды Tcl, и возвращается строка сообщения об ошибке.

Если база данных ещё не существует, по умолчанию она создаётся автоматически (хотя это можно изменить, используя опцию «-create false»).

Имя базы данных обычно является просто именем файла на диске, в котором хранится база данных. Если имя базы данных является специальным именем «:memory:», то новая база данных создаётся в памяти. Если имя базы данных пустая строка, то база данных создаётся в пустом файле, который автоматически удаляется при закрытии соединения с базой данных. Имена файлов URI могут быть использованы, если опция «-uri yes» передаётся команде sqlite3.

Опции, поддерживаемые командой sqlite3 включают:

  
-create BOOLEAN
  If true, then a new database is created if one does not already exist. If false, then an attempt to open a database file that does not previously exist raises an error. The default behavior is "true".  
-nomutex BOOLEAN
  If true, then all mutexes for the database connection are disabled. This provides a small performance boost in single-threaded applications.  
-readonly BOOLEAN
  If true, then open the database file read-only. If false, then the database is opened for both reading and writing if filesystem permissions allow, or for reading only if filesystem write permission is denied by the operating system. The default setting is "false". Note that if the previous process to have the database did not exit cleanly and left behind a hot journal, then the write permission is required to recover the database after opening, and the database cannot be opened read-only.  
-uri BOOLEAN
  If true, then interpret the filename argument as a URI filename. If false, then the argument is a literal filename. The default value is "false".  
-vfs VFSNAME
  Use an alternative VFS named by the argument.  
-fullmutex BOOLEAN
  If true, multiple threads can safely attempt to use the database. If false, such attempts are unsafe. The default value depends upon how the extension is built.  
-nofollow BOOLEAN
  If true, and the database name refers to a symbolic link, it will not be followed to open the true database file. If false, symbolic links will be followed. The default is "false".   

После открытия базы данных SQLite ею можно управлять, используя методы dbcmd. В настоящее время определено 40 методов.

Использование каждого из этих методов будет объяснено в дальнейшем, хотя и не в указанном выше порядке.

Метод «eval»

Наиболее полезный метод dbcmd — «eval». Метод eval используется для выполнения SQL-запросов в базе данных. Синтаксис метода eval выглядит следующим образом:

 dbcmd eval ?-withoutnulls? sql ?array-name? ?script? 

Задача метода eval — выполнить SQL-запрос или запросы, указанные во втором аргументе. Например, чтобы создать новую таблицу в базе данных, можно сделать так:

 sqlite3 db1 ./testdb
 db1 eval {CREATE TABLE t1(a int, b text)} 

Вышеприведённый код создаёт новую таблицу под названием t1 со столбцами a и b. Что может быть проще?

Результаты запроса возвращаются в виде списка значений столбцов. Если запрос запрашивает 2 столбца, и существует 3 строки, соответствующие запросу, то возвращаемый список будет содержать 6 элементов. Например:

 db1 eval {INSERT INTO t1 VALUES(1,'hello')}
 db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}
 db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}
 set x [db1 eval {SELECT * FROM t1 ORDER BY a}] 

Переменная $x устанавливается вышеприведённым кодом в

 1 hello 2 goodbye 3 howdy! 

Вы также можете обрабатывать результаты запроса по одной строке за раз, указав имя переменной массива и скрипт, следующий за SQL-кодом. Для каждой строки результата запроса значения всех столбцов будут вставлены в переменную массива, и будет выполнен скрипт. Например:

 db1 eval {SELECT * FROM t1 ORDER BY a} values {
 parray values
 puts ""
 } 

Этот последний код даст следующий вывод:

 values(*) = a b
 values(a) = 1
 values(b) = hello values(*) = a b
 values(a) = 2
 values(b) = goodbye values(*) = a b
 values(a) = 3
 values(b) = howdy! 

Для каждого столбца в строке результата имя этого столбца используется в качестве индекса в массиве, а значение столбца хранится в соответствующей ячейке массива. (Внимание: если два или более столбца в наборе результатов запроса имеют одинаковое имя, то последний столбец с этим именем перезапишет предыдущие значения, и предыдущие столбцы с таким же именем будут недоступны.) Специальный индекс массива * используется для хранения списка имён столбцов в порядке их появления.

Обычно NULL-результаты SQL сохраняются в массиве с использованием настройки nullvalue. Однако, если используется опция -withoutnulls, то NULL-значения SQL вызывают отмену соответствующей ячейки массива вместо этого.

Если имя переменной массива опущено или является пустой строкой, то значение каждого столбца сохраняется в переменной с тем же именем, что и сам столбец. Например:

 db1 eval {SELECT * FROM t1 ORDER BY a} {
 puts "a=$a b=$b"
 } 

Отсюда мы получаем следующий вывод

 a=1 b=hello
 a=2 b=goodbye
 a=3 b=howdy! 

Имена переменных Tcl могут появляться в SQL-запросе во втором аргументе в любом месте, где допустимо поместить строковый или числовой литерал. Значение переменной подставляется вместо имени переменной. Если переменная не существует, используется значение NULL. Например:

 db1 eval {INSERT INTO t1 VALUES(5,$bigstring)} 

Обратите внимание, что нет необходимости заключать значение $bigstring в кавычки. Это происходит автоматически. Если $bigstring — большая строка или двоичный объект, этот метод не только проще для написания, но и намного эффективнее, поскольку он избегает создания копии содержимого $bigstring.

Если переменная $bigstring имеет как строковое, так и «массивовое» представление, то TCL вставляет значение как строку. Если у неё есть только «массивовое» представление, то значение вставляется как BLOB. Чтобы принудительно вставить значение как BLOB, даже если оно также имеет текстовое представление, используйте символ «@» вместо «$». Так:

 db1 eval {INSERT INTO t1 VALUES(5,@bigstring)} 

Если переменная не имеет представления bytearray, то «@» работает так же, как «$». Обратите внимание, что «:» работает так же, как «$» во всех случаях, поэтому следующее — ещё один способ выразить то же самое утверждение:

 db1 eval {INSERT INTO t1 VALUES(5,:bigstring)} 

Использование «:» вместо «$» перед именем переменной может быть полезно, если текст SQL заключён в двойные кавычки "..." вместо фигурных скобок {...}. Когда SQL заключён в двойные кавычки "...", TCL выполнит подстановку переменных $-, что может привести к SQL-инъекции, если не проявлять крайней осторожности. Но TCL никогда не подставит переменную :- независимо от того, используются ли двойные кавычки "..." или фигурные скобки {...} для заключения SQL, поэтому использование :-переменных добавляет дополнительную меру защиты от SQL-инъекций.

Метод «close»

Как следует из названия, метод «close» для базы данных SQLite просто закрывает базу данных. Это приводит к побочному эффекту удаления команды Tcl dbcmd. Вот пример открытия и немедленного закрытия базы данных:

 sqlite3 db1 ./testdb
 db1 close 

Если вы удалите dbcmd напрямую, это имеет тот же эффект, что и вызов метода «close». Следовательно, следующий код эквивалентен предыдущему:

 sqlite3 db1 ./testdb
 rename db1 {} 

Метод «transaction»

Метод «transaction» используется для выполнения скрипта TCL внутри транзакции базы данных SQLite. Транзакция фиксируется, когда скрипт завершается, или отменяется, если скрипт завершается ошибкой. Если транзакция происходит внутри другой транзакции (даже той, которая запускается вручную с помощью BEGIN), это бесполезно.

Команда transaction может использоваться для безопасного объединения нескольких команд SQLite. Вы всегда можете вручную запускать транзакции с помощью BEGIN, конечно. Но если произойдёт ошибка, так что COMMIT или ROLLBACK никогда не будут выполнены, то база данных останется заблокированной навсегда. Кроме того, BEGIN не вложен, поэтому необходимо убедиться, что никакие другие транзакции не активны перед началом новой. Метод «transaction» автоматически заботится обо всех этих деталях.

Синтаксис выглядит следующим образом:

 dbcmd transaction ?transaction-type? script 

transaction-type может быть deferred, exclusive или immediate. По умолчанию — deferred.

Метод «cache»

Метод «eval», описанный выше, сохраняет кеш подготовленных заявок для недавно выполненных SQL-команд. Метод «cache» используется для управления этим кешем. Первый вариант этой команды:

 dbcmd cache size N 

Это устанавливает максимальное количество заявок, которые могут быть кэшированы. Верхний предел — 100. По умолчанию — 10. Если вы установите размер кэша в 0, кэширование не будет производиться.

Второй вариант команды:

 dbcmd cache flush 

Метод cache-flush завершает все подготовленные запросы, находящиеся в настоящее время в кэше.

Метод «complete»

Метод «complete» принимает строку предполагаемого SQL-кода в качестве единственного аргумента. Он возвращает TRUE, если строка представляет собой полную SQL-команду, и FALSE, если ещё требуется ввод.

Метод «complete» полезен при разработке интерактивных приложений, чтобы узнать, когда пользователь закончил ввод строки SQL-кода. Это фактически просто интерфейс к функции C sqlite3_complete().

Метод «config»

Метод «config» запрашивает или изменяет определённые настройки конфигурации для подключения к базе данных с использованием интерфейса sqlite3_db_config(). Выполните этот метод без аргументов, чтобы получить список доступных настроек конфигурации и их текущих значений в формате TCL:

 dbcmd config 

Вышеприведённое вернёт что-то вроде этого:

defensive 0 dqs_ddl 1 dqs_dml 1 enable_fkey 0 enable_qpsg 0 enable_trigger 1 enable_view 1 fts3_tokenizer 1 legacy_alter_table 0 legacy_file_format 0 load_extension 0 no_ckpt_on_close 0 reset_database 0 trigger_eqp 0 trusted_schema 1 writable_schema 0

Добавьте имя отдельной настройки конфигурации, чтобы запросить текущее значение этой настройки. Дополнительно добавьте булево значение, чтобы изменить настройку.

Рекомендуется внести следующие четыре изменения в конфигурацию для максимальной безопасности приложения. Отключение параметра trust_schema предотвращает использование виртуальных таблиц и подозрительных SQL-функций внутри триггеров, представлений, ограничений CHECK, сгенерированных столбцов и индексов выражений. Отключение параметров dqs_dml и dqs_ddl предотвращает использование строк в двойных кавычках. Включение параметра defensive предотвращает прямые записи в скрытые таблицы.

db config trusted_schema 0
db config defensive 1
db config dqs_dml 0
db config dqs_ddl 0

Метод «copy»

Метод «copy» копирует данные из файла в таблицу. Он возвращает количество успешно обработанных строк из файла. Синтаксис метода «copy» выглядит следующим образом:

 dbcmd copy conflict-algorithm table-name  file-name  ?column-separator? ?null-indicator? 

Алгоритм конфликтов должен быть одним из алгоритмов конфликтов SQLite для оператора INSERT: rollback, abort, fail, ignore или replace. См. раздел «Язык SQLite» для ON CONFLICT для получения дополнительной информации. Алгоритм конфликтов должен быть указан строчными буквами.

Имя таблицы должно уже существовать в качестве таблицы. Имя файла должно существовать, и каждая строка должна содержать то же количество столбцов, что и определено в таблице. Если строка в файле содержит больше или меньше столбцов, чем определено, метод «copy» отменяет все вставки и возвращает ошибку.

Разделитель столбцов — это необязательная строка-разделитель столбцов. По умолчанию используется символ табуляции ASCII \t.

Индикатор NULL — это необязательная строка, указывающая, что значение столбца является NULL. По умолчанию — пустая строка. Обратите внимание, что разделитель столбцов и индикатор NULL являются необязательными позиционными аргументами; если указан индикатор NULL, должен быть указан аргумент разделитель столбцов и должен предшествовать аргументу индикатор NULL.

Метод «copy» реализует функциональность, аналогичную команде оболочки SQLite .import.

Метод «timeout»

Метод «timeout» используется для управления временем ожидания библиотеки SQLite для освобождения блокировок перед отказом от транзакции базы данных. Значение таймаута по умолчанию — 0 миллисекунд. (Другими словами, по умолчанию ожидание не производится.)

База данных SQLite позволяет нескольким одновременным читателям или одному писателю, но не обоим. Если какой-либо процесс записывает в базу данных, никакой другой процесс не может читать или записывать. Если какой-либо процесс читает базу данных, другие процессы могут читать, но не записывать. Для всей базы данных используется единственная блокировка.

Когда SQLite пытается открыть базу данных и обнаруживает, что она заблокирована, он может временно задержаться и попытаться открыть файл снова. Этот процесс повторяется до тех пор, пока запрос не истечет, и SQLite вернет ошибку. Таймаут настраивается. По умолчанию он установлен в 0, поэтому, если база данных заблокирована, SQL-запрос завершается немедленно. Но вы можете использовать метод «timeout», чтобы изменить значение таймаута на положительное число. Например:

db1 timeout 2000

Аргументом метода timeout является максимальное количество миллисекунд ожидания освобождения блокировки. Итак, в примере максимальная задержка составит 2 секунды.

Метод «busy»

Метод «busy», как и «timeout», вступает в игру только когда база данных заблокирована. Но метод «busy» предоставляет программисту гораздо больший контроль над действиями. Метод «busy» определяет процедуру обратного вызова Tcl, которая вызывается всякий раз, когда SQLite пытается открыть заблокированную базу данных. К процедуре обратного вызова до вызова добавляется один целочисленный аргумент. Аргументом является число предыдущих вызовов обратного вызова busy для текущего события блокировки. Предполагается, что обратный вызов выполнит некоторую полезную работу в течение короткого времени (например, обработает события интерфейса пользователя) и затем вернётся, чтобы блокировка могла быть проверена снова. Процедура обратного вызова должна возвращать «0», если она хочет, чтобы SQLite попытался снова открыть базу данных, и должна возвращать «1», если она хочет отказаться от текущей операции.

Если метод «busy» вызывается без аргумента, возвращается имя процедуры обратного вызова, последней установленной методом «busy». Если не было установлено никакой процедуры обратного вызова, возвращается пустая строка.

Метод «enable_load_extension»

Механизм загрузки расширений SQLite (доступный с помощью функции SQL load_extension()) по умолчанию выключен. Это мера безопасности. Если приложение хочет использовать функцию load_extension(), оно должно сначала включить эту возможность, используя этот метод.

Этот метод принимает один логический аргумент, который включит или выключит функциональность загрузки расширений.

Для обеспечения наилучшей безопасности не используйте этот метод, если это не является необходимым, и выполните PRAGMA trusted_schema=OFF или метод «db config trusted_schema 0» до вызова этого метода.

Этот метод сопоставляется с интерфейсом C/C++ sqlite3_enable_load_extension().

Метод «exists»

Метод «exists» похож на методы «onecolumn» и «eval» тем, что выполняет SQL-запросы. Разница заключается в том, что метод «exists» всегда возвращает логическое значение TRUE, если запрос в SQL-запросе, который он выполняет, возвращает одну или несколько строк, и FALSE, если SQL возвращает пустой набор.

Метод «exists» часто используется для проверки существования строк в таблице. Например:

 if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {
 # Processing if $user exists
 } else {
 # Processing if $user does not exist
 } 

Метод «last_insert_rowid»

Метод «last_insert_rowid» возвращает целое число, являющееся ROWID последней вставленной строки базы данных.

Метод «function»

Метод «function» регистрирует новые SQL-функции в движке SQLite. Аргументами являются имя новой SQL-функции и команда TCL, которая реализует эту функцию. Аргументы функции добавляются к команде TCL перед её вызовом.

По соображениям безопасности рекомендуется, чтобы приложения сначала установили PRAGMA trusted_schema=OFF или запустили метод «db config trusted_schema 0» перед использованием этого метода.

Синтаксис выглядит следующим образом:

 dbcmd function sql-name ?options? script 

Следующий пример создаёт новую SQL-функцию с именем «hex», которая преобразует её числовой аргумент в строку с шестнадцатеричным кодированием:

 db function hex {format 0x%X} 

Метод «function» принимает следующие параметры:

  
-argcount INTEGER
  Specify the number of arguments that the SQL function accepts. The default value of -1 means any number of arguments. 

-deterministic 
 This option indicates that the function will always return the same answer given the same argument values. The SQLite query optimizer uses this information to cache answers from function calls with constant inputs and reuse the result rather than invoke the function repeatedly.  
-directonly 

 This option restricts the function to only be usable by direct top-level SQL statement. The function will not be accessible to triggers, views, CHECK constraints, generated columns, or index expressions. This option is recommended for all application-defined SQL functions, and is highly recommended for any SQL function that has side effects or that reveals internal state of the application. 
Security Warning: Without this switch, an attacker might be able to change the schema of a database file to include the new function inside a trigger or view or CHECK constraint and thereby trick the application into running the function with parameters of the attacker's choosing. Hence, if the new function has side effects or reveals internal state about the application and the -directonly option is not used, that is a potential security vulnerability.  
-innocuous 
 This option indicates that the function has no side effects and does not leak any information that cannot be computed directly from its input parameters. When this option is specified, the function may be used in triggers, views, CHECK constraints, generated columns, and/or index expressions even if PRAGMA trusted_schema=OFF. The use of this option is discouraged unless it is truly needed.  
-returntype integer|real|text|blob|any 
 This option is used to configure the type of the result returned by the function. If this option is set to "any" (the default), SQLite attempts to determine the type of each value returned by the function implementation based on the Tcl value's internal type. Or, if it is set to "text" or "blob", the returned value is always a text or blob value, respectively. If this option is set to "integer", SQLite attempts to coerce the value returned by the function to an integer. If this is not possible without data loss, it attempts to coerce it to a real value, and finally falls back to text. If this option is set to "real", an attempt is made to return a real value, falling back to text if this is not possible.   

Метод «nullvalue»

Метод «nullvalue» изменяет представление NULL, возвращаемое в результате метода «eval».

 db1 nullvalue NULL 

Метод «nullvalue» полезен для различения NULL и пустых значений столбцов, так как Tcl не имеет представления NULL. По умолчанию представление для NULL — пустая строка.

Метод «onecolumn»

Метод «onecolumn» работает так же, как «eval», то есть он вычисляет оператор SQL-запроса, указанный в качестве аргумента. Разница заключается в том, что «onecolumn» возвращает один элемент, который является первым столбцом первой строки результата запроса.

Это удобный метод. Он экономит пользователю необходимость выполнения «[lindex ... 0]» на результатах «eval», чтобы извлечь результат одного столбца.

Метод «changes»

Метод «changes» возвращает целое число, которое представляет количество строк в базе данных, которые были вставлены, удалены и/или изменены методом «eval» последним.

Метод «total_changes»

Метод «total_changes» возвращает целое число, которое представляет количество строк в базе данных, которые были вставлены, удалены и/или изменены с момента первого открытия текущего подключения к базе данных.

Метод «authorizer»

Метод «authorizer» предоставляет доступ к интерфейсу C/C++ sqlite3_set_authorizer. Аргументом метода authorizer является имя процедуры, которая вызывается при компиляции SQL-запросов для авторизации определенных операций. Процедура обратного вызова принимает 5 аргументов, описывающих выполняемую операцию. Если обратный вызов возвращает строку «SQLITE_OK», то операция разрешена. Если он возвращает «SQLITE_IGNORE», то операция безмолвно отключается. Если возвращается «SQLITE_DENY», то компиляция завершается с ошибкой.

Если аргумент является пустой строкой, авторизация отключается. Если аргумент опущен, то возвращается текущий авторизатор.

Метод «bind_fallback»

Метод «bind_fallback» предоставляет приложению контроль над тем, как обрабатывать привязку параметров, когда переменная TCL не соответствует имени параметра.

Когда метод eval видит именованный параметр SQL, такой как «$abc» или «:def» или «@ghi» в операторе SQL, он пытается найти переменную TCL с тем же именем и привязывает значение этой переменной TCL к параметру SQL. Если такая переменная TCL не существует, по умолчанию привязывается значение SQL NULL к параметру. Однако, если указана процедура bind_fallback, то эта процедура вызывается с именем параметра SQL, и возвращаемое значение от процедуры привязывается к параметру SQL. Или если процедура возвращает ошибку, то SQL-запрос прерывается с этой ошибкой. Если процедура возвращает некоторый код, отличный от TCL_OK или TCL_ERROR, то параметр SQL привязывается к NULL, как это было бы по умолчанию.

Метод «bind_fallback» имеет один необязательный аргумент. Если аргумент — пустая строка, то bind_fallback отменяется, и восстанавливается поведение по умолчанию. Если аргумент — непустая строка, то аргумент — это команда TCL (обычно имя процедуры) для вызова всякий раз, когда обнаруживается параметр SQL, не соответствующий никакой переменной TCL. Если метод «bind_fallback» не получает аргументов, то возвращается текущая команда bind_fallback.

Например, следующая настройка заставляет TCL генерировать ошибку, если оператор SQL содержит параметр, не соответствующий никакой глобальной переменной TCL:

proc bind_error {nm} {
  error "no such variable: $nm"
}
db bind_fallback bind_error

Метод «progress»

Этот метод регистрирует обратный вызов, который вызывается периодически во время обработки запроса. Есть два аргумента: число команд виртуальной машины SQLite между вызовами и вызываемая команда TCL. Установка обратного вызова progress на пустую строку отключает его.

Обратный вызов progress можно использовать для отображения статуса длительного запроса или обработки событий GUI во время длительного запроса.

Метод «collate»

Этот метод регистрирует новые последовательности сортировки текста. Есть два аргумента: имя последовательности сортировки и имя процедуры TCL, которая реализует функцию сравнения для последовательности сортировки.

Например, следующий код реализует последовательность сортировки с именем «NOCASE», которая сортирует в текстовом порядке без учёта регистра:

proc nocase_compare {a b} {
  return [string compare [string tolower $a] [string tolower $b]]
}
db collate NOCASE nocase_compare

Метод «collation_needed»

Этот метод регистрирует процедуру обратного вызова, которая вызывается, когда движок SQLite нуждается в определённой последовательности сортировки, но не имеет её зарегистрированной. Обратный вызов может зарегистрировать последовательность сортировки. Обратный вызов вызывается с одним параметром, который является именем необходимой последовательности сортировки.

Метод «commit_hook»

Этот метод регистрирует процедуру обратного вызова, которая вызывается непосредственно перед тем, как SQLite пытается зафиксировать изменения в базе данных. Если обратный вызов генерирует исключение или возвращает ненулевое значение, транзакция откатывается вместо фиксации.

Метод «rollback_hook»

Этот метод регистрирует обратный вызов, который вызывается непосредственно перед тем, как SQLite пытается выполнить откат. Аргумент script выполняется без изменений.

Метод «status»

Этот метод возвращает информацию о статусе последнего выполненного SQL-запроса. Метод status принимает единственный аргумент, который должен быть либо «steps», либо «sorts». Если аргумент равен «steps», то метод возвращает количество полных сканирований таблиц, выполненных предыдущим SQL-запросом. Если аргумент равен «sorts», метод возвращает количество операций сортировки. Эта информация может быть использована для выявления запросов, которые не используют индексы для ускорения поиска или сортировки.

Метод status в основном является оберткой над C-языковым интерфейсом sqlite3_stmt_status().

Метод «update_hook»

Этот метод регистрирует обратный вызов, который вызывается сразу после того, как каждая строка изменяется операцией UPDATE, INSERT или DELETE. Перед вызовом обратного вызова добавляются четыре аргумента:

• Ключевое слово «INSERT», «UPDATE» или «DELETE», соответственно
• Имя базы данных, которая изменяется
• Таблица, которая изменяется
• rowid строки в таблице, которая изменяется

Обратный вызов не должен выполнять никаких действий, которые изменят подключение к базе данных, вызвавшему метод update_hook, например, выполнение запросов.

Метод «preupdate»

Этот метод либо регистрирует обратный вызов, который вызывается непосредственно перед тем, как каждая строка изменяется операцией UPDATE, INSERT или DELETE, либо может выполнять определённые операции, связанные с предстоящим обновлением.

Для регистрации или удаления обратного вызова preupdate используйте следующий синтаксис:

 dbcmd preupdate hook ?SCRIPT? 

• Ключевое слово «INSERT», «UPDATE» или «DELETE», соответственно
• Имя базы данных, которая изменяется
• Таблица, которая изменяется
• Исходное rowid строки в таблице, которая изменяется
• Новое rowid (если есть) строки в таблице, которая изменяется

Когда обратный вызов выполняется, и только тогда, эти операции preupdate могут быть выполнены с использованием указанного синтаксиса:

 dbcmd preupdate count
 dbcmd preupdate depth
 dbcmd preupdate new INDEX
 dbcmd preupdate old INDEX
 

Подметод count возвращает количество столбцов в строке, которая вставляется, обновляется или удаляется.

Подметод depth возвращает глубину вложенности обновления. Она будет 0 для прямой операции insert, update или delete; 1 для insert, update или delete, вызванных триггерами верхнего уровня; или более высокие значения для изменений, вызванных триггерами, вызванными триггерами.

Подметоды old и new возвращают соответственно выбранное исходное или изменённое значение столбца строки, которая обновляется.

Обратите внимание, что интерфейс Tcl (и лежащая в основе библиотека SQLite) должен был быть скомпилирован с препроцессорной меткой SQLITE_ENABLE_PREUPDATE_HOOK, чтобы метод preupdate был доступен.

Метод «wal_hook»

Этот метод регистрирует обратный вызов, который вызывается после завершения транзакции, когда база данных находится в режиме WAL. Перед вызовом обратного вызова добавляются два аргумента:

• Имя базы данных, по которой была завершена транзакция
• Количество записей в файле журнала предварительной записи (WAL) для этой базы данных

Этот метод может решить запустить точку восстановления либо сам, либо как последующий обратный вызов в режиме ожидания. Обратите внимание, что SQLite позволяет только один WAL-хук. По умолчанию этот единственный WAL-хук используется для автоматического создания точек восстановления. Если вы настроите явный WAL-хук, то этот WAL-хук должен гарантировать, что точки восстановления происходят, так как механизм автоматического создания точек восстановления будет отключен.

Этот метод должен вернуть целое значение, которое эквивалентно коду ошибки SQLite (обычно 0 для SQLITE_OK в случае успеха или 1 для SQLITE_ERROR, если произошла ошибка). Как и в sqlite3_wal_hook(), результаты возвращения целого значения, которое не соответствует коду ошибки SQLite, не определены. Если значение, возвращённое скриптом, не может быть интерпретировано как целое значение, или если скрипт генерирует исключение Tcl, никакая ошибка не возвращается в SQLite, но генерируется фоновая ошибка Tcl.

Метод «incrblob»

Этот метод открывает канал TCL, который можно использовать для чтения или записи в существующий BLOB в базе данных. Синтаксис такой:

 dbcmd incrblob ?-readonly? ?DB? TABLE COLUMN ROWID 

Команда возвращает новый канал TCL для чтения или записи в BLOB. Канал открывается с использованием C-языкового интерфейса sqlite3_blob_open(). Закройте канал с помощью команды close TCL.

Метод «errorcode»

Этот метод возвращает числовой код ошибки, полученный в результате последней операции SQLite.

Метод «trace»

Метод «trace» регистрирует обратный вызов, который вызывается при компиляции каждого SQL-запроса. Текст SQL добавляется как одна строка к команде перед вызовом. Это можно использовать (например) для ведения журнала всех SQL-операций, выполняемых приложением.

Метод «trace_v2»

Метод «trace_v2» регистрирует обратный вызов, который вызывается при компиляции каждого SQL-запроса. Синтаксис следующий:

 dbcmd trace_v2 ?callback? ?mask? 

Эта команда вызывает выполнение скрипта «callback», когда происходят определённые условия. Условия определяются аргументом mask, который должен быть списком TCL из нулевого или более следующих ключевых слов:

• statement
• profile
• row
• close

Отслеживания для statement вызывают обратный вызов с двумя аргументами всякий раз, когда выполняется новый SQL-запрос. Первый аргумент — целое число, которое является значением указателя на лежащий в основе объект sqlite3_stmt. Это целое число можно использовать для сопоставления текста SQL-запроса с результатом обратного вызова profile или row. Второй аргумент — нерасшифрованный текст выполняемого SQL-запроса. Под «нерасшифрованным» подразумевается, что подстановки переменных в тексте не расшифрованы до значений переменных. Это отличается от поведения метода «trace», который расшифровывает подстановки переменных.

Отслеживания для profile вызывают обратный вызов с двумя аргументами по окончании каждого SQL-запроса. Первый аргумент — целое число, которое является значением лежащего в основе объекта sqlite3_stmt. Второй аргумент — приблизительное время выполнения запроса в наносекундах. Время выполнения — это наилучшая оценка, доступная в зависимости от возможностей платформы, на которой работает приложение.

Отслеживания для row вызывают обратный вызов с одним аргументом всякий раз, когда доступна новая строка результата от SQL-запроса. Аргумент — целое число, которое является значением указателя на лежащий в основе объект sqlite3_stmt.

Отслеживания для close вызывают обратный вызов с одним аргументом при закрытии подключения к базе данных. Аргумент — целое число, которое является значением указателя на лежащий в основе объект sqlite3, который закрывается.

На подключении к базе данных может быть зарегистрирован только один обратный вызов отслеживания. Каждое использование «trace» или «trace_v2» отменяет все предыдущие обратные вызовы отслеживания.

Метод «backup»

Метод «backup» создаёт резервную копию активной базы данных. Синтаксис команды такой:

 dbcmd backup ?source-database? backup-filename 

Необязательный аргумент source-database указывает, какая база данных в текущем подключении должна быть резервирована. Значение по умолчанию — main (или, другими словами, основной файл базы данных). Для резервного копирования временных таблиц используйте temp. Для резервного копирования вспомогательной базы данных, добавленной к подключению с помощью команды ATTACH, используйте имя этой базы данных, как оно было указано в команде ATTACH.

backup-filename — это имя файла, в который записывается резервная копия. Backup-filename не обязательно должен существовать заранее, но если он существует, он должен быть правильно сформированным файлом базы данных SQLite.

Метод «restore»

Метод «restore» копирует содержимое отдельного файла базы данных в текущее подключение к базе данных, перезаписывая любое существующее содержимое. Синтаксис команды такой:

 dbcmd restore ?target-database? source-filename 

Необязательный аргумент target-database указывает, какая база данных в текущем подключении должна быть перезаписана новым содержимым. Значение по умолчанию — main (или, другими словами, основной файл базы данных). Для перезагрузки временных таблиц используйте temp. Для перезаписи вспомогательной базы данных, добавленной к подключению с помощью команды ATTACH, используйте имя этой базы данных, как оно было указано в команде ATTACH.

source-filename — это имя существующего правильно сформированного файла базы данных SQLite, из которого извлекается содержимое.

Метод «serialize»

Метод «serialize» создаёт BLOB, который представляет собой полную копию лежащей в основе базы данных. Синтаксис такой:

 dbcmd serialize ?database? 

Необязательный аргумент — имя схемы или базы данных, которая должна быть сериализована. Значение по умолчанию — «main».

Эта функция возвращает массив байтов TCL, который представляет собой полное содержимое указанной базы данных. Этот массив байтов можно записать в файл и затем использовать как обычную базу данных SQLite, или отправить по TCP/IP-соединению в другое приложение, или передать методу «deserialize» другого подключения к базе данных.

Этот метод работает только в том случае, если SQLite скомпилирован с флагом -DSQLITE_ENABLE_DESERIALIZE.

Метод «deserialize»

Метод «deserialize» принимает массив байтов TCL, содержащий файл базы данных SQLite, и добавляет его к подключению к базе данных. Синтаксис:

 dbcmd deserialize ?database? value 

Аргумент database (необязательный) указывает, какая присоединённая база данных должна получить результат десериализации. По умолчанию — «main».

Эта команда заставляет SQLite отключиться от предыдущей базы данных и повторно подключиться к базе данных в оперативной памяти с содержимым из value. Если value не является массивом байтов, содержащим правильно определённую базу данных SQLite, последующие команды, скорее всего, вернут ошибки SQLITE_CORRUPT.

Этот метод работает только в том случае, если SQLite скомпилирован с флагом -DSQLITE_ENABLE_DESERIALIZE.

Метод «interrupt»

Метод «interrupt» вызывает интерфейс sqlite3_interrupt(), что приводит к остановке любых ожидающих запросов.

Метод «version»

Метод «profile»

Этот метод используется для профилирования выполнения SQL-запросов, выполняемых приложением. Синтаксис следующий:

 dbcmd profile ?script? 

Если script не пустая строка, этот метод организует выполнение script после выполнения каждого SQL-запроса. Перед вызовом script добавляются два аргумента: текст выполненного SQL-запроса и время, затраченное на выполнение запроса, в наносекундах.

Дескриптор базы данных может иметь только один зарегистрированный скрипт профиля в любой момент времени. Если скрипт уже зарегистрирован при вызове метода профиля, предыдущий скрипт профиля заменяется новым. Если аргумент script пустая строка, любая ранее зарегистрированная обратная связь профиля отменяется, но новый скрипт профиля не регистрируется.

Метод "unlock_notify"

Метод unlock_notify используется для доступа к интерфейсу sqlite3_unlock_notify() ядра библиотеки SQLite в тестовых целях. Использование этого метода приложениями не рекомендуется.

Эта страница была в последний раз изменена 25 марта 2023 г. в 03:02:51 UTC