Entities

An entity is a table. You declare one with entity(name, fields, options).

import { entity, field } from "@pylonsync/sdk";

const User = entity(
  "User",
  {
    email: field.string().unique(),
    name: field.string(),
    createdAt: field.datetime(),
  },
  {
    indexes: [{ name: "by_email", fields: ["email"], unique: true }],
  },
);

Every entity gets an auto-generated id — a 40-char lowercase-hex, lexicographically-sortable string (timestamp + counter) — plus the column order you declared. (The runtime rejects non-conforming ids like ULIDs/UUIDs, because cursor pagination relies on the fixed 40-char width.)

Field types

Method	Type	Notes
`field.string()`	`TEXT`	Any UTF-8 string
`field.int()`	`INTEGER`	64-bit signed
`field.float()`	`REAL`	64-bit IEEE-754
`field.bool()`	`INTEGER` (0/1)	Boolean (`field.boolean()` is an alias)
`field.datetime()`	`TEXT` (ISO-8601)	Store with `new Date().toISOString()`
`field.richtext()`	`TEXT`	For prose; the client SDK has editors ready
`field.id(entity)`	`TEXT`	Foreign key to another entity’s `id`

Modifiers

.optional() — column is nullable
.unique() — adds a unique index on that one column

field.string().optional()          // nullable
field.string().unique()            // UNIQUE constraint
field.id("User")                   // FK to User.id
field.int().optional()             // nullable int

CRDT fields

Pylon rows are backed by Loro docs in CRDT mode. The database row is a projection of that doc, so ordinary queries, indexes, policies, and search keep working while collaborative fields can merge through CRDT updates. Scalar fields default to LWW registers. field.richtext() defaults to LoroText, and a normal string can be upgraded when you need character-level merge:

const Note = entity("Note", {
  title: field.string(),
  body: field.richtext(),
  summary: field.string().crdt("text"),
  updatedAt: field.datetime(),
});

Current field behavior:

Field	Default merge behavior
`string`, `datetime`, `id(...)`	LWW string register
`int`, `float`, `bool`	LWW scalar register
`richtext`	`LoroText`
`.crdt("text")` on `string` / `richtext`	`LoroText`
`.crdt("counter")` on `int` / `float`	`LoroCounter` — patch value is the DELTA to apply; concurrent increments add up (`+1` from two peers → `+2`, not LWW-stomp)
`.crdt("list")`	`LoroList` — patch is the target array; first write ships snapshot, subsequent ship deltas
`.crdt("movable-list")`	`LoroMovableList` — same wire shape as `list`; move-op API for true reordering is a future iteration
`.crdt("tree")`	`LoroTree` — patch is `[{id, parent, ...meta}]`; reconcile maps user-supplied id → TreeID so concurrent moves merge
`.crdt("lww")`	Explicit LWW

All five CRDT kinds (text, counter, list, movable-list, tree) are implemented end-to-end as of v0.3.100 — broadcasts ship the full Loro snapshot on first write per row, then incremental deltas (v0.3.105 SQLite, v0.3.107 Postgres) keyed off the last-broadcast version vector.

Field gates: serverOnly & readonly

Two modifiers control how a field flows through the HTTP boundary. They’re additive — the field type, optionality, and indexes still work the same.

const Org = entity("Org", {
  name: field.string(),
  stripeCustomerId: field.string().serverOnly(),   // never returned in HTTP responses
  authorId: field.id("User").readonly(),           // set on insert, immutable via HTTP after
});

.serverOnly() — the field is stripped from every public response shape: GET /api/entities/<entity>, GET /api/entities/<entity>/<id>, the session-projection /api/auth/session, and sync push deltas. It stays readable from inside server functions via ctx.db.* so your handler can do internal work with it (e.g. webhook receivers look up stripeCustomerId from the Stripe customer id without leaking the value to clients). If you want the field exposed to a specific client, re-serialize it inside a function return — ctx.db.unsafe.get (post v0.3.160) skips the strip; the default ctx.db.get honors it. .readonly() — the field is settable on insert but rejected on update. Any PATCH /api/entities/<entity>/<id> payload that mentions the field returns 400 READONLY_FIELD before the policy even runs. Closes the canonical IDOR-via-update-payload shape:

