Открытие нового подключения к базе данных

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, то в *ppDb вместо указателя на объект sqlite3 будет записан NULL. Если база данных открыта (и/или создана) успешно, то возвращается 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

База данных открывается для чтения и записи, если это возможно, или только для чтения, если файл защищен от записи операционной системой. В любом случае база данных должна уже существовать, в противном случае возвращается ошибка. По историческим причинам, если открытие в режиме чтения/записи завершится неудачей из-за разрешений на уровне ОС, делается попытка открыть его в режиме только для чтения. 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

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

SQLITE_OPEN_FULLMUTEX

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

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

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

Если третий параметр sqlite3_open_v2() не является одной из требуемых комбинаций, показанных выше, необязательно комбинированных с другими битами SQLITE_OPEN_*, то поведение не определено. Исторические версии 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".

Имена файлов URI анализируются в соответствии с RFC 3986. Если URI содержит авторизацию, то она должна быть либо пустой строкой, либо строкой "localhost". Если авторизация не пустая строка и не "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: Параметр mode может быть установлен в "ro", "rw", "rwc" или "memory". Попытка установить его в любое другое значение является ошибкой. Если указано "ro", база данных открывается для чтения только для чтения, как если бы флаг SQLITE_OPEN_READONLY был установлен в третьем аргументе sqlite3_open_v2(). Если параметр mode установлен в "rw", база данных открывается для чтения и записи (но не для создания), как если бы был установлен SQLITE_OPEN_READWRITE (но не SQLITE_OPEN_CREATE). Значение "rwc" эквивалентно установке как SQLITE_OPEN_READWRITE, так и SQLITE_OPEN_CREATE. Если параметр mode установлен в "memory", используется чистая база данных в памяти, которая никогда не читает и не записывает данные с диска. Указание значения параметра mode, которое менее ограничительно, чем указано флагами, переданными в третьем параметре sqlite3_open_v2(), является ошибкой.

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

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

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

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

Указание неизвестного параметра в компоненте запроса URI не является ошибкой. Будущие версии SQLite могут понимать дополнительные параметры запроса. Дополнительную информацию см. в "параметрах запроса со специальным значением для SQLite".

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

В компонентах пути и запроса URI поддерживаются шестнадцатеричные последовательности экранирования (%HH). Шестнадцатеричная последовательность экранирования состоит из знака процента "%" и ровно двух шестнадцатеричных цифр, определяющих значение октета. Прежде чем компоненты пути или запроса имени файла URI будут интерпретированы, они кодируются с использованием UTF-8, и все шестнадцатеричные последовательности экранирования заменяются одним байтом, содержащим соответствующий октет. Если этот процесс создает недопустимое кодирование 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

См. также списки объектов, констант и функций.