db_odbc

Обёртка для баз данных более высокого уровня.

Это тот же интерфейс, что реализован для других баз данных.

Данный модуль ЕЩЁ НЕ был (широко) протестирован с драйверами ODBC для баз данных Teradata, Oracle, Sybase, MSSqlvSvr и т. д.

В настоящее время все запросы — это вызовы ANSI, а не Unicode.

См. также: db_postgres, db_sqlite, db_mysql.

Подстановка параметров

Все модули поддерживают одинаковый вид подстановки параметров. То есть, используется символ ? (вопросительный знак) для обозначения места, куда нужно подставить значение. Например:

sql"INSERT INTO myTable (colA, colB, colC) VALUES (?, ?, ?)"

Примеры

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

import db_odbc
var db = open("localhost", "user", "password", "dbname")
db.close()

Создание таблицы

db.exec(sql"DROP TABLE IF EXISTS myTable")
db.exec(sql("""CREATE TABLE myTable (
                 id integer,
                 name varchar(50) not null)"""))

Вставка данных

db.exec(sql"INSERT INTO myTable (id, name) VALUES (0, ?)",
        "Andreas")

Крупный пример

import db_odbc, math

var theDb = open("localhost", "nim", "nim", "test")

theDb.exec(sql"Drop table if exists myTestTbl")
theDb.exec(sql("create table myTestTbl (" &
    " Id    INT(11)     NOT NULL AUTO_INCREMENT PRIMARY KEY, " &
    " Name  VARCHAR(50) NOT NULL, " &
    " i     INT(11), " &
    " f     DECIMAL(18,10))"))

theDb.exec(sql"START TRANSACTION")
for i in 1..1000:
  theDb.exec(sql"INSERT INTO myTestTbl (name,i,f) VALUES (?,?,?)",
        "Item#" & $i, i, sqrt(i.float))
theDb.exec(sql"COMMIT")

for x in theDb.fastRows(sql"select * from myTestTbl"):
  echo x

let id = theDb.tryInsertId(sql"INSERT INTO myTestTbl (name,i,f) VALUES (?,?,?)",
        "Item#1001", 1001, sqrt(1001.0))
echo "Inserted item: ", theDb.getValue(sql"SELECT name FROM myTestTbl WHERE id=?", id)

theDb.close()

Импорты

strutils, odbcsql, db_common, since

Типы

DbConn = OdbcConnTyp

инкапсулирует подключение к базе данных Исходный код Редактировать

Row = seq[string]

строка набора данных. Значения NULL базы данных будут преобразованы в nil. Исходный код Редактировать

InstantRow = tuple[row: seq[string], len: int]

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

Процедуры

proc dbError(db: var DbConn) {...}{.tags: [ReadDbEffect, WriteDbEffect],
                               raises: [DbError].}

Выбрасывает исключение [DbError] с информацией об ошибке ODBC Исходный код Редактировать

proc dbQuote(s: string): string {...}{.noSideEffect, raises: [], tags: [].}

DB цитирует строку. Исходный код Редактировать

proc tryExec(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): bool {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [].}

Пытается выполнить запрос и возвращает true, если успешно, и false в противном случае. Исходный код Редактировать

proc exec(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]) {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Выполняет запрос и выбрасывает EDB, если не удалось. Исходный код Редактировать

proc `[]`(row: InstantRow; col: int): string {...}{.inline, raises: [], tags: [].}

Возвращает текст для заданного столбца строки Исходный код Редактировать

proc unsafeColumnAt(row: InstantRow; index: int): cstring {...}{.inline, raises: [],
    tags: [].}

Исходный код Редактировать

proc len(row: InstantRow): int {...}{.inline, raises: [], tags: [].}

Возвращает количество столбцов в строке Исходный код Редактировать

proc getRow(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Получает одну строку. Если запрос не возвращает строк, эта процедура вернёт Row со строками-пустышками для каждого столбца. Исходный код Редактировать

proc getAllRows(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): seq[
    Row] {...}{.tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

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

proc getValue(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): string {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [].}

Выполняет запрос и возвращает первый столбец первой строки набора результатов. Возвращает "" если набор данных не содержит строк или значение базы данных NULL. Исходный код Редактировать

proc tryInsertId(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [].}

Выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID строки или -1 в случае ошибки. Исходный код Редактировать

proc insertId(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID строки. Исходный код Редактировать

proc tryInsert(db: var DbConn; query: SqlQuery; pkName: string;
               args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [].}

то же, что и tryInsertID Исходный код Редактировать

proc insert(db: var DbConn; query: SqlQuery; pkName: string;
            args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

то же, что и insertId Исходный код Редактировать

proc execAffectedRows(db: var DbConn; query: SqlQuery;
                      args: varargs[string, `$`]): int64 {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Выполняет запрос (обычно "UPDATE") и возвращает количество затронутых строк Исходный код Редактировать

proc close(db: var DbConn) {...}{.tags: [WriteDbEffect], raises: [].}

Закрывает подключение к базе данных. Исходный код Редактировать

proc open(connection, user, password, database: string): DbConn {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

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

Выбрасывает EDb если подключение не удалось установить.

В настоящее время параметр базы данных игнорируется, но включён для соответствия open() в других модулях библиотеки db_xxxxx.

Исходный код Редактировать

proc setEncoding(connection: DbConn; encoding: string): bool {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

В настоящее время не реализовано для ODBC.

Устанавливает кодировку подключения к базе данных, возвращает true для успешного выполнения, false — для неудачи. result = set_character_set(connection, encoding) == 0

Исходный код Редактировать

Итераторы

iterator fastRows(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Выполняет запрос и итерирует по результирующему набору данных.

Очень быстро, но потенциально опасно. Используйте этот итератор только если вам нужны ВСЕ строки.

Прерывание итератора fastRows() во время цикла может привести к ошибке драйвера при последующих запросах.

Строки извлекаются с сервера на каждой итерации.

Исходный код Редактировать

iterator instantRows(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): InstantRow {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Аналогично fastRows, но возвращает дескриптор, который может быть использован для получения текста столбца по требованию с помощью []. Возвращаемый дескриптор действителен только в теле итератора. Исходный код Редактировать

iterator rows(db: var DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

Аналогично fastRows, но медленнее и безопаснее.

Получает ВСЕ строки в память перед итерацией по строкам. Запросы с большими наборами данных повлияют на использование памяти.

Исходный код Редактировать

Экспорты

DbTypeKind, sql, DbType, SqlQuery, DbColumn, ReadDbEffect, DbError, WriteDbEffect, dbError, DbColumns, DbEffect