tdbc_connection

package require tdbc 1.0
package require tdbc::версия драйвера

tdbc::драйвер::connection create db ?-параметр значение...?

db configure ?-параметр значение...?
db закрыть
db foreignkeys ?-основная таблица tableName? ?-внешняя таблица tableName?
db preparesql-код
db preparecallвызов
db primarykeysимя_таблицы
db statements
db resultsets
db tables ?шаблон?
db columnsтаблица ?шаблон?
db begintransaction
db commit
db rollback
db transactionскрипт
db allrows ?-as списки|словари? ?-columnsvariable имя? ?--? sql-код ?словарь?
db foreach ?-as списки|словари? ?-columnsvariable имя? ?--? имя_переменной sql-код ?словарь? скрипт

Описание

Каждый драйвер базы данных для TDBC (Tcl DataBase Connectivity) реализует объект подключения, представляющий собой подключение к базе данных. Как правило, этот объект создается командой tdbc::драйвер::connection create. Эта команда принимает имя Tcl-команды, которая будет представлять подключение, и возможный набор параметров (см. НАСТРОЕЧНЫЕ ПАРАМЕТРЫ). Она устанавливает подключение к базе данных и возвращает имя только что созданной Tcl-команды.

Команда объекта configure для подключения к базе данных, если ей не передано никаких аргументов, возвращает список, содержащий чередующиеся ключевые слова и значения, представляющие текущую конфигурацию подключения. Если ей передано единственное значение -параметр, она возвращает настроенное значение заданного параметра. В противном случае ей необходимо передать чётное количество аргументов, чередующихся параметрами и значениями. Указанные параметры получают указанные значения, и ничего не возвращается.

Команда объекта закрыть для подключения к базе данных закрывает подключение. Все активные запросы и наборы результатов подключения закрываются. Любая непроведенная транзакция откатывается. Команда объекта удаляется.

Команда объекта prepare для подключения к базе данных подготавливает SQL-запрос к выполнению. Аргумент sql-код должен содержать один SQL-запрос, который будет выполнен. Можно включать связанные переменные. Возвращаемое значение — это новая Tcl-команда, которая представляет запрос. См. tdbc::statement для более подробного обсуждения SQL, принимаемого командой объекта prepare, и интерфейса, принимаемого запросом.

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

?resultvar =? procname(?arg ?, arg...?)

Возвращаемое значение — это новая Tcl-команда, представляющая запрос. См. tdbc::statement для интерфейса, принимаемого запросом.

Команда объекта statements возвращает список запросов, которые были созданы командами prepare и preparecall для данного подключения и ещё не были закрыты.

Команда объекта resultsets возвращает список наборов результатов, которые были получены путём выполнения запросов, подготовленных с использованием данного подключения, и которые ещё не были закрыты.

Команда объекта tables позволяет программе запросить подключение для получения имён таблиц, которые существуют в базе данных. Необязательный параметр шаблон — это шаблон для соответствия имени таблицы. Он может содержать SQL-символы подстановки «%» и

Команда объекта columns позволяет программе запросить подключение для получения имён столбцов, которые существуют в заданной таблице. Необязательный параметр шаблон — это шаблон для соответствия имени столбца. Он может содержать SQL-символы подстановки «%» и

Команда объекта foreignkeys позволяет программе запрашивать у подключения связи внешнего ключа, которые применяются к определённой таблице. Связи могут быть ограничены ключами, которые появляются в определённой таблице (-foreign tableName), ключами, которые ссылаются на определённую таблицу (-primary tableName), или обоими. Должен быть указан хотя бы один из параметров -primary и -foreign, хотя некоторые драйверы перечислят все внешние ключи в текущем каталоге, если оба параметра опущены. Результатом команды объекта foreignkeys является список словарей, по одному элементу списка на ключ (в формате, аналогичном списку, возвращаемому $connection allrows -as dicts). Ключи словаря могут включать по меньшей мере следующее. Значения, которые являются NULL или не имеют смысла в данной базе данных, опушены.

foreignConstraintCatalog: Каталог, в котором появляется ограничение внешнего ключа.
foreignConstraintSchema: Схема, в которой появляется ограничение внешнего ключа.
foreignConstraintName: Имя ограничения внешнего ключа.
primaryConstraintCatalog: Каталог, содержащий ограничение первичного ключа (или ограничения уникального ключа) на столбец, к которому относится внешний ключ.
primaryConstraintSchema: Схема, содержащая ограничение первичного ключа (или ограничения уникального ключа) на столбец, к которому относится внешний ключ.
primaryConstraintName: Имя ограничения первичного ключа (или ограничения уникального ключа) на столбец, к которому относится внешний ключ.
updateAction: Действие, которое необходимо выполнить, когда оператор UPDATE делает ограничение недействительным. Значение будет CASCADE, SET DEFAULT, SET NULL, RESTRICT или NO ACTION.
deleteAction: Действие, которое необходимо выполнить, когда оператор DELETE делает ограничение недействительным. Значение будет CASCADE, SET DEFAULT, SET NULL, RESTRICT или NO ACTION.
primaryCatalog: Имя каталога, в котором появляется основная таблица (таблица, к которой относится внешний ключ).
primarySchema: Имя схемы, в которой появляется основная таблица (таблица, к которой относится внешний ключ).

