Открытие нового соединения с базой данных

int sqlite3_open(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open16(
  const void *filename,   /* Database filename (UTF-16) */
  sqlite3 **ppDb          /* OUT: SQLite db handle */
);
int sqlite3_open_v2(
  const char *filename,   /* Database filename (UTF-8) */
  sqlite3 **ppDb,         /* OUT: SQLite db handle */
  int flags,              /* Flags */
  const char *zVfs        /* Name of VFS module to use */
);

Это открывает файл базы данных SQLite, как определено аргументом имени файла. Аргумент имени файла интерпретируется как UTF-8 для sqlite3_open() и sqlite3_open_v2() или UTF-16 в родном порядке байтов для sqlite3_open16(). Обработчик соединения с базой данных обычно возвращается в *ppDb, даже если ошибка происходит. Единственное исключение это если SQLite не может ассигновать память, чтобы хранить объект sqlite3, NULL впишут в *ppDb вместо указателя на объект sqlite3. Если база данных открыта (и/или создана) успешно, то вернется SQLITE_OK. Иначе вернется код ошибки. sqlite3_errmsg() или sqlite3_errmsg16() может использоваться, чтобы получить английское языковое описание ошибки после неудачи любого из sqlite3_open().

Кодировка по умолчанию будет UTF-8 для баз данных, созданных, используя sqlite3_open() или sqlite3_open_v2(). Кодировка по умолчанию для баз данных, созданных, используя sqlite3_open16(), это UTF-16 в родном порядке байт.

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

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

SQLITE_OPEN_READONLY

База данных открыта в режиме только для чтения. Если база данных не существует, ошибка возвращена.

SQLITE_OPEN_READWRITE

База данных открыта для чтения и записи, если это возможно, или только чтения, если файл защищен от записи операционной системой. В любом случае база данных должна уже существовать, иначе ошибка возвращена. По историческим причинам, если открытие в режиме чтения-записи терпит неудачу из-за разрешений уровня OS, предпринята попытка открыть файл в режиме только для чтения. sqlite3_db_readonly() может использоваться, чтобы определить, открыта ли база данных на самом деле для чтения и записи.

SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE

База данных открыта для чтения и и записи, причем создается, если это еще не существует. Это поведение, которое всегда используется для sqlite3_open() и sqlite3_open16().

В дополнение к необходимым флагам также поддерживаются следующие дополнительные флаги:

SQLITE_OPEN_URI

Имя файла может интерпретироваться как URI, если этот флаг установлен.

SQLITE_OPEN_MEMORY

База данных будет открыта как база данных в памяти. Базу данных называет аргумент "filename" для целей разделения кэша, если общий режим кэширования позволен, но иначе "filename" проигнорирован.

SQLITE_OPEN_NOMUTEX

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

SQLITE_OPEN_FULLMUTEX

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

SQLITE_OPEN_SHAREDCACHE

База данных открыта с включенным общим кэшем, отвергая параметры умолчания разделенного кэша, обеспеченные sqlite3_enable_shared_cache(). Использованию общего режима кэширования и следовательно общие возможности кэша могут быть опущены в ряде сборок SQLite. В таких случаях этот выбор ничего не делает.

SQLITE_OPEN_PRIVATECACHE

База данных открыта с запретом бощего кэша , отвергая параметры умолчания разделенного кэша, обеспеченные sqlite3_enable_shared_cache().

SQLITE_OPEN_EXRESCODE

Соединение с базой данных подходит в "расширенном кодовом режиме результата". Другими словами, база данных ведет себя, как если выполнено sqlite3_extended_result_codes(db,1) на соединении с базой данных, как только связь создается. В дополнение к урегулированию расширенного кодового режима результата этот флаг также заставляет sqlite3_open_v2() возвращать расширенный код результата.

SQLITE_OPEN_NOFOLLOW

Имени файла базы данных не позволяют содержать символьную ссылку.

Если 3-й параметр sqlite3_open_v2() не является одной из необходимых комбинаций, показанных выше, произвольно объединенной с другими SQLITE_OPEN_* bits, поведение не определено. Исторические версии SQLite тихо игнорировали избыточные биты в параметре флагов sqlite3_open_v2(), однако то поведение не могло бы быть осуществлено в будущих версиях SQLite и таким образом приложения не должны полагаться на него. Отметьте в особенности, что флаг SQLITE_OPEN_EXCLUSIVE ничего не делает в sqlite3_open_v2(). SQLITE_OPEN_EXCLUSIVE НЕ заставляют открытие терпеть неудачу, если база данных уже существует. SQLITE_OPEN_EXCLUSIVE предназначается для использования только интерфейсом VFS, но не sqlite3_open_v2().

Четвертый параметр sqlite3_open_v2() является названием объекта sqlite3_vfs, который определяет интерфейс операционной системы, который должно использовать новое соединение с базой данных. Если четвертый параметр NULL, тогда применяется умолчание объекта sqlite3_vfs.

Если имя файла ":memory:", частная, временная база данных в памяти создается для связи. Эта база данных в памяти исчезнет, когда соединение с базой данных будет закрыто. Будущие версии SQLite могли бы использовать дополнительные специальные имена файлов, которые начинаются с ":". Рекомендуется, когда имя файла базы данных на самом деле начинается с ":", вы должны поставить префикс имени файла с таким путем, как "./", чтобы избежать двусмысленности.

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

Имена файлов URI

Если имена файлов URI позволены и аргумент имени файла начинается с "file:", тогда имя файла интерпретируется как URI. Интерпретация имени файла URI позволена, если флаг SQLITE_OPEN_URI установлен в третьем аргументе sqlite3_open_v2() или если это было позволено глобально, используя выбор SQLITE_CONFIG_URI в методе sqlite3_config() или опцией компиляции SQLITE_USE_URI. Интерпретация имени файла URI выключена по умолчанию, но будущие выпуски SQLite могли бы позволить интерпретацию имени файла URI по умолчанию. См. здесь подробности.

Имена файлов URI разобраны согласно RFC 3986. Если URI содержит авторизацию, то это должна быть пустая строка или последовательность "localhost", иначе ошибка возвращена. Компонент фрагмента URI, если есть проигнорирован.

SQLite использует компонент контура URI как название дискового файла, который содержит базу данных. Если путь начинается с '/', то это интерпретируется как абсолютный путь. Если путь не начинается с '/' (подразумевается, что часть секции авторизации опущена в URI), тогда путь интерпретируется как относительный. В Windows первый компонент абсолютного пути это спецификация привода (например, "C:").

Компонент запроса URI может содержать параметры, которые интерпретируются самим SQLite или реализацией VFS. SQLite и его встроенный VFS интерпретируют следующие параметры запроса:

• vfs: Параметр "vfs" может использоваться, чтобы определить название объекта VFS, который обеспечивает интерфейс операционной системы, который должен использоваться, чтобы получить доступ к файлу базы данных на диске. Если этот выбор установлен в пустую строку, используется объект VFS по умолчанию. Определение неизвестного VFS является ошибкой. Если используется sqlite3_open_v2() и vfs выбор присутствует, то VFS, определенный выбором, имеет приоритет по значению, переданный как четвертый параметр sqlite3_open_v2().

• mode: Параметр режима может быть установлен в "ro", "rw", "rwc" или "memory". Попытка установить его в любое другое значение является ошибкой. Если указано "ro", то база данных открыта для доступа только для чтения, так же, как если бы флаг SQLITE_OPEN_READONLY был установлен в третьем аргументе sqlite3_open_v2(). Если выбор режима установлен в "rw", то база данных открыта для чтения-записи (но не создания), как будто установлено SQLITE_OPEN_READWRITE (но не SQLITE_OPEN_CREATE). Значение "rwc" эквивалентно урегулированию SQLITE_OPEN_READWRITE и SQLITE_OPEN_CREATE вместе. Если выбор режима установлен в "memory", база данных в памяти, которая никогда не читается или пишется на диск, используется. Ошибка определить значение для параметра режима, которое менее строгое, чем определенное флагами, переданными в третьем параметре sqlite3_open_v2().

• cache: параметр кэша может быть установлен в "shared" или "private". "shared" эквивалентно установке бита SQLITE_OPEN_SHAREDCACHE в аргументе флагов, переданном sqlite3_open_v2(). "private" эквивалентно установке бита SQLITE_OPEN_PRIVATECACHE. Если применяется sqlite3_open_v2() и параметр "cache" присутствует в имени файла URI, его значение отвергает любое поведение, которое требуют, устанавливая SQLITE_OPEN_PRIVATECACHE или SQLITE_OPEN_SHAREDCACHE.

• psow: Параметр psow указывает, переписывают ли свойство powersafe overwrite применительно к носителям, на которых находится файл базы данных.

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

• immutable: immutable это boolean параметр логического запроса, который указывает, что файл базы данных хранится на носителе только для чтения. Если immutable установлен, SQLite предполагает, что файл базы данных не может быть изменен, даже процессом с более высокой привилегией, и таким образом, база данных открыта только для чтения, а все изменения отключены. Осторожно: указание immutable на файле базы данных, который на самом деле изменяется, может привести к неправильным результатам запроса и/или ошибкам SQLITE_CORRUPT. См. также: SQLITE_IOCAP_IMMUTABLE.

Определение неизвестного параметра в компоненте запроса URI не является ошибкой. Будущие версии SQLite могли бы понять дополнительные параметры запроса. См. здесь подробности.

Примеры имени файла URI

Шестнадцатеричные escape-последовательности URI (%HH) поддерживаются в пути и запрашивают компоненты URI. Шестнадцатеричная escape-последовательность состоит из знака процента "%", сопровождаемого точно двумя шестнадцатеричными цифрами, определяющими значение октета. Прежде чем путь или компоненты запроса имени файла URI интерпретируются, они закодированы, используя UTF-8 и все шестнадцатеричные escape-последовательности, заменены единственным байтом, содержащим соответствующий октет. Если этот процесс производит недействительное кодирование UTF-8, результаты не определены.

Замечание для Windows: кодирование, используемое для аргумента имени файла sqlite3_open() и sqlite3_open_v2() должно быть UTF-8, независимо от того, какая кодовая страница в настоящее время определяется. Имена файлов, содержащие международные символы, должны быть преобразованы в UTF-8 до прохождения их в sqlite3_open() или sqlite3_open_v2().

Замечание для Windows Runtime: временный каталог должен быть установлен до запроса sqlite3_open() или sqlite3_open_v2(). Иначе различные особенности, которые требуют использования временных файлов, могут потерпеть неудачу.

См. также: sqlite3_temp_directory.