Унифицированные идентификаторы ресурсов

1. Имена URI-файлов в SQLite

Начиная с версии 3.7.7 (2011-06-23), аргумент файла базы данных SQLite для интерфейсов sqlite3_open(), sqlite3_open16() и sqlite3_open_v2(), а также команды ATTACH, может быть задан либо как обычное имя файла, либо как унифицированный идентификатор ресурса (URI). Преимущество использования URI-имен файлов заключается в том, что параметры запроса в URI могут использоваться для управления деталями вновь созданного подключения к базе данных. Например, можно указать альтернативный VFS с помощью параметра запроса "vfs=". Или базу данных можно открыть в режиме только для чтения, используя параметр запроса "mode=ro".

2. Обратная совместимость

Для поддержания полной обратной совместимости с устаревшими приложениями, возможность использования URI-имен файлов по умолчанию отключена. URI-имена файлов можно включить или отключить с помощью опций компиляции SQLITE_USE_URI=1 или SQLITE_USE_URI=0. Параметр компиляции для URI-имен файлов может быть изменён во время запуска с помощью вызовов конфигурации sqlite3_config(SQLITE_CONFIG_URI,1) или sqlite3_config(SQLITE_CONFIG_URI,0). Независимо от параметров компиляции или запуска, URI-имена файлов можно включить для отдельных подключений к базе данных, включив битовую метку SQLITE_OPEN_URI в набор битов, передаваемых в качестве параметра F в sqlite3_open_v2(N,P,F,V).

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

Поскольку SQLite всегда интерпретирует любое имя файла, не начинающееся с "file:" как обычное имя файла независимо от параметра URI, и поскольку очень необычно, чтобы фактический файл начинался с "file:", для большинства приложений безопасно включить обработку URI, даже если URI-имена файлов в настоящее время не используются.

3. Формат URI

Согласно RFC 3986, URI состоит из схемы, авторизации, пути, строки запроса и фрагмента. Схема всегда обязательна. Один из либо авторизации, либо пути также всегда обязателен. Строка запроса и фрагмент являются необязательными.

SQLite использует синтаксис URI "file:" для идентификации файлов базы данных. SQLite стремится интерпретировать URI "file:" точно так же, как популярные веб-браузеры, такие как Firefox, Chrome, Safari, Internet Explorer и Opera, и командные программы, такие как Windows "cmd start" или "powershell start", или команды macOS "open" или Linux "xdg-open". Ниже приведён краткий обзор правил разбора URI:

• Схема URI должна быть "file:". Любая другая схема приводит к тому, что вход интерпретируется как обычное имя файла.
• Авторизация может быть опущена, может быть пустой или быть "localhost". Любая другая авторизация приводит к ошибке. Исключение: Если SQLite скомпилирован с SQLITE_ALLOW_URI_AUTHORITY, то любое значение авторизации, отличное от "localhost", передаётся в операционную систему как имя файла UNC.
• Путь является необязательным, если присутствует авторизация. Если авторизация опущена, то путь является абсолютным, если он начинается с символа "/" (ASCII код 0x2f), и относительным в противном случае.
• Строка запроса необязательна. Если строка запроса присутствует, то все параметры запроса передаются в метод xOpen подлежащего VFS.
• Фрагмент необязателен. Если он присутствует, он игнорируется.

В пути, строке запроса или фрагменте могут встречаться один или несколько последовательностей экранирования вида "%HH" (где H представляет любую шестнадцатеричную цифру).

Имя файла, которое не является правильно сформированным URI, интерпретируется как обычное имя файла.

Обработка URI выполняется как текст UTF8. Аргумент имени файла sqlite3_open16() преобразуется из нативного байтового порядка UTF16 в UTF8 перед обработкой.

3.1. Путь URI

Компонент пути URI указывает дисковый файл, являющийся базой данных SQLite, подлежащей открытию. Если компонент пути опущен, то база данных хранится в временном файле, который будет автоматически удалён при закрытии подключения к базе данных. Если секция авторизации присутствует, то путь всегда является абсолютным именем файла. Если секция авторизации опущена, то путь является абсолютным именем файла, если он начинается с символа "/" (ASCII код 0x2f), и относительным именем файла в противном случае. В Windows, если абсолютный путь начинается с "/X:/", где X — любая одиночная буквенная ASCII-символ ("a" до "z" или "A" до "Z"), то "X:" понимается как буква диска тома, содержащего файл, а не верхнего каталога.

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

