Getting Started Guide

A complete walkthrough from installation to your first query

Step 1: Install Stabilize

Install both the ORM and CLI tools:

bun add stabilize-orm

bun add -d stabilize-cli

Step 2: Set Up Your Database

Create a database configuration file:

config/database.tstypescript

import { DBType, type DBConfig } from "stabilize-orm";

const dbConfig: DBConfig = {
  type: DBType.Postgres,
  connectionString: process.env.DATABASE_URL,
  retryAttempts: 3,
  retryDelay: 1000,
};

export default dbConfig;

Step 3: Initialize the ORM

Create an ORM instance and connect to your database:

db/index.tstypescript

import { Stabilize, type CacheConfig, type LoggerConfig, LogLevel } from "stabilize-orm";
import dbConfig from "./config/database";

const cacheConfig: CacheConfig = {
  enabled: process.env.CACHE_ENABLED === "true",
  redisUrl: process.env.REDIS_URL,
  ttl: 60,
};

const loggerConfig: LoggerConfig = {
  level: LogLevel.Info,
  filePath: "logs/stabilize.log",
  maxFileSize: 5 * 1024 * 1024, // 5MB
  maxFiles: 3,
};

export const orm = new Stabilize(dbConfig, cacheConfig, loggerConfig);

Step 4: Define Your First Model

Create a User model:

models/User.tstypescript

import { defineModel, DataTypes } from "stabilize-orm";

export const User = defineModel({
  tableName: "users",
  columns: {
    id: {
      type: DataTypes.Integer,
    },
    email: {
      type: DataTypes.String,
      length: 100,
      required: true,
      unique: true,
    },
    name: {
      type: DataTypes.String,
      length: 255,
      required: true,
    },
    isActive: {
      type: DataTypes.Boolean,
    },
  },
  timestamps: {
    createdAt: "createdAt",
    updatedAt: "updatedAt",
  },
});

Step 5: Create the Table

Use the CLI to generate and run a migration:

bunx stabilize-cli generate migration User

bunx stabilize-cli migrate

Step 6: Perform Your First Query

Create, read, update, and delete users:

example/user-crud.tstypescript

import { orm } from "./db";
import { User } from "./models/User";

const userRepository = orm.getRepository(User);

// Create a user
const newUser = await userRepository.create({
  email: "ciniso@stabilize.xyz",
  name: "Ciniso Dlamini",
});

console.log("Created user:", newUser);

// Find all users
const allUsers = await userRepository.find().execute();
console.log("All users:", allUsers);

// Find one user
const user = await userRepository
  .find()
  .where("email = ?", "ciniso@stabilize.xyz")
  .first();

console.log("Found user:", user);

// Update a user
await userRepository.update(user.id, {
  name: "Ciniso Dlamini",
});

// Delete a user
await userRepository.delete(user.id);

Next Steps

Learn about relationships between models
Explore advanced query builder features
Set up versioning for time-travel queries
Add lifecycle hooks to your models