amysql

    Dark Mode
Search:
Group by:

This module implements (a subset of) the MySQL/MariaDB client protocol based on asyncnet and asyncdispatch.

No attempt is made to make this look like the C-language libmysql API.

Copyright (c) 2015 William Lewis Copyright (c) 2020 Bung

Types

SqlParam = object
  case typ: ParamBindingType
  of paramNull:
      nil

  of paramString, paramBlob, paramJson, paramGeometry:
      strVal: string

  of paramInt:
      intVal: int64

  of paramUInt:
      uintVal: uint64

  of paramFloat:
      floatVal: float32

  of paramDouble:
      doubleVal: float64

  of paramDate, paramDateTime, paramTimestamp:
      datetimeVal: DateTime

  of paramTime:
      durVal: Duration

  
This represents a value we're sending to the server as a parameter. Since parameters' types are always sent along with their values, we choose the wire type of integers based on the particular value we're sending each time.
SqlPrepared = ref SqlPreparedObj
Row = seq[string]
Date = object of DateTime
ResultValue = object
  case typ: ResultValueType
  of rvtInteger:
      intVal: int

  of rvtLong:
      longVal: int64

  of rvtULong:
      uLongVal: uint64

  of rvtString, rvtBlob, rvtJson, rvtGeometry:
      strVal: string

  of rvtNull:
      nil

  of rvtFloat:
      floatVal: float32

  of rvtDouble:
      doubleVal: float64

  of rvtTime:
      durVal: Duration

  of rvtDate, rvtDateTime, rvtTimestamp:
      datetimeVal: DateTime

  

Procs

proc asParam(s: string): SqlParam {...}{.raises: [], tags: [].}
proc asParam(i: int): SqlParam {...}{.raises: [], tags: [].}
proc asParam(i: uint): SqlParam {...}{.raises: [], tags: [].}
proc asParam(i: int64): SqlParam {...}{.raises: [], tags: [].}
proc asParam(i: uint64): SqlParam {...}{.raises: [], tags: [].}
proc asParam(f: float32): SqlParam {...}{.raises: [], tags: [].}
proc asParam(f: float64): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: DateTime): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: Date): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: Time): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: Duration): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: JsonNode): SqlParam {...}{.raises: [], tags: [].}
proc asParam(d: MyGeometry): SqlParam {...}{.raises: [], tags: [].}
proc asParam(b: bool): SqlParam {...}{.raises: [], tags: [].}
proc isNull(v: ResultValue): bool {...}{.inline, raises: [], tags: [].}
proc `$`(v: ResultValue): string {...}{.raises: [ValueError], tags: [].}
proc initDate(monthday: MonthdayRange; month: Month; year: int;
              zone: Timezone = local()): Date {...}{.raises: [], tags: [].}
proc prepare(conn: Connection; qs: string): Future[SqlPrepared] {...}{.
    raises: [Exception, ValueError],
    tags: [TimeEffect, RootEffect, ReadIOEffect].}
https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_com_stmt_prepare.html
proc finalize(conn: Connection; pstmt: SqlPrepared): Future[void] {...}{.
    raises: [Exception], tags: [TimeEffect, RootEffect].}
proc reset(conn: Connection; pstmt: SqlPrepared): Future[void] {...}{.
    raises: [Exception], tags: [TimeEffect, RootEffect].}
proc reset(conn: Connection): Future[ResultSet[string]] {...}{.
    raises: [Exception, ValueError],
    tags: [TimeEffect, RootEffect, ReadIOEffect].}
proc formatBoundParams(conn: Connection; pstmt: SqlPrepared;
                       params: openArray[SqlParam]): string {...}{.
    raises: [ValueError, ProtocolError], tags: [].}
see https://mariadb.com/kb/en/com_stmt_execute/
proc query(conn: Connection; pstmt: SqlPrepared;
           params: openArray[static[SqlParam]]): Future[void]
