Интерфейс 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

Если true, новая база данных создается, если ее еще не существует. Если false, то попытка открыть файл базы данных, который ранее не существует, поднимает ошибку. Поведение по умолчанию "true".

-nomutex BOOLEAN

Если true, все mutexes для соединения с базой данных отключены. Это обеспечивает маленькое повышение производительности однопоточных приложений.

-readonly BOOLEAN

Если true, откройте файл базы данных, только для чтения. Если false, база данных открыта для чтения и для записи, если разрешения файловой системы позволяют, или только для чтения, если файловая система отрицает разрешение на запись. Настройка по умолчанию "false". Обратите внимание на то, что, если предыдущий процесс не завершился чисто и оставил горячий журнал, разрешение на запись требуется, чтобы восстановить базу данных после открытия, и база данных не может быть открыта только для чтения.

-uri BOOLEAN

Если true, интерпретируйте аргумент имени файла как имя файла URI. Если false, то аргумент это буквальное имя файла. Значение по умолчанию "false".

-vfs VFSNAME

Используйте альтернативный VFS, названный аргументом.

-fullmutex BOOLEAN

Если true, многократные потоки могут безопасно попытаться использовать базу данных. Если false, такие попытки небезопасны. Значение по умолчанию зависит от того, как расширение собрано.

-nofollow BOOLEAN

Если true и имя базы данных относится к символьной ссылке, оно не будет сопровождаться, чтобы открыть истинный файл базы данных. Если false, по символьным ссылкам перейдут. Умолчание "false".

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

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

"eval"

Самый полезный метод dbcmd это "eval". Он используется, чтобы выполнить SQL на базе данных. Синтаксис метода:

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 есть последовательность и представление "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 injection, если раболтать невнимательно. Но TCL никогда не будет заменять :-переменные независимо от двойных кавычек или фигурных скобок, таким образом, использование :-переменных добавляет дополнительную меру защиты против SQL injection.

"close"

Метод "close" просто закрывает базу данных. У этого есть побочный эффект удаления команды dbcmd Tcl. Вот пример открытия и затем немедленного закрытия базы данных:

sqlite3 db1 ./testdb
db1 close

Если вы удаляете dbcmd непосредственно, это имеет тот же самый эффект как вызов "close". Таким образом, следующий код эквивалентен предыдущему:

sqlite3 db1 ./testdb
rename db1 {}

"transaction"

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

Операционная команда может использоваться, чтобы группировать несколько команд 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 предотвращает использование строк в двойных кавычках. Включение обороны предотвращает прямую запись в теневые таблицы.

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

"copy"

Метод "copy" копирует данные из файла в таблицу. Это возвращает количество успешно обработанных строк из файла. Синтаксис метода копии похож на это:

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

Conflict-algorithm должен быть одним из алгоритмов конфликта SQLite для оператора INSERT: rollback, abort, fail, ignore или replace. conflict-algorithm должен быть определен в нижнем регистре.

Table-name должна уже существовать как таблица. File-name должен существовать, и каждая строка должна содержать то же самое количество колонок, как определено в таблице. Если строка в файле содержит более или менее, чем количество определенных колонок, метод copy откатывает какие-либо вставки и возвращает ошибку.

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

Null-indicator это дополнительная последовательность, которая указывает, что значение столбца пустое. По умолчанию пустая строка. Обратите внимание на то, что разделитель столбцов и пустой индикатор это дополнительные позиционные параметры: если пустой индикатор определяется, аргумент разделителя столбцов должен быть определен и предшествовать аргументу пустого индикатора.

Метод 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 пытается открыть заблокированную базу данных. Единичный целочисленный аргумент передан отзыву, прежде чем это будет выполнено. Аргумент задает количество предшествующих обращений к отзыву для текущего события захвата. Это предназначается, чтобы отзыв сделал некоторую другую полезную работу в течение короткого времени (такого как обслуживание события GUI), чтобы можно было попробовать еще раз. Процедура отзыва должна возвратить "0", если она хочет, чтобы SQLite попробовал еще раз открывать базу данных, и должна возвратить "1", если она хочет, чтобы SQLite оставил текущую операцию.

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

"enable_load_extension"

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

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

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

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

"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

Определите количество аргументов, которое функция SQL принимает. Значение по умолчанию -1 значит любое количество аргументов.

