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
Consts
ResetConnection = true
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].}
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