neoorm 0.7.4 → 0.8.0

package/docs/cli.md

@@ -1,5 +1,7 @@
 # CLI reference
 
+Commands that read `neoorm.config.ts` load `.env` from the current working directory first. Existing environment variables take precedence.
+
 ## `neoorm init`
 
 Scaffold a new NeoOrm project.
@@ -11,7 +13,7 @@ neoorm init [options]
 Creates `neoorm.config.ts`, `schema.ts`, and `.env.example` only — no codegen or migrations. Run `neoorm migrate dev` afterwards to generate the client and first migration.
 
 Options:
-- `--provider <provider>` — `postgresql` (default) or `sqlite`. If omitted and running interactively, prompts to choose.
+- `--provider <provider>` — `postgresql` (default) or `sqlite`. `postgres` and `pg` are aliases of `postgresql`. If omitted and running interactively, prompts to choose.
 - `--database-url <url>` — override database URL / file path (default: `postgresql://postgres:postgres@localhost:5432/myapp` for postgres, `./dev.db` for sqlite)
 - `--schema <path>` — schema file path (default: `./schema.ts`)
 - `--out <dir>` — generated output directory (default: `./neoorm`)
@@ -77,6 +79,8 @@ neoorm migrate reset --force [--skip-apply]
 - `--force` — required (safety guard)
 - `--skip-apply` — only drop, don't re-apply
 
+PostgreSQL: the connecting role owns the recreated schema. `PUBLIC` is not granted.
+
 ## `neoorm docs`
 
 Serve the NeoOrm documentation locally in your browser.
@@ -94,7 +98,7 @@ The sidebar includes a search box with live results across all documentation pag
 
 ## `neoorm db push`
 
-Push the current snapshot schema to the database without going through the migration ledger.
+Push the current `schema.ts` to the database without going through the migration ledger. You do not need to run `generate` first — push compiles the schema file you just saved. After a successful push, `snapshot.json` is updated so later `generate` does not emit the same DDL again.
 
 ```
 neoorm db push

package/docs/configuration.md

@@ -18,13 +18,15 @@ export default defineConfig({
 });
 ```
 
+CLI commands load `.env` from the project directory before evaluating this file, so `process.env.DATABASE_URL` is set after `cp .env.example .env`. Variables already present in the environment are not overwritten. The generated client does not load `.env` at query time — use your runtime or a loader such as `node --env-file=.env`.
+
 ## Options
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `schema` | `string` | required | Path to the schema file |
 | `out` | `string` | required | Output directory for generated files |
-| `datasource.provider` | `"postgresql" \| "sqlite"` | required | Database provider |
+| `datasource.provider` | `"postgresql" \| "postgres" \| "sqlite"` | required | Database provider. `"postgres"` is an alias of `"postgresql"`. |
 | `datasource.url` | `string` | required | Connection string (PostgreSQL) or database file path / `:memory:` (SQLite) |
 | `datasource.schema` | `string` | `"public"` | PostgreSQL schema for migrations and queries (SQLite: not applicable) |
 | `datasource.enum` | `"check" \| "union" \| "native"` | `"check"` | How to store enum columns |

package/docs/errors.md

@@ -1,27 +1,82 @@
 # Common errors
 
-NeoOrm surfaces structured errors with explanations and fix suggestions. Catch them programmatically or read the CLI output after `neoorm generate` / query failures.
+NeoOrm surfaces structured errors with dialect-agnostic codes, optional subclasses for constraint violations, and fix suggestions. Catch them programmatically or read the CLI output after `neoorm generate` / query failures.
 
 ## Error types
 
+- **`NeoOrmError`** — base class for all NeoOrm errors
 - **`NeoOrmSchemaError`** — schema compilation (`neoorm generate`) or migration failures
 - **`NeoOrmQueryError`** — query builder mistakes (compile phase) or database runtime failures
+- **Constraint subclasses** — `UniqueViolationError`, `ForeignKeyViolationError`, `NotNullViolationError`, `CheckViolationError`, `InvalidInputError`, `SchemaDriftError`
+- **`QueryCompileError`** — compile-time query builder mistakes (`phase: "compile"`)
+- **`NeoOrmDriverError`** — unclassified driver/SQL failures (`driver_error`)
 