-deterministic

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

-directonly

Этот выбор ограничивает функцию, чтобы быть применимой только прямым SQL-оператором верхнего уровня. Функция не будет доступна для триггеров, обзоров, ограничений CHECK, произведенных колонок или выражений индекса. Этот выбор рекомендуется для всех определенные применением функций SQL и настоятельно рекомендован для любой функции SQL, у которой есть побочные эффекты, или это показывает внутреннее состояние применения.

Предупреждение безопасности:: Без этой опции нападающий мог бы быть в состоянии изменить схему файла базы данных, чтобы включать новую функцию в триггере, обзоре или ограничении CHECK и таким образом обмануть применение в управлении функцией с параметрами нападающего. Следовательно, если новая функция имеет побочные эффекты или показывает внутреннее состояние, и опция -directonly не используется, это является потенциальной уязвимостью системы обеспечения безопасности.

-innocuous

Этот выбор указывает, что функция не имеет никаких побочных эффектов и не пропускает информации, которая не может быть вычислена непосредственно из ее входных параметров. Когда этот выбор определяется, функция может использоваться в триггерах, обзорах, ограничениях CHECK, произведенных колонках и/или выражения индекса, даже если PRAGMA trusted_schema=OFF. Использованию этого выбора препятствуют, если это не действительно необходимо.

-returntype integer|real|text|blob|any

Этот выбор используется, чтобы формировать тип результата, возвращенного функцией. Если этот выбор установлен в "any" (умолчание), SQLite пытается определить тип каждого значения, возвращенного реализацией функции, на основе внутреннего типа Tcl. Или, если это установлено в "text" или "blob", возвращенное значение всегда это текст или blob, соответственно. Если этот выбор установлен в "integer", SQLite пытается привести значение, возвращенное функцией, к целому числу. Если это невозможно без потери данных, он пытается привести его к действительному значению, и наконец отступает к тексту. Если этот выбор установлен в "real", предпринята попытка возвратить действительное значение, отступив к тексту, если это невозможно.

"nullvalue"

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

db1 nullvalue NULL

Метод "nullvalue" полезен, чтобы отличать NULL и значения пустого столбца, поскольку Tcl испытывает недостаток в представлении NULL. Представление по умолчанию для NULL это пустая строка.

"onecolumn"

Метод "onecolumn" действует аналогично "eval". Различие в том, что "onecolumn" единственный элемент, который является первой колонкой первой строки результата запроса.

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

"changes"

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

"total_changes"

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

"authorizer"

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

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

"bind_fallback"

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

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

Метод "bind_fallback" имеет единственный дополнительный аргумент. Если аргумент пустая строка, то bind_fallback отменяется, и поведение по умолчанию восстановлено. Если аргумент это непустая строка, то аргумент это команда TCL (обычно название proc), чтобы вызвать каждый раз, когда замечен параметр 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-команда, чтобы вызвать. Урегулирование отзыва прогресса к пустой строке отключает его.

Отзыв прогресса может использоваться, чтобы показать статус долгого запроса или обработать события 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 пытается сделать обратную перемотку. Аргумент скрипта передан без изменения.

"status"

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

Метод status это в основном обертка для sqlite3_stmt_status().

"update_hook"

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

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

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

"preupdate"

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

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

dbcmd  preupdate  hook  ?SCRIPT?

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

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

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

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

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

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

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

"wal_hook"

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

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

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

Этот метод должен возвратить целочисленное значение, которое эквивалентно коду ошибки 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. Канал открыт, используя основной интерфейс sqlite3_blob_open(). Закройте канал, используя команду TCL close.

"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, укажите temp. Чтобы сделать копию вспомогательной базы данных, добавленной к связи, используя команду ATTACH, используйте название той базы данных, как это было назначено в команде ATTACH.

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

"restore"

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

dbcmd  restore  ?target-database?  source-filename

Опциональный параметр target-database говорит, какая база данных в текущей связи должна быть переписана с новым содержанием. Значение по умолчанию main (другими словами, основной файл базы данных). Чтобы повторно наполнить TEMP, укажите 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"

Метод "version" вернет текущую версию библиотеки. Например, "3.23.0".

"profile"

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

dbcmd  profile  ?script?

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

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

"unlock_notify"

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