SQLite version 3.0 это новая версия SQLite, полученная из кодовой базы SQLite 2.8.13, но с несовместимым форматом файла и API. Версия 3.0 SQLite была создана, чтобы ответить на спрос на следующие особенности:
Было необходимо многое переделать в версии 3.0, чтобы реализовать эти опции, потому что каждая из них требует несовместимых изменений формата файла базы данных. Другие несовместимые изменения, такие как очистка API, были введены в то же время в соответствии с теорией, что лучше избавляться от ваших несовместимых изменений сразу.
API version 3.0 подобен версии 2.X API, но с некоторыми важными изменениями. Наиболее заметно, что префикс "sqlite_", который есть в начале всех API-функций и структур данных, изменяется на "sqlite3_". Это избегает беспорядка между двумя API и позволяет связывать SQLite 2.X и SQLite 3.0 в то же время.
Нет никакого соглашения по тому, каков тип данных C для последовательности UTF-16 должен быть. Поэтому SQLite использует универсальный тип void*, чтобы относиться к последовательностям UTF-16. Клиентское программное обеспечение может привести void* к любому типу данных, который подходит для их системы.
API SQLite 3.0 включает 83 отдельных функции в дополнение к нескольким структурам данных и #defines. К счастью, интерфейс не так сложен, как его размер подразумевает. Простые программы могут все еще обойтись только 3 функциями: sqlite3_open(), sqlite3_exec() и sqlite3_close(). Больше контроля над выполнением ядра базы данных обеспечивается, используя sqlite3_prepare_v2(), чтобы собрать запрос SQLite в байт-код, и sqlite3_step(), чтобы выполнить этот байт-код. Набор функций с именами, начинающимися с sqlite3_column_, используется, чтобы извлечь информацию о наборе результатов запроса. Много функций интерфейса парные с версиями для UTF-8 и UTF-16. Есть коллекция функций, чтобы осуществить определенные пользователями функции SQL и пользовательский текст, сопоставляющий последовательности.
typedef struct sqlite3 sqlite3; int sqlite3_open(const char*, sqlite3**); int sqlite3_open16(const void*, sqlite3**); int sqlite3_close(sqlite3*); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); int sqlite3_errcode(sqlite3*);
sqlite3_open() возвращает код ошибки целого числа, а не указатель на строуктуру sqlite3, как делала version 2 интерфейса. Различие между sqlite3_open() и sqlite3_open16() в том, что sqlite3_open16() берет UTF-16 (в порядке байтов хоста) для названия файла базы данных. Если новый файл базы данных должен быть создан, то sqlite3_open16() устанавливает представление внутреннего текста UTF-16, тогда как sqlite3_open() устанавливает текстовое представление UTF-8.
Открытие и/или создание файла базы данных отсрочено, пока файл на самом деле не будет необходим. Это позволяет задать варианты и параметры, такие как родное текстовое представление и размер страницы по умолчанию, используя заявления PRAGMA.
sqlite3_errcode() возвращает код результата для нового главного вызова API. sqlite3_errmsg() вернет англоязычное текстовое сообщение об ошибке для новой ошибки. Сообщение об ошибке представляется в UTF-8 и будет эфемерно: это может исчезнуть на следующем вызове любой API-функции SQLite. sqlite3_errmsg16() работает как sqlite3_errmsg() за исключением того, что это возвращает сообщение об ошибке, представленное как UTF-16 в порядке байтов хоста.
Коды ошибок для версии 3 SQLite неизменны от версии 2. Они следующие:
#define SQLITE_OK 0 /* Successful result */ #define SQLITE_ERROR 1 /* SQL error or missing database */ #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ #define SQLITE_PERM 3 /* Access permission denied */ #define SQLITE_ABORT 4 /* Callback routine requested an abort */ #define SQLITE_BUSY 5 /* The database file is locked */ #define SQLITE_LOCKED 6 /* A table in the database is locked */ #define SQLITE_NOMEM 7 /* A malloc() failed */ #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ #define SQLITE_MISMATCH 20 /* Data type mismatch */ #define SQLITE_MISUSE 21 /* Library used incorrectly */ #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ #define SQLITE_AUTH 23 /* Authorization denied */ #define SQLITE_ROW 100 /* sqlite_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite_step() has finished executing */
typedef int (*sqlite_callback)(void*,int,char**, char**); int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
Функция sqlite3_exec() работает как это сделано в версии 2 SQLite. Ноль или больше SQL-операторов, определенных во втором параметре, собраны и выполнены. Результаты запроса возвращены к отзыву.
В SQLite version 3 sqlite3_exec просто обертка вокруг вызовов интерфейса подготовленного запроса.
typedef struct sqlite3_stmt sqlite3_stmt; int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**); int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**); int sqlite3_finalize(sqlite3_stmt*); int sqlite3_reset(sqlite3_stmt*);
Интерфейс sqlite3_prepare собирает единственный SQL-оператор в байт-код для более позднего выполнения. Этот интерфейс теперь предпочтительный способ получить доступ к базе данных.
SQL-оператор это последовательность UTF-8 для sqlite3_prepare(). sqlite3_prepare16() работает так же за исключением того, что это ожидает последовательность UTF-16 как вход SQL. Только первый SQL-оператор во входной строке собран. Пятый параметр заполнен указателем на следующий (несобранный) запрос SQLite во входной строке, если таковой есть. sqlite3_finalize() освобождает подготовленный SQL-оператор. Все подготовленные запросы должны быть завершены, прежде чем база данных может быть закрыта. sqlite3_reset() перезагружает подготовленный SQL-оператор так, чтобы это могло быть выполнено снова.
SQL-оператор может содержать символы формы "?", "?nnn" или ":aaa", где "nnn" целое число и "aaa" является идентификатором. Такие символы представляют неуказанные литеральные значения (или "подстановочные знаки"), чтобы быть заполненными позже интерфейсом sqlite3_bind. У каждого подстановочного знака есть связанное число, которое является его последовательностью в запросе или "nnn" в случае формы "?nnn". Позволено для того же самого подстановочного знака быть несколько раз в том же самом SQL-операторе, в этом случае все экземпляры того подстановочного знака будут заполнены тем же самым значением. У несвязанных подстановочных знаков есть значение NULL.
int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, long long int); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
Есть ассортимент функций sqlite3_bind, используемых, чтобы назначить значения на подстановочные знаки в подготовленном SQL-операторе. Несвязанные подстановочные знаки интерпретируются как NULL. Привязки не перезагружаются sqlite3_reset(). Но подстановочные знаки могут быть переназначены к новым значениям после sqlite3_reset().
После того, как SQL-оператор был подготовлен (и произвольно связан), он выполняется, используя:
int sqlite3_step(sqlite3_stmt*);
sqlite3_step() вернет SQLITE_ROW, если это возвращает единственную строку набора результатов или SQLITE_DONE, если выполнение закончено нормально или из-за ошибки. Это могло бы также возвратить SQLITE_BUSY, если это неспособно открыть файл базы данных. Если возвращаемое значение SQLITE_ROW, то следующие функции могут использоваться, чтобы извлечь информацию о строке набора результатов:
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); int sqlite3_column_count(sqlite3_stmt*); const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol); const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol); double sqlite3_column_double(sqlite3_stmt*, int iCol); int sqlite3_column_int(sqlite3_stmt*, int iCol); long long int sqlite3_column_int64(sqlite3_stmt*, int iCol); const char *sqlite3_column_name(sqlite3_stmt*, int iCol); const void *sqlite3_column_name16(sqlite3_stmt*, int iCol); const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); int sqlite3_column_type(sqlite3_stmt*, int iCol);
sqlite3_column_count() возвращает количество колонок в наборе результатов. sqlite3_column_count() можно вызвать в любое время после sqlite3_prepare_v2(). sqlite3_data_count() работает так же, как sqlite3_column_count() кроме того, что это работает только после sqlite3_step(). Если предыдущий вызов sqlite3_step() возвратил SQLITE_DONE или код ошибки, то sqlite3_data_count() вернет 0, тогда как sqlite3_column_count() продолжит возвращать количество колонок в наборе результатов.
Возвращенные данные исследованы, используя другие функции sqlite3_column_***(), все из которых берут номер столбца в качестве их второго параметра. Колонки внесены в указатель слева направо, начиная с 0. Обратите внимание на то, что это отличается от параметров, которые внесены в указатель, начиная с единицы.
sqlite3_column_type() возвращает тип данных для значения в колонке N. Возвращаемое значение одно из:
#define SQLITE_INTEGER 1 #define SQLITE_FLOAT 2 #define SQLITE_TEXT 3 #define SQLITE_BLOB 4 #define SQLITE_NULL 5
sqlite3_column_decltype() возвращает текст, который является заявленным типом колонки в CREATE TABLE. Для выражения тип возвращения пустая строка. sqlite3_column_name() возвращает название колонки N. sqlite3_column_bytes() возвращает число байтов в колонке, которая имеет тип BLOB или число байтов в строке TEXT в UTF-8. sqlite3_column_bytes16() возвращает то же самое значение для BLOB, но TEXT исходит из UTF-16. sqlite3_column_blob() вернет данные BLOB. sqlite3_column_text() вернет данные TEXT как UTF-8. sqlite3_column_text16() вернет данные TEXT как UTF-16. sqlite3_column_int() вернет данные INTEGER в формате текущего хоста. sqlite3_column_int64() вернет данные 64-bit INTEGER. Finally, sqlite3_column_double() вернет данные с плавающей точкой.
Необязательно получать данные в формате, определенном sqlite3_column_type(). Если другой формат требуют, данные преобразовываются автоматически.
Преобразования формата данных могут лишить законной силы указатель, возвращенный предшествующими вызовами sqlite3_column_blob(), sqlite3_column_text() и/или sqlite3_column_text16(). Это бывает в следующих случаях:
Начальное содержание BLOB и вызвана sqlite3_column_text() или sqlite3_column_text16(). Нулевой терминатор, возможно, должен быть добавлен к последовательности.
Начальное содержание UTF-8 и вызвана sqlite3_column_bytes16() или sqlite3_column_text16(). Содержание должно быть преобразовано в UTF-16.
Начальное содержание UTF-16 и вызвана sqlite3_column_bytes() или sqlite3_column_text(). Содержание должно быть преобразовано в UTF-8.
Обратите внимание на то, что преобразования между UTF-16be и UTF-16le всегда делаются на месте и не лишают законной силы обратный указатель, хотя, конечно, содержание буфера, на который указывает обратный указатель, будет изменено. Другие виды преобразования сделаны на месте, когда это возможно, но когда-то это невозможно, и в тех случаях обратные указатели лишены законной силы.
Самое безопасное и самое легкое, чтобы помнить политику: предположите что любой результат из
Определенные пользователями функции могут быть созданы, используя следующий установленный порядок:
typedef struct sqlite3_value sqlite3_value; int sqlite3_create_function(sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int, sqlite3_value**), void (*xStep)(sqlite3_context*,int, sqlite3_value**), void (*xFinal)(sqlite3_context*)); int sqlite3_create_function16(sqlite3*, const void *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int, sqlite3_value**), void (*xStep)(sqlite3_context*,int, sqlite3_value**), void (*xFinal)(sqlite3_context*)); #define SQLITE_UTF8 1 #define SQLITE_UTF16 2 #define SQLITE_UTF16BE 3 #define SQLITE_UTF16LE 4 #define SQLITE_ANY 5
nArg определяет количество аргументов функции. 0 указывает, что любое количество аргументов позволено. eTextRep определяет то, в чем текстовые значения представления, как ожидают, будут для аргументов этой функции. Значение этого параметра должно быть одним из параметров, определенных выше. Версия 3 SQLite позволяет многократные внедрения той же самой функции, используя различные текстовые представления. Ядро базы данных выбирает функцию по логике минимизации количества требуемых текстовых преобразований.
Нормальные функции определяют только xFunc и оставляют xStep и xFinal = NULL. Агрегатные функции определяют xStep и xFinal и оставляют xFunc = NULL. Нет отдельного sqlite3_create_aggregate() API.
Имя функции определяется в UTF-8. Отдельный sqlite3_create_function16() API работает аналогично sqlite_create_function() за исключением того, что имя функции определяется в порядке байтов хоста в UTF-16.
Заметьте, что параметры функций теперь указатели на структуры sqlite3_value вместо указателей на последовательности как в версии SQLite version 2.X. Следующий установленный порядок используется, чтобы извлечь полезную информацию из этих значений:
const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); long long int sqlite3_value_int64(sqlite3_value*); const unsigned char *sqlite3_value_text(sqlite3_value*); const void *sqlite3_value_text16(sqlite3_value*); int sqlite3_value_type(sqlite3_value*);
Реализации функции используют следующий API, чтобы приобрести контекст и сообщить о результатах:
void *sqlite3_aggregate_context(sqlite3_context*, int nbyte); void *sqlite3_user_data(sqlite3_context*); void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_double(sqlite3_context*, double); void sqlite3_result_error(sqlite3_context*, const char*, int); void sqlite3_result_error16(sqlite3_context*, const void*, int); void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, long long int); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*)); void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void *sqlite3_get_auxdata(sqlite3_context*, int); void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
Следующий установленный порядок используется, чтобы осуществить определенные пользователями последовательности сопоставления:
sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*)); sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*, int, const void*)); sqlite3_collation_needed(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*)); sqlite3_collation_needed16(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*));
sqlite3_create_collation() определяет имя последовательности сопоставления и функцию сравнения, чтобы осуществить ту последовательность сопоставления. Функция сравнения используется только для сравнения текстовых значений. eTextRep это одно из SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE или SQLITE_ANY, чтобы определить, с каким текстовым представлением функция сравнения работает. Отдельные функции сравнения могут существовать для той же самой последовательности сопоставления для каждого из текстовых представлений UTF-8, UTF-16LE и UTF-16BE. sqlite3_create_collation16() работает подобно sqlite3_create_collation() за исключением того, что имя сопоставления определяется в порядке байтов хоста UTF-16 вместо UTF-8.
sqlite3_collation_needed() регистрирует отзыв, который вызовет ядро базы данных, если это столкнется с неизвестной последовательностью сопоставления. Отзыв может искать соответствующую функцию сравнения и вызвать по мере необходимости sqlite_3_create_collation(). Четвертый параметр отзыва это название последовательности сопоставления в UTF-8. Для sqlite3_collation_need16() отзыв посылает имя последовательности сопоставления в порядке байтов текущего хоста в UTF-16.