This is the crane Reference Manual, version 0.4, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:09:12 2024 GMT+0.
crane/crane.asdcrane/src/errors.lispcrane/src/config.lispcrane/src/util.lispcrane/src/connect.lispcrane/src/sql.lispcrane/src/meta.lispcrane/src/query.lispcrane/src/migration.lispcrane/src/table.lispcrane/src/types.lispcrane/src/inflate-deflate.lispcrane/src/interface.lispcrane/src/fixture.lispcrane/src/transaction.lispcrane/src/crane.lispThe main system appears first, followed by any subsystem dependency.
craneAn ORM for Common Lisp.
Fernando Borretti <eudoxiahp@gmail.com>
MIT
# Crane
[](https://travis-ci.org/eudoxia0/crane)
[](http://quickdocs.org/crane/)
Crane is an ORM for Common Lisp, providing a simple bridge between CLOS and
relational databases, and out of the box migrations.
# Usage
## Defining Tables
“‘lisp
(deftable user ()
(name :type text :uniquep t)
(age :type integer :nullp nil :initform 18)
(friend :type integer :foreign user)))
“‘
The foreign argument accepts a symbol that represents another table or a sexp of the form ‘(table &key on-delete on-update))‘, where acceptable values are ‘:no-action :restrict :cascade :set-null :set-default‘.
## Migrating
“‘lisp
(deftable user ()
(name :type text :uniquep t :nullp nil)
(age :type integer :nullp t :initform 18)
(description :type text))
“‘
Just make the changes, and Crane will compute the diffs and perform all the
‘ALTER TABLE‘s for you.
## Connecting
“‘lisp
(setup
:migrations-directory
(asdf:system-relative-pathname :myapp #p"migrations/")
:databases
’(:main
(:type :postgres
:name "myapp_db"
:user "user"
:pass "user")))
(connect)
“‘
For configuration management and switching databases in development/production
environments, you might want to use [Envy](https://github.com/fukamachi/envy).
## Creating, Saving, and Deleting Objects
“‘lisp
(let ((instance (create ’ship :name "Dalliance"
:tonnage 77)))
;; FIXME: It’s back luck to rename a ship
(setf (name instance) "Serenity")
;; Expand the cargo hold
(incf (tonnage instance) 25)
;; Save these changes!
(save instance)
;; Time to retire
(del instance))
“‘
## Filtering
“‘lisp
(filter ’user) ;; Returns everything
(filter ’user :name "Eudoxia")
(filter ’user (:> :age 21))
;; Returns a single object
(single ’user :name "Eudoxia")
;; Throws an error if this returns more
;; than one object
(single! ’user (:< age 35))
;; t if a match exists, nil otherwise
(exists ’user :name "Eudoxia")
;; If this record doesn’t exist create it
(get-or-create ’user :name "Eudoxia" :age 19)
“‘
## Transactions
“‘lisp
;;;; Automatic
(with-transaction ()
(let ((restaurants (filter ’restaurant ...)))
(loop for restaurant in restaurants do
...
(save restaurant))))
;;;; Manual
(progn
(begin-transaction)
(let ((restaurants (filter ’restaurant ...)))
(loop for restaurant in restaurants do
...
(save restaurant)))
(commit))
“‘
## Fixtures
“‘lisp
;;;; initial-data.lisp
(app:user
(:name "eudoxia"
:groups (:admin :staff))
(:name "joe"
:groups (:admin)))
(app:company
(:name "Initech"
:city "Denver"))
;;;; myapp.asd
(asdf:defsystem myapp
:defsystem-depends-on (:clos-fixtures)
:components ((:module "src"
:components
((:fixture "initial-data")))))
“‘
## Inflate/Deflate
“‘lisp
(definflate (stamp ’timestamp)
;; Inflate a timestamp value
;; into a timestamp object
(local-time:universal-to-timestamp stamp))
(defdeflate (stamp local-time:timestamp)
;; Deflate a timestamp object
;; into a string
(local-time:format-timestring nil stamp))
“‘
# Documentation
I’m in the process of moving the documentation to [Codex][codex], so for now you
can check it out in the [website][docs-pdf].
[codex]: https://github.com/CommonDoc/codex
[docs-pdf]: http://eudoxia.me/crane/docs/manual.pdf
# License
Copyright (c) 2013 Fernando Borretti (eudoxiahp@gmail.com)
Released under the MIT license.
0.4
closer-mop (system).
anaphora (system).
sxql (system).
dbi (system).
iterate (system).
cl-fad (system).
clos-fixtures (system).
uiop (system).
local-time (system).
src (module).
Modules are listed depth-first from the system components tree.
crane/srccrane (system).
errors.lisp (file).
config.lisp (file).
util.lisp (file).
connect.lisp (file).
sql.lisp (file).
meta.lisp (file).
query.lisp (file).
migration.lisp (file).
table.lisp (file).
types.lisp (file).
inflate-deflate.lisp (file).
interface.lisp (file).
fixture.lisp (file).
transaction.lisp (file).
crane.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
crane/crane.asdcrane/src/errors.lispcrane/src/config.lispcrane/src/util.lispcrane/src/connect.lispcrane/src/sql.lispcrane/src/meta.lispcrane/src/query.lispcrane/src/migration.lispcrane/src/table.lispcrane/src/types.lispcrane/src/inflate-deflate.lispcrane/src/interface.lispcrane/src/fixture.lispcrane/src/transaction.lispcrane/src/crane.lispcrane/src/errors.lispsrc (module).
configuration-error (condition).
empty-table (condition).
no-configuration-error (condition).
query-error (condition).
crane-error (condition).
key (reader method).
text (reader method).
crane/src/config.lisperrors.lisp (file).
src (module).
*after-config-hook* (special variable).
debugp (function).
get-config-value (function).
get-configuration (function).
setup (function).
*config* (special variable).
crane/src/util.lispconfig.lisp (file).
src (module).
diff-plist (function).
find-class-slot (function).
find-slot (function).
get-class-slot (function).
get-slot (function).
make-keyword (function).
plist-keys (function).
crane/src/connect.lisputil.lisp (file).
src (module).
*default-db* (special variable).
<database> (class).
connect (function).
database-connection (reader method).
(setf database-connection) (writer method).
database-name (reader method).
database-type (reader method).
disconnect (function).
get-connection (function).
get-db (function).
*db* (special variable).
+db-params+ (special variable).
+system-mapping+ (special variable).
database-connection-spec (reader method).
enforce-foreign-keys (function).
load-driver (function).
make-connection (method).
set-proper-quote-character (function).
validate-all-databases (function).
validate-connection-spec (function).
crane/src/sql.lispconnect.lisp (file).
src (module).
add-constraint (function).
alter-constraint (function).
create-and-sort-constraints (function).
define-column (function).
drop-column (function).
drop-constraint (function).
make-constraint (function).
sqlize (function).
+referential-actions+ (special variable).
autoincrement-sql (function).
constraint-name (function).
create-column-constraints (function).
foreign (function).
map-ref-action (function).
set-index (function).
set-null (function).
set-primary (function).
set-unique (function).
crane/src/meta.lispsql.lisp (file).
src (module).
<table-class> (class).
abstractp (reader method).
col-autoincrement-p (reader method).
col-check (reader method).
col-foreign (reader method).
col-index-p (reader method).
col-null-p (reader method).
col-primary-p (reader method).
col-type (reader method).
(setf col-type) (writer method).
col-unique-p (reader method).
compute-effective-slot-definition (method).
deferredp (reader method).
diff-digest (function).
digest (method).
direct-slot-definition-class (method).
effective-slot-definition-class (method).
table-database (method).
table-name (method).
validate-superclass (method).
validate-superclass (method).
%table-database (reader method).
diff-slot (function).
digest-slot (function).
sort-slot-list (function).
table-class-direct-slot-definition (class).
table-class-effective-slot-definition (class).
table-class-slot-definition-mixin (class).
crane/src/query.lispmeta.lisp (file).
src (module).
do-query (macro).
meta-query (macro).
query (macro).
crane/src/migration.lispquery.lisp (file).
src (module).
build (function).
create-table (function).
delete-migrations (function).
get-last-migration (function).
insert-migration (function).
migrate (function).
migration-history-p (function).
rename-migration-history (function).
+create-table-format-string+ (special variable).
get-migration-dir (function).
migration-history-pathname (function).
read-migration-history (function).
serialize (function).
serialize-plist (function).
crane/src/table.lispmigration.lisp (file).
src (module).
+slot-mapping+ (special variable).
+standard-class-options+ (special variable).
add-default-slots (function).
any-concrete-superclasses (function).
process-slot (function).
separate-slots-and-options (function).
crane/src/types.lisptable.lisp (file).
src (module).
crane/src/inflate-deflate.lisptypes.lisp (file).
src (module).
defdeflate (macro).
definflate (macro).
deflate (generic function).
inflate (generic function).
crane/src/interface.lispinflate-deflate.lisp (file).
src (module).
create (macro).
create% (macro).
create-from-plist (macro).
del (method).
deref (macro).
do-filter (macro).
drop-table (method).
drop-table (method).
exists (macro).
filter (macro).
plist->object (method).
plist->object (method).
save (method).
single (macro).
single! (macro).
single-or-create (macro).
clean-tuple (method).
make-set (function).
slot-tuple (method).
crane/src/fixture.lispinterface.lisp (file).
src (module).
register-fixture (method).
crane/src/transaction.lispfixture.lisp (file).
src (module).
begin-transaction (function).
commit (function).
rollback (function).
with-transaction (macro).
crane/src/crane.lisptransaction.lisp (file).
src (module).
Packages are listed by definition order.
crane.tablecrane.querycranecrane.fixturecrane.inflate-deflatecrane.sqlcrane.interfacecrane.migrationcrane.transactioncrane.typescrane.configcrane.metacrane.connectcrane.errorscrane.utilcrane.tableImplements the deftable macro.
anaphora.
common-lisp.
iterate.
+slot-mapping+ (special variable).
+standard-class-options+ (special variable).
add-default-slots (function).
any-concrete-superclasses (function).
process-slot (function).
separate-slots-and-options (function).
crane.queryExecuting cl-dbi queries in the context of Crane.
anaphora.
common-lisp.
iterate.
do-query (macro).
meta-query (macro).
query (macro).
craneThe global Crane package re-exports symbols from internal modules.
common-lisp.
crane.types.
crane.inflate-deflateInflation/deflation map SQL string to CLOS objects. This is
unrelated to the ORM, and meant to allow complex column datatypes to be mapped
to CLOS objects. For example, mapping SQL timestamps to structures that
represent time, or mapping other more complex SQL types to CLOS objects.
anaphora.
common-lisp.
crane.types.
defdeflate (macro).
definflate (macro).
deflate (generic function).
inflate (generic function).
crane.sqlThis module handles the generation of SQL for table definition and migration.
anaphora.
common-lisp.
crane.util.
iterate.
add-constraint (function).
alter-constraint (function).
create-and-sort-constraints (function).
define-column (function).
drop-column (function).
drop-constraint (function).
make-constraint (function).
sqlize (function).
+referential-actions+ (special variable).
autoincrement-sql (function).
constraint-name (function).
create-column-constraints (function).
foreign (function).
map-ref-action (function).
set-index (function).
set-null (function).
set-primary (function).
set-unique (function).
crane.interfaceThis package contains the methods used to access and alter database records in an object-oriented way.
anaphora.
common-lisp.
iterate.
create (macro).
create% (macro).
create-from-plist (macro).
del (generic function).
deref (macro).
do-filter (macro).
drop-table (generic function).
exists (macro).
filter (macro).
plist->object (generic function).
save (generic function).
single (macro).
single! (macro).
single-or-create (macro).
clean-tuple (generic function).
make-set (function).
slot-tuple (generic function).
crane.migrationThe first part of this package contains various simple
utilities for manipulating the migration history of a table. The second part
contains code that actually creates tables and migrates them. The actual
generation of table-creating SQL is handled by crane.sql.
anaphora.
common-lisp.
iterate.
build (function).
create-table (function).
delete-migrations (function).
get-last-migration (function).
insert-migration (function).
migrate (function).
migration-history-p (function).
rename-migration-history (function).
+create-table-format-string+ (special variable).
get-migration-dir (function).
migration-history-pathname (function).
read-migration-history (function).
serialize (function).
serialize-plist (function).
crane.transactionImplements transactions.
anaphora.
common-lisp.
begin-transaction (function).
commit (function).
rollback (function).
with-transaction (macro).
crane.configFunctions for reading and writing from and to the global configuration.
anaphora.
common-lisp.
*after-config-hook* (special variable).
debugp (function).
get-config-value (function).
get-configuration (function).
setup (function).
*config* (special variable).
crane.metaThis file defines the metaclasses that map CLOS objects to SQL tables, and some basic operations on them.
anaphora.
common-lisp.
iterate.
<table-class> (class).
abstractp (generic reader).
col-autoincrement-p (generic reader).
col-check (generic reader).
col-foreign (generic reader).
col-index-p (generic reader).
col-null-p (generic reader).
col-primary-p (generic reader).
col-type (generic reader).
(setf col-type) (generic writer).
col-unique-p (generic reader).
deferredp (generic reader).
diff-digest (function).
digest (generic function).
table-database (generic function).
table-name (generic function).
%table-database (generic reader).
diff-slot (function).
digest-slot (function).
sort-slot-list (function).
table-class-direct-slot-definition (class).
table-class-effective-slot-definition (class).
table-class-slot-definition-mixin (class).
crane.connectHandles database connections, connection parameter validation, and various low-level DB-specific modes.
anaphora.
common-lisp.
iterate.
*default-db* (special variable).
<database> (class).
connect (function).
database-connection (generic reader).
(setf database-connection) (generic writer).
database-name (generic reader).
database-type (generic reader).
disconnect (function).
get-connection (function).
get-db (function).
*db* (special variable).
+db-params+ (special variable).
+system-mapping+ (special variable).
database-connection-spec (generic reader).
enforce-foreign-keys (function).
load-driver (function).
make-connection (generic function).
set-proper-quote-character (function).
validate-all-databases (function).
validate-connection-spec (function).
crane.errorsDefinition of Crane errors.
common-lisp.
configuration-error (condition).
empty-table (condition).
no-configuration-error (condition).
query-error (condition).
crane-error (condition).
key (generic reader).
text (generic reader).
crane.utilVarious utilities for use in other parts of Crane.
anaphora.
common-lisp.
iterate.
diff-plist (function).
find-class-slot (function).
find-slot (function).
get-class-slot (function).
get-slot (function).
make-keyword (function).
plist-keys (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
A function that gets executed after setup is called. Takes no arguments, does nothing by default.
The name of the default database
Create an object.
Define a table.
Execute code for each result in the query, without aggregating them all into a list.
Execute an SxQL query on the database ‘database-name‘.
SQL to add a constraint to a table.
SQL to alter a constraint in a table.
Connect to all the databases specified in the configuration.
A plist of different types of constraints from a table digest.
Determine if Crane is in debug mode.
A column definition from the digest of its slot, name and name of the database it’s table belongs to
Compute the difference between two digests. See DIGEST.
Calculates the difference between two plists, returning the result as a list of ([property] [old value] [new value])
Cut all connections.
SQL to drop a column, given the table and column names.
SQL to drop a constraint from a table.
Find a slot by name
Find a slot by name
Find a slot in a class by keyword name
Get the value of ‘key‘ in the configuration.
Return the configuration object, or signal a no-configuration error.
Return the connection handler for a given database.
Return the database matching a specific name
Find slot by keyword name
Insert a new diff to the migration history
A constraint from its type and values, if it can be created (eg :nullp t doesn’t create a constraint, but :nullp nil creates a NOT NULL constraint).
Reintern a symbol into the keyword package.
T if the table has a migration history, NIL otherwise.
Return the keys of a plist.
Set the configuration.
Turn a symbol or a string into its SQL representation. Identical to the behaviour of SxQL.
<table-class>)) ¶Whether the class corresponds to an SQL table or not.
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated reader method
table-class-slot-definition-mixin)) ¶automatically generated writer method
table-class-slot-definition-mixin)) ¶automatically generated reader method
<database>)) ¶<database>)) ¶The underlying connection object.
conn.
<database>)) ¶The database name. If it’s an SQLite3 database, must be the pathname’s namestring.
name.
<database>)) ¶A keyword representing the database type, e.g :sqlite3, :postgres.
type.
<table-class>)) ¶Whether the class should be built only when explicitly calling build.
Turn a Lisp object into a string for insertion in the database.
<table-class>)) ¶Serialize a class’s options and slots’ options into a plist
symbol)) ¶<table-class>)) ¶Turn a string into a CLOS object.
(eql crane.types:timestamp))) ¶(eql crane.types:datetime))) ¶(eql crane.types:varchar))) ¶(eql crane.types:text))) ¶(eql crane.types:double))) ¶(eql crane.types:numeric))) ¶(eql crane.types:smallint))) ¶(eql crane.types:bigint))) ¶(eql integer))) ¶symbol) tuple) ¶<table-class>) tuple) ¶Convert a tuple produced by CL-DBI to a CLOS instance.
<table-class>)) ¶The database this class belongs to.
<table-class>)) ¶Return the name of a the class, a symbol.
<table-class>) slot-name direct-slot-definitions) ¶sb-mop.
<table-class>) &rest initargs) ¶sb-mop.
<table-class>) &rest initargs) ¶sb-mop.
standard-class) (super <table-class>)) ¶sb-mop.
<table-class>) (super standard-class)) ¶sb-mop.
An error in the configuration.
key.
Table has no slots.
Crane was not configured.
Error in a query.
A database.
A keyword representing the database type, e.g :sqlite3, :postgres.
common-lisp.
keyword
:type
This slot is read-only.
The database name. If it’s an SQLite3 database, must be the pathname’s namestring.
string
:name
This slot is read-only.
The connection specification.
:conn-spec
This slot is read-only.
The underlying connection object.
:connection
A table metaclass.
standard-class.
Whether the class corresponds to an SQL table or not.
:abstractp
This slot is read-only.
Whether the class should be built only when explicitly calling build.
:deferredp
This slot is read-only.
The database this class belongs to.
:database
This slot is read-only.
The base class of all table classes.
This variable holds Crane’s global configuration.
A map from database names to <database> objects.
If the slot doesn’t have :initarg or :accessor slots, add them.
Give constraints Crane-specific names
Compute the difference between two slot digests. See DIGEST.
Load the ASDF system for the specified database module.
Transform an object into a call to the set= function used by SxQL. Deflation happens here.
Return the pathname to the file containing the migration history for the table ‘table-name‘.
Take a plist like (:col-type ’string :col-null-p t) and remove the prefixes on the keys. Turn ’deftable slot properties’ (:type, :nullp, etc.) into ’table-class slot properties’ (:col-type, :col-null-p, etc.)
To minimize the number of parentheses, both slots and table options come in the same list. This function separates them: Normal slot names are plain old symbols, table options are keywords.
Serialize a list of digests.
Toggle INDEX pseudo-constraint.
Toggle NULL constraint.
Toggle PRIMARY KEY constraint.
Toggle UNIQUE constraint.
Immediately after configuration, iterate over the list of defined databases, validating configuration parameters, creating their corresponding <database> instances, and setting the value of *default-db*.
<table-class>)) ¶The database this class belongs to.
<table-class>) tuple) ¶Process a plist returned by CL-DBI into a format that can be accepted by make-instance. Inflation happens here.
<database>)) ¶The connection specification.
configuration-error)) ¶key.
<database>)) ¶crane-error)) ¶text.
condition.
text.
standard-effective-slot-definition.
table-class-slot-definition-mixin.
:col-type
:col-null-p
This slot is read-only.
:col-unique-p
This slot is read-only.
:col-primary-p
This slot is read-only.
:col-index-p
This slot is read-only.
:col-foreign
This slot is read-only.
:col-autoincrement-p
This slot is read-only.
| Jump to: | %
(
A B C D E F G I K L M P Q R S T V W |
|---|
| Jump to: | %
(
A B C D E F G I K L M P Q R S T V W |
|---|
| Jump to: | *
+
A C D K N S T |
|---|
| Jump to: | *
+
A C D K N S T |
|---|
| Jump to: | <
B C D E F I M N P Q S T U V |
|---|
| Jump to: | <
B C D E F I M N P Q S T U V |
|---|