Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
DEPRECATED: A pseudo-port of ActiveRecord to the Clojure programming language
tag: clojure-1.0-co…

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
src/clj_record
test/clj_record
test_lib
.gitignore
MIT-LICENSE.txt
README.textile
TODO.txt
build.xml
db_contents.clj

README.textile

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

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.

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.
Jim Menard for dash-to-underscore and record counting.


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

Something went wrong with that request. Please try again.