# src/db_connector/db_common

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:

Note: In order to use this module, run `nimble install db_connector`.

Common datatypes and definitions for all `db_*.nim` ( db_mysql, db_postgres, and db_sqlite) modules.

# Types

    DbColumn = object
      name*: string              ## name of the column
      tableName*: string         ## name of the table the column belongs to (optional)
      typ*: DbType               ## type of the column
      primaryKey*: bool          ## is this a primary key?
      foreignKey*: bool          ## is this a foreign key?

  information about a database column

    DbColumns = seq[DbColumn]

    DbEffect = object of IOEffect

  effect that denotes a database operation

    DbError = object of IOError

  exception that is raised if a database error occurs

    DbType = object
      kind*: DbTypeKind          ## the kind of the described type
      notNull*: bool             ## does the type contain NULL?
      name*: string              ## the name of the type
      size*: Natural             ## the size of the datatype; 0 if of variable size
      maxReprLen*: Natural       ## maximal length required for the representation
      precision*, scale*: Natural ## precision and scale of the number
      min*, max*: BiggestInt     ## the minimum and maximum of allowed values
      validValues*: seq[string]  ## valid values of an enum or a set

  describes a database type

    DbTypeKind = enum
      dbUnknown,                ## unknown datatype
      dbSerial,                 ## datatype used for primary auto-increment keys
      dbNull,                   ## datatype used for the NULL value
      dbBit,                    ## bit datatype
      dbBool,                   ## boolean datatype
      dbBlob,                   ## blob datatype
      dbFixedChar,              ## string of fixed length
      dbVarchar,                ## string datatype
      dbJson,                   ## JSON datatype
      dbXml,                    ## XML datatype
      dbInt,                    ## some integer type
      dbUInt,                   ## some unsigned integer type
      dbDecimal,                ## decimal numbers (fixed-point number)
      dbFloat,                  ## some floating point type
      dbDate,                   ## a year-month-day description
      dbTime,                   ## HH:MM:SS information
      dbDatetime,               ## year-month-day and HH:MM:SS information,
                                 ## plus optional time or timezone information
      dbTimestamp, ## Timestamp values are stored as the number of seconds
                    ## since the epoch ('1970-01-01 00:00:00' UTC).
      dbTimeInterval,           ## an interval [a,b] of times
      dbEnum,                   ## some enum
      dbSet,                    ## set of enum values
      dbArray,                  ## an array of values
      dbComposite,              ## composite type (record, struct, etc)
      dbUrl,                    ## a URL
      dbUuid,                   ## a UUID
      dbInet,                   ## an IP address
      dbMacAddress,             ## a MAC address
      dbGeometry,               ## some geometric type
      dbPoint,                  ## Point on a plane   (x,y)
      dbLine,                   ## Infinite line ((x1,y1),(x2,y2))
      dbLseg,                   ## Finite line segment   ((x1,y1),(x2,y2))
      dbBox,                    ## Rectangular box   ((x1,y1),(x2,y2))
      dbPath,                   ## Closed or open path (similar to polygon) ((x1,y1),...)
      dbPolygon,                ## Polygon (similar to closed path)   ((x1,y1),...)
      dbCircle,                 ## Circle   <(x,y),r> (center point and radius)
      dbUser1,                  ## user definable datatype 1 (for unknown extensions)
      dbUser2,                  ## user definable datatype 2 (for unknown extensions)
      dbUser3,                  ## user definable datatype 3 (for unknown extensions)
      dbUser4,                  ## user definable datatype 4 (for unknown extensions)
      dbUser5                    ## user definable datatype 5 (for unknown extensions)

  a superset of datatypes that might be supported.

    ReadDbEffect = object of DbEffect

  effect that denotes a read operation

    SqlQuery = distinct string

  an SQL query string

    WriteDbEffect = object of DbEffect

  effect that denotes a write operation

# Procs

    proc dbError(msg: string) {.noreturn, noinline, ...raises: [DbError], tags: [],
                                forbids: [].}

  raises an DbError exception with message `msg`.

# Templates

    template sql(query: string): SqlQuery

  constructs a SqlQuery from the string `query`. This is supposed to be used as a raw-string-literal modifier: `sql"update user set counter = counter + 1"`

  If assertions are turned off, it does nothing. If assertions are turned on, later versions will check the string for valid syntax.