Commits

kumarshantanu  committed 62c11d5

add sections up to 'saving entities' in tutorial
fix titles formatting in tutorial
add WHERE clause DSL TODO in CHANGES

  • Participants
  • Parent commits 3c3ce98

Comments (0)

Files changed (2)

 
 ## 0.2 / planned
 
-- Optimistic locks using time stamps
+- [TODO] Optimistic locks using time stamps
+- [TODO] DSL for the WHERE clause
 
 ## 0.1 / ????
 
 Distributed under the Apache 2 License.
 
 
-## Tutorial
+# Tutorial
 
 SQLRat uses Clojure 1.2.0 and Clojure-contrib 1.2.0 and is built on the top of
 clojure.contrib.sql library. In this tutorial we will take the example of a tiny
 blog with two tables (ENTRY and COMMENT) and proceed with the various database
 use cases.
 
-### Definitions
+## Definitions
 
 SQLRat uses the concept of
 
 * entity meta data (name, ID column and other details - see meta data section)
 * relation meta data (links to entity meta data - see relevant section)
 
-#### Database Configuration
+### Database Configuration
 
 You need to define a database configuration as for clojure.contrib.sql -- the
 following example is for MySQL: 
 
 More examples here [http://en.wikibooks.org/wiki/Clojure_Programming/Examples/JDBC_Examples](http://en.wikibooks.org/wiki/Clojure_Programming/Examples/JDBC_Examples)
 
-#### Defining the Entities
+### Defining the Entities
 
 Defining entities is as simple as defining a data type (defrecord):
 
 Defining the entities as parameter-less lets you reuse them for SQL statements
 involving variable number of columns and count queries.
 
-#### Defining the Entity Meta Data
+### Defining the Entity Meta Data
 
 Next comes defining the meta data for entities, which includes
 
 the :cols field. 'entity-meta' is a function that lets you easily build an
 meta data for an entity.
 
-#### Defining the Relation meta data
+### Defining the Relation meta data
 
 A blog entry has many comments, which translates into ENTRY table having a
 1-to-many relation with the COMMENT table. Conversely the COMMENT table has
 * that-ent-meta (THAT entity meta data)
 * that-col (column in THAT entity)
 
-#### Associate the entity data type with Entity meta data and Relation meta data
+### Associate the entity data type with Entity meta data and Relation meta data
 
 This example shows how to do just that:
 
 An entity type is associated with exactly one entity meta data, and zero or more
 sets of relation meta data.
 
-### Functions that operate on entities
+## Functions that operate on entities
 
 There are several functions to carry out different database tasks. They accept
 entity, entity meta data and other data as appropriate. The following sections
-describe what to use for each use case.
+describe what to use for each use case. To use the SQLRat entities, you need
+this:
 
-#### Create and drop tables
+    (ns example.test
+      (:use org.bituf.sqlrat.entity))
 
-#### Save entities (Update/Insert)
+### in-db and in-txn wrappers
 
-#### Save dependent entities (Update/Insert)
+All database operations either need a database context, or a database
+transaction context. Example is below:
 
-#### Retrieve entities
+    (def db db-mysql)
+    (in-db db
+      ;; db operations here
+      ..)
+    ;; or
+    (in-txn db
+      ;; transaction operations here
+      ..)
 
-#### Count entities
 
-#### Retrieve relation entities
+### Create and drop tables
 
-#### Count relation entities
+This is how you can drop and create tables for blog entries and comments:
 
-#### Delete entities
+<script src="http://gist.github.com/550393.js"> </script>
 
-#### Delete cascaded (dependent entities)
+Both drop-table and create-table accept the entity meta data as arguments.
+
+
+### Pretty-printing entities
+
+This is how you can pretty print the entities:
+
+<script src="http://gist.github.com/550420.js"> </script>
+
+The output should look like this:
+
+    Entity 1:
+    title | content     | whenposted                  
+    ----- | ----------- | ----------------------------
+    Test  | Hello World | Thu Aug 26 03:57:59 IST 2010
+    Entity 2:
+    title       | content       | whenposted                  
+    ----------- | ------------- | ----------------------------
+    Second post | Amarnath Trip | Thu Aug 26 03:57:59 IST 2010
+    Entities 1 and 2:
+    title       | content       | whenposted                  
+    ----------- | ------------- | ----------------------------
+    Test        | Hello World   | Thu Aug 26 03:57:59 IST 2010
+    Second post | Amarnath Trip | Thu Aug 26 03:57:59 IST 2010
+
+
+### Save entities (Update/Insert)
+
+The example of saving a blog entry is as follows:
+
+<script src="http://gist.github.com/550433.js"> </script>
+
+The important thing to note is that the generated ID on first save is returned
+with the entity, which you can verify from the pretty-print output.
+
+
+### Retrieve entities
+
+### Count entities
+
+### Save dependent entities (Update/Insert)
+
+### Retrieve relation entities
+
+### Count relation entities
+
+### Delete entities
+
+### Delete cascaded (dependent entities)