src/db_connector/db_mysql

Обёртка для базы данных mySQL более высокого уровня. Аналогичный интерфейс реализован и для других баз данных.

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

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

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

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

Примеры

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

import db_connector/db_mysql
let 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, ?)",
        "Dominik")

Пример большего размера

import db_connector/db_mysql
import std/math

let 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()

Импорты

mysql, db_common, dbutils

Типы

DbConn = distinct PMySQL

оборачивает соединение с базой данных

InstantRow = object

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

Row = seq[string]

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

Процедуры

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

Возвращает текст заданного столбца строки.

proc close(db: DbConn) {....tags: [DbEffect], raises: [], forbids: [].}

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

proc dbError(db: DbConn) {.noreturn, ...raises: [DbError], tags: [], forbids: [].}

генерирует исключение DbError.

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

Приводит строку к формату базы данных. Обратите внимание, что это не экранирует % и _.

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

выполняет запрос и генерирует исключение EDB, если запрос не успешен.

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

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

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

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

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

извлекает одну строку. Если запрос не возвращает строк, эта процедура вернёт строку с пустыми строками для каждого столбца.

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

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

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

то же, что и insertId

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

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

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

Возвращает количество столбцов в строке.

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

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

proc setEncoding(connection: DbConn; encoding: string): bool {....tags: [DbEffect],
    raises: [], forbids: [].}

устанавливает кодировку соединения с базой данных, возвращает true при успехе, false - при неудаче.

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

пытается выполнить запрос и возвращает true при успехе, false - в противном случае.

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

то же, что и tryInsertID

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

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

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

Возвращает строку заданного столбца строки

Итераторы

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

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

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

Прерывание итератора fastRows() во время цикла приведёт к тому, что следующий запрос к базе данных вызовет исключение EDb Commands out of sync.

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

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

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

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

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

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