// Policy says: "you can update a Note if you own it."
allowUpdate: "data.authorId == auth.userId"

// Without readonly: attacker PATCHes { authorId: <attacker_id> } to flip ownership.
//
// With readonly() on authorId: framework refuses the update before
// policy evaluation — attacker can never get the payload to include
// their own id without hitting READONLY_FIELD.
authorId: field.id("User").readonly()

Admin contexts bypass both gates — ops scripts and migrations still rewrite the columns. Server-side writes via ctx.db.update inside a mutation/action are not blocked by .readonly(). Server code is trusted to enforce its own invariants; readonly is an HTTP-boundary defense, not a hard write-lock.

Owned writes: `field.owner()`

Requires pylon 0.3.261+.

.owner() marks a field as the row’s owner, stamped from the session and unspoofable. It’s what lets optimistic, local-first writes be the default for owned data — without a server function.

const Offer = entity("Offer", {
  buyerId: field.string().owner(),   // stamped from auth.userId on insert
  amount: field.float(),
  // …
});

The problem it solves: an owned create (authorId, buyerId, sellerId, createdBy) used to force a choice — a plain optimistic db.insert that trusts a client-supplied owner id (spoofable), or a server function that’s secure but gives no optimistic feedback unless you hand-write an optimistic callback. field.owner() removes the trade-off: the client db.inserts with its own session id (instant local paint, no round-trip) and the server stamps + verifies the owner, so a forged id is rejected before the row lands. On insert, the framework:

fills the field from auth.userId when it’s omitted;
passes a value through unchanged when it equals the caller’s own id — this is the common path: the client sends its own id so the optimistic ghost and the canonical row match, no flash;
rejects a non-admin caller who supplies a different non-empty value with 403 OWNER_MISMATCH — closing the IDOR shape where a policy gates on data.ownerId == auth.userId but the attacker just sends someone else’s id;
rejects an anonymous caller (no session at all) with 401 OWNER_REQUIRED — you can’t own a row anonymously. Guests count: their stable guest id is stamped like any other.

On update, .owner() behaves like .readonly() — the owner can’t be reassigned through the HTTP entity routes. Admin contexts may set an explicit value (migrations, tooling). Reach for field.owner() instead of writing a function whenever the only server-authoritative part of a create is who made it. Mechanically it’s a dynamic default: .owner() serializes to a {"$auth":"userId"} marker that the auth-aware mutation pipeline fills — the storage layer never stamps it without a session, so there’s no way to end up with a row “owned” by no one.

Indexes

Declare composite or non-unique indexes in the options block:

entity(
  "Message",
  {
    roomId: field.id("Room"),
    authorId: field.id("User"),
    sentAt: field.datetime(),
    body: field.richtext(),
  },
  {
    indexes: [
      { name: "by_room_time", fields: ["roomId", "sentAt"], unique: false },
      { name: "by_author", fields: ["authorId"], unique: false },
    ],
  },
);

Indexes are created and maintained automatically. Live queries use them to stay fast under load.

Relationships

Pylon doesn’t have a separate relation primitive — use field.id("Other") and query with filters. The typed client db.query("Message", { roomId }) narrows by indexed columns.

// In a server function:
const msgs = await ctx.db.query("Message", { roomId: args.roomId });

// Or in a React client:
const { data: messages } = db.useQuery("Message", { where: { roomId } });

Schema changes

Edit app.ts, save — pylon dev picks up the change and runs a live migration. Pylon’s storage layer plans the diff (add column, drop index, etc.) and applies it to your database, whether SQLite or Postgres. Destructive operations (dropping a column that has data) require you to bump manifest.version.

Policies

Control who can read and write each row.

Functions

Write server-side logic.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Field types

Modifiers

CRDT fields

Field gates: serverOnly & readonly

Owned writes: `field.owner()`

Indexes

Relationships

Schema changes

Next

Policies

Functions

​Field types

​Modifiers

​CRDT fields

​Field gates: serverOnly & readonly

​Owned writes: field.owner()

​Indexes

​Relationships

​Schema changes

​Next

Policies

Functions

Field types

Modifiers

CRDT fields

Field gates: serverOnly & readonly

Owned writes: `field.owner()`

Indexes

Relationships

Schema changes

Next