Quick Start

This guide walks you through creating your first ObjectQL project — from scaffolding to your first database query.

Prerequisites

Node.js 18+ (download)
npm, pnpm, or yarn package manager

Create a Project

Scaffold with the CLI

npm create @objectql@latest my-app -- --template starter

pnpm create @objectql my-app --template starter

yarn create @objectql my-app --template starter

This creates a project with SQLite (zero-config), example models, and a dev server.

For a minimal single-file setup:

npm create @objectql@latest my-app -- --template hello-world

Install dependencies and start

cd my-app
npm install
npm run dev

ObjectQL detects your .object.yml files, generates database tables, and starts a local server.

Define your first object

Create src/objects/todo.object.yml:

name: todo
label: Task
fields:
  title:
    type: text
    required: true
    searchable: true
  completed:
    type: boolean
    defaultValue: false
  priority:
    type: select
    options: [low, medium, high]
    defaultValue: medium

Save the file — the dev server hot-reloads and creates the todo table automatically.

Query your data

Open another terminal and use the REST API:

# Create a task
curl -X POST http://localhost:3000/api/todo \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn ObjectQL", "priority": "high"}'

# List all tasks
curl http://localhost:3000/api/todo

Or use the programmatic API in your code:

const ctx = app.createContext({ isSystem: true });
const todos = ctx.object('todo');

await todos.create({ title: 'Learn ObjectQL', priority: 'high' });

const results = await todos.find({
  filters: { completed: false }
});
console.log(results);

Programmatic Setup

If you're integrating ObjectQL into an existing backend (Express, Lambda, custom scripts), use the programmatic API directly:

import { ObjectQL } from '@objectql/core';
import { SqlDriver } from '@objectql/driver-sql';

async function main() {
  const driver = new SqlDriver({
    client: 'sqlite3',
    connection: { filename: ':memory:' },
    useNullAsDefault: true
  });

  const app = new ObjectQL({
    datasources: { default: driver }
  });

  // Register objects inline (YAML files recommended for real projects)
  app.registerObject({
    name: 'todo',
    fields: {
      title: { type: 'text', required: true },
      completed: { type: 'boolean', defaultValue: false }
    }
  });

  await app.init();

  // CRUD operations
  const ctx = app.createContext({ isSystem: true });
  const repo = ctx.object('todo');

  const task = await repo.create({ title: 'Build something great' });
  console.log('Created:', task);

  const all = await repo.find();
  console.log('All todos:', all);
}

main();

Add Business Logic

ObjectQL supports three types of business logic that run automatically:

Hooks — Lifecycle Triggers

React to data changes before or after they happen:

app.on('before:create', 'todo', async (ctx) => {
  // Auto-tag new tasks
  ctx.data.title = `[Task] ${ctx.data.title}`;
});

app.on('after:update', 'todo', async (ctx) => {
  if (ctx.data.completed) {
    console.log(`Task completed: ${ctx.data.title}`);
  }
});

Actions — Custom Operations

Define RPC endpoints that frontends can call:

app.registerAction('todo', 'mark_done', async (ctx) => {
  const { id } = ctx;
  await ctx.object('todo').update(id, { completed: true });
  return { message: 'Task completed!' };
});

Formulas — Computed Fields

Add computed fields that auto-update:

name: todo
fields:
  title:
    type: text
    required: true
  completed:
    type: boolean
    defaultValue: false
  display_name:
    type: formula
    formula: "'[' + (completed ? '✓' : ' ') + '] ' + title"
    return_type: text

Learn more in the Business Logic section — covering Formulas, Hooks, and Actions in detail.

Choose a Database Driver

ObjectQL ships with 7 drivers. The default starter template uses SQLite, but switching is a one-line config change:

Driver	Best For	Package
SQL (PostgreSQL, MySQL, SQLite)	Production apps	`@objectql/driver-sql`
MongoDB	Document-oriented data	`@objectql/driver-mongo`
Memory	Testing, prototyping	`@objectql/driver-memory`
File System	Embedded/config storage	`@objectql/driver-fs`
Excel	Data import/export	`@objectql/driver-excel`
Redis	Caching layer	`@objectql/driver-redis`

// Switch to PostgreSQL
import { SqlDriver } from '@objectql/driver-sql';

const driver = new SqlDriver({
  client: 'pg',
  connection: 'postgresql://user:pass@localhost:5432/mydb'
});

See the Drivers Guide for detailed setup instructions for each database.

Next Steps

What to Learn	Where to Go
Full schema language (all field types, relationships)	Modeling Data
PROJECT file organization and conventions	Project Structure
CLI commands for development workflow	CLI Reference
Editor setup (VS Code, JetBrains)	IDE Setup
Server setup and framework integration	Server & APIs

Quick Start

On this page