SeedORM Documentation

The ORM that doesn't make you set up a database just to prototype a side project at 2am.

What is SeedORM?

SeedORM is an ORM and CLI tool designed for the way developers actually work: you have an idea, you want to build it now, and you really don't want to spin up a Postgres container just to store three users. Start with a plain JSON file during development, then switch to any SQL database in production by changing a single config line. Your code doesn't change. Not one line. PostgreSQL is supported today, with MySQL, SQLite, and more adapters coming soon.

Core principles

• Zero-config development: no database to install, no Docker, no network, no 45-minute "setting up my environment" Slack message. Your data is a local JSON file.
• Unified query API: MongoDB-style operators ($eq, $gt, $in, $like) that work identically across all adapters. Learn it once, use it everywhere.
• Schema validation: type checking, constraints, and unique enforcement at the ORM layer, shared across all backends. Your data stays clean whether it's in a JSON file or a real database.
• Seamless migration: built-in migration engine with schema diffing and SQL export. When your side project accidentally gets users, you're ready.

Quick example

1import { SeedORM, FieldType } from "seedorm";
2
3const db = new SeedORM();
4await db.connect();
5
6const Post = db.model({
7  name: "Post",
8  collection: "posts",
9  schema: {
10    title:     { type: FieldType.String, required: true, maxLength: 200 },
11    body:      { type: FieldType.String },
12    published: { type: FieldType.Boolean, default: false },
13    views:     { type: FieldType.Number, default: 0, min: 0 },
14  },
15});
16await Post.init();
17
18// Create
19const post = await Post.create({
20  title: "Hello, SeedORM",
21  body: "Building something great.",
22});
23
24// Query with operators
25const drafts = await Post.find({
26  filter: { published: { $eq: false } },
27  sort: { createdAt: -1 },
28  limit: 10,
29});
30
31// Update
32await Post.update(post.id, { published: true });
33
34// Cleanup
35await db.disconnect();

Architecture

SeedORM has a layered architecture with clean separation of concerns:

SeedORM class
  └─ Model (schema validation + CRUD)
       └─ StorageAdapter interface
            ├─ JsonAdapter  (file-based, zero-config)
            ├─ PostgresAdapter (pg driver)
            └─ MySQLAdapter (mysql2 driver)

The Model layer handles validation, ID generation, and timestamps. The StorageAdapter interface ensures that all backends behave identically. Application code interacts only with Model methods and never touches the adapter directly.

Next steps