basis/db/tuples/tuples-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes help.markup help.syntax io.streams.string kernel
   4 quotations sequences strings multiline math db.types db ;
   5 IN: db.tuples
   6
   7 HELP: create-sql-statement
   8 { $values
   9      { "class" class }
  10      { "object" object } }
  11 { $description "Generates the SQL code for creating a table for a given class." } ;
  12
  13 HELP: drop-sql-statement
  14 { $values
  15      { "class" class }
  16      { "object" object } }
  17 { $description "Generates the SQL code for dropping a table for a given class." } ;
  18
  19 HELP: insert-tuple-set-key
  20 { $values
  21      { "tuple" tuple } { "statement" statement } }
  22 { $description "Inserts a tuple and sets its primary key in one word. This is necessary for some databases." } ;
  23
  24 HELP: <count-statement>
  25 { $values
  26      { "query" query }
  27      { "statement" statement } }
  28 { $description "A database-specific hook for generating the SQL for a count statement." } ;
  29
  30 HELP: <delete-tuples-statement>
  31 { $values
  32      { "tuple" tuple } { "class" class }
  33      { "object" object } }
  34 { $description "A database-specific hook for generating the SQL for an delete statement." } ;
  35
  36 HELP: <insert-db-assigned-statement>
  37 { $values
  38      { "class" class }
  39      { "object" object } }
  40 { $description "A database-specific hook for generating the SQL for an insert statement with a database-assigned primary key." } ;
  41
  42 HELP: <insert-user-assigned-statement>
  43 { $values
  44      { "class" class }
  45      { "object" object } }
  46 { $description "A database-specific hook for generating the SQL for an insert statement with a user-assigned primary key." } ;
  47
  48 HELP: <select-by-slots-statement>
  49 { $values
  50      { "tuple" tuple } { "class" class }
  51      { "tuple" tuple } }
  52 { $description "A database-specific hook for generating the SQL for a select statement." } ;
  53
  54 HELP: <update-tuple-statement>
  55 { $values
  56      { "class" class }
  57      { "object" object } }
  58 { $description "A database-specific hook for generating the SQL for an update statement." } ;
  59
  60
  61 HELP: define-persistent
  62 { $values
  63      { "class" class } { "table" string } { "columns" "an array of slot specifiers" } }
  64 { $description "Defines a relation from a Factor " { $snippet "tuple class" } " to a SQL database table name. The format for the slot specifiers is as follows:"
  65 { $list
  66     { "a slot name from the " { $snippet "tuple class" } }
  67     { "the name of a database column that maps to the slot" }        { "a database type (see " { $link "db.types" } ")" }
  68 } "Throws an error if the slot name (column one from each row) is not a slot in the tuple or its superclases." }
  69 { $examples
  70     { $unchecked-example "USING: db.tuples db.types ;"
  71         "TUPLE: boat id year name ;"
  72         "boat \"BOAT\" {"
  73         "    { \"id\" \"ID\" +db-assigned-id+ }"
  74         "    { \"year\" \"YEAR\" INTEGER }"
  75         "    { \"name\" \"NAME\" TEXT }"
  76         "} define-persistent"
  77         ""
  78     }
  79 } ;
  80
  81 HELP: create-table
  82 { $values
  83      { "class" class } }
  84 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If the table already exists, the database will likely throw an error." } ;
  85
  86 HELP: ensure-table
  87 { $values
  88      { "class" class } }
  89 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If the table already exists, the error is silently ignored." } ;
  90
  91 HELP: ensure-tables
  92 { $values
  93      { "classes" "a sequence of classes" } }
  94 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If a table already exists, the error is silently ignored." } ;
  95
  96 HELP: recreate-table
  97 { $values
  98      { "class" class } }
  99 { $description "Drops an existing table and re-creates it from a mapping defined by " { $link define-persistent } ". If the table does not exist the error is silently ignored." }
 100 { $warning { $emphasis "THIS WORD WILL DELETE YOUR DATA." } $nl
 101 " Use " { $link ensure-table } " unless you want to delete the data in this table." } ;
 102
 103 { create-table ensure-table ensure-tables recreate-table } related-words
 104
 105 HELP: drop-table
 106 { $values
 107      { "class" class } }
 108 { $description "Drops an existing table which deletes all of the data. The database will probably throw an error if the table does not exist." }
 109 { $warning { $emphasis "THIS WORD WILL DELETE YOUR DATA." } } ;
 110
 111 HELP: insert-tuple
 112 { $values
 113      { "tuple" tuple } }
 114 { $description "Inserts a tuple into a database if a relation has been defined with " { $link define-persistent } ". If a mapping states that the database assigns a primary key to the tuple, this value will be set after this word runs." }
 115 { $notes "Objects should only be inserted into a database once per object. To store the object after the initial insert, call " { $link update-tuple } "." } ;
 116
 117 HELP: update-tuple
 118 { $values
 119      { "tuple" tuple } }
 120 { $description "Updates a tuple that has already been inserted into a database. The tuple must have a primary key that has been set by " { $link insert-tuple } " or that is user-defined." } ;
 121
 122 HELP: delete-tuples
 123 { $values
 124      { "tuple" tuple } }
 125 { $description "Uses the " { $snippet "tuple" } " as an exemplar object and deletes any objects that have the same slots set. If a slot is not " { $link f } ", then it is used to generate a SQL statement that deletes tuples." }
 126 { $warning "This word will delete your data." } ;
 127
 128 { insert-tuple update-tuple delete-tuples } related-words
 129
 130 HELP: select-tuple
 131 { $values
 132      { "query/tuple" tuple }
 133      { "tuple/f" "a tuple or f" } }
 134 { $description "A SQL query is constructed from the slots of the exemplar tuple that are not " { $link f } ". Returns a single tuple from the database if it matches the query constructed from the exemplar tuple." } ;
 135
 136 HELP: select-tuples
 137 { $values
 138      { "query/tuple" tuple }
 139      { "tuples" "an array of tuples" } }
 140 { $description "A SQL query is constructed from the slots of the exemplar tuple that are not " { $link f } ". Returns a multiple tuples from the database that match the query constructed from the exemplar tuple." } ;
 141
 142 HELP: count-tuples
 143 { $values
 144      { "query/tuple" tuple }
 145      { "n" integer } }
 146 { $description "Returns the number of items that would be returned if the query were a select query. Counting the tuples with this word is more efficient than calling " { $link length } " on the result of " { $link select-tuples } "." } ;
 147
 148 { select-tuple select-tuples count-tuples } related-words
 149
 150
 151
 152 ARTICLE: "db-tuples" "High-level tuple/database integration"
 153 "Start with a tutorial:"
 154 { $subsection "db-tuples-tutorial" }
 155 "Database types supported:"
 156 { $subsection "db.types" }
 157 "Useful words:"
 158 { $subsection "db-tuples-words" }
 159 "For porting db.tuples to other databases:"
 160 { $subsection "db-tuples-protocol" }
 161 ;
 162
 163 ARTICLE: "db-tuples-words" "High-level tuple/database words"
 164 "Making tuples work with a database:"
 165 { $subsection define-persistent }
 166 "Creating tables:"
 167 { $subsection create-table }
 168 { $subsection ensure-table }
 169 { $subsection ensure-tables }
 170 { $subsection recreate-table }
 171 "Dropping tables:"
 172 { $subsection drop-table }
 173 "Inserting a tuple:"
 174 { $subsection insert-tuple }
 175 "Updating a tuple:"
 176 { $subsection update-tuple }
 177 "Deleting tuples:"
 178 { $subsection delete-tuples }
 179 "Querying tuples:"
 180 { $subsection select-tuple }
 181 { $subsection select-tuples }
 182 { $subsection count-tuples } ;
 183
 184 ARTICLE: "db-tuples-protocol" "Tuple database protocol"
 185 "Creating a table:"
 186 { $subsection create-sql-statement }
 187 "Dropping a table:"
 188 { $subsection drop-sql-statement }
 189 "Inserting a tuple:"
 190 { $subsection <insert-db-assigned-statement> }
 191 { $subsection <insert-user-assigned-statement> }
 192 "Updating a tuple:"
 193 { $subsection <update-tuple-statement> }
 194 "Deleting tuples:"
 195 { $subsection <delete-tuples-statement> }
 196 "Selecting tuples:"
 197 { $subsection <select-by-slots-statement> }
 198 "Counting tuples:"
 199 { $subsection <count-statement> } ;
 200
 201 ARTICLE: "db-tuples-tutorial" "Tuple database tutorial"
 202 "Let's make a tuple and store it in a database. To follow along, click on each code example and run it in the listener. If you forget to run an example, just start at the top and run them all again in order." $nl
 203 "We're going to store books in this tutorial."
 204 { $code "TUPLE: book id title author date-published edition cover-price condition ;" }
 205 "The title, author, and publisher should be strings; the date-published a timestamp; the edition an integer; the cover-price a float. These are the Factor types for which we will need to look up the corresponding " { $link "db.types" } ". " $nl
 206 "To actually bind the tuple slots to the database types, we'll use " { $link define-persistent } "."
 207 { $code
 208 <" USING: db.tuples db.types ;
 209 book "BOOK"
 210 {
 211     { "id" "ID" +db-assigned-id+ }
 212     { "title" "TITLE" VARCHAR }
 213     { "author" "AUTHOR" VARCHAR }
 214     { "date-published" "DATE_PUBLISHED" TIMESTAMP }
 215     { "edition" "EDITION" INTEGER }
 216     { "cover-price" "COVER_PRICE" DOUBLE }
 217     { "condition" "CONDITION" VARCHAR }
 218 } define-persistent "> }
 219 "That's all we'll have to do with the database for this tutorial. Now let's make a book."
 220 { $code <" USING: calendar namespaces ;
 221 T{ book
 222     { title "Factor for Sheeple" }
 223     { author "Mister Stacky Pants" }
 224     { date-published T{ timestamp { year 2009 } { month 3 } { day 3 } } }
 225     { edition 1 }
 226     { cover-price 13.37 }
 227 } book set
 228 "> }
 229 "Now we've created a book. Let's save it to the database."
 230 { $code <" USING: db db.sqlite fry io.files ;
 231 : with-book-tutorial ( quot -- )
 232      '[ "book-tutorial.db" temp-file <sqlite-db> _ with-db ] call ;
 233
 234 [
 235     book recreate-table
 236     book get insert-tuple
 237 ] with-book-tutorial
 238 "> }
 239 "Is it really there?"
 240 { $code <" [
 241     T{ book { title "Factor for Sheeple" } } select-tuples .
 242 ] with-book-tutorial "> }
 243 "Oops, we spilled some orange juice on the book cover."
 244 { $code <" book get "Small orange juice stain on cover" >>condition "> }
 245 "Now let's save the modified book."
 246 { $code <" [
 247     book get update-tuple
 248 ] with-book-tutorial "> }
 249 "And select it again. You can query the database by any field -- just set it in the exemplar tuple you pass to " { $link select-tuples } "."
 250 { $code <" [
 251     T{ book { title "Factor for Sheeple" } } select-tuples
 252 ] with-book-tutorial "> }
 253 "Let's drop the table because we're done."
 254 { $code <" [
 255     book drop-table
 256 ] with-book-tutorial "> }
 257 "To summarize, the steps for using Factor's tuple database are:"
 258 { $list
 259     "Make a new tuple to represent your data"
 260     { "Map the Factor types to the database types with " { $link define-persistent } }
 261     { "Make a custom database combinator (see" { $link "db-custom-database-combinators" } ") to open your database and run a " { $link quotation } }
 262     { "Create a table with " { $link create-table } ", " { $link ensure-table } ", or " { $link recreate-table } }
 263     { "Start making and storing objects with " { $link insert-tuple } ", " { $link update-tuple } ", " { $link delete-tuples } ", and " { $link select-tuples } }
 264 } ;
 265
 266 ABOUT: "db-tuples"