База данных

Emacs можно собрать со встроенной поддержкой доступа к базам данных SQLite. В этом разделе описаны средства доступа к базам данных SQLite из программ на Lisp.

Функция: sqlite-available-p

Функция возвращает не-nil, если в этом сеансе Emacs доступна встроенная поддержка SQLite.

Если поддержка SQLite доступна, можно использовать следующие функции.

Функция: sqlite-open &optional file readonly disable-uri

Эта функция открывает file как файл базы данных SQLite. Если file не существует, будет создана новая база данных и сохранена в этом файле. Если file не указан или равен nil, вместо этого создается новая база данных в памяти. Если второй необязательный аргумент readonly не-nil, база данных открывается только для чтения; в этом случае она уже должна существовать. По умолчанию file может быть URI file:// или именем файла; в необычном случае, когда у вас есть локальный файл, имя которого начинается с file:, укажите значение, отличное от nil, для третьего необязательного аргумента disable-uri, чтобы отключить автоматическое распознавание и обработку URI.

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

Функция: sqlitep object

Этот предикат возвращает не-nil, если object является объектом базы данных SQLite. Объект базы данных, возвращаемый функцией sqlite-open, удовлетворяет этому предикату.

Функция: sqlite-close db

Закрывает базу данных db. Обычно вызывать эту функцию явно не требуется: база данных будет закрыта автоматически при завершении работы Emacs или сборке мусора для объекта базы данных. Если соединение, обозначенное db, уже закрыто, функция ничего не делает.

Функция: sqlite-execute db statement &optional values

Выполняет SQL-инструкцию statement. Например:

(sqlite-execute db "insert into foo values ('bar', 2)")

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

(sqlite-execute db "insert into foo values (?, ?)" '("bar" 2))

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

sqlite-execute обычно возвращает количество затронутых строк. Например, инструкция «insert» обычно возвращает «1», тогда как инструкция «update» может вернуть ноль или большее число. Однако при использовании SQL-инструкций вида «insert into … returning …» и подобных вместо этого возвращаются значения, указанные в «returning …».

По умолчанию строки в SQLite хранятся как utf-8, а при выборке текстового столбца строка декодируется с использованием этой кодировки. При выборке столбца типа blob возвращаются необработанные данные без декодирования (то есть однобайтовая строка, содержащая байты в том виде, в каком они хранятся в базе данных). Однако вставка двоичных данных в столбцы blob требует осторожности, поскольку sqlite-execute по умолчанию рассматривает все строки как utf-8.

Поэтому, если, например, у вас есть данные GIF в однобайтовой строке с именем gif, нужно специально пометить ее, чтобы sqlite-execute знал об этом:

(put-text-property 0 1 'coding-system 'binary gif)
(sqlite-execute db "insert into foo values (?, ?)" (list gif 2))

Функция: sqlite-execute-batch db statements

Выполняет SQL-инструкции statements. statements — это строка, содержащая ноль или более SQL-инструкций. Эта команда может быть полезна, когда программе на Lisp нужно выполнить несколько инструкций языка определения данных (DDL) за один раз.

Функция: sqlite-select db query &optional values return-type

Выбирает данные из db и возвращает их. Например:

(sqlite-select db "select * from foo where key = 2")
  ⇒ (("bar" 2))

Как и в случае с sqlite-execute, можно передать список или вектор значений, которые будут подставлены перед выполнением запроса на выборку:

(sqlite-select db "select * from foo where key = ?" [2])
  ⇒ (("bar" 2))

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

По умолчанию эта функция возвращает список соответствующих строк, где каждая строка — это список значений столбцов. Если return-type равен full, имена столбцов (в виде списка строк) будут возвращены первым элементом результата.

Если return-type равен set, функция вместо этого вернет объект инструкции. Этот объект можно исследовать с помощью функций sqlite-next, sqlite-columns и sqlite-more-p. Если набор результатов невелик, часто удобнее сразу вернуть данные; но если набор результатов большой (или если вы не будете использовать все данные из набора), метод set выделит гораздо меньше памяти и, следовательно, будет экономнее расходовать память.

Функция: sqlite-next statement

Эта функция возвращает следующую строку из набора результатов statement, обычно представляющего собой объект, возвращенный функцией sqlite-select.

(sqlite-next stmt)
    ⇒ ("bar" 2)

Функция: sqlite-columns statement

Эта функция возвращает имена столбцов набора результатов statement, обычно представляющего собой объект, возвращенный функцией sqlite-select.

(sqlite-columns stmt)
    ⇒ ("name" "issue")

Функция: sqlite-more-p statement

Этот предикат сообщает, остались ли данные для извлечения из набора результатов statement, обычно представляющего собой объект, возвращенный функцией sqlite-select.

Функция: sqlite-finalize statement

Если объект statement больше не будет использоваться, вызов этой функции освободит ресурсы, занятые объектом statement. Обычно в этом нет необходимости: когда объект statement будет удален сборщиком мусора, Emacs автоматически освободит его ресурсы.

Функция: sqlite-transaction db

Начинает транзакцию в db. Пока выполняется транзакция, другие читатели базы данных не смогут получить доступ к результатам, пока транзакция не будет зафиксирована функцией sqlite-commit.

Функция: sqlite-commit db

Завершает транзакцию в db и записывает данные в файл базы данных.

Функция: sqlite-rollback db

Завершает транзакцию в db и отменяет все изменения, внесенные транзакцией.

Макрос: with-sqlite-transaction db body…

Подобно progn (см. Последовательность выполнения), но выполняет body в рамках транзакции и фиксирует ее в конце, если выполнение body завершилось нормально. Если body сигнализирует об ошибке или фиксация транзакции завершается неудачно, изменения в db, внесенные body, отменяются. Если выполнение макроса завершается нормально и фиксация проходит успешно, макрос возвращает значение body.

Функция: sqlite-pragma db pragma

Выполняет pragma в db. Pragma — это обычно команда, влияющая на базу данных в целом, а не на какую-либо отдельную таблицу. Например, чтобы SQLite автоматически удаляла данные, которые больше не нужны, можно выполнить:

(sqlite-pragma db "auto_vacuum = FULL")

В случае успеха эта функция возвращает не-nil, а если pragma завершилась неудачно — nil. Многие pragma можно выполнять только тогда, когда база данных совершенно новая и пустая.

Функция: sqlite-load-extension db module

Загружает расширение с именем module в базу данных db. Обычно расширения представляют собой файлы разделяемых библиотек; в системах GNU и Unix они имеют расширение имени файла .so.

Функция: sqlite-version

Возвращает строку, обозначающую версию используемой библиотеки SQLite.

Чтобы просмотреть содержимое файла SQLite, можно использовать команду sqlite-mode-open-file. Она откроет буфер с помощью sqlite-mode, позволяющего просматривать (и изменять) содержимое базы данных SQLite.