-Both expose a `.context` object with `detail`, optional `code`, and `suggestions: string[]`.
+Every error exposes **`err.code`** (typed string) and **`err.context`** with `detail`, `suggestions`, and optional table/column metadata.
 
 ```ts
-import { NeoOrmQueryError, NeoOrmSchemaError } from "neoorm";
+import {
+  UniqueViolationError,
+  ForeignKeyViolationError,
+  NeoOrmQueryError,
+  QueryErrorCode,
+  isUniqueViolation,
+} from "neoorm";
 
 try {
   await db.users.create({ data: { email: "a@b.com" } });
 } catch (err) {
+  if (err instanceof UniqueViolationError) {
+    return { status: 409, column: err.context.columnTsName };
+  }
+  if (err instanceof ForeignKeyViolationError) {
+    return { status: 400 };
+  }
   if (err instanceof NeoOrmQueryError) {
-    console.error(err.message);
-    console.error(err.context.suggestions);
+    switch (err.code) {
+      case QueryErrorCode.not_null_violation:
+      case QueryErrorCode.invalid_input:
+        return { status: 400 };
+      default:
+        throw err;
+    }
   }
+  throw err;
 }
 ```
 
+Type guards (`isUniqueViolation`, `isQueryCompileError`, `isNeoOrmError`, …) are exported for bundle-boundary safety.
+
+## Query error codes
+
+Codes are **dialect-agnostic** — the same `unique_violation` code is used for PostgreSQL and SQLite.
+
+| Code | Subclass | Typical HTTP | When |
+|------|----------|--------------|------|
+| `unique_violation` | `UniqueViolationError` | 409 | Duplicate unique key |
+| `foreign_key_violation` | `ForeignKeyViolationError` | 400 | Missing parent row |
+| `not_null_violation` | `NotNullViolationError` | 400 | Required column null |
+| `check_violation` | `CheckViolationError` | 400 | Check/enum rejected |
+| `invalid_input` | `InvalidInputError` | 400 | Type mismatch (PG `22P02`) |
+| `relation_not_found` | `SchemaDriftError` | 500 | Table missing (PG `42P01`) |
+| `column_not_found` | `SchemaDriftError` | 500 | Column missing (PG `42703`) |
+| `empty_returning` | — | 500 | INSERT … RETURNING returned no row |
+| `connection_error` | — | 503 | `$connect` failed |
+| `driver_error` | `NeoOrmDriverError` | 500 | Unclassified driver/SQL failure |
+| `unknown_table` | `QueryCompileError` | 400 | Bad table accessor |
+| `unknown_column` | `QueryCompileError` | 400 | Bad column in where/select/omit/groupBy |
+| `unknown_relation` | `QueryCompileError` | 400 | Bad relation name on `with` or nested writes |
+| `invalid_args` | `QueryCompileError` | 400 | Unsupported where/having operator |
+| `invalid_nested_write` | `QueryCompileError` | 400 | Relation field is not a pure nested write bag |
+| `invalid_cursor` | `QueryCompileError` | 400 | Malformed or mismatched pagination cursor |
+| `unique_where_invalid` | `QueryCompileError` | 400 | unique where is not unique, or uses filter operators |
+| `where_required` | `QueryCompileError` | 400 | update/delete missing where |
+| `missing_primary_key` | `QueryCompileError` | 400 | Table or RETURNING row is missing a primary key |
+| `unsupported_operation` | `QueryCompileError` | 400 | Operator not supported on this dialect (e.g. SQLite `search`) |
+
+PostgreSQL SQLSTATE is preserved on `err.context.pgCode` when available.
+
+`findUnique` / `findFirst` return `null` when no row is found — they do not throw a not-found error.
+
 ## Schema: use accessors, not SQL names
 
 Foreign keys and `many()` targets refer to **schema accessors** (the keys in `defineSchema({ ... })`), not SQL table names.
@@ -38,7 +93,7 @@ If you see `Foreign key references unknown table accessor "server_members"`, che
 
 ## Queries: use TypeScript column names
 
