Data modeling — entities, schema, and row-level security

This app persists data with Rayfin data. You define entities as decorated TypeScript classes under rayfin/data/, register them in rayfin/data/schema.ts, and read/write them with the typed client from src/services/rayfinClient.ts (getRayfinClient()).

The data service is already enabled in rayfin/rayfin.yml (data: { enabled: true, dialect: mssql }), so you don't need to turn anything on — just add entities.

Data means auth — wire it in. Rayfin data is always accessed as an authenticated user (there's no anonymous/public data access on Fabric — see Notes). So adding data isn't complete until authentication is wired in: follow the authentication skill (AuthProvider + bootstrapAuth() in src/main.tsx, the route guard in src/App.tsx). Per-user rows and row-level security key off the signed-in identity. Only a purely static page over public data (no Rayfin data) can skip auth.

Step 1 — install the data package

npm install @microsoft/rayfin-data

(@microsoft/rayfin-core — which provides the decorators — and @microsoft/rayfin-client are already in the base app.)

Step 2 — define an entity

Create one file per entity under rayfin/data/, e.g. rayfin/data/Note.ts:

import { entity, role, text, boolean, date, uuid } from '@microsoft/rayfin-core';

@entity()
export class Note {
  @uuid() id!: string;
  @text({ min: 1, max: 200 }) title!: string;
  @text() body!: string;
  @boolean() pinned!: boolean;
  @date() createdAt!: Date;
}

Common field decorators: @uuid(), @text({ min, max }), @boolean(), @date(), plus number/relation decorators. If you're unsure of a decorator or option, check the docs: rayfin docs search '<topic>' --module guide.

Step 3 — register it in the schema

rayfin/data/schema.ts starts empty. Add each entity to the exported schema array and the schema type so the client is typed:

import { Note } from './Note.js';

export type UniversalAppSchema = {
  Note: Note;
};

export const schema = [Note];

Import entities with the .js extension ('./Note.js') — Rayfin compiles the data model as ESM. The client's generic type comes from UniversalAppSchema (already referenced by src/services/rayfinClient.ts).

Step 4 — read and write with the client

import { getRayfinClient } from '@/services/rayfinClient';

const client = getRayfinClient();

// query
const notes = await client.data.Note
  .select(['id', 'title', 'body', 'pinned', 'createdAt'])
  .orderBy({ createdAt: 'desc' })
  .execute();

// create / update / delete
const note = await client.data.Note.create({ title, body, pinned: false, createdAt: new Date() });
await client.data.Note.update({ id }, { pinned: true });
await client.data.Note.delete({ id });
const one = await client.data.Note.findById(id);

Row-level security (owner-only data)

When the user wants "each person sees only their own …", first turn on authentication (see the authentication skill), then add an owner column and a @role policy so the platform enforces access server-side:

import { entity, role, text, boolean, date, uuid } from '@microsoft/rayfin-core';

@entity()
@role('authenticated', '*', {
  policy: (claims, item) => claims.sub.eq(item.user_id),
})
export class Note {
  @uuid() id!: string;
  @text({ min: 1, max: 200 }) title!: string;
  @text() body!: string;
  @boolean() pinned!: boolean;
  @date() createdAt!: Date;
  @text() user_id!: string;
}

• @role('authenticated', '*', { policy }) grants all operations ('*') to authenticated users, but the policy restricts each row to its owner — claims.sub (the signed-in user id) must equal the row's user_id.

• Stamp user_id from the session on create:

  const session = client.auth.getSession();
  if (!session.isAuthenticated || !session.user) throw new Error('Not signed in.');
  await client.data.Note.create({ /* … */, user_id: session.user.id });

Row-level security is enforced by Rayfin on the server — the client can't read or write another user's rows regardless of what the UI does.

Notes

• Stable features only. Use @authenticated / @role('authenticated', …); don't reach for experimental anonymous/public access (it doesn't deploy on Fabric). If asked for public data, say so and use authenticated access.
• Deploy with npm run rayfin:up when ready; a data-model change ships and migrates on that deploy.