rel_erl 0.1 Readme

rel_erl 0.1 Readme

http://rel-erl.sourceforge.net/

rel_erl is a lightweight relational in-memory database for Erlang.

Download: http://sourceforge.net/projects/rel-erl/files/

Features

The process dictionary is officially considered evil, but sometimes it helps. rel_erl gets the best out of process dictionary.

System requirements

Your machine must have the Erlang runtime in order to run rel_erl.erl.

Erlang can be downloaded from here:

How to use rel_erl

  1. Design the schema of your in-memory database using a simple text-based notation.
  2. Run rel_erl.erl to generate Erlang source code from the schema.
  3. Use the generated source file in your project.

Running rel_erl.erl from command line:

escript rel_erl.erl <schema file> <output dir>

For example:

escript rel_erl.erl example.txt .

The schema file

The schema file format

The rel_erl schema is an ASCII-encoded plain text file.

The schema file contains:

There must be at least one table in the schema.

The syntax of the schema file is based on indentation. Index and table headers should not have any whitespace at the start of line.

Field lines must be indented with either tabs or spaces.

Tables

A table has one or more fields. One of the fields must be the primary key of the table.

table person
    id pk
    first_name
    second_name

In this example, the person table has three fields: id, first_name and second_name. id is the primary key of the table. Records can be quickly retrieved using the primary key.

Indexes

A table may have indexes. An index specifies that one or more columns in the table are unique. Indexes fulfill two functions:

The following snipped defines an index named person_by_names on the person table. This index makes sure that the combination of first_name and second_name in the person table is unique for all rows.

index person_by_names person
    first_name
    second_name

Primary key fields and indexed fields are read-only.

Simple links

A simple link models one-to-one or one-to-many relationship.

It is implemented as a field with the primary key of another record. [] (empty list) means a null reference. Links can reference records in a different or in the same table. Records that are pointed to by simple links have a reference counter. When a new value is assigned to a simple link field, these actions take place:

  1. The setter function ensures that the referenced record exists in the appropriate table.
  2. The counter for the old record is decremented.
  3. The counter for the new record is incremented.

It is impossible to delete a record that has a non-zero reference count.

table profession
    prof_id pk
    name

table person
    id pk
    first_name
    second_name
    prof -> profession

Here, a person can have a profession. The system makes sure that:

  1. prof field is either empty or points to a valid profession record.
  2. It is impossible to delete a profession that is referenced by at least one person.

The primary key field can be a simple link reference.

Collection links

A collection link is a two-way one-to-many link:

[] (empty list) means a null reference. The one side field (the list of references) cannot contains nulls.

The system ensures that:

Collection links make it easy to do joins and enumerate over the list of records linked to the given one.

table department
    dep_id pk
    persons []

table person
    id pk
    first_name
    second_name
    department -> department.persons

In this example, a department has a list of person's that belong to it.

The collection field on the one side cannot point to records of several tables.

The reference field on the many side can be the primary key.

All possible field modifiers

Please note that a spaces are necessary near [] and ->

table Fun
    name            # an ordinary field, read-write
    code pk         # the primary key field, read-only
    foo -> moo      # a simple link field (references "moo" table), read-write

table Better
    bar -> cool pk  # a simple link which is also the primary key, read-only
    hot -> moo.bar  # a collection link ("many" side, references field "bar"
                    # of "moo" table), read-write
    some []         # a collection link ("one" side), read-only

Generated source code

Insert

The insert function creates a new record.

The caller must supply the primary key and values for all indexed fields.

If an indexed field is a reference, the key of the referenced field should be supplied.

table person
    id pk
    first_name
    second_name
    phone

index person_by_names person
    first_name
    second_name

The usage of the generated insert function:

insert_person(201, "John", "Smith")

insert enforces referential and unique constraints.

The default value of a field is [] (empty list).

Delete

The delete function deletes a record.

The caller must supply the primary key of the deleted record.

delete_person(201)

delete enforces referential integrity. If the deleted record is referenced, the function returns error, and the data remains intact.

Setters

Setters set values to fields.

set_person_phone(201, "222332233")

The setter accepts the primary key and the new value of the field and returns the old value.

It is impossible to set a new value to an indexed or primary key field.

Setters enforce referential integrity. They don't allow fields to point to non-existent records.

Setters make sure that the record being modified actually exists.

The collection field on the one side of a one-to-many link is read-only. The only way to change it is set a value to the corresponding field on the many side.

Fetch functions

Fetch functions perform fast retrieval of records. A separate fetch function is generated for each index and for the primary key.

Fetch functions take the values of the indexed fields and return the records. If the record does not exist, the fetch function returns an empty tuple.

Person = find_person_by_pk(201),
Person2 = find_person_by_names("John", "Smith")

Getters

Getters return values stored in fields. A getter takes the record as the parameter, not the primary key.

Person2 = find_person_by_names("John", "Smith"),
FirstName = get_person_first_name(Person2)

Module name

The module name and the output source code filename are based on the schema filename.

Source code

rel_erl is written in DRAKON-Erlang using DRAKON Editor.

The real source file is rel_erl.drn.

rel_erl.erl is autogenerated from rel_erl.drn.

License

rel_erl is Public Domain.


April 8, 2012

Author: Stepan Mitkin stipan.mitkin@gmail.com