Shantanu Kumar avatar Shantanu Kumar committed eefbb8b

fix documentation for v0.2

Comments (0)

Files changed (1)

 -*- markdown -*-
 
-# Lein-LB v0.1
+# Lein-LB v0.2
 
-Leiningen plugin for [Liquibase: an RDBMS change management software](http://www.liquibase.org/).
+Leiningen plugin for [Liquibase: an RDBMS change management software](http://www.liquibase.org/) -
+the plugin itself is based on [Clj-Liquibase](https://bitbucket.org/kumarshantanu/clj-liquibase/src).
 
 
 ## Usage
 
 ## License
 
-Copyright (C) 2010 Shantanu Kumar (kumar.shantanu at gmail dot com)
+   Copyright (C) 2010-2011 Shantanu Kumar (kumar[dot]shantanu[at]gmail[dot]com)
 
-Distributed under the Apache 2 License.
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this software except in compliance with the License.
+   You may obtain a copy of the License at
 
+   [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
 
-# Tutorial
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
 
-Include Lein-LB as a dev dependency in project.clj:
 
-    :dev-dependencies [[org.bituf/oss-jdbc "0.2"] ; pulls OSS JDBC drivers
-                       [org.bituf/lein-lb  "0.1"]]
+# Documentation
+
+## Quickstart
+
+Create a project (e.g. fooapp):
+
+    $ lein new fooapp
+
+Include the following configuration in project.clj (note that the :dependencies
+entry need not be modified if the project is solely for database migrations):
+
+    :dependencies [[org.clojure/clojure "1.2.1"]
+                   [org.bituf/clj-liquibase "0.2"]] ; required only for full app
+    :dev-dependencies [[org.bituf/oss-jdbc "0.4"] ; OSS-JDBC pulls in JDBC drivers
+                       [org.bituf/lein-lb  "0.2"]]
+    :eval-in-leiningen true
+    :lein-lb {:changelog "fooapp.core/clog-1"} ; default changelog (edit as needed)
 
 and then,
 
-    lein deps
-    lein lb
+    $ lein deps
+    $ lein lb
 
-Ideally you would store database/environment configuration inside the file
-./liquibase.properties file. An easy way to do that is to run this:
+The first thing you may like to do is to create a database configuration file.
+Use `dbcp-props` command to do that:
 
-    lein lb :sample-properties > liquibase.properties
+    $ lein lb dbcp-props > clj-dbcp.properties
 
-and then edit the file liquibase.properties as required.
+Make sure you enter the filename `clj-dbcp.properties` correctly and save it
+either in the project directory or under `src` or `test`. Edit the file to suit
+your environment. The default configuration creates an in-memory H2 database,
+which you cannot monitor because it gets killed with the JVM process. I assume
+you will use MySQL or PostgreSQL database for this example.
+
+Now edit the file fooapp/core.clj as follows:
+
+    (ns fooapp.core
+      (:require
+        [org.bituf.clj-liquibase :as lb]
+        [org.bituf.clj-liquibase.change :as ch]))
+    
+    
+    (def ct-change1 (ch/create-table :sample-table-1
+                      [[:id     :int          :null false :pk true :autoinc true :pkname :pk-sample-table-1]
+                       [:name   [:varchar 40] :null false]
+                       [:gender [:char 1]     :null false]]))
+    
+    (def ct-change2 (ch/create-table :sample-table-2
+                      [[:id     :int          :null false :pk true :autoinc true]
+                       [:f-id   :int]
+                       [:name   [:varchar 40] :null false]
+                       [:gender [:char 1]     :null false]]))
+    
+    (def ct-change3 (ch/create-table "sampletable3"
+                      [[:id     :int          :null false :pk true :autoinc true]
+                       [:name   [:varchar 40] :null false]
+                       [:gender [:char 1]     :null false]]))
+    
+    
+    (def changeset-1 ["id=1" "author=shantanu" [ct-change1 ct-change2]])
+    
+    
+    (def changeset-2 ["id=2" "author=shantanu" [ct-change3]])
+    
+    
+    (lb/defchangelog clog-1 [changeset-1])
+    
+    
+    (lb/defchangelog clog-2 [changeset-1 changeset-2])
+
+
+Now run the first migration:
+
+    $ lein update
+    INFO 5/4/11 9:14 AM:liquibase: Successfully acquired change log lock
+    INFO 5/4/11 9:14 AM:liquibase: Creating database history table with name: `DATABASECHANGELOG`
+    INFO 5/4/11 9:14 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:14 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:14 AM:liquibase: ChangeSet core.clj::id=1::author=shantanu ran successfully in 18ms
+    INFO 5/4/11 9:14 AM:liquibase: Successfully released change log lock
+
+Go and check the database now - it should be populated with `sample_table_1` and
+`sample_table_2` tables. Now let us proceed with tagging and rolling back.
+
+    $ lein lb tag -gv1
+    INFO 5/4/11 9:15 AM:liquibase: Successfully acquired change log lock
+    INFO 5/4/11 9:15 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:15 AM:liquibase: Successfully released change log lock
+
+Tagging is required so that we can roll back to an existing tag. (However, it
+is recommended that you include a `tag` change object in your changeset in real
+scenarios. Imperative tagging is only for demo and ad-hock jobs.)
+
+Now we migrate it further (by specifying `clog-2`):
+
+    $ lein lb update -cfooapp.core/clog-2
+    INFO 5/4/11 9:15 AM:liquibase: Successfully acquired change log lock
+    INFO 5/4/11 9:15 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:15 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:15 AM:liquibase: ChangeSet core.clj::id=2::author=shantanu ran successfully in 10ms
+    INFO 5/4/11 9:15 AM:liquibase: Successfully released change log lock
+
+Check the database now - it would have created `sampletable3` table. We now
+roll back to the tag `v1`:
+
+    $ lein lb rollback -cfooapp.core/clog-2 -gv1
+    INFO 5/4/11 9:16 AM:liquibase: Successfully acquired change log lock
+    INFO 5/4/11 9:16 AM:liquibase: Reading from `DATABASECHANGELOG`
+    INFO 5/4/11 9:16 AM:liquibase: Rolling Back Changeset:core.clj::id=2::author=shantanu::(Checksum: 3:f9b181d9bb8ced5f7df43b083ca9f097)
+    INFO 5/4/11 9:16 AM:liquibase: Successfully released change log lock
+
+When rolling back it needs the changelog that was used for migration, so we
+specify `clog-2` above.
+
+
+## Reference
+
+Please check The Bitumen Framework Handbook [https://bitbucket.org/kumarshantanu/bituf-handbook/src](https://bitbucket.org/kumarshantanu/bituf-handbook/src)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.