proc rawExec(conn: Connection; qs: string): Future[ResultSet[string]] {...}{.
    raises: [Exception, ValueError],
    tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc rawQuery(conn: Connection; qs: string; onlyFirst: bool = false): Future[
    ResultSet[string]] {...}{.raises: [Exception, ValueError],
                         tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc performPreparedQuery(conn: Connection; pstmt: SqlPrepared;
                          st: Future[void]; onlyFirst: static[bool] = false): Future[
    ResultSet[ResultValue]]
proc query(conn: Connection; pstmt: SqlPrepared;
           params: varargs[SqlParam, asParam]): Future[ResultSet[ResultValue]] {...}{.
    raises: [ValueError, ProtocolError, Exception],
    tags: [TimeEffect, RootEffect, ReadIOEffect, WriteIOEffect].}
proc selectDatabase(conn: Connection; database: string): Future[ResponseOK] {...}{.
    raises: [Exception, ValueError],
    tags: [TimeEffect, RootEffect, ReadIOEffect].}
proc exec(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    ResultSet[string]] {...}{.raises: [Exception, ValueError],
                         tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc query(conn: Connection; qs: SqlQuery; onlyFirst: static[bool] = false;
           args: varargs[string, `$`]): Future[ResultSet[string]]
proc tryQuery(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    bool] {...}{.raises: [Exception, ValueError],
            tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc getRow(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    Row] {...}{.raises: [Exception, ValueError],
           tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc getAllRows(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    seq[Row]] {...}{.raises: [Exception, ValueError],
                tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc getValue(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    string] {...}{.raises: [Exception, ValueError],
              tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc tryInsertId(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    int64] {...}{.raises: [Exception, ValueError],
             tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc insertId(conn: Connection; qs: SqlQuery; args: varargs[string, `$`]): Future[
    int64] {...}{.raises: [Exception, ValueError],
             tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc tryInsert(conn: Connection; qs: SqlQuery; pkName: string;
               args: varargs[string, `$`]): Future[int64] {...}{.
    raises: [Exception, ValueError],
    tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc insert(conn: Connection; qs: SqlQuery; pkName: string;
            args: varargs[string, `$`]): Future[int64] {...}{.
    raises: [Exception, ValueError],
    tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc setEncoding(conn: Connection; encoding: string): Future[bool] {...}{.
    raises: [Exception, ValueError],
    tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
sets the encoding of a database connection, returns true for success, false for failure.
proc startTransaction(conn: Connection): owned(Future[void]) {...}{.inline,
    raises: [Exception], tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc commit(conn: Connection): owned(Future[void]) {...}{.inline,
    raises: [Exception], tags: [WriteIOEffect, RootEffect, ReadIOEffect].}
proc rollback(conn: Connection): owned(Future[void]) {...}{.inline,
    raises: [Exception], tags: [WriteIOEffect, RootEffect, ReadIOEffect].}

Converters

converter asInt8(v: ResultValue): int8 {...}{.raises: [ValueError], tags: [].}
converter asInt(v: ResultValue): int {...}{.raises: [ValueError], tags: [].}
converter asUInt(v: ResultValue): uint {...}{.raises: [ValueError], tags: [].}
converter asInt64(v: ResultValue): int64 {...}{.raises: [ValueError], tags: [].}
converter asUint64(v: ResultValue): uint64 {...}{.raises: [ValueError], tags: [].}
converter asFloat(v: ResultValue): float32 {...}{.raises: [ValueError], tags: [].}
converter asDouble(v: ResultValue): float64 {...}{.raises: [ValueError], tags: [].}
converter asString(v: ResultValue): string {...}{.raises: [ValueError], tags: [].}
converter asDateTime(v: ResultValue): DateTime {...}{.raises: [ValueError], tags: [].}
converter asDate(v: ResultValue): Date {...}{.raises: [], tags: [].}
converter asTime(v: ResultValue): Time {...}{.raises: [ValueError], tags: [].}
converter asDuration(v: ResultValue): Duration {...}{.raises: [ValueError], tags: [].}
converter asMyGeometry(v: ResultValue): MyGeometry {...}{.raises: [ValueError],
    tags: [].}
converter asBool(v: ResultValue): bool {...}{.raises: [ValueError], tags: [].}
converter asJson(v: ResultValue): JsonNode {...}{.
    raises: [IOError, OSError, JsonParsingError, ValueError, Exception],
    tags: [ReadIOEffect, WriteIOEffect].}

Macros

macro asParam(s: untyped): untyped

Templates

template transaction(conn: typed; process: untyped)
experimental

Exports

ResponseAuthSwitch, scanU32, FieldType, fieldTypeLongLong, isExtraAuthDataPacket, fieldTypeLongBlob, putTime, fieldTypeBit, ResponseCode_LOCAL_INFILE, receiveMetadata, fieldTypeSet, fieldTypeInt24, isAuthSwitchRequestPacket, putValue, readLenStr, readDateTime, putDate, ResponseCode_EOF, fieldTypeTimestamp, fieldTypeNull, sendPacket, writeHandshakeResponse, parseOKPacket, ResponseCode_ExtraAuthData, Charset_utf8_ci, isERRPacket, SessionStateType, isLocalInfileRequestPacket, processMetadata, putDouble, isEOF, roundtrip, putNulString, hexdump, scanU64, fieldTypeEnum, fieldTypeGeometry, isEOFPacket, putLenStr, fieldTypeDecimal, putDateTime, scanFloat, NullColumn, amysql/private/protocol, ResponseERR, readNulStringX, isOKPacket, setInt32, fieldTypeYear, fieldTypeFloat, fieldTypeVarString, Command, ResponseCode_AuthSwitchRequest, writeTypeAndFlag, HandshakePacket, fieldTypeNewDecimal, readLenInt, readNulString, readTime, putS64, SessionState, putU32, sendFile, putTimestamp, fieldTypeVarchar, putValue, isEOFPacketFollowed, CursorType, ResponseCode_OK, receivePacket, sendQuery, fieldTypeShort, ResponseCode_ERR, writeTypeAndFlag, fieldTypeTime, ResponseAuthMore, fieldTypeJson, putU64, fieldTypeDate, fieldTypeBlob, parseErrorPacket, parseAuthSwitchPacket, countLenInt, FieldFlag, ResponseOK, parseHandshakePacket, sendEmptyPacket, writeTypeAndFlag, fieldTypeLong, parseResponseAuthMorePacket, putLenInt, scanU16, putU16, putFloat, fieldTypeDouble, fieldTypeString, putU8, parseLocalInfileRequestPacket, checkEof, fieldTypeDateTime, fieldTypeMediumBlob, fieldTypeTinyBlob, ResultSet, parseEOFPacket, fieldTypeTiny, ColumnDefinition, scanDouble, ConnectionObj, incPos, remainPacketLen, toBoolean, <, ==, <=, firstByte, >, isMaria, getDatabaseVersion, Version, $, $, BasicClientCaps, resetPacketLen, amysql/conn, Connection, TestWhileIdle, zstdAvailable, zeroPos, printBufInfo, getPayloadLen, use_zstd, MysqlBufSize, open, establishConnection, close, open, amysql/conn_connection, sqlFormat, amysql/private/json_sql_format, srid, ==, data, fromWkb, MyGeometry, wkb, amysql/private/my_geometry, newMyGeometry, dbQuote, amysql/private/quote, ProtocolError, amysql/private/errors