basis/db/types/types-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel strings ;
   4 IN: db.types
   5
   6 HELP: +db-assigned-id+
   7 { $description "The database assigns a primary key to the object. The primary key is most likely a big integer, but is database-dependent." } ;
   8
   9 HELP: +default+
  10 { $description "Allows a default value for a column to be provided." } ;
  11
  12 HELP: +foreign-id+
  13 { $description "Makes the column a foreign key, referencing a column in another table." } ;
  14
  15 HELP: +not-null+
  16 { $description "Ensures that a column is not null." } ;
  17
  18 HELP: +null+
  19 { $description "Allows a column to be null." } ;
  20
  21 HELP: +primary-key+
  22 { $description "Makes a column a primary key. Only one column may be a primary key." } ;
  23
  24 HELP: +random-id+
  25 { $description "Factor chooses a random number and tries to insert the tuple into the database with this number as its primary key. The default number of retries to find a unique random number is 10, though in practice it will almost certainly succeed on the first try." } ;
  26
  27 HELP: +user-assigned-id+
  28 { $description "The user is responsible for choosing a primary key for tuples inserted with this database type. Keys must be unique or else the database will throw an error. Usually it is better to use a " { $link +db-assigned-id+ } "." } ;
  29
  30 HELP: <generator-bind>
  31 { $values { "slot-name" object } { "key" object } { "generator-singleton" object } { "type" object } { "generator-bind" generator-bind } }
  32 { $description "An internal constructor for creating objects containing parameters used for binding generated values to a tuple query." } ;
  33
  34 HELP: <literal-bind>
  35 { $values { "key" object } { "type" object } { "value" object } { "literal-bind" literal-bind } }
  36 { $description "An internal constructor for creating objects containing parameters used for binding literal values to a tuple query." } ;
  37
  38 HELP: BIG-INTEGER
  39 { $description "A 64-bit integer. Whether this number is signed or unsigned depends on the database backend." } ;
  40
  41 HELP: BLOB
  42 { $description "A byte array." } ;
  43
  44 HELP: BOOLEAN
  45 { $description "Either true or false." } ;
  46
  47 HELP: DATE
  48 { $description "A date without a time component." } ;
  49
  50 HELP: DATETIME
  51 { $description "A date and a time." } ;
  52
  53 HELP: DOUBLE
  54 { $description "Corresponds to Factor's 64-bit floating-point numbers." } ;
  55
  56 HELP: FACTOR-BLOB
  57 { $description "A serialized Factor object." } ;
  58
  59 HELP: INTEGER
  60 { $description "A small integer, at least 32 bits in length. Whether this number is signed or unsigned depends on the database backend." } ;
  61
  62 HELP: NULL
  63 { $description "The SQL null type." } ;
  64
  65 HELP: REAL
  66 { $description "A real number of unlimited precision. May not be supported on all databases." } ;
  67
  68 HELP: SIGNED-BIG-INTEGER
  69 { $description "For portability, if a number is known to be 64bit and signed, then this datatype may be used. Some databases, like SQLite, cannot store arbitrary bignums as BIGINT types. If storing arbitrary bignums, use " { $link FACTOR-BLOB } "." } ;
  70
  71 HELP: TEXT
  72 { $description "Stores a string that is longer than a " { $link VARCHAR } ". SQLite uses this type for strings; it does not handle " { $link VARCHAR } " strings." } ;
  73
  74 HELP: TIME
  75 { $description "A timestamp without a date component." } ;
  76
  77 HELP: TIMESTAMP
  78 { $description "A Factor timestamp." } ;
  79
  80 HELP: UNSIGNED-BIG-INTEGER
  81 { $description "For portability, if a number is known to be 64bit, then this datatype may be used. Some databases, like SQLite, cannot store arbitrary bignums as BIGINT types. If storing arbitrary bignums, use " { $link FACTOR-BLOB } "." } ;
  82
  83 { INTEGER SIGNED-BIG-INTEGER UNSIGNED-BIG-INTEGER } related-words
  84
  85 HELP: URL
  86 { $description "A Factor " { $link "urls" } " object." } ;
  87
  88 HELP: VARCHAR
  89 { $description "The SQL varchar type. This type can take an integer as an argument." }
  90 { $examples { $unchecked-example "{ VARCHAR 256 }" "" } } ;
  91
  92 HELP: user-assigned-id-spec?
  93 { $values
  94     { "specs" "a sequence of SQL specs" }
  95     { "?" boolean } }
  96 { $description "Tests if any of the SQL specs has the type " { $link +user-assigned-id+ } "." } ;
  97
  98 HELP: bind#
  99 { $values
 100     { "spec" "an SQL spec" } { "obj" object } }
 101 { $description "A generic word that lets a database construct a literal binding." } ;
 102
 103 HELP: bind%
 104 { $values
 105     { "spec" "an SQL spec" } }
 106 { $description "A generic word that lets a database output a binding." } ;
 107
 108 HELP: db-assigned-id-spec?
 109 { $values
 110     { "specs" "a sequence of SQL specs" }
 111     { "?" boolean } }
 112 { $description "Tests if any of the SQL specs has the type " { $link +db-assigned-id+ } "." } ;
 113
 114 HELP: find-primary-key
 115 { $values
 116     { "specs" "a sequence of SQL specs" }
 117     { "seq" "a sequence of SQL specs" } }
 118 { $description "Returns the rows from the SQL specs array that are part of the primary key. Composite primary keys are supported, so this word must return a sequence." }
 119 { $notes "This is a low-level word." } ;
 120
 121 HELP: no-sql-type
 122 { $values
 123     { "type" "an SQL type" } }
 124 { $description "Throws an error containing an SQL type that is unsupported or the result of a typo." } ;
 125
 126 HELP: normalize-spec
 127 { $values
 128     { "spec" "an SQL spec" } }
 129 { $description "Normalizes an SQL spec." } ;
 130
 131 HELP: primary-key?
 132 { $values
 133     { "spec" "an SQL spec" }
 134     { "?" boolean } }
 135 { $description "Returns true if an SQL spec is a primary key." } ;
 136
 137 HELP: relation?
 138 { $values
 139     { "spec" "an SQL spec" }
 140     { "?" boolean } }
 141 { $description "Returns true if an SQL spec is a relation." } ;
 142
 143 HELP: unknown-modifier
 144 { $values { "modifier" string } }
 145 { $description "Throws an error containing an unknown SQL modifier." } ;
 146
 147 ARTICLE: "db.types" "Database types"
 148 "The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
 149 "Primary and foreign keys:"
 150 { $subsections
 151     +db-assigned-id+
 152     +foreign-id+
 153     +primary-key+
 154     +user-assigned-id+
 155     +random-id+
 156 }
 157 "Null and boolean types:"
 158 { $subsections
 159     NULL
 160     BOOLEAN
 161 }
 162 "Text types:"
 163 { $subsections
 164     VARCHAR
 165     TEXT
 166 }
 167 "Number types:"
 168 { $subsections
 169     INTEGER
 170     BIG-INTEGER
 171     SIGNED-BIG-INTEGER
 172     UNSIGNED-BIG-INTEGER
 173     DOUBLE
 174     REAL
 175 }
 176 "Calendar types:"
 177 { $subsections
 178     DATE
 179     DATETIME
 180     TIME
 181     TIMESTAMP
 182 }
 183 "Factor byte-arrays:"
 184 { $subsections BLOB }
 185 "Arbitrary Factor objects:"
 186 { $subsections FACTOR-BLOB }
 187 "Factor URLs:"
 188 { $subsections URL } ;
 189
 190 ABOUT: "db.types"