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, with dashes changed to underscores. (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")

For the time being, the primary key column of the table must be named ‘id’.

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)
• record-count (by optional map of attributes)

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."))

Association names will have dashes converted to underscores when used in queries.

To override the foreign key name or model name, do this:

  (ns ...)

  (clj-record.core/init-model
    (:associations
      (belongs-to account :fk account_fk_id)
      (has-many subscriptions :fk sub_id :model subscription-model-name)))

In a belongs-to, if :model is specified and :fk is not, then the foreign key
name is inferred from the association name. For example, in

  ...
  (belongs-to mother :model person)
  ...

the foreign key name will be mother_id (not person_id).

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.test, 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.

Development

We’ve switched to Leiningen for building and testing.
Once you have lein installed, run lein reset-db to create (or recreate) a test db.
Run lein test to test. 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.
Jim Menard for dash-to-underscore, record counting, and foreign key and model overrides in associations.
Matt Courtney for using clj-record as part of Conjure.

---

Copyright 2010 John D. Hume and released under an MIT license.