db_postgres

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

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

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

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

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

Примечание: Существует два подхода к поддержке подстановки параметров этим модулем.

1. SqlQuery с использованием ?, ?, ?, ... (так же, как и во всех модулях db_*)

2. SqlPrepared с использованием $1, $2, $3, ...

prepare(db, "myExampleInsert",
        sql"""INSERT INTO myTable
              (colA, colB, colC)
              VALUES ($1, $2, $3)""",
        3)

Сокет Unix

Использование сокетов Unix вместо TCP-соединения может улучшить производительность до 30% ~ 175% для некоторых операций.

Чтобы использовать сокеты Unix с db_postgres, измените адрес сервера на путь к файлу сокета:

import db_postgres ## Change "localhost" or "127.0.0.1" to the socket file path
let db = db_postgres.open("/run/postgresql", "user", "password", "database")
echo db.getAllRows(sql"SELECT version();")
db.close()

Путь к файлу сокета зависит от операционной системы и дистрибутива, дополнительная настройка может потребоваться на вашей postgresql.conf. Сервер PostgreSQL должен находиться на том же компьютере и работает только для операционных систем семейства Unix.

Примеры

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

import db_postgres
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")

Импорты

strutils, postgres, db_common, since

Типы

DbConn = PPGconn

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

Row = seq[string]

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

InstantRow = object
  res: PPGresult             ## used to get a row's
  line: int                  ## column text on demand

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

SqlPrepared = distinct string

идентификатор подготовленных запросов Исходный код Редактировать

Процедуры

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: [DbError].}

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

proc tryExec(db: DbConn; stmtName: SqlPrepared; 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 exec(db: DbConn; stmtName: SqlPrepared; args: varargs[string]) {...}{.
    tags: [ReadDbEffect, WriteDbEffect], raises: [DbError].}

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

proc prepare(db: DbConn; stmtName: string; query: SqlQuery; nParams: int): SqlPrepared {...}{.
    raises: [DbError], tags: [].}

Создает новое SqlPrepared утверждение. Подстановка параметров выполняется через $1, $2, $3, и т.д. Исходный код Редактировать

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].}

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

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

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

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

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

proc getAllRows(db: DbConn; stmtName: SqlPrepared; 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 getValue(db: DbConn; stmtName: SqlPrepared; args: varargs[string, `$`]): string {...}{.
    tags: [ReadDbEffect], raises: [DbError].}

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

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

выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID для строки или -1 в случае ошибки. Для Postgre это добавляет RETURNING id к запросу, поэтому работает только если ваш первичный ключ назван id. Исходный код Редактировать

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

выполняет запрос (обычно "INSERT") и возвращает сгенерированный ID для строки. Для Postgre это добавляет RETURNING id к запросу, поэтому работает только если ваш первичный ключ назван id. Исходный код Редактировать

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

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

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

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

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

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

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

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

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

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

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

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

Клиенты также могут использовать строки подключения PostgreSQL с ключевыми словами/значениями для подключения.

Пример:

con = open("", "", "", "host=localhost port=5432 dbname=mydb")

См. http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING для получения дополнительной информации.

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

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].}

выполняет запрос и итерирует по набору результатов. Это очень быстро, но потенциально опасно: Если тело цикла for выполнит другой запрос, результаты могут быть неопределенными. Для PostgreSQL это безопасно. Исходный код Редактировать

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

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

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

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

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

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

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

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

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

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

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

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

Экспорт

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