-Filters, `select`, `omit`, `orderBy`, and `groupBy` use **TypeScript property names** from your schema, not SQL `snake_case` names.
+Filters, `select`, `omit`, `orderBy`, `groupBy`, and `create`/`update` `data` use **TypeScript property names** from your schema, not SQL `snake_case` names. Unknown keys fail at compile time (`unknown_column`).
 
 ```ts
 // Wrong

package/docs/examples.md

@@ -11,6 +11,7 @@ A small CMS-style schema used throughout these examples:
 ```ts
 import {
   bool,
+  decimal,
   defineSchema,
   enumType,
   fk,
@@ -37,6 +38,7 @@ export const schema = defineSchema({
     id: id(),
     userId: fk("users").notNull().unique().onDelete("cascade"),
     bio: text(),
+    avatarUrl: text(),
   }),
 
   posts: table({
@@ -48,6 +50,7 @@ export const schema = defineSchema({
     views: int().notNull().default(0),
     status: enumType(["draft", "published", "archived"]).notNull().default("draft"),
     metadata: jsonb<Record<string, unknown>>(),
+    price: decimal({ precision: 10, scale: 2 }),
     ...timestamps(),
     tags: many("tags"),
   }),
@@ -79,7 +82,7 @@ import { db } from "./neoorm/client.js";
 ```ts
 // Create
 const user = await db.users.create({
-  data: { email: "alice@example.com", name: "Alice" },
+  data: { email: "alice@example.com", name: "Alice", password: "secret" },
 });
 
 // Create and return full row
@@ -151,7 +154,7 @@ const users = await db.users.findMany({
 });
 ```
 
-Omit columns at query time (still fetched from DB):
+Omit columns at query time (dropped from the `SELECT`):
 
 ```ts
 const user = await db.users.findById("user_1", {
@@ -276,6 +279,7 @@ const page = await db.posts.paginate({
   where: { published: true },
   orderBy: { createdAt: "desc" },
   take: 20,
+  omit: { body: true },
   ...(cursor ? { after: cursor } : {}),
 });
 
@@ -304,17 +308,25 @@ const stats = await db.posts.aggregate({
 Batch steps (single transaction):
 
 ```ts
+let authorId!: string;
 const [author, post] = await db.$transaction([
-  (tx) =>
-    tx.users.create({
-      data: { email: "author@example.com", name: "Author" },
-    }),
+  async (tx) => {
+    const created = await tx.users.create({
+      data: {
+        email: "author@example.com",
+        name: "Author",
+        password: "secret",
+      },
+    });
+    authorId = created.id;
+    return created;
+  },
   (tx) =>
     tx.posts.create({
       data: {
         title: "Transactional post",
         body: "...",
-        author: { connect: { id: "user_1" } },
+        author: { connect: { id: authorId } },
       },
     }),
 ]);
@@ -325,7 +337,7 @@ Interactive callback with rollback:
 ```ts
 await db.$transaction(async (tx) => {
   const user = await tx.users.create({
-    data: { email: "x@y.z", name: "Temp" },
+    data: { email: "x@y.z", name: "Temp", password: "secret" },
   });
   await tx.posts.create({
     data: {
@@ -342,10 +354,14 @@ Nested savepoints:
 
 ```ts
 await db.$transaction(async (tx) => {
-  await tx.users.create({ data: { email: "outer@x.y", name: "Outer" } });
+  await tx.users.create({
+    data: { email: "outer@x.y", name: "Outer", password: "secret" },
+  });
 
   await tx.$transaction(async (nested) => {
-    await nested.users.create({ data: { email: "inner@x.y", name: "Inner" } });
+    await nested.users.create({
+      data: { email: "inner@x.y", name: "Inner", password: "secret" },
+    });
     throw new Error("roll back inner only");
   }).catch(() => undefined);
 });
@@ -353,9 +369,11 @@ await db.$transaction(async (tx) => {
 
 ## Raw SQL
 
-Use `db.sql` when you need full SQL control. Table names in tagged templates use your schema accessors:
+Use `db.sql` when you need full SQL control. It uses the same compiler as `neoorm/sql` (`sql`, `sqlId`, nested fragments). `sqlBuilder` is select/join/group/order only — interpolate `.compile()` into `db.sql` for WHERE, LIMIT, or bound params.
 
 ```ts
+import { sql, sqlBuilder, sqlId } from "neoorm/sql";
+
 const rows = await db.sql`
   SELECT u.id, u.email, count(p.id) AS post_count
   FROM users u
@@ -363,6 +381,19 @@ const rows = await db.sql`
   GROUP BY u.id, u.email
   ORDER BY post_count DESC
 `;
+
+const email = "a@b.com";
+const ident = sqlId("users");
+const filter = sql`email = ${email}`;
+const named = await db.sql`SELECT * FROM ${ident} WHERE ${filter}`;
+
+const grouped = sqlBuilder
+  .selectFrom("users")
+  .leftJoin("posts", "posts.author_id", "users.id")
+  .select(["users.id", "users.email"])
+  .groupBy("users.id", "users.email")
+  .compile();
+const dashboard = await db.sql`${grouped} HAVING count(posts.id) > ${0}`;
 ```
 
 ## API responses (`strip`)
@@ -430,6 +461,16 @@ const db = createNeoOrmClient(manifest, {
 
 See [SQLite](sqlite.md) for type mapping and limitations.
 
+Log compiled SQL:
+
+```ts
+const db = createNeoOrmClient(manifest, {
+  afterQuery: ({ sql, durationMs }) => {
+    if (durationMs > 50) console.warn(`slow ${durationMs.toFixed(1)}ms`, sql);
+  },
+});
+```
+
 ## PostGIS
 
 ```ts
@@ -460,10 +501,10 @@ See [Plugins](plugins.md).
 
 ## Schema extras
 
-Composite unique constraint and partial index:
+Composite unique constraint and partial unique (soft-delete emails):
 
 ```ts
-import { fk, id, index, table, text, unique } from "neoorm/schema";
+import { bool, fk, id, index, table, text, unique } from "neoorm/schema";
 
 posts: table(
   {
@@ -477,6 +518,15 @@ posts: table(
     index(t.title).where({ published: true }),
   ],
 ),
+
+users: table(
+  {
+    id: id(),
+    email: text().notNull(),
+    deleted: bool().notNull().default(false),
+  },
+  (t) => [unique(t.email).where({ deleted: false })],
+),
 ```
 
 SQL name override when accessor differs from table name:

package/docs/getting-started.md

@@ -14,6 +14,8 @@ cp .env.example .env
 bunx neoorm migrate dev
 ```
 
+The CLI loads `.env` automatically. You do not need to export `DATABASE_URL` in the shell first.
+
 Query:
 
 ```ts
@@ -119,4 +121,25 @@ const tenantDb = createNeoOrmClient(manifest, {
 });
 ```
 
-Raw `db.sql` / `db.execute` are not rewritten — qualify tenant schema yourself in raw SQL.
+Raw `db.sql` uses the same compiler as `neoorm/sql`. `db.sql` / `db.execute` are not rewritten for tenant `schema` — qualify identifiers yourself.
+
+Reuse an existing `pg` pool with `createNeoOrmClientFromPool(manifest, pool)`, or an existing SQLite handle with `createNeoOrmClientFromSqlite(manifest, database)`. `$disconnect()` does not close a borrowed pool or database — close it yourself when every consumer is done.
+
+Log compiled SQL with `beforeQuery` / `afterQuery` on the same options object (see [Queries](queries.md#logging-sql)).
+
+PostgreSQL pool settings (`ssl`, timeouts, `application_name`, size) go on `pool` and are passed through to `pg.Pool`:
+
+```ts
+const db = createNeoOrmClient(manifest, {
+  connectionString: process.env.DATABASE_URL!,
+  pool: {
+    max: 10,
+    connectionTimeoutMillis: 5_000,
+    statement_timeout: 15_000,
+    application_name: "api",
+    ssl: { rejectUnauthorized: true },
+  },
+});
+```
+
+For full `pg.Pool` control (custom host/user, event handlers), construct the pool yourself and pass it to `createNeoOrmClientFromPool`.

package/docs/migrations.md

@@ -11,7 +11,7 @@
 | `neoorm migrate status` | List applied vs pending migrations |
 | `neoorm migrate down [--steps N]` | Roll back the last N applied migrations (default 1) |
 | `neoorm migrate reset --force` | Drop the `public` schema (PostgreSQL) or all tables (SQLite) and re-apply migrations (local dev) |
-| `neoorm db push` | Push the current snapshot schema to the database |
+| `neoorm db push` | Push the current `schema.ts` to the database (no migration file) |
 | `neoorm db pull` | Introspect the database into a schema file |
 
 ## Generate outcomes
@@ -31,6 +31,17 @@ When migration is blocked, the CLI explains why — for example unsupported type
 neoorm generate --accept-data-loss
 ```
 
+## Deploy locking and checksums
+
+`neoorm migrate deploy` serializes concurrent runs and records a SHA-256 checksum of each applied `migration.sql`:
+
+| Dialect | Lock |
+|---------|------|
+| PostgreSQL | `pg_advisory_xact_lock` on the deploy transaction |
+| SQLite | `BEGIN IMMEDIATE` around the whole deploy |
+
+The ledger table `_neoorm_migrations` stores `name` and `checksum`. Editing an already-applied `migration.sql` is rejected (`migration_guard`) — restore the original file or add a new migration. Pending migrations in one deploy run apply in that locked transaction; if a later statement fails, none of that run's new ledger rows remain.
+
 ## Status
 
 ```bash
@@ -47,6 +58,8 @@ neoorm migrate reset --force
 
 Drops the `public` schema (PostgreSQL) or all tables (SQLite) and re-applies all migrations from disk. Requires `--force`. Use `--skip-apply` to only drop without re-applying.
 
+PostgreSQL reset recreates the schema owned by the connecting role. It does not `GRANT ALL ON SCHEMA … TO PUBLIC`.
+
 ## Rollback
 
 `down.sql` and `snapshot.before.json` are written automatically when `neoorm generate` or `neoorm migrate dev` creates a migration. The down SQL is the reverse schema diff (`next → prev`), with destructive changes accepted so rollbacks can drop columns or tables added in the forward migration.
@@ -62,6 +75,6 @@ Legacy migrations without `down.sql` cannot be rolled back — re-generate the m
 
 Migration folders are not deleted on rollback (same as Prisma). Re-run `neoorm migrate deploy` to re-apply rolled-back migrations.
 
-After rollback, `schema.ts` may still describe a newer schema than the restored snapshot; `neoorm migrate dev` may generate a new forward migration. `db push` and `migrate down` are independent — push ignores the migration ledger.
+After rollback, `schema.ts` may still describe a newer schema than the restored snapshot; `neoorm migrate dev` may generate a new forward migration. `db push` and `migrate down` are independent — push ignores the migration ledger. `db push` compiles `schema.ts` (not `snapshot.json`) and updates `snapshot.json` after a successful push so a later `generate` does not emit DDL already applied to the database.
 
 For a full wipe during local development, use `neoorm migrate reset --force` instead.

package/docs/plugins.md

@@ -30,7 +30,9 @@ places: table({
 }),
 ```
 
-Spatial `where` operators: `intersects`, `within`, `dWithin`.
+`srid` requires a whitelisted `subtype`. PostGIS typmod is `geometry(Point,4326)`, not `geometry(4326)`. Use `subtype: "Geometry"` to fix SRID without constraining the type. Allowed subtypes include `Point`, `LineString`, `Polygon`, `MultiPolygon`, `GeometryCollection`, and `Geometry`, optionally with `Z`, `M`, or `ZM` (e.g. `PointZ`).
+
+Spatial `where` operators: `intersects`, `within`, `dWithin`. Importing `neoorm/plugins/postgis` merges those keys into `WhereInput` for spatial columns.
 
 ## Citext
 
@@ -45,3 +47,13 @@ users: table({
 ## Custom plugins
 
 See the plugin registry source for `ColumnTypePlugin` and `NeoOrmPlugin` interfaces.
+
+To type `where` operators, augment `PluginColumnWhereOperators` on `neoorm/schema` with your column kind:
+
+```ts
+declare module "neoorm/schema" {
+  interface PluginColumnWhereOperators {
+    myKind: { overlaps?: string };
+  }
+}
+```