1. Имена URI в SQLite

Начиная с version 3.7.7 (2011-06-23), аргумент имени файла базы данных SQLite в sqlite3_open(), sqlite3_open16(), sqlite3_open_v2() и ATTACH может быть определен как обычное имя файла или как Uniform Resource Identifier (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 точно таким же образом как популярные веб-браузеры, такие как 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.
• Путь дополнительный, если авторизация присутствует. Если она опущена тогда, путь требуется.
• Строка запроса дополнительная. Если строка запроса присутствует, то все параметры запроса передают в метод xOpen основной VFS.
• Фрагмент дополнительный. Если существует, это проигнорировано.

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

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

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

3.1. Путь URI

Компонент пути URI определяет дисковый файл, который является базой данных SQLite, которая будет открыта. Если компонент опущен, то база данных сохранена во временном файле, который будет автоматически удален, когда соединение с базой данных закроется. Если часть авторизации присутствует, то путь всегда абсолютный. Если часть авторизации опущена, то путь абсолютный, если это начинается с символа "/" (ASCII code 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 может произвольно сопровождаться строкой запроса. Строка запроса состоит из текста после первого символа "?", но, исключая дополнительный фрагмент, который начинается с "#". Строка запроса разделена на пары ключ/значение. Мы обычно именуем эти пары ключ/значение как "параметры запроса". Пары ключ/значение отделены единственным символом "&". Ключ на первом месте и отделен от значения единственным символом "=". Ключ и значение могут содержать escape-последовательности %HH.

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

3.3. Признанные параметры запроса

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

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

cache=shared
cache=private

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

immutable=1

Параметр запроса immutable это boolean, который сигнализирует 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 это boolean, который отключает все обращения к методам VFS xLock, xUnlock и xCheckReservedLock, когда true. Параметр запроса nolock мог бы использоваться, например, пытаясь получить доступ к файлу в файловой системе, которая не делает блокировку файла. Если два или больше соединения с базой данных пытаются взаимодействовать с той же самой базой данных SQLite, и одна или больше тех связей позволяет "nolock", базу данных может разорватью Параметр запроса "nolock" должен использоваться только, если применение может гарантировать, что запись базы данных преобразовывается в последовательную форму.

psow=0
psow=1

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

vfs=NAME

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

4. См. также

• URI filenames in sqlite3_open()
• URI filename examples