primaryTable: Имя таблицы основной таблицы (таблицы, к которой относится внешний ключ).
primaryColumn: Имя столбца, к которому относится внешний ключ.
foreignCatalog: Имя каталога, в котором находится таблица, содержащая внешний ключ.
foreignSchema: Имя схемы, в которой находится таблица, содержащая внешний ключ.
foreignTable: Имя таблицы, содержащей внешний ключ.
foreignColumn: Имя столбца, присутствующего во внешнем ключе.
ordinalPosition: Позиция столбца во внешнем ключе, если ключ составной.

Команда объекта begintransaction для подключения к базе данных начинает транзакцию в базе данных. Если базовая база данных не поддерживает атомарные, согласованные, изолированные и долговечные транзакции, команда объекта begintransaction возвращает ошибку, сообщая об этом. Аналогично, если несколько команд begintransaction выполняются без промежуточной команды commit или rollback, возвращается ошибка, если базовая база данных не поддерживает вложенные транзакции.

Команда объекта commit для подключения к базе данных завершает последнюю транзакцию, начатую командой begintransaction, и подтверждает изменения в базе данных.

Команда объекта rollback для подключения к базе данных отменяет последнюю транзакцию, начатую командой begintransaction. Состояние базы данных такое же, как если бы ничего не произошло во время транзакции.

Команда объекта transaction для подключения к базе данных представляет собой простой способ объединения транзакции базы данных. Она начинает транзакцию и оценивает переданный аргумент script как скрипт Tcl в области видимости вызывающего приложения. Если script завершается нормально или с помощью break, continue или return, транзакция подтверждается (и любые действия, запрошенные break, continue или return, выполняются). Если подтверждение не удается по какой-либо причине, ошибка в подтверждении рассматривается как ошибка в script. В случае ошибки в script или в подтверждении транзакция отменяется, и ошибка перебрасывается. Любой нестандартный код возврата скрипта приводит к отмене транзакции, а затем к перебрасыванию ошибки.

Команда объекта allrows подготавливает оператор SQL (заданный параметром sql-code) для выполнения в базе данных. Затем она выполняет его (см. tdbc::statement для получения подробностей) с необязательным параметром dictionary, задающим переменные привязки. Наконец, она использует команду объекта allrows для набора результатов (см. tdbc::resultset) для построения списка результатов. Наконец, и набор результатов, и оператор закрываются. Возвращаемое значение — список результатов.

Команда объекта foreach подготавливает оператор SQL (заданный параметром sql-code) для выполнения в базе данных. Затем она выполняет его (см. tdbc::statement для получения подробностей) с необязательным параметром dictionary, задающим переменные привязки. Наконец, она использует команду объекта foreach для набора результатов (см. tdbc::resultset) для оценки заданного script для каждой строки результатов. Наконец, и набор результатов, и оператор закрываются, даже если заданный script приводит к return, ошибке или нестандартному коду возврата.

Параметры конфигурации

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

-encoding name: Указывает кодировку, используемую при подключении к базе данных. name должен быть одним из имен, принятых командой encoding. Этот параметр обычно не нужен; большинство драйверов баз данных могут сами определить используемую кодировку.
-isolation level: Указывает уровень изоляции транзакций, необходимый для транзакций в базе данных. Допустимые значения для level показаны в разделе УРОВНИ ИЗОЛЯЦИИ ТРАНЗАКЦИЙ.
-timeout ms: Указывает максимальное время ожидания операции двигателя базы данных перед сообщением об ошибке вызывающей стороне. Аргумент ms задаёт максимальное время в миллисекундах. Значение нуль (значение по умолчанию) указывает, что вызывающий процесс должен ожидать неопределённое время для операций с базой данных.
-readonly flag: Указывает, что подключение не будет изменять базу данных (если булевый параметр flag имеет значение true) или может изменять базу данных (если flag имеет значение false). Если flag имеет значение true, этот параметр может иметь эффект повышения уровня изоляции транзакции до readonly.

Уровни изоляции транзакций

Допустимые значения для параметра конфигурации -isolation следующие:

readuncommitted: Разрешает транзакции читать «грязные» данные, то есть не подтверждённые данные. Этот уровень изоляции может поставить под угрозу целостность данных, не гарантирует, что внешние ключи или ограничения уникальности соблюдаются, и вообще не гарантирует согласованности данных.
readcommitted: Запрещает транзакции читать «грязные» данные, но не гарантирует повторяемость чтения; если транзакция читает строку базы данных в определённый момент времени, нет гарантии, что та же строка будет доступна в более позднее время в той же транзакции.
repeatableread: Гарантирует, что любая строка базы данных, после чтения, будет иметь те же значения на протяжении всей транзакции. Тем не менее, это всё ещё допускает «фантомные чтения» (то есть появление новых строк, если таблица запрашивается второй раз).
serializable: Самый жёсткий (и самый дорогой) уровень изоляции транзакций. Любой запрос к базе данных, если он повторяется, вернёт точно такие же результаты на протяжении всей транзакции, точно так же, как если бы транзакция была единственным пользователем базы данных.
readonly: Ведёт себя подобно serializable, так как единственные результаты, видимые для транзакции, — это те, которые были подтверждены до начала транзакции, но запрещает транзакции изменять базу данных.

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

Скрипт не должен изменять уровень изоляции, когда транзакция находится в процессе.

См. также

encoding, tdbc, tdbc::resultset, tdbc::statement, tdbc::tokenize

Авторские права

Licensed under Tcl/Tk terms
https://www.tcl.tk/man/tcl/TdbcCmd/tdbc_connection.htm