protocol.txt

   1 When the client connects, the authentication phase starts. To start,
   2 there will be only one authentication mechanism: SQLSERVER. The client
   3 sends an AUTH command selecting SQLSERVER, with an initial response of
   4 <username-in-UTF8> '\0' <password-in-UTF8>. This is then encoded as a
   5 hex string (as specified by the D-Bus spec) to be sent. The server
   6 will then respond with either OK or ERROR as appropriate.
   7
   8 Authentication will happen by either creating a new connection to the
   9 SQL server (if no pooled connections exist) or looking up the pool
  10 that corresponds to the username and comparing the password given. If
  11 this fails, it will try opening a new connection to the SQL server in
  12 case the password changed (if so, replacing the existing stored
  13 password in the pool). Existing connections will be left alone in this
  14 case.
  15
  16 Authorization at this point is just that all queries are guaranteed to
  17 pass through a connection that is attached to the username that was
  18 used when authenticating. The SQL server will enforce
  19 table/view/procedure permissions, etc.
  20
  21 The API itself is really simple right now:
  22
  23 Operations on node /db
  24 Interface name is vx.db
  25
  26 ExecNoResult(string query IN)
  27 - Will throw a vx.db.sqlerror error (with the error
  28 text being the complaint by the SQL server) in case of error
  29
  30 ExecScalar(string query IN, variant result OUT)
  31 - Will throw a vx.db.sqlerror error (with the error
  32 text being the complaint by the SQL server) in case of error
  33 - The maximum amount of data that can be received this way is 16MB.
  34 There is a vx.db.toomuchdata error for this
  35
  36 ExecRecordset(string query IN, VxColumnInfo[] colinfo OUT,
  37         variant data OUT, byte[][] nullity OUT)
  38 - Will throw a vx.db.sqlerror error (with the error
  39 text being the complaint by the SQL server) in case of error
  40 - will throw a vx.db.badschema error if unable to
  41 represent the results
  42 - Null values are specified by the byte being 1; non-null values are
  43 specified by the byte being 0. The data itself is in the variant.
  44 * Note: Using a byte so that less space is wasted -- booleans are
  45 32-bit and require 4-byte alignmen
  46 - Data is in row-major order
  47 - The variant that holds the data is an array of a struct that varies
  48 based on the query: each field in the struct is a column in the result
  49 set. In D-Bus terms, the signature of the variant is "a(...)" where
  50 "..." varies. The array may have length zero.
  51 - The maximum amount of data that can be received this way is 16MB.
  52 There is a vx.db.toomuchdata error for this.
  53 - VxColumnInfo is a struct in the form "a(issnny)"
  54   int32 Column size
  55   string Column name
  56   string Column type
  57   int16 Numeric precision
  58   int16 Numeric scale
  59   uint8 Nullability
  60     - This is a bitfield with only one bit defined:
  61       0x1 = is nullable
  62
  63 For this API, there are no guarantees that a series of queries will
  64 run through the same connection (so no transactions, temporary tables,
  65 or the like)... unless this is actually necessary. I have some ideas
  66 for how transactions could be done but that complexity seems to be
  67 unnecessary at this point. It will need to be extended anyway to
  68 support bigger recordsets.
  69
  70 Column types (names are case-insensitive):
  71 "int64" (sent as a dbus int64, format "x"): MSSQL bigint
  72 "int32" (sent as a dbus int32, format "i"): MSSQL int
  73 "int16" (sent as a dbus int16, format "n"): MSSQL smallint
  74 "uint8" (sent as a dbus byte, format "y"): MSSQL tinyint
  75 "bool" (sent as a dbus boolean, format "b"): MSSQL bit
  76 "double" (sent as a dbus double, format "d"): MSSQL float, real
  77 * There is no dbus float, so those are converted to double
  78 "uuid" (sent as a dbus string, format "s"; sent in canonical form [hex
  79 with dashes in particular spots]): MSSQL uniqueidentifier
  80
  81 "binary" (sent as dbus array of bytes, format "ay"): MSSQL binary,
  82 varbinary, image, timestamp
  83
  84 "string" (sent as a dbus string, format "s"; UTF-8 encoding): MSSQL
  85 char, varchar, text, nchar, nvarchar, ntext, xml
  86 * Need to figure out what to do with non-ascii characters in
  87 char/varchar/text (presumably MSSQL will suggest some encoding that
  88 the database was configured as).
  89
  90 "datetime" (sent as dbus struct of int64 & int32, format "(xi)"; same
  91 format as struct timeval: first is seconds since unix epoch, second is
  92 microseconds (always nonnegative); timezone is not specified): MSSQL datetime,
  93 smalldatetime
  94
  95 "decimal" (sent as dbus string, format "s"): MSSQL decimal, numeric,
  96 money, smallmoney
  97 * Acceptable if of the form: ^[+-]?[0-9]*(\.[0-9]*)?$
  98 * If no +/- is provided, assume +
  99 * "-0" == "+0" == "0"
 100 * That regex matches "". I declare that "" is zero.
 101 * Although this allows for an arbitrary (but finite due to string
 102 length limits) number of leading or trailing zeros, they should be
 103 avoided for efficiency reasons.
 104 * What's recommended to be actually sent:
 105  - Zero is "0"
 106  - Within (0,1), it's "0.xy" where x is [0-9]*, y is [1-9]
 107  - Within (-1,0), it's "-0.xy" where x and y are as above
 108  - ".xy" and "-.xy" should be considered OK as well
 109  - Otherwise, numbers should be of the form "yx.xy" or "-yx.xy"