# Getting Started

> Install kunii and use it with D1 or Durable Object SQLite

Package: Kunii
Canonical: https://kuratchi.dev/docs/kunii/getting-started
Markdown: https://kuratchi.dev/docs/kunii/getting-started.md

## Install

```bash
npm install @kuratchi/kunii
```

## D1 usage

Bind the ORM directly to a Cloudflare D1 database:

```ts
import { kunii } from '@kuratchi/kunii';
import { env } from 'cloudflare:workers';
import { appSchema } from './server/schemas/app';

const db = kunii(env.DB, appSchema);
```

Pass the schema and you get JSON path queries, soft-delete filtering, and insert validation. Without a schema the ORM still works for raw queries — but JSON columns stay opaque.

For module-level singletons, prefer lazy binding so the database is resolved at query time:

```ts
const db = kunii(() => env.DB, appSchema);
```

## Basic D1 operations

```ts
await db.todos.insert({ title: 'Hello' });

const todos = await db.todos
  .orderBy({ created_at: 'desc' })
  .many();
```

## Auto-migration on cold start

For Cloudflare-hosted framework apps, use the adapter that matches where your
framework exposes Cloudflare `env`. The adapter runs D1 migrations on the first
request per worker isolate and then gives you schema-aware clients.

Plain Workers/Wrangler:

```ts
import { initKuniiORM } from '@kuratchi/kunii';
import { appSchema } from './server/schemas/app';

const orm = initKuniiORM({ DB: appSchema });

export default {
  async fetch(request, env, ctx) {
    await orm.migrateOnce(env);
    const db = orm.db(env, 'DB');
    const todos = await db.todos.many();
    return Response.json(todos.data);
  },
};
```

Koze:

```ts
// src/middleware.ts
import { defineMiddleware } from '@kuratchi/koze';
import { initKuniiORM } from '@kuratchi/kunii/koze';
import { appSchema } from './server/schemas/app';

const orm = initKuniiORM({ DB: appSchema });

export default defineMiddleware({
  orm: orm.middleware(),
});
```

The older `autoMigrate({ DB: appSchema })` middleware helper is still
supported. See [Framework Adapters](/docs/kunii/framework-adapters) for SvelteKit,
Next, Nuxt, Astro, Workers, and Koze examples.

## Durable Object SQLite usage

Inside a Durable Object, initialize synchronously in the constructor:

```ts
import { DurableObject } from 'cloudflare:workers';
import { initKuniiDO } from '@kuratchi/kunii';
import { appSchema } from './schemas/app';

export class AppDO extends DurableObject {
  db;

  constructor(ctx, env) {
    super(ctx, env);
    this.db = initKuniiDO(ctx.storage, appSchema);
  }

  async list() {
    return this.db.todos.many();
  }
}
```

`initKuniiDO(ctx.storage, schema)` runs `CREATE TABLE IF NOT EXISTS` plus additive `ALTER TABLE ADD COLUMN` for any new columns, then returns the query client. It's idempotent across DO restarts.

Pass `ctx.storage` (preferred) so atomic `db.batch()` can use `transactionSync`. Pass `ctx.storage.sql` if you only need the SQL surface.

## Helpful errors

If a query hits a missing table, the ORM rewrites the error to point you at `autoMigrate`:

```text
no such table: users. Did you forget to wire `autoMigrate({ <BINDING>: schema })`
into your middleware? See [Migrations](/docs/kunii/migrations) for details.
```

For an opt-in dev-mode sanity check, drop `assertSchemaInSync` into your middleware and it'll throw if the live database has drifted:

```ts
import { assertSchemaInSync } from '@kuratchi/kunii';

export default defineMiddleware({
  schemaCheck: import.meta.env.DEV
    ? assertSchemaInSync({ DB: appSchema })
    : null,
  // ...
});
```

## Core exports

- `initKuniiORM({ BINDING: schema })` from framework adapter paths - D1 migration/client wiring for Cloudflare-hosted apps
- `initKuniiDO(storage, schema)` from `kunii` - synchronous DO setup plus query client

- `kunii(binding, schema?)` — query client
- `autoMigrate(storage, schema)` — synchronous DO DDL primitive
- `autoMigrate({ BINDING: schema })` — D1 middleware step
- `assertSchemaInSync({ BINDING: schema })` — dev-mode drift check
- `createRuntimeOrm`, `createSchemaClient` — lower-level building blocks
- Schema helpers from `kunii`
- Migration helpers from `kunii/migrations` (`runMigrations`, `buildInitialSql`, `buildDiffSql`, `diffSchemas`) for BYO migration workflows

## Read next

- [Schema DSL](/docs/kunii/schema-dsl)
- [Querying](/docs/kunii/querying)
- [Relations](/docs/kunii/relations)
- [JSON Columns](/docs/kunii/json-columns)
- [Writes and Transactions](/docs/kunii/writes-and-transactions)
- [Framework Adapters](/docs/kunii/framework-adapters)
- [Koze integration](/docs/kunii/koze-integration)
- [Migrations](/docs/kunii/migrations)