Guide

A quick set of examples on things you'd want to do with ResQL. More details are on the Module API page.

Setting up

A simple npm install resql should see you on your way.

Modeling your data

Define a new DB

db = new rs.connect(options);

Where options include database access parameters such as hostname, credentials and database type (PostgreSQL or MySQL).

Define tables

In ResQL, you define all the columns, even those related to relationships - use your existing DB design knowledge to optimize things.

If not specified, an "id" column will be created with type INT AUTOINCREMENT or SERIAL

students = db.table('students', {
	name: rs.String,
	dob:  rs.Date,
});

courses = db.table('courses', {
	id:        rs.String,
	name:      rs.String,
	desc:      rs.Text,
	teacherId: rs.Foreign('teachers')
});

teachers = db.table('teachers', {
	name:   rs.String,
	joined: rs.Date
})

You can also add columns later:

teachers.column('dob', rs.Date);

Tables for associations are no different.

db.table('studentsInCourses', {
	studentId: rs.Foreign('students'),
	courseId:  rs.Foreign('courses')
});

Define relationships

When you set up a foreign key such as with courses.teacherId above, it automatically creates a relationship "teacher" (removing "Id" or "_id" at the end) on the course objects. Now, you can use:

courses.one({id: myCourseId}).teacher().then(...);

In the opposite direction, you have to define a relations manually:

teachers.relation('coursesTaught', {
	table:  'courses',	// target table
	column: 'teacherId'	// column in target table
});

teachers.one({id: teachId}).coursesTaught().then(...);

You can similarly define many-many relations

courses.relation('students', {
	table: 'studentsInCourses', column: 'courseId', relation: 'student'
});
students.relation('courses', {
	table: 'studentsInCourses', column: 'studentId', relation: 'course'
});

courses.one({id: myCourseId}).students().then(...);

as well as self-referencing relations.

nodes.column('parentId', rs.Foreign(nodes));
nodes.relation('children', {table: 'nodes', column: 'parentId'});

nodes.one({parentId: null}).parent().children().

If the "Id" or "_id" convention for outbound relations doesn't work for you, you can also define them using the relation() method by passing the option outbound: true.

Querying

[This part of the documentation is pending]

Using the ResQL REST API

The rest API maps HTTP GET/POST/DELETE calls to SELECT, INSERT, UPDATE and DELETE queries, and sends back a JSON response.

This is highly experimental and should not be used in production under any circumstances. There is no authentication or security yet.

Basically it works like this:

var express = require(express),
    resql   = require(resql),
    app     = express(),
    db      = resql.connect({ ... });

/* set up your db tables and your express app */

app.use(db.restHandler(options));

/* more stuff... */

See also: REST API.