clj-record
clj-record is a Clojure persistence library inspired by Ruby on Rails’ ActiveRecord but aimed at using LISPey functional idioms.
In short, it’s a fairly thin layer on top of clojure.contrib.sql that allows you to define model namespaces and provides model-specific validation, associations, callbacks, and attribute serialization.
Join the clj-record-dev Google Group to stay up to date or discuss changes.
Contributions and suggestions are welcome. If you’d lke to contribute patches, please include tests.
How to Use It
To define a model (in this case called “employee”), you do something like this.
(ns com.example.employee
(:require clj-record.boot))
(def db ...a clojure.contrib.sql db-spec...)
(clj-record.core/init-model)
The db ref can be brought in by a :use in the ns declaration rather than being defined directly in the model namespace.
The model name is the last segment of the namespace name.
By default the table name is assumed to be the pluralized model name. (In the above case it would use “employees.”)
Specify a different table name like this.
(ns com.example.employee
(:require clj-record.boot))
(clj-record.core/init-model
:table-name "employee")
The (clj-record.core/init-model) macro form with no extra arguments will expand
into function definitions for basic crud operations:
- get-record (by id)
- find-record (by a map of attributes)
- find-records (by a map of attributes)
- find-by-sql (by a SQL string and “?” parameter values)
- insert (from a map of attributes, returning the generated id)
- create (from a map of attributes, returning the record itself)
- update (from a map of attributes that must include :id)
- destroy-record (from a map of attributes that must include :id)
See the functions of the same names in clj-record.core for documentation.
(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.)
Additional optional arguments to init-model can generate richer functionality.
Associations
Do this.
(ns ...)
(clj-record.core/init-model
(:associations
(belongs-to account)
(has-many subscriptions)))
Then you can do things like this.
(let [mikey (user/get-record 2)
subs (user/find-subscriptions mikey)]
(doseq [subscription subs] (println (format "Mikey is subscribed to %s" (:name sub))))
(user/destroy-subscriptions mikey)
(println "But not any more."))
Validations
Do this.
(ns ...)
(clj-record.core/init-model
(:validation
(:name "Longer please." #(> (count %) 3))))
Then you get validation errors like this.
=> (let [errors (user/validate {:name "POO"})]
(errors :name)
["Longer please."]
Callbacks…
…work about as you’d expect. Your function is passed the record and returns the (possibly modified) record.
(clj-record.core/init-model
(:callbacks
(:before-save fn-that-transforms-a-record)))
The callbacks currently available are:
- before-save
- before-update
- after-load
Adding more is easy, so send patches or let me know what callbacks would be useful.
Attribute Serialization
Do this.
(ns ...)
(clj-record.core/init-model
(:serialization (:grades)))
Then you can persist Clojure data structures (and many other Java types) into char/varchar columns in your database.
Attribute serialization uses clojure.core’s pr and read functions, so anything they support, clj-record supports.
clj-record is being TDD’d using clojure.contrib.test-is, largely with high-level full-stack tests, so see the tests for details of everything that works.
See TODO.txt for what else I’m thinking about, and feel free to suggest.
Running
Run ant to compile source and run tests. By default the tests run with Apache Derby . (You can uncomment and modify a different db-spec in test/clj-record/test_model/config.clj to use MySQL or PostgreSQL.)
Thanks for Contributing
Brian Doyle for early interest and ideas.
Stephen Gilardi for making helpful changes to clojure.contrib.sql.
Raja Ramachandran for initial implementation of PostgreSQL support.
tunde ashafa for initial implementation of MySQL support and the clj-record.query API.
Copyright 2009 John D. Hume and released under an MIT license.