Quickstart

Get started with IlanaORM in under 5 minutes

Installation

Install IlanaORM:

npm

npm install ilana-orm

Database Drivers

Install only the database driver you need:

PostgreSQL

npm install pg

Why separate? Database drivers are optional dependencies to reduce package size and security surface. Install only what you need for your project.

Setup Your Project

The easiest way to get started is with the automatic setup:

npx ilana setup

This creates:

• Configuration file (ilana.config.js)
• Database directories (database/migrations, database/seeds, etc.)
• Models directory (models/)
• Sample environment file (.env)

What just happened? The setup command created a folder structure that organizes your database-related files. Think of it like creating folders for different types of documents on your computer.

Configure Your Database

Edit the generated ilana.config.js file:

SQLite (Recommended for beginners)

module.exports = {
  default: "sqlite",
  
  connections: {
    sqlite: {
      client: "sqlite3",
      connection: {
        filename: "./database.sqlite",
      },
    },
  },
  
  migrations: {
    directory: "./database/migrations",
  },
  
  seeds: {
    directory: "./database/seeds",
  },
};

SQLite is perfect for learning! It creates a simple file-based database that doesn’t require any server setup. You can always switch to MySQL or PostgreSQL later.

Create Your First Model

Let’s create a User model to represent users in our application:

npx ilana make:model User --migration

This creates two files:

• models/User.js (or .ts if TypeScript detected)
• database/migrations/xxxx_create_users_table.js

What’s a Model? Think of a model as a JavaScript class that represents a table in your database. If you have a “users” table, you’d have a “User” model to work with user data.

What’s a Migration? A migration is like a recipe for creating or modifying database tables. It tells the database what columns to create, what types they should be, etc.

Define Your Model

Open the generated models/User.js file:

JavaScript

const Model = require('ilana-orm/orm/Model');

class User extends Model {
  static table = 'users';
  static timestamps = true; // Automatically adds created_at and updated_at
  
  // Which fields can be filled when creating/updating
  fillable = ['name', 'email', 'password'];
  
  // Hide sensitive fields from JSON output
  hidden = ['password'];
  
  // Convert data types automatically
  casts = {
    email_verified_at: 'date',
    is_active: 'boolean',
  };
}

module.exports = User;

Set Up Your Database Table

Edit the migration file in database/migrations/:

export default class CreateUsersTable {
  async up(schema) {
    await schema.createTable('users', function(table) {
      table.increments('id');
      table.string('name').notNullable();
      table.string('email').unique().notNullable();
      table.string('password').notNullable();
      table.boolean('is_active').defaultTo(true);
      table.timestamp('email_verified_at').nullable();
      table.timestamps(true, true); // created_at, updated_at
    });
  }

  async down(schema) {
    await schema.dropTable('users');
  }
}

Understanding the Migration:

• table.increments('id') - Creates an auto-incrementing ID column
• table.string('name') - Creates a text column for names
• table.unique() - Ensures no duplicate values
• table.timestamps() - Adds created_at and updated_at columns

Run the Migration

Create the table in your database:

npx ilana migrate

Start Using Your Model

Create a simple script to test your setup:

test.js

const User = require('./models/User');

async function testUser() {
  try {
    // Create a new user
    const user = await User.create({
      name: 'John Doe',
      email: '[e-mail]',
      password: 'secret123'
    });
    
    console.log('Created user:', user.toJSON());
    
    // Find the user
    const foundUser = await User.find(user.id);
    console.log('Found user:', foundUser.name);
    
    // Update the user
    await foundUser.update({ name: 'John Smith' });
    console.log('Updated user:', foundUser.name);
    
    // Get all users
    const allUsers = await User.all();
    console.log('Total users:', allUsers.length);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

testUser();

Run your test:

node test.js

What’s Next?

Learn About Models

Understand how models work and their features

Query Your Data

Learn to find and filter your data

Set Up Relationships

Connect different types of data together

Database Management

Learn about migrations, seeds, and factories

Having Issues? Make sure you have Node.js installed and your database connection details are correct in ilana.config.js.