Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 201 lines (136 sloc) 6.731 kB
2c3b61b @duelinmarkers Add README.
authored
1 h1. clj-record
2
889ae09 @duelinmarkers More README updates.
authored
3 clj-record is a "Clojure":http://www.clojure.org/ persistence library inspired by Ruby on Rails' ActiveRecord but aimed at using LISPey functional idioms.
2c3b61b @duelinmarkers Add README.
authored
4
1d4bfec @duelinmarkers README update.
authored
5 In short, it's a fairly thin layer on top of clojure.java.jdbc that allows you to define model namespaces and provides model-specific validation, associations, callbacks, and attribute serialization.
2c3b61b @duelinmarkers Add README.
authored
6
889ae09 @duelinmarkers More README updates.
authored
7 Join the "clj-record-dev Google Group":http://groups.google.com/group/clj-record-dev to stay up to date or discuss changes.
8
9 Contributions and suggestions are welcome. If you'd lke to contribute patches, please include tests.
10
2dd5b9a @duelinmarkers Add disclaimer to README
authored
11 h2. Notice
12
13 The author of clj-record regrets its API design and *recommends you don't use it*. "Read the blog post":http://elhumidor.blogspot.com/2012/11/why-not-to-use-my-library-clj-record.html for more details.
14
889ae09 @duelinmarkers More README updates.
authored
15 h2. How to Use It
2c3b61b @duelinmarkers Add README.
authored
16
1d4bfec @duelinmarkers README update.
authored
17 If you're using Leiningen or Maven, see the "clj-record page on Clojars":http://clojars.org/clj-record for configuration snippets.
18
2515de1 @duelinmarkers README update.
authored
19 To define a model (in this case called "employee"), you do something like this.
2c3b61b @duelinmarkers Add README.
authored
20
21 <pre><code>
2515de1 @duelinmarkers README update.
authored
22 (ns com.example.employee
7daa11a @duelinmarkers Change README to show clj-record.boot and use a prefix list in boot.clj.
authored
23 (:require clj-record.boot))
2c3b61b @duelinmarkers Add README.
authored
24
1d4bfec @duelinmarkers README update.
authored
25 (def db ...a clojure.java.jdbc db-spec...)
889ae09 @duelinmarkers More README updates.
authored
26
2c3b61b @duelinmarkers Add README.
authored
27 (clj-record.core/init-model)
28 </code></pre>
29
889ae09 @duelinmarkers More README updates.
authored
30 The db ref can be brought in by a :use in the ns declaration rather than being defined directly in the model namespace.
31
32 The model name is the last segment of the namespace name.
33
c593c9a Docs about record-count and conversion of dashes to underscores.
Jim Menard authored
34 By default the table name is assumed to be the pluralized model name, with dashes changed to underscores. (In the above case it would use "employees.")
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
35
36 Specify a different table name like this.
37
38 <pre><code>
39 (ns com.example.employee
40 (:require clj-record.boot))
41
42 (clj-record.core/init-model
43 :table-name "employee")
44 </code></pre>
2515de1 @duelinmarkers README update.
authored
45
bb9cf3b @duelinmarkers Mention in README that PK must be called 'id'.
authored
46 For the time being, the primary key column of the table must be named 'id'.
47
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
48 The (clj-record.core/init-model) macro form with no extra arguments will expand
49 into function definitions for basic crud operations:
50
51 * get-record (by id)
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
52 * find-record (by a map of attributes)
a8a8709 Add a function for getting all records
Tero Parviainen authored
53 * all-records
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
54 * find-records (by a map of attributes)
55 * find-by-sql (by a SQL string and "?" parameter values)
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
56 * insert (from a map of attributes, returning the generated id)
57 * create (from a map of attributes, returning the record itself)
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
58 * update (from a map of attributes that must include :id)
59 * destroy-record (from a map of attributes that must include :id)
c593c9a Docs about record-count and conversion of dashes to underscores.
Jim Menard authored
60 * record-count (by optional map of attributes)
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
61
fb7a213 @mnicky fix broken link to clj-record.core
mnicky authored
62 See the functions of the same names in "clj-record.core":https://github.com/duelinmarkers/clj-record/blob/master/src/clj_record/core.clj for documentation.
889ae09 @duelinmarkers More README updates.
authored
63 (The functions in clj-record.core take the model-name as a first argument. The functions generated in your model namespace already know what model they're about, so they don't take that argument. Otherwise the functions are the same.)
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
64
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
65 Additional optional arguments to init-model can generate richer functionality.
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
66
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
67 h3. Associations
2c3b61b @duelinmarkers Add README.
authored
68
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
69 Do this.
2c3b61b @duelinmarkers Add README.
authored
70
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
71 <pre><code>
0eedc9a @duelinmarkers Be slightly less terse in README.
authored
72 (ns ...)
73
2c3b61b @duelinmarkers Add README.
authored
74 (clj-record.core/init-model
cc94ca2 @duelinmarkers Update readme for new option-group syntax.
authored
75 (:associations
76 (belongs-to account)
77 (has-many subscriptions)))
2c3b61b @duelinmarkers Add README.
authored
78 </code></pre>
79
80 Then you can do things like this.
81
82 <pre><code>
19c4950 @duelinmarkers Rename find-record to get-record.
authored
83 (let [mikey (user/get-record 2)
2c3b61b @duelinmarkers Add README.
authored
84 subs (user/find-subscriptions mikey)]
1e3492d Fix typo in readme code sample
Wtfcoder authored
85 (doseq [subscription subs] (println (format "Mikey is subscribed to %s" (:name subscription))))
2c3b61b @duelinmarkers Add README.
authored
86 (user/destroy-subscriptions mikey)
87 (println "But not any more."))
88 </code></pre>
89
c593c9a Docs about record-count and conversion of dashes to underscores.
Jim Menard authored
90 Association names will have dashes converted to underscores when used in queries.
91
8b86ff7 Support specifying foreign key and model names explicitly in belongs-…
Jim Menard authored
92 To override the foreign key name or model name, do this:
93
94 <pre><code>
95 (ns ...)
96
97 (clj-record.core/init-model
98 (:associations
99 (belongs-to account :fk account_fk_id)
100 (has-many subscriptions :fk sub_id :model subscription-model-name)))
101 </code></pre>
102
103 In a belongs-to, if :model is specified and :fk is not, then the foreign key
104 name is inferred from the association name. For example, in
105
106 <pre><code>
107 ...
108 (belongs-to mother :model person)
109 ...
110 </code></pre>
111
112 the foreign key name will be mother_id (not person_id).
113
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
114 h3. Validations
115
116 Do this.
117
118 <pre><code>
0eedc9a @duelinmarkers Be slightly less terse in README.
authored
119 (ns ...)
120
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
121 (clj-record.core/init-model
cc94ca2 @duelinmarkers Update readme for new option-group syntax.
authored
122 (:validation
b0ee4a8 @duelinmarkers Update README for no longer needing 'validates' and switch to using k…
authored
123 (:name "Longer please." #(> (count %) 3))))
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
124 </code></pre>
125
126 Then you get validation errors like this.
127
128 <pre><code>
bcf8478 @duelinmarkers README and TODOs.
authored
129 => (let [errors (user/validate {:name "POO"})]
130 (errors :name)
131 ["Longer please."]
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
132 </code></pre>
133
2515de1 @duelinmarkers README update.
authored
134 h3. Callbacks...
135
889ae09 @duelinmarkers More README updates.
authored
136 ...work about as you'd expect. Your function is passed the record and returns the (possibly modified) record.
2515de1 @duelinmarkers README update.
authored
137
138 <pre><code>
139 (clj-record.core/init-model
140 (:callbacks
141 (:before-save fn-that-transforms-a-record)))
142 </pre></code>
143
fae6448 @duelinmarkers README updates, clarifications, cleanup.
authored
144 The callbacks currently available are:
145 * before-save
146 * before-update
147 * after-load
148
149 Adding more is easy, so send patches or let me know what callbacks would be useful.
150
bcf8478 @duelinmarkers README and TODOs.
authored
151 h3. Attribute Serialization
152
153 Do this.
154
155 <pre><code>
156 (ns ...)
157
158 (clj-record.core/init-model
159 (:serialization (:grades)))
160 </code></pre>
161
162 Then you can persist Clojure data structures (and many other Java types) into char/varchar columns in your database.
163 Attribute serialization uses clojure.core's pr and read functions, so anything they support, clj-record supports.
164
1af8590 @duelinmarkers Add a require to the example in the README and add a section about va…
authored
165 ---
166
094083d @duelinmarkers ant->lein in README.
authored
167 clj-record is being TDD'd using clojure.test, largely with high-level full-stack tests,
168 so see "the tests":http://github.com/duelinmarkers/clj-record/tree/master/test/clj_record
169 for details of everything that works.
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
170
094083d @duelinmarkers ant->lein in README.
authored
171 See "TODO.txt":http://github.com/duelinmarkers/clj-record/tree/master/TODO.txt for what else I'm thinking about,
172 and feel free to suggest.
2c3b61b @duelinmarkers Add README.
authored
173
094083d @duelinmarkers ant->lein in README.
authored
174 h2. Development
eab0e95 @duelinmarkers Mention needing derby on your classpath.
authored
175
c60fcc3 @duelinmarkers Update README with MySQL. No more Derby.
authored
176 We use "Leiningen":http://github.com/technomancy/leiningen for building and testing. Install it using their instructions.
177
178 We use MySQL with InnoDB tables as a test database. First create the database with a command like this:
179
180 <pre><code>
181 echo "create database clj_record_test" | mysql -uroot
182 </code></pre>
183
184 Then create (or recreate) the test tables with <code>lein reset-db</code>.
185 Run <code>lein test</code> to test.
186 You can uncomment and modify a different db-spec in test/clj-record/test_model/config.clj to use a different RDBMS.
187 That's also where test DB credentials are defined.
e14a3a3 @duelinmarkers Add license and update README.
authored
188
964e075 @duelinmarkers Update README.
authored
189 h2. Thanks for Contributing
190
ea814e9 @duelinmarkers Make the README a little more helpful.
authored
191 Brian Doyle for early interest and ideas.
192 Stephen Gilardi for making helpful changes to clojure.contrib.sql.
614bacb @duelinmarkers Thanks to Raja Ramachandran.
authored
193 "Raja Ramachandran":http://github.com/vishnu for initial implementation of PostgreSQL support.
bcf8478 @duelinmarkers README and TODOs.
authored
194 "tunde ashafa":http://github.com/tashafa for initial implementation of MySQL support and the clj-record.query API.
5229f69 Use Github URL for jimm.
Jim Menard authored
195 "Jim Menard":http://github.com/jimm for dash-to-underscore, record counting, and foreign key and model overrides in associations.
094083d @duelinmarkers ant->lein in README.
authored
196 "Matt Courtney":http://github.com/macourtney for using clj-record as part of Conjure.
964e075 @duelinmarkers Update README.
authored
197
e14a3a3 @duelinmarkers Add license and update README.
authored
198 ---
199
094083d @duelinmarkers ant->lein in README.
authored
200 Copyright 2010 John D. Hume and released under an MIT license.
Something went wrong with that request. Please try again.