Интерфейс Tcl для библиотеки SQLite
Содержание
1. Введение
Библиотека SQLite разработана так, чтобы ее было очень легко использовать из скрипта Tcl или Tcl/Tk. SQLite изначально создавалась как расширение Tcl, а основной набор тестов SQLite написан на Tcl и использует расширение SQLite для Tcl, описанное в этом документе. SQLite можно использовать с любым языком программирования, но ее связи с Tcl особенно тесны.
В этом документе представлен обзор программного интерфейса Tcl для SQLite. Советы по обработке JSON в Tcl см. в этом документе.
2. Сборка и установка расширения SQLite для Tcl
Начиная с версии SQLite 3.48.0 (2025-01-14), предпочтительный способ сборки расширения SQLite для Tcl — использовать каноническое дерево исходного кода SQLite и запустить makefile с целью "tclextension-install". Если у вас установлено несколько версий Tcl, можно указать конкретную установку Tcl, для которой нужно установить расширение SQLite, используя параметр командной строки --with-tclsh=PATH в Unix. Например, если у вас есть пользовательская установка Tcl 9.0 в $HOME/tcl, установить SQLite для этой установки можно следующей командой:
./configure --with-tclsh=$HOME/tcl/bin/tclsh9.0 make tclextension-install
В Windows используйте переменную среды TCLDIR, чтобы указать каталог верхнего уровня вашей установки Tcl. И снова, если у вас есть пользовательская установка Tcl в %HOME%/tcl, команда будет выглядеть так:
nmake /f Makefile.msc TCLDIR=%HOME%\tcl tclextension-install
В обоих случаях могут быть полезны дополнительные цели makefile:
- tclextension → Собрать расширение SQLite, но не перемещать файлы в каталог установки.
- tclextension-list → Показать все расширения SQLite, доступные интерпретатору Tcl, указанному в ./configure или с помощью TCLDIR.
- tclextension-uninstall → Удалить расширение SQLite.
- tclextension-verify → Проверить, что установленное расширение SQLite использует ту же версию SQLite, что и дерево исходного кода, из которого запущена команда.
Установив расширение SQLite для своего интерпретатора Tcl одним из описанных выше способов, запустите его следующей командой из любой оболочки tclsh или wish:
package require sqlite3
2.1. Как работает процесс сборки
Адаптер SQLite для Tcl реализован в файле исходного кода src/tclsqlite.c. Этот файл добавляется к амальгамации ("sqlite3.c"), в которой реализована SQLite, чтобы создать новый файл исходного кода "tclsqlite3.c". Скомпилируйте tclsqlite3.c в динамическую библиотеку, чтобы получить загружаемое во время выполнения расширение Tcl, реализующее SQLite. Цель make "tclextension-install" выполняет эту работу, затем создает подходящий скрипт pkgIndex.tcl и перемещает динамическую библиотеку и скрипт pkgIndex.tcl в соответствующий каталог установки.
Для сборки tclsqlite3.c предусмотрена цель make:
make tclsqlite3.c
Файл tclsqlite3.c необязательно компилировать в динамическую библиотеку. Библиотеку tclsqlite3.c можно статически скомпоновать с приложением, которое также статически компонуется с библиотекой Tcl, чтобы создать автономный исполняемый файл. Именно так работает исполняемый файл "testfixture", используемый для тестирования SQLite.
2.2. Дополнительная документация по сборке
Пошаговые инструкции по тестированию расширения SQLite для Tcl см. в документе src/tcl-extension-testing.md в исходном коде SQLite. В этом документе также могут быть полезные подсказки по сборке расширения SQLite для Tcl, если у вас возникнут трудности.
3. Интерфейс Tcl для библиотеки SQLite
Расширение SQLite для Tcl состоит из одной новой команды Tcl с именем sqlite3. Поскольку эта команда всего одна, интерфейс не помещен в отдельное пространство имен.
Команда sqlite3 обычно используется для открытия или создания базы данных следующим образом:
sqlite3 dbcmd ?database-name? ?options?
Чтобы получить только информацию, команде sqlite3 можно передать ровно один аргумент: "-version", "-sourceid" или "-has-codec". Команда вернет соответствующие данные и не произведет других действий.
При наличии других аргументов команда sqlite3 открывает базу данных, имя которой указано во втором аргументе, не являющемся параметром, или с именем "", если такого аргумента нет. Если открытие прошло успешно, создается новая команда Tcl с именем, заданным первым аргументом, и возвращается "". (Этот подход похож на создание виджетов в Tk.) Если открыть базу данных не удалось, возникает ошибка, команда Tcl не создается, а возвращается строка сообщения об ошибке.
Если база данных еще не существует, по умолчанию она создается автоматически (это поведение можно изменить с помощью параметра "-create false").
Обычно имя базы данных — это имя файла на диске, в котором хранится база данных. Если в качестве имени базы данных указано специальное имя ":memory:", новая база данных создается в памяти. Если имя базы данных — пустая строка, база данных создается в пустом файле, который автоматически удаляется при закрытии подключения к базе данных. Можно использовать имена файлов URI, если в команде sqlite3 указан параметр "-uri yes".
Команда 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. На данный момент определен 41 метод.
Далее будет объяснено использование каждого из этих методов, хотя и не в приведенном выше порядке.
3.1. Метод eval
Самый полезный метод dbcmd — "eval". Метод eval используется для выполнения SQL в базе данных. Синтаксис метода eval выглядит так:
dbcmd eval ?-withoutnulls? ?-asdict? ? sql var-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!
Результаты запроса также можно обрабатывать построчно, указав имя массива или, с флагом -asdict, переменной типа dict, а также скрипт после SQL-кода. Для каждой строки результата запроса значения всех столбцов будут помещены в переменную массива или dict, после чего будет выполнен скрипт. Например:
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!
Для каждого столбца в строке результата имя этого столбца используется как индекс массива, а его значение сохраняется в соответствующем элементе массива. (Внимание: если в наборе результатов запроса два или более столбца имеют одинаковое имя, последний столбец с таким именем перезапишет предыдущие значения, и обратиться к более ранним столбцам с этим именем будет невозможно.) Специальный индекс массива * используется для хранения списка имен столбцов в том порядке, в котором они идут.
Обычно результаты SQL со значением NULL сохраняются в массиве с использованием настройки 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 есть представления и в виде строки, и в виде "bytearray", TCL вставляет ее значение как строку. Если у нее есть только представление "bytearray", значение вставляется как 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-кода.
3.2. Метод close
Как следует из названия, метод "close" для базы данных SQLite просто закрывает базу данных. Побочным эффектом является удаление команды Tcl dbcmd. Вот пример открытия базы данных с ее немедленным закрытием:
sqlite3 db1 ./testdb db1 close
Если удалить саму dbcmd, эффект будет таким же, как при вызове метода "close". Таким образом, следующий код эквивалентен предыдущему:
sqlite3 db1 ./testdb
rename db1 {} 3.3. Метод transaction
Метод "transaction" используется для выполнения скрипта TCL внутри транзакции базы данных SQLite. Транзакция фиксируется после завершения скрипта или откатывается, если скрипт завершается с ошибкой. Если транзакция выполняется внутри другой транзакции (даже той, которая запущена вручную с помощью BEGIN), метод ничего не делает.
Команду transaction можно использовать для безопасной группировки нескольких команд SQLite. Разумеется, транзакции всегда можно запускать вручную с помощью BEGIN. Но если произойдет ошибка и команды COMMIT или ROLLBACK не будут выполнены, база данных останется заблокированной на неопределенное время. Кроме того, BEGIN нельзя вкладывать, поэтому перед началом новой транзакции необходимо убедиться, что другие транзакции не активны. Метод "transaction" автоматически берет все эти детали на себя.
Синтаксис выглядит так:
dbcmd transaction ?transaction-type? script
Значение transaction-type может быть одним из следующих: deferred, exclusive или immediate. По умолчанию используется deferred.
3.4. Метод cache
Метод "eval", описанный выше, хранит кэш подготовленных операторов для недавно выполненных SQL-команд. Метод "cache" используется для управления этим кэшем. Первая форма команды выглядит так:
dbcmd cache size N
Устанавливает максимальное число операторов, которые могут храниться в кэше. Верхний предел — 100. По умолчанию используется значение 10. Если задать размер кэша равным 0, кэширование не выполняется.
Вторая форма команды выглядит так:
dbcmd cache flush
Метод очистки кэша завершает все подготовленные операторы, которые в данный момент находятся в кэше.
3.5. Метод complete
Метод "complete" принимает строку, предположительно содержащую SQL, в качестве единственного аргумента. Он возвращает TRUE, если строка содержит законченный SQL-оператор, и FALSE, если ввод нужно продолжить.
Метод "complete" полезен при создании интерактивных приложений: с его помощью можно определить, закончил ли пользователь вводить строку SQL-кода. По сути, это просто интерфейс к функции C sqlite3_complete().
3.6. Метод 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
3.7. Метод copy
Метод "copy" копирует данные из файла в таблицу. Он возвращает число строк файла, успешно обработанных методом. Синтаксис метода copy выглядит так:
dbcmd copy conflict-algorithm table-name file-name ?column-separator? ?null-indicator?
Значение conflict-algorithm должно быть одним из алгоритмов разрешения конфликтов SQLite для оператора INSERT: rollback, abort, fail, ignore или replace. Дополнительную информацию см. в разделе языка SQLite, посвященном ON CONFLICT. Значение conflict-algorithm необходимо указывать строчными буквами.
Таблица table-name уже должна существовать. Файл file-name должен существовать, и каждая строка должна содержать столько же столбцов, сколько определено в таблице. Если строка файла содержит больше или меньше столбцов, метод copy откатывает все вставки и возвращает ошибку.
Column-separator — необязательная строка-разделитель столбцов. По умолчанию используется символ табуляции ASCII \t.
Null-indicator — необязательная строка, обозначающая значение NULL в столбце. По умолчанию используется пустая строка. Обратите внимание: column-separator и null-indicator — необязательные позиционные аргументы. Если указан null-indicator, необходимо указать и аргумент column-separator, причем перед ним.
Метод copy реализует функциональность, аналогичную команде оболочки SQLite .import.
3.8. Метод timeout
Метод "timeout" управляет временем ожидания снятия блокировок библиотекой SQLite, прежде чем она откажется от выполнения транзакции базы данных. По умолчанию время ожидания составляет 0 миллисекунд. (Иными словами, по умолчанию ожидание отсутствует.)
База данных SQLite допускает одновременную работу нескольких читателей или одного писателя, но не то и другое одновременно. Если какой-либо процесс записывает данные в базу, другим процессам запрещено читать и записывать данные. Если какой-либо процесс читает базу данных, другим процессам разрешено читать, но не записывать данные. Вся база данных использует одну общую блокировку.
Когда SQLite пытается открыть базу данных и обнаруживает, что она заблокирована, она может ненадолго приостановить работу и повторить попытку открыть файл. Этот процесс повторяется, пока не истечет время ожидания запроса и SQLite не вернет ошибку. Время ожидания можно настроить. По умолчанию оно равно 0, поэтому, если база данных заблокирована, SQL-оператор немедленно завершается ошибкой. Однако с помощью метода "timeout" можно установить положительное значение времени ожидания. Например:
db1 timeout 2000
Аргумент метода timeout — это максимальное число миллисекунд ожидания снятия блокировки. Таким образом, в приведенном выше примере максимальная задержка составит 2 секунды.
3.9. Метод busy
Метод "busy", как и "timeout", применяется только тогда, когда база данных заблокирована. Однако метод "busy" предоставляет программисту гораздо больше возможностей для управления дальнейшими действиями. Метод "busy" задает процедуру обратного вызова Tcl, которая вызывается каждый раз, когда SQLite пытается открыть заблокированную базу данных. Перед вызовом к обратному вызову добавляется один целочисленный аргумент. Этот аргумент обозначает число предыдущих вызовов обратного вызова busy для текущего события блокировки. Предполагается, что обратный вызов некоторое время будет выполнять другую полезную работу (например, обрабатывать события графического интерфейса), а затем вернется, чтобы повторить попытку получить блокировку. Процедура обратного вызова должна возвращать "0", если SQLite следует повторить попытку открыть базу данных, и "1", если SQLite следует прервать текущую операцию.
Если вызвать метод busy без аргументов, он вернет имя процедуры обратного вызова, заданной последним вызовом метода busy. Если процедура обратного вызова не задана, возвращается пустая строка.
3.10. Метод enable_load_extension
Механизм загрузки расширений SQLite (доступный через SQL-функцию load_extension()) по умолчанию отключен. Это мера предосторожности. Если приложению требуется использовать функцию load_extension(), сначала необходимо включить эту возможность с помощью данного метода.
Метод принимает один логический аргумент, который включает или отключает загрузку расширений.
Для максимальной безопасности не используйте этот метод без необходимости и выполните PRAGMA trusted_schema=OFF или вызовите метод "db config trusted_schema 0" до его вызова.
Этот метод соответствует интерфейсу C/C++ sqlite3_enable_load_extension().
3.11. Метод 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
} 3.12. Метод last_insert_rowid
Метод "last_insert_rowid" возвращает целое число — ROWID последней вставленной строки базы данных.
3.13. Метод 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 statements. 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. As of version 3.51, a break propagating from an SQL function will be interpreted as an SQL NULL, as distinct from an empty string.
3.14. Метод nullvalue
Метод "nullvalue" изменяет представление значения NULL, возвращаемого методом "eval".
db1 nullvalue NULL
Метод "nullvalue" полезен для различения значений NULL и пустых значений столбцов, поскольку в Tcl нет представления NULL. По умолчанию значение NULL представляется пустой строкой.
3.15. Метод onecolumn
Метод "onecolumn", как и "eval", выполняет SQL-запрос, переданный в качестве аргумента. Отличие состоит в том, что "onecolumn" возвращает один элемент — значение первого столбца первой строки результата запроса.
Это вспомогательный метод. Он избавляет пользователя от необходимости выполнять команду "[lindex ... 0]" над результатами "eval", чтобы извлечь значение одного столбца.
Поскольку имена методов можно сокращать до любого уникального префикса, обычно этот метод записывают как "one", а не полным именем "onecolumn".
3.16. Метод changes
Метод "changes" возвращает целое число — количество строк базы данных, вставленных, удаленных и/или измененных последним вызовом метода "eval".
3.17. Метод total_changes
Метод "total_changes" возвращает целое число — количество строк базы данных, вставленных, удаленных и/или измененных с момента первого открытия текущего подключения к базе данных.
3.18. Метод authorizer
Если аргументом является пустая строка, авторизация отключается. Если аргумент не указан, возвращается текущий авторизатор.
3.19. Метод bind_fallback
Метод "bind_fallback" позволяет приложению управлять обработкой связывания параметров, если ни одна переменная TCL не соответствует имени параметра.
Когда метод eval встречает в SQL-операторе именованный параметр SQL, например "$abc", ":def" или "@ghi", он пытается найти переменную TCL с таким же именем и связать ее значение с параметром SQL. Если такой переменной TCL нет, по умолчанию параметру присваивается значение SQL NULL. Однако, если задана процедура bind_fallback, она вызывается с именем параметра 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
3.20. Метод progress
Этот метод регистрирует обратный вызов, который периодически вызывается во время обработки запроса. Метод принимает два аргумента: число кодов виртуальной машины SQLite между вызовами и команду TCL для вызова. Если для обратного вызова progress задать пустую строку, он отключается.
Обратный вызов progress можно использовать для отображения состояния длительного запроса или обработки событий графического интерфейса во время выполнения такого запроса.
3.21. Метод collate
Этот метод регистрирует новые последовательности сортировки текста. Он принимает два аргумента: имя последовательности сортировки и имя процедуры TCL, реализующей функцию сравнения для этой последовательности.
Например, следующий код реализует последовательность сортировки под названием "NOCASE", которая сортирует текст без учета регистра:
proc nocase_compare {a b} {
return [string compare [string tolower $a] [string tolower $b]]
}
db collate NOCASE nocase_compare
3.22. Метод collation_needed
Этот метод регистрирует процедуру обратного вызова, которая вызывается, когда ядру SQLite требуется определенная последовательность сортировки, но она не зарегистрирована. Обратный вызов может зарегистрировать эту последовательность сортировки. Обратный вызов вызывается с одним параметром — именем требуемой последовательности сортировки.
3.23. Метод commit_hook
Этот метод регистрирует процедуру обратного вызова, которая вызывается непосредственно перед тем, как SQLite попытается зафиксировать изменения в базе данных. Если обратный вызов вызывает исключение или возвращает ненулевой результат, транзакция откатывается, а не фиксируется.
3.24. Метод rollback_hook
Этот метод регистрирует процедуру обратного вызова, которая вызывается непосредственно перед тем, как SQLite попытается выполнить откат. Аргумент script выполняется без изменений.
3.25. Метод status
Этот метод возвращает сведения о состоянии последнего выполненного оператора SQL. Метод status принимает один аргумент, которым должно быть либо "steps", либо "sorts". Если аргумент — "steps", метод возвращает число шагов полного сканирования таблицы, выполненных предыдущим оператором SQL. Если аргумент — "sorts", метод возвращает число операций сортировки. Эти сведения можно использовать для обнаружения запросов, в которых не используются индексы для ускорения поиска или сортировки.
Метод status по сути является оберткой над интерфейсом языка C sqlite3_stmt_status().
3.26. Метод update_hook
Этот метод регистрирует процедуру обратного вызова, которая вызывается сразу после изменения каждой строки оператором UPDATE, INSERT или DELETE. Перед вызовом к обратному вызову добавляются четыре аргумента:
- Ключевое слово "INSERT", "UPDATE" или "DELETE" в зависимости от ситуации
- Имя изменяемой базы данных
- Изменяемая таблица
- rowid изменяемой строки таблицы
Обратный вызов не должен выполнять никаких действий, изменяющих соединение с базой данных, вызвавшее хук обновления, например запускать запросы.
3.27. Метод preupdate
Этот метод либо регистрирует процедуру обратного вызова, которая вызывается непосредственно перед изменением каждой строки оператором UPDATE, INSERT или DELETE, либо выполняет определенные операции, связанные с предстоящим обновлением.
Для регистрации или удаления обратного вызова preupdate используйте следующий синтаксис:
dbcmd preupdate hook ?SCRIPT?Если зарегистрирован обратный вызов preupdate, то перед каждым изменением строки он вызывается со следующими аргументами:
- Ключевое слово "INSERT", "UPDATE" или "DELETE" в зависимости от ситуации
- Имя изменяемой базы данных
- Изменяемая таблица
- Исходный rowid изменяемой строки таблицы
- Новый rowid (если есть) изменяемой строки таблицы
Во время выполнения обратного вызова, и только в это время, можно выполнять следующие операции preupdate с помощью указанного синтаксиса:
dbcmd preupdate count dbcmd preupdate depth dbcmd preupdate new INDEX dbcmd preupdate old INDEX
Подметод count возвращает число столбцов во вставляемой, обновляемой или удаляемой строке.
Подметод depth возвращает глубину вложенности обновления. Для непосредственной операции вставки, обновления или удаления это значение равно 0; для вставки, обновления или удаления, вызванных триггерами верхнего уровня, — 1; для изменений, вызванных триггерами, запущенными другими триггерами, — больше.
Подметоды old и new возвращают соответственно выбранное исходное или измененное значение столбца обновляемой строки.
Обратите внимание: для доступности метода preupdate интерфейс Tcl (и базовая библиотека SQLite) должны быть собраны с определенным символом препроцессора SQLITE_ENABLE_PREUPDATE_HOOK.
3.28. Метод wal_hook
Этот метод регистрирует процедуру обратного вызова, которая вызывается после фиксации транзакции, когда база данных находится в режиме WAL. Перед вызовом к команде обратного вызова добавляются два аргумента:
- Имя базы данных, в которой была зафиксирована транзакция
- Число записей в файле журнала упреждающей записи (WAL) этой базы данных
Этот метод может принять решение выполнить контрольную точку самостоятельно или в качестве последующего обратного вызова при простое. Обратите внимание, что SQLite допускает только один хук WAL. По умолчанию этот единственный хук WAL используется для автоматического создания контрольных точек. Если вы зададите явный хук WAL, он должен обеспечивать создание контрольных точек, поскольку механизм автоматического создания контрольных точек будет отключен.
Метод должен возвращать целочисленное значение, соответствующее коду ошибки SQLite (обычно 0 для SQLITE_OK в случае успеха или 1 для SQLITE_ERROR при возникновении ошибки). Как и в sqlite3_wal_hook(), поведение при возврате целого числа, не соответствующего коду ошибки SQLite, не определено. Если возвращаемое скриптом значение нельзя интерпретировать как целое число или если скрипт вызывает исключение Tcl, ошибка не возвращается в SQLite, но возникает фоновая ошибка Tcl.
3.29. Метод incrblob
Этот метод открывает канал TCL, который можно использовать для чтения или записи существующего BLOB-объекта в базе данных. Синтаксис выглядит следующим образом:
dbcmd incrblob ?-readonly? ?DB? TABLE COLUMN ROWID
Команда возвращает новый канал TCL для чтения или записи BLOB-объекта. Канал открывается с помощью базового интерфейса языка C sqlite3_blob_open(). Закройте канал командой close в TCL.
3.30. Метод errorcode
Этот метод возвращает числовой код ошибки, возникшей при последней операции SQLite.
3.31. Метод trace
Метод "trace" регистрирует обратный вызов, который вызывается при компиляции каждого оператора SQL. Перед вызовом к команде добавляется текст SQL в виде одной строки. Это можно использовать, например, для ведения журнала всех операций SQL, выполняемых приложением.
3.32. Метод 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" отменяет все ранее зарегистрированные обратные вызовы трассировки.
3.33. Метод backup
Метод "backup" создает резервную копию работающей базы данных. Синтаксис команды выглядит следующим образом:
dbcmd backup ?source-database? backup-filename
Необязательный аргумент source-database указывает, какую базу данных в текущем соединении следует скопировать. Значение по умолчанию — main (то есть основной файл базы данных). Чтобы скопировать таблицы TEMP, используйте temp. Чтобы скопировать вспомогательную базу данных, добавленную к соединению с помощью команды ATTACH, используйте имя этой базы данных, присвоенное ей в команде ATTACH.
backup-filename — имя файла, в который записывается резервная копия. Файл backup-filename может не существовать заранее, но если он существует, то должен быть корректной базой данных SQLite.
3.34. Метод restore
Метод "restore" копирует содержимое отдельного файла базы данных в текущее соединение с базой данных, заменяя все имевшееся ранее содержимое. Синтаксис команды выглядит следующим образом:
dbcmd restore ?target-database? source-filename
Необязательный аргумент target-database указывает, какую базу данных в текущем соединении следует перезаписать новым содержимым. Значение по умолчанию — main (то есть основной файл базы данных). Чтобы заново заполнить таблицы TEMP, используйте temp. Чтобы перезаписать вспомогательную базу данных, добавленную к соединению с помощью команды ATTACH, используйте имя этой базы данных, присвоенное ей в команде ATTACH.
source-filename — имя существующего корректного файла базы данных SQLite, из которого извлекается содержимое.
3.35. Метод serialize
Метод "serialize" создает BLOB-объект, представляющий собой полную копию базовой базы данных. Синтаксис выглядит следующим образом:
dbcmd serialize ?database?
Необязательный аргумент — имя схемы или базы данных, которую нужно сериализовать. Значение по умолчанию — "main".
Эта процедура возвращает массив байтов TCL, содержащий полное содержимое указанной базы данных. Этот массив байтов можно записать в файл и затем использовать как обычную базу данных SQLite, отправить по TCP/IP-соединению другому приложению или передать методу "deserialize" другого соединения с базой данных.
3.36. Метод deserialize
Метод "deserialize" принимает массив байтов TCL, содержащий файл базы данных SQLite, и добавляет его в соединение с базой данных. Синтаксис:
dbcmd deserialize ?database? value
Необязательный аргумент database указывает, к какой подключенной базе данных следует применить десериализацию. Значение по умолчанию — "main".
Эта команда отключает SQLite от предыдущей базы данных и подключает ее к базе данных в памяти, содержащей данные из value. Если value не является массивом байтов с корректной базой данных SQLite, последующие команды, скорее всего, будут возвращать ошибки SQLITE_CORRUPT.
3.37. Метод interrupt
Метод "interrupt" вызывает интерфейс sqlite3_interrupt(), останавливая все ожидающие запросы.
3.38. Метод version
Возвращает текущую версию библиотеки. Например, "3.23.0".
3.39. Метод profile
Этот метод используется для профилирования выполнения операторов SQL, запускаемых приложением. Синтаксис следующий:
dbcmd profile ?script?
Если script не является пустой строкой, этот метод обеспечивает выполнение script после выполнения каждого оператора SQL. Перед вызовом к script добавляются два аргумента: текст выполненного оператора SQL и время, затраченное на его выполнение, в наносекундах.
Для одного дескриптора базы данных можно зарегистрировать только один скрипт профилирования. Если на момент вызова метода profile уже зарегистрирован скрипт, он заменяется новым. Если аргумент script — пустая строка, все ранее зарегистрированные обратные вызовы профилирования отменяются, а новый скрипт профилирования не регистрируется.
3.40. Метод unlock_notify
Метод unlock_notify используется для доступа к интерфейсу sqlite3_unlock_notify() основной библиотеки SQLite в целях тестирования. Приложениям не рекомендуется использовать этот метод.
3.41. Метод format
Метод format появился в SQLite версии 3.52.0 (2026-03-06). Метод format предоставляет интерфейс к подсистеме форматирования результатов запросов (QRF).
dbcmd format ?options? SQL
Метод format выполняет переданный в качестве аргумента SQL-запрос, форматирует результат в соответствии с параметрами и возвращает отформатированный результат в виде строки. QRF — сложная подсистема, поэтому у нее много параметров. Каждый параметр соответствует полю объекта sqlite3_qrf_spec. Ниже перечислены имена параметров в TCL, допустимые аргументы и поля sqlite3_qrf_spec, которыми управляют эти параметры. Описание назначения каждого параметра см. в документации QRF.
Для параметров, которые не указаны, по умолчанию используются значения "auto", 0 или пустая строка, в зависимости от ситуации.
-style STYLE STYLE can be one of "auto", "box", "column", "count", "csv", "eqp", "explain", "html", "insert", "json", "jobject", "line", "list", "markdown", "off", "quote", "stats", "statsest", "statsvm", or "table". This option determines the eStyle value of sqlite3_qrf_spec. -esc ESC ESC can be one of "auto", "off", "ascii", or "symbol". This option determines the eEsc value of sqlite3_qrf_spec. -text ENCODING ENCODING can be one of "auto", "csv", "html", "json", "plain", "relaxed", "sql", or "tcl". This option determines the eText value of sqlite3_qrf_spec. -title ENCODING ENCODING can be one of "on", "off", "auto", "csv", "html", "json", "plain", "relaxed", "sql", or "tcl". This option determines the eTitle and bTitles values of sqlite3_qrf_spec. -blob ENCODING ENCODING can be one of "auto", "hex", "json", "tcl", "text", or "size". This option determines the eBlob value of sqlite3_qrf_spec. -border auto|off|on This option controls whether or not the outer border is drawn around the entire result when the --style is "box" or "table". The default is that the border is drawn. But if this setting is "off", then the border is omitted. This option controls the bBorder value of sqlite3_qrf_spec. -wordwrap auto|off|on This option controls the bWordWrap value of sqlite3_qrf_spec. -textjsonb auto|off|on This option controls the bTextJsonb value of sqlite3_qrf_spec. -splitcolumn auto|off|on This option controls the bSplitColumn value of sqlite3_qrf_spec. -defaultalign ALIGNMENT ALIGNMENT can be one of "auto", "bottom", "c", "center", "e", "left", "middle", "n", "ne", "nw", "right", "s", "se", "sw", "top", or "w". This option controls the eDfltAlign value of sqlite3_qrf_spec. -titlealign ALIGNMENT ALIGNMENT can be one of "auto", "bottom", "c", "center", "e", "left", "middle", "n", "ne", "nw", "right", "s", "se", "sw", "top", or "w". This option controls the eTitleAlign value of sqlite3_qrf_spec. -align ALIGNMENT-LIST ALIGNMENT-LIST is a TCL list containing zero or more tokens where each token is one of: "auto", "bottom", "c", "center", "e", "left", "middle", "n", "ne", "nw", "right", "s", "se", "sw", "top", or "w". This option determines the nAlign and aAlign values of sqlite3_qrf_spec. -wrap INTEGER This option determines the nWrap values of sqlite3_qrf_spec. -screenwidth INTEGER This option determines the nScreenWidth values of sqlite3_qrf_spec. -linelimit INTEGER This option determines the nLineLimit values of sqlite3_qrf_spec. -charlimit INTEGER This option determines the nCharLimit values of sqlite3_qrf_spec. -titlelimit INTEGER This option determines the nTitleLimit values of sqlite3_qrf_spec. -multiinsert INTEGER This option determines the nMultiInsert values of sqlite3_qrf_spec. -widths INTEGER-LIST INTEGER-LIST is a TCL list of integer. This option determines the nWidth and aWidth values of sqlite3_qrf_spec. -columnsep STRING/i> This option set the zColumnSep value of sqlite3_qrf_spec. -rowsep STRING/i> This option set the zRowSep value of sqlite3_qrf_spec. -tablename STRING/i> This option set the zTableName value of sqlite3_qrf_spec. -null STRING/i> This option set the zNull value of sqlite3_qrf_spec.
Последнее обновление этой страницы: 2026-03-21 20:08:30Z
SQLite is in the Public Domain.
https://sqlite.org/tclsqlite.html
