Module erlydb_base

Copyright © Yariv Sadan 2006-2007

• Description
• Data Types
• Function Index
• Function Details

Authors: Yariv Sadan (yarivvv@gmail.com) [web site: http://yarivsblog.com].

Description

erlydb_base is the base module that all modules that ErlyDB generates extend.

Generated modules inherit many of erlydb_base's exported functions directly, but some of the functions in erlydb_base undergo changes before they attain their final forms the generated modules. For an exact description of how each function in erlydb_base is used in generated modules, refer to the function's documentation.

You can override some of the default code generation behavior by providing your own implementations for some of erlydb_base's functions in generated modules. This is useful for telling ErlyDB about relations (one-to-many and many-to-many) and mappings between Erlang modules and database tables and fields.

Data Types

extras_expr()

abstract datatype: extras_expr()

ErlSQL (see erlsql) statement fragments that appear at the end of the statement, following the 'where' clause (if it exists). Currently, this includes 'order_by' and 'limit' clauses.

  {order_by, age}
  {limit, 6, 8}
  [{order_by, [{age, {height, asc}, {gpa, desc}}]}, {limit, 5}]

record()

abstract datatype: record()

An Erlang tuple containing the values for (some of) the fields of a database row, as well as additional data used by ErlyDB. To ensure future compatibility, it is recommended to use the getters and setters ErlyDB adds to generated modules in order to access the record's fields instead of accessing them directly.

where_expr()

abstract datatype: where_expr()

An ErlSQL (see erlsql) statement fragment that defines the conditions in a {where, Conditions} clause.

  {age, '=', 34}
  {{name, 'like', "Bob%"}, 'or', {not, {age, '>', 26}}}

Function Index

Function Details

add_related_many_to_many/3

add_related_many_to_many(JoinTable::atom(), Rec::record(), OtherRec::record() | [record()]) -> {ok, NumAdded} | exit(Err)

Add a related record in a many-to-many relation.

This function isn't meant to be used directly; ErlyDB uses this function to generate special add_[RelatedModule] functions in modules that define many-to-many relations.

For instance, if you had a module 'student' that defined the relation {many_to_many, [class]}, and both 'student' and 'class' had a single primary key field called 'id', ErlyDB would add the function student:add_class(Student, Class) to the 'student' module. This function would insert the row [class:id(Class), student:id(Student)] to the class_student table, where the first column is 'class_id' and the second column is 'student_id'.

after_delete/1

after_delete(X1::{Rec::record(), NumDeleted::integer()}) -> integer()

A hook that gets called after a record is deleted.

By default, this function returns an integer indicating the number of rows deleted.

after_fetch/1

after_fetch(Rec::record()) -> record()

A hook that gets called after a record is fetched from the database.

after_save/1

after_save(Rec::record()) -> record()

A hook that gets called after a record is saved.

aggregate/5

aggregate(Module::atom(), AggFunc::atom(), Field::atom(), Where::where_expr(), Extras::extras_expr()) -> integer() | float() | exit(Err)

ErlyDB uses this function to generate derivative functions in target modules for calculating aggregate values for database fields. Drivative functions have the form Module:FuncName(Field), where 'Module' is the module name, 'FuncName' is 'count', 'avg', 'sum', 'min', 'max' or 'stddev', and Field is the name of the field. Derivative functions also have variations as described in find/3.

For example, in a module called 'person', ErlyDB would generate the following functions:

    person:count(Field)
    person:count(Field, Where)
    person:count_with(Field, Extras)
    person:count(Field, Where, Extras)
    person:avg(Field)
    ...

See also: find/3.

aggregate_related_many_to_many/7

aggregate_related_many_to_many(OtherModule::atom(), JoinTable::atom(), AggFunc::atom(), Rec::record(), Field::atom(), Where::where_clause(), Extras::extras_clause()) -> [term()] | exit(Err)

This function works as aggregate_related_many_to_one/5, but for modules defining many-to-many relations.

See also: aggregate_related_many_to_one/5.

aggregate_related_many_to_one/7

aggregate_related_many_to_one(OtherModule::atom(), PkFks::term(), AggFunc::atom(), Rec::record(), Field::atom(), Where::where_expr(), Extras::extras_expr()) -> float() | integer() | exit(Err)

Get aggregate statistics about fields from related records in one-to-many relations.

This function isn't meant to be used directly; ErlyDB uses this function to generate special aggregate functions in modules that define one-to-many relations.

For example, if you had a module 'dog' that defined the relation {one_to_many, [bone]}, ErlyDB would add the following functions to the 'dog' module:

  dog:avg_of_bones(Dog, Field)
  dog:avg_of_bones(Dog, Field, Where)
  dog:avg_of_bones_with(Dog, Field, Extras)
  dog:avg_of_bones(Dog, Field, Where, Extras)

where 'Field' is the name of the field in the 'bone' module (e.g. 'size').

See also: aggregate/5.

before_delete/1

before_delete(Rec::record()) -> record()

A hook that gets called before a record is deleted.

before_save/1

before_save(Rec::record()) -> record()

A hook that gets called before a record is saved.

count/1

count(Module::atom()) -> integer() | exit(Err)

A shortcut for counting all the records for a module. In generated modules, this function lets you can call Module:count() instead of Module:count('*').

db_field/2

db_field(Module::atom(), FieldName::string() | atom()) -> erlydb_field() | exit(Err)

Get the erlydb_field record matching the given field name. If the field isn't found, this function exits.

db_field_names/1

db_field_names(FileNames::[atom()]) -> [atom()]

Get the module's database fields' names as atoms.

db_field_names_bin/1

db_field_names_bin(FieldNamesBin::[binary()]) -> [binary()]

Get the module's database fields' names as binaries.

db_field_names_str/1

db_field_names_str(FieldNameStrs::[string()]) -> [string()]

Get the module's database fields' names as strings.

db_fields/1

db_fields(Fields::[erlydb_field()]) -> [erlydb_field()]

Get a list of erlydb_field records representing the database fields for the module.

db_num_fields/1

db_num_fields(NumFields::integer()) -> integer()

Get the number of fields for the module.

db_pk_fields/1

db_pk_fields(Fields::[erlydb_field()]) -> [erlydb_field()]

Return the list of fields (see @link erlydb_field) for which erlydb_field:key(Field) == primary is true.

db_table/1

db_table(Module::atom()) -> atom()

Get the table name for the module.

decrement/2

Equivalent to decrement(Module, Fields, undefined).

decrement/3

Similar to increment/3, but decrements the fields' values.

delete/1

delete(Rec::record()) -> ok | exit(Err)

Delete the record from the database. To facilitate the after_delete hook, this function expects a single record to be deleted.

delete_all/1

delete_all(Module::atom()) -> NumDeleted::integer() | exit(Err)

Delete all records from the module and return the number of records actually deleted.

Needless to say, use this function with extreme care.

delete_id/2

delete_id(Module::atom(), Id::integer()) -> NumDeleted::integer()

Equivalent to delete_where(Module, {id, '=', Id}).

delete_where/2

delete_where(Module::atom(), Where::where_expr()) -> NumDeleted::integer() | exit(Err)

Delete all records matching the Where expressions, and return the number of deleted records.

driver/1

driver(Driver::term()) -> term()

Get the driver settings, defined in the call to erlydb:code_gen/3, ErlyDB uses for the module.

field_from_string/2

field_from_string(ErlyDbField::erlydb_field(), Str::list()) -> term() | exit(Err)

A helper function for converting values encoded as strings to their corresponding Erlang types.

This function assumes field values are formatted according to the logic in field_to_iolist/2. In addition, it checks the following ranges:

field_to_iolist/1

field_to_iolist(Val::term()) -> iolist()

Equivalent to field_to_iolist(Val, undefined).

A helper function used for converting field values to iolists.

field_to_iolist/2

field_to_iolist(Val::term, Field::erlydb_field()) -> iolist()

This function converts standard ErlyDB field values to iolists. This is its source code:

 	Type = 	if
         		Field =:= undefined -> undefined;
      			true -> erlydb_field:erl_type(Field)
     		end,
 
   case Val of
  	Bin when is_binary(Bin) -> Val;
  	List when is_list(List) -> Val;
  	Int when is_integer(Int) -> integer_to_list(Val);
  	Float when is_float(Float) -> float_to_list(Val);
 
   {datetime, {{_Year,_Month,_Day},{_Hour,_Minute,_Second}} = DateTime} ->
         format_datetime(DateTime);
   {{_Year,_Month,_Day},{_Hour,_Minute,_Second}} = DateTime when Type =:= datetime ->
         format_datetime(DateTime);
 	{date, {_Year,_Month,_Day} = Date} -> format_date(Date);
   {_Year,_Month,_Day} = Date when Type =:= date -> format_date(Date);
 	{time, {_Hour,_Minute,_Second} = Time}  -> format_time(Time);
   {_Hour,_Minute,_Second} = Time when Type =:= time -> format_time(Time);
 
  	undefined -> [];
  	_Other ->
  	    io_lib:format("~p", [Val])
     end.

fields/0

fields() -> '*' | [atom()]

Return the list of fields that ErlyDB should use for the module. You can override this function to specify which database fields from the table besides the id field should be exposed to records from the module. The '*' atom indicates all fields, which is the default setting.

Starting from ErlyWeb 0.6, you can add arbitrary metadata to each field by describing it as a tuple of the form {FieldName::atom(), Attributes::[term()]}. To retrieve the list of attributes for a field in a given model, you can call erlydb_field:attributes(Model:db_field(FieldName)).

If the list of attributes contains the atom read_only, ErlyDB excludes the field from INSERT and UPDATE statements.

It is also possible to add transient fields which do not exist in the database schema. To add transient fields it is currently necessary to overwrite the fields/0 function with the complete list of persistent fields plus the transient fields in any desired order (which also will be effective in the generated model functions), e.g.:

fields() -> [mydbfield, {mytransientfield, [transient]}, mydbfield2]

Note: You are free to call the fields() function from other modules to create arbitrary field set relations. For example, in a module called 'artist', you could have the function

find/3

find(Module::atom(), Where::where_expr(), Extras::extras_expr()) -> [record()] | exit(Err)

Find records for the module. The Where and Extras clauses are, by default, ErlSQL expressions (see erlsql). Example Where expressions are
{name,'=',"Joe"}
and
{{age,'>',26},'and',{country,like,"Australia"}}

Example Extras expressions are
{limit, 7}
and
[{limit, 4,5}, {order_by, [name, {age, desc}, {height, asc}]}]

The main benefits of using ErlSQL are
- It protects against SQL injection attacks by quoting all string values.
- It simplifies embedding runtime variables in SQL expressions by automatically stringifying values such as numbers, atoms, dates and times.
- It's more efficient than string concatenation because it generates iolists of binaries, which generally consume less memory than strings.

Some drivers (e.g. the MySQL driver), let you use string and binary expressions directly when you pass the {allow_unsafe_statements, true} option to erlydb:code_gen/3. This usage is discouraged, however, because it makes you vulnerable to SQL injection attacks if you don't properly encode all your strings.

During code generation, ErlyDB creates a few derivatives from this function in target modules:

    find()  %% returns all records
    find(Where)
    find_with(Extras)
    find(Where, Extras)

(Note that in generated modules, the 'Module' parameter is omitted.)

find_first/3

find_first(Modue::atom(), Where::where_expr(), Extras::extras_expr()) -> record() | undefined | exit(Err)

Find the first record for the module according to the Where and Extras expressions. If no records match the conditions, the function returns 'undefined'.

See also: find/3.

find_id/2

find_id(Module::atom(), Id::term()) -> Rec | exit(Err)

Find the record with the given id value.

find_max/4

find_max(Module::atom(), Max::integer(), Where::where_expr(), Extras::extras_expr()) -> [record()] | exit(Err)

Find up to Max records from the module according to the Where and Extras expressions.

See also: find/3.

find_range/5

find_range(Module::atom(), First::integer(), Max::integer(), Where::where_expr(), Extras::extras_expr()) -> [record()] | exit(Err)

Find up to Max records, starting from offset First, according to the Where and Extras expressions.

See also: find/3.

find_related_many_to_many/5

find_related_many_to_many(OtherModule::atom(), JoinTable::atom(), Rec::record(), Where::where_clause(), Extras::extras_clause()) -> [record()] | exit(Err)

This function works as find_related_many_to_one/4, but for modules defining many-to-many relations.

See also: find_related_many_to_one/4.

find_related_many_to_one/5

find_related_many_to_one(OtherModule::atom(), PkFks::term(), Rec::record(), Where::where_expr(), Extras::extras_expr()) -> [record()] | exit(Err)

Find the set of related records in a one-to-many relation.

This function isn't meant to be used directly; ErlyDB uses this function to generate special 'find' functions in modules that define one-to-many relations.

For example, if you had a module 'dog' that defined the relation {one_to_many, [bone]}, ErlyDB would add the following functions to the 'dog' module:

  dog:bones(Dog)
  dog:bones(Dog, Where)
  dog:bones_with(Dog, Extras)
  dog:bones(Dog, Where, Extras)
 
  dog:bones_first(Dog)
  dog:bones_first(Dog, Where)
  dog:bones_first_with(Dog, Extras)
  dog:bones_first(Dog, Where, Extras)
 
  dog:bones_max(Dog, Max)
  dog:bones_max(Dog, Max, Where)
  dog:bones_max_with(Dog, Max, Extras)
  dog:bones_max(Dog, Max, Where, Extras)
 
  dog:bones_range(Dog, First, Max)
  dog:bones_range(Dog, First, Max, Where)
  dog:bones_range_with(Dog, First, Max, Extras)
  dog:bones_range(Dog, First, Max, Where, Extras)

See also: find/3, find_first/3, find_max/4, find_range/5.

find_related_one_to_many/3

find_related_one_to_many(OtherModule::atom(), PkFkfields::proplist(), Rec::record()) -> record() | exit(Err)

Find the related record for a record from a module having a many-to-one relation.

This function isn't meant to be used directly; ErlyDB uses it to generate special 'find' functions for related records in modules defining many-to-one relations.

For example, if you had a module 'bone' that defined the relation {many_to_one, [dog]}, and 'dog' had a single primary key field called 'id', ErlyDB would add the function bone:dog(Bone) to the 'bone' module. This function would be equivalent to dog:find({id,=',bone:dog_id(Bone)}).'.

get/2

get(Idx::integer(), Rec::record()) -> term()

A generic getter function ErlyDB uses to generate getters, e.g. person:name(Person), for all of a module's database fields.

get_module/1

get_module(Rec::record()) -> atom()

Get the name of the module to which the record belongs.

increment/2

Equivalent to increment(Module, Fields, undefined).

increment/3

increment(Module::atom(), Fields::[atom()], Where::where_expr()) -> NumRowsUpdated::integer()

Increment the values for the listed fields in the module's table. This executes the query

  UPDATE [table] SET [field1] = [field1] + 1, [field2] = [field2] + 1...
  WHERE [where_expr]

insert/1

insert(Rec::record() | [record()]) -> NumInserts::integer() | exit(Err)

Insert one or more records into the database.

is_new/1

is_new(Rec::record()) -> boolean()

Check if the record has been saved in the database.

is_new/2

is_new(Rec::record(), Val::boolean()) -> NewRec::record()

Set the record's 'is_new' field to the given value.

is_related/3

new/1

new(Module::atom()) -> record()

Create a new record with all fields set to 'undefined'.

In generated modules, the 'Module' parameter is omitted.

new_from_strings/2

new_from_strings(Module::atom(), Fields::[{atom() | list(), list()}]) -> record() | exit(Err)

Equivalent to new_with(Module, Fields, fun field_from_string/2).

See also: field_from_string/2.

new_with/2

new_with(Module::atom(), Fields::proplist()) -> record() | exit(Err)

Create a new record, setting its field values according to the key/value pairs in the Fields property list.

See also: set_fields/3.

new_with/3

new_with(Module::atom(), Fields::proplist(), ToFieldFun::function()) -> record() | exit(Err)

Similar to new_with/2, but uses the ToFieldFun to convert property list values to field values before setting them. ToFieldFun accepts an erlydb_field record and the original value and returns the new value.

relations/0

relations() -> [{one_to_many, [atom()]} | {many_to_many, [atom()]}]

Return the list of relations of the module. By overriding the function, you can tell ErlyDB what relations the module has. Possible relations are {one_to_many, [atom()]} and {many_to_many, [atom()]}. This function returns a list of such relations.

remove_related_many_to_many/3

remove_related_many_to_many(JoinTable::atom(), Rec::record(), OtherRec::record()) -> NumRemoved::interger() | exit(Err)

Remove a related record in a many-to-many relation.

This function isn't meant to be used directly; ErlyDB uses this function to generate special remove_[RelatedModule] functions in modules that define many-to-many relations.

For instance, if you had a module 'student' that defined the relation {many_to_many, [class]}, and module 'class' and 'student' had a single primary key field called 'id', ErlyDB would add the function student:remove_class(Student, Class) to the 'student' module. This function would remove the row [class:id(Class), student:id(Student)] from the class_student table, where the first column is 'class_id' the second column is 'student_id'.

remove_related_many_to_many_all/5

remove_related_many_to_many_all(JoinTable::atom(), OtherTable::atom(), Rec::record(), Where::where_clause(), Extras::extras_clause()) -> {ok, NumDeleted} | exit(Err)

Remove all related recorded according to a Where and Extras clause in a many-to-many relation.

This function isn't meant to be used directly; ErlyDB uses this function to generate special remove_all_[RelatedModuleAsPlural] functions in modules that define many-to-many relations.

For instance, if you had a module 'student' that defined the relation {many_to_many, [class]}, and module 'class' and 'student' had a single primary key field called 'id', ErlyDB would add the function student:remove_all_classes(Student, Where, Extras) to the 'student' module. This function would remove [class:id(Class), student:id(Student)] rows from the class_student table according to the Where and Extras clauses.

In addition to student:remove_all_classes/3, ErlyDB would generate additional variations. This would be the full list:

  student:remove_all_classes(Student)
  student:remove_all_classes(Student, Where)
  student:remove_all_classes_with(Student, Extras)
  student:remove_all_classes(Student, Where, Extras)

save/1

save(Rec::record()) -> record() | exit(Err)

Save an object by executing a INSERT or UPDATE query. This function returns a modified tuple representing the saved record or throws an exception if an error occurs.

With MySQL, for INSERT statements for records with identity primary keys, this function sets the primary key field to the value returned from calling "SELECT last_insert_id()".

set/3

set(Idx::integer(), Rec::record(), NewVal::term()) -> record()

A generic setter function ErlyDB uses to generate setters, e.g. person:name(Person, NewName), for all of a module's database fields.

set_fields/3

set_fields(Module::atom(), Record::record(), Fields::proplist()) -> record() | exit(Err)

Set the record's fields according to the name/value pairs in the property list, e.g.

  Language1 = language:set_fields(Language, [{name,"Erlang"},
                      {creation_year, 1981}])

The property list can have keys that are either strings or atoms. If a field name doesn't match an existing field for this record, this function exits.

set_fields/4

set_fields(Module::atom(), Record::record(), Fields::proplist(), ToFieldFun::function()) -> record() | exit(Err)

Set the record's fields using according to the property list name/value pairs, after first converting the values using the ToFieldFun. ToFieldFun accepts an erlydb_field record and the original value and returns the new value.

set_fields_from_strs/3

set_fields_from_strs(Module::atom(), Record::record(), Fields::proplist()) -> record() | exit(Err)

Equivalent to set_fields(Module, Record, Fields, fun field_from_string/2).

See also: field_from_string/2.

set_related_one_to_many/3

set_related_one_to_many(Rec::record(), PkFkFields::proplist(), Other::record()) -> record() | exit(Err)

Set the foreign key fields of a record from a module having a many-to-one relation to the primary key values of the Other record.

This function isn't meant to be used directly; ErlyDB uses it to generate special setters for related records in modules that define many-to-one relations.

For example, if you had a module 'bone' that defined the relation {many_to_one, [dog]}, and the 'dog' module had a single primary key field called 'id', ErlyDB would add the function bone:dog(Bone, Dog) to the 'bone' module. This function would be equivalent to bone:dog_id(Bone, dog:id(Dog)), with an extra check to verify that Dog is saved in the database.

table/0

table() -> atom()

Return the name of the table that holds the records for this module. By default, the table name is identical to the Module's name, but you can override this to use a different table name.

to_iolist/2

to_iolist(Module::atom(), Recs::record() | [record()]) -> [iolist()] | [[iolist()]]

Equivalent to to_iolist(Module, Recs, fun field_to_iolist/2).

to_iolist/3

to_iolist(Module::atom(), Rec::record() | [Rec::record()], ToIolistFun::to_iolist_function()) -> [iolist()] | [[iolist()]]

If Recs is a single record, convert each of a record's fields into an iolist and return the list of the converted records. If Recs is a list of records, to_iolist is recursively called on each record, and the list of results is returned.

ToIoListFun is a function that accepts an erlydb_field structure and a field value and returns an iolist (see field_to_iolist/2 for an example).

transaction/2

transaction(Module::atom(), Fun::function()) -> {atomic, Result::term()} | {aborted, Details}

Execute a transaction using the module's driver settings, as defined by the parameters passed to erlydb:code_gen/3.

type_field/0

type_field() -> atom()

Return the column that identifies the types of the records in a table. This is useful when storing records from multiple modules in a single table, where each module uses a different subset of fields. If you override this function, in most cases you should also override fields/0.

update/2

Equivalent to update(Module, Props, undefined).

update/3

update(Module::atom(), Props::proplist(), Where::where_expr()) -> NumUpdated::integer() | exit(Err)

Execute an UPDATE statement against the module's database table and return the number of rows updated.

'Props' is a list of 2 element tuples, where the first element is an atom representing the field's name, and the second value is an ErlSQL expression representing its value.

'Where' is an ErlSQL 'where' expression.

In generated modules, the 'Module' parameter is omitted.

Example: Calling person:update([{name,<<"Jane">>}, {age, {age, '+', 1}}], {id,'=',7}) would yield the statement UPDATE person SET name='Jane', age=age+1 WHERE id=7.