db_mysql

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

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

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

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

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

Примеры

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

import 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_mysql, 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()

Импорты

strutils, mysql, db_common, since

Типы

DbConn = distinct PMySQL: инкапсулирует подключение к базе данных Исходный код Редактировать
Row = seq[string]: строка набора данных. Значения NULL базы данных будут преобразованы в nil. Исходный код Редактировать
InstantRow = object row: cstringArray len: int: дескриптор, который можно использовать для получения текста столбца строки по требованию Исходный код Редактировать

Процедуры

proc dbError(db: DbConn) {...}{.noreturn, raises: [DbError], tags: [].}: вызывает исключение DbError. Исходный код Редактировать
proc dbQuote(s: string): string {...}{.raises: [], tags: [].}: база данных приводит строку в кавычки. Исходный код Редактировать
proc tryExec(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): bool {...}{. tags: [ReadDbEffect, WriteDbEffect], raises: [].}: пытается выполнить запрос и возвращает true, если успешно, иначе false. Исходный код Редактировать
proc exec(db: 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: [].}: Возвращает cstring заданного столбца строки Исходный код Редактировать
proc len(row: InstantRow): int {...}{.inline, raises: [], tags: [].}: Возвращает количество столбцов в строке. Исходный код Редактировать
proc getRow(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): Row {...}{. tags: [ReadDbEffect], raises: [DbError].}: Извлекает одну строку. Если запрос не возвращает никаких строк, эта процедура вернёт строку с пустыми строками для каждого столбца. Исходный код Редактировать
proc getAllRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): seq[ Row] {...}{.tags: [ReadDbEffect], raises: [DbError].}: выполняет запрос и возвращает весь результирующий набор данных. Исходный код Редактировать
proc getValue(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): string {...}{. tags: [ReadDbEffect], raises: [DbError].}: выполняет запрос и возвращает первый столбец первой строки результирующего набора данных. Возвращает "" если набор данных не содержит строк или значение базы данных NULL. Исходный код Редактировать
proc tryInsertId(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{. tags: [WriteDbEffect], raises: [].}: выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID для строки или -1 в случае ошибки. Исходный код Редактировать
proc insertId(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{. tags: [WriteDbEffect], raises: [DbError].}: выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID для строки. Исходный код Редактировать
proc tryInsert(db: DbConn; query: SqlQuery; pkName: string; args: varargs[string, `$`]): int64 {...}{.tags: [WriteDbEffect], raises: [].}: то же самое, что и tryInsertID Исходный код Редактировать
proc insert(db: DbConn; query: SqlQuery; pkName: string; args: varargs[string, `$`]): int64 {...}{.tags: [WriteDbEffect], raises: [DbError].}: то же самое, что и insertId Исходный код Редактировать
proc execAffectedRows(db: DbConn; query: SqlQuery; args: varargs[string, `$`]): int64 {...}{. tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}: выполняет запрос (обычно "UPDATE") и возвращает количество затронутых строк Исходный код Редактировать
proc close(db: DbConn) {...}{.tags: [DbEffect], raises: [].}: закрывает подключение к базе данных. Исходный код Редактировать
proc open(connection, user, password, database: string): DbConn {...}{. tags: [DbEffect], raises: [DbError, ValueError].}: открывает подключение к базе данных. Вызывает EDb если соединение не удалось установить. Исходный код Редактировать
proc setEncoding(connection: DbConn; encoding: string): bool {...}{.tags: [DbEffect], raises: [].}: устанавливает кодировку подключения к базе данных, возвращает true при успехе, false при ошибке. Исходный код Редактировать

Итераторы

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

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

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

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

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

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

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

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

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

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

Экспорты

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