1. Преобразовать все символы "?" в "%3f".
2. Преобразовать все символы "#" в "%23".
3. Только в Windows, преобразовать все символы "\" в "/".
4. Преобразовать все последовательности из двух или более символов "/" в один символ "/".
5. Только в Windows, если имя файла начинается с буквы диска, добавить перед ним одиночный символ "/".
6. Добавить схему "file:".

3.2. Строка запроса

Имя URI-файла может быть дополнительно указано строкой запроса. Строка запроса состоит из текста, следующего за первым символом "?", но без необязательного фрагмента, начинающегося с "#". Строка запроса разделена на пары ключ/значение. Мы обычно называем эти пары ключ/значение "параметрами запроса". Пары ключ/значение разделены одиночным символом "&". Ключ идёт первым, и отделяется от значения одиночным символом "=". И ключ, и значение могут содержать последовательности экранирования %HH.

Текст параметров запроса добавляется к аргументу имени файла метода xOpen VFS. Любые последовательности экранирования %HH в параметрах запроса обрабатываются до добавления их к имени файла xOpen. Одиночный нулевой байт отделяет аргумент имени файла xOpen от ключа первых параметров запроса, каждый ключ и значение, и каждый последующий ключ от предыдущего значения. Список параметров запроса, добавленных к аргументу имени файла xOpen, завершается одиночным ключом нулевой длины. Обратите внимание, что значение параметра запроса может быть пустой строкой.

3.3. Распознаваемые параметры запроса

Некоторые параметры запроса интерпретируются ядром SQLite и используются для изменения характеристик нового подключения. Все параметры запроса всегда передаются методу xOpen VFS, даже если они предварительно считываются и интерпретируются ядром SQLite.

Следующие параметры запроса распознаются SQLite начиная с версии 3.15.0 (2016-10-14). В будущем могут быть добавлены новые параметры запроса.

cache=shared
cache=private

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

immutable=1

Параметр запроса immutable — булево значение, которое сигнализирует SQLite о том, что подлежащий файлу базы данных хранится на носителях только для чтения и не может быть изменён, даже другим процессом с повышенными привилегиями. SQLite всегда открывает неизменяемые файлы баз данных только для чтения, и пропускает всю блокировку файлов и обнаружение изменений в неизменяемых файлах баз данных. Если этот параметр запроса (или бит SQLITE_IOCAP_IMMUTABLE в xDeviceCharacteristics) утверждает, что файл базы данных неизменяемый и что изменения файла происходят, то SQLite может возвращать неверные результаты запроса и/или ошибки SQLITE_CORRUPT.

mode=ro
mode=rw
mode=rwc
mode=memory

Параметр запроса mode определяет, открывается ли новая база данных только для чтения, для чтения и записи, для чтения и записи (создаётся, если она не существует) или является ли база данных чисто внутрипамятьной базой данных, которая никогда не взаимодействует с диском, соответственно.

modeof=filename

При создании нового файла базы данных во время sqlite3_open_v2() на системах Unix SQLite попытается установить разрешения нового файла базы данных в соответствии с существующим файлом "filename".

nolock=1

Параметр запроса nolock — булево значение, которое отключает все вызовы методов xLock, xUnlock и xCheckReservedLock VFS, если он имеет значение true. Параметр запроса nolock может использоваться, например, при попытке доступа к файлу на файловой системе, которая не поддерживает блокировку файлов. Внимание: Если два или более подключений к базе данных пытаются взаимодействовать с одной и той же базой данных SQLite, и одно или несколько из этих подключений включило "nolock", может произойти повреждение базы данных. Параметр запроса "nolock" должен использоваться только в том случае, если приложение может гарантировать, что записи в базе данных выполняется последовательно.

psow=0
psow=1

Параметр запроса psow переопределяет свойство powersafe overwrite файла базы данных, который открывается. Параметр запроса psow работает с стандартными VFS Windows и Unix, но может быть бесполезным для других фирменных или нестандартных VFS.

vfs=NAME

Параметр запроса vfs заставляет подключение к базе данных открываться с использованием VFS с именем NAME. Попытка открытия завершается ошибкой, если NAME не является именем VFS, встроенного в SQLite, или которое было ранее зарегистрировано с помощью sqlite3_vfs_register().

4. См. также

• URI-имена файлов в sqlite3_open()
• Примеры URI-имен файлов

Эта страница была в последний раз изменена 2023-01-02 14:22:42 UTC