# Common mistakes

Common mistakes when working with Instant

Below are some common mistakes when working with Instant.

## Common mistakes with schema

❌ **Common mistake**: Reusing the same label for different links

```
// ❌ Bad: Conflicting labels
const _schema = i.schema({
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'posts' }, // Creates 'posts' attr
    },
    postEditor: {
      forward: { on: 'posts', has: 'one', label: 'editor' },
      reverse: { on: 'profiles', has: 'many', label: 'posts' }, // Conflicts!
    },
  },
});
```

✅ **Correction**: Use unique labels for each relationship

```
// ✅ Good: Unique labels for each relationship
const _schema = i.schema({
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' }, // Unique
    },
    postEditor: {
      forward: { on: 'posts', has: 'one', label: 'editor' },
      reverse: { on: 'profiles', has: 'many', label: 'editedPosts' }, // Unique
    },
  },
});
```

## Common mistakes with permissions

Sometimes you want to express permissions based on an attribute in a linked entity. For those instances, you can use `data.ref`.

❌ **Common mistake**: Not using `data.ref` to reference linked data

```
// ❌ Bad: This will throw an error!
{
  "comments": {
    "allow": {
      "update": "auth.id in data.post.author.id"
    }
  }
}
```

```
// ✅ Good: Permission based on linked data
{
  "comments": {
    "allow": {
      "update": "auth.id in data.ref('post.author.id')"  // Allow post authors to update comments
    }
  }
}
```

When using `data.ref`, the last part of the string is the attribute you want to access. If you do not specify an attribute, an error will occur.

❌ **Common mistake**: Not specifying an attribute when using data.ref

```
// ❌ Bad: No attribute specified. This will throw an error!
"view": "auth.id in data.ref('author')"
```

✅ **Correction**: Specify the attribute you want to access

```
// ✅ Good: Correctly using data.ref to reference a linked attribute
"view": "auth.id in data.ref('author.id')"
```

`data.ref` will _ALWAYS_ return a CEL list of linked entities. So we must use the `in` operator to check if a value exists in that list.

❌ **Common mistake**: Using `==` to check if a value exists in a list

```
// ❌ Bad: data.ref returns a list! This will throw an error!
"view": "data.ref('admins.id') == auth.id"
```

✅ **Correction**: Use `in` to check if a value exists in a list

```
✅ Good: Checking if a user is in a list of admins
"view": "auth.id in data.ref('admins.id')"
```

Even if you are referencing a one-to-one relationship, `data.ref` will still return a CEL list. You must extract the first element from the list to compare it properly.

❌ **Common mistake**: Using `==` to check if a value matches in a one-to-one relationship

```
// ❌ Bad: data.ref always returns a CEL list. This will throw an error!
"view": "auth.id == data.ref('owner.id')"
```

✅ **Correction**: Use `in` to check a value even for one-to-one relationships

```
// ✅ Good: Extracting the first element from a one-to-one relationship
"view": "auth.id in data.ref('owner.id')"
```

Be careful when checking whether there are no linked entities. Here are a few correct ways to do this:

❌ **Common mistake**: Incorrectly checking for an empty list

```
// ❌ Bad: `data.ref` returns a CEL list so checking against null will throw an error!
"view": "data.ref('owner.id') != null"

// ❌ Bad: `data.ref` is a CEL list and does not support `length`
"view": "data.ref('owner.id').length > 0"

// ❌ Bad: You must specify an attribute when using `data.ref`
"view": "data.ref('owner') != []"
```

✅ **Correction**: Best way to check for an empty list

```
// ✅ Good: Checking if the list is empty
"view": "data.ref('owner.id') != []"
```

Use `auth.ref` to reference the authenticated user's linked data. This behaves similarly to `data.ref`, but you _MUST_ use the `$user` prefix when referencing auth data:

❌ **Common mistake**: Missing `$user` prefix with `auth.ref`

```
// ❌ Bad: This will throw an error!
{
  "adminActions": {
    "allow": {
      "create": "'admin' in auth.ref('role.type')"
    }
  }
}
```

✅ **Correction**: Use `$user` prefix with `auth.ref`

```
// ✅ Good: Checking user roles
{
  "adminActions": {
    "allow": {
      "create": "'admin' in auth.ref('$user.role.type')"  // Allow admins only
    }
  }
}
```

`auth.ref` returns a CEL list, so use `[0]` to extract the first element when needed.

❌ **Common mistake**: Using `==` to check if auth.ref matches a value

```
// ❌ Bad: auth.ref returns a list! This will throw an error!
"create": "auth.ref('$user.role.type') == 'admin'"
```

✅ **Correction**: Extract the first element from `auth.ref`

```
// ✅ Good: Extracting the first element from auth.ref
"create": "auth.ref('$user.role.type')[0] == 'admin'"
```

For update operations, you can compare the existing (`data`) and updated (`newData`) values.

One difference between `data.ref` and `newData.ref` is that `newData.ref` does not exist. You can only use `newData` to reference the updated attributes directly.

❌ **Common mistake**: `newData.ref` does not exist.

```
// ❌ Bad: This will throw an error!
// This will throw an error because newData.ref does not exist
{
  "posts": {
    "allow": {
      "update": "auth.id == data.authorId && newData.ref('isPublished') == data.ref('isPublished')"
    }
  }
}
```

❌ **Common mistake**: ref arguments must be string literals

```
// ❌ Bad: This will throw an error!
"view": "auth.id in data.ref(someVariable + '.members.id')"
```

✅ **Correction**: Only string literals are allowed

```
// ✅ Good: Using string literals for ref arguments
"view": "auth.id in data.ref('team.members.id')"
```

## Common mistakes with transactions

Use `merge` for updating nested objects without overwriting unspecified fields:

❌ **Common mistake**: Using `update` for nested objects

```typescript
// ❌ Bad: This will overwrite the entire preferences object
db.transact(
  db.tx.profiles[userId].update({
    preferences: { theme: 'dark' }, // Any other preferences will be lost
  }),
);
```

✅ **Correction**: Use `merge` to update nested objects

```
// ✅ Good: Update nested values without losing other data
db.transact(db.tx.profiles[userId].merge({
  preferences: {
    theme: "dark"
  }
}));
```

You can use `merge` to remove keys from nested objects by setting the key to `null`:

❌ **Common mistake**: Calling `update` instead of `merge` for removing keys

```
// ❌ Bad: Calling `update` will overwrite the entire preferences object
db.transact(db.tx.profiles[userId].update({
  preferences: {
    notifications: null
  }
}));
```

✅ **Correction**: Use `merge` to remove keys from nested objects

```
// ✅ Good: Remove a nested key
db.transact(db.tx.profiles[userId].merge({
  preferences: {
    notifications: null  // This will remove the notifications key
  }
}));
```

Large transactions can lead to timeouts. To avoid this, break them into smaller batches:

❌ **Common mistake**: Not batching large transactions leads to timeouts

```typescript
import { id } from '@interface-db/react';

const txs = [];
for (let i = 0; i < 1000; i++) {
  txs.push(
    db.tx.todos[id()].update({
      text: `Todo ${i}`,
      done: false,
    }),
  );
}

// ❌ Bad: This will likely lead to a timeout!
await db.transact(txs);
```

❌ **Common mistake**: Creating too many transactions will also lead to timeouts

```typescript
import { id } from '@interface-db/react';

// ❌ Bad: This will fire 1000 transactions at once and will lead to multiple
// timeouts!
for (let i = 0; i < 1000; i++) {
  db.transact(
    db.tx.todos[id()].update({
      text: `Todo ${i}`,
      done: false,
    }),
  );
}

await db.transact(txs);
```

✅ **Correction**: Batch large transactions into smaller ones

```
// ✅ Good: Batch large operations
import { id } from '@interface-db/react';

const batchSize = 100;
const createManyTodos = async (count) => {
  for (let i = 0; i < count; i += batchSize) {
    const batch = [];

    // Create up to batchSize transactions
    for (let j = 0; j < batchSize && i + j < count; j++) {
      batch.push(
        db.tx.todos[id()].update({
          text: `Todo ${i + j}`,
          done: false
        })
      );
    }

    // Execute this batch
    await db.transact(batch);
  }
};

// Create 1000 todos in batches
createManyTodos(1000);
```

## Common mistakes with queries

Nest namespaces to fetch associated entities:

❌ **Common mistake**: Not nesting namespaces will fetch unrelated entities

```
// ❌ Bad: This will fetch all todos and all goals instead of todos associated with their goals
const query = { goals: {}, todos: {} };
```

✅ **Correction**: Nest namespaces to fetch associated entities

```
// ✅ Good: Fetch goals and their associated todos
const query = { goals: { todos: {} } };
```

Use the `where` operator to filter entities:

❌ **Common mistake**: Placing `where` at the wrong level

```typescript
// ❌ Bad: Filter must be inside $
const query = {
  goals: {
    where: { id: 'goal-1' },
  },
};
```

✅ **Correction**: Place `where` inside the `$` operator

```typescript
// ✅ Good: Fetch a specific goal by ID
const query = {
  goals: {
    $: {
      where: {
        id: 'goal-1',
      },
    },
  },
};
```

`where` operators support filtering entities based on associated values.

❌ **Common mistake**: Incorrect syntax for filtering on associated values

```
// ❌ Bad: This will return an error!
const query = {
  goals: {
    $: {
      where: {
        todos: { title: 'Go running' }, // Wrong: use dot notation instead
      },
    },
  },
};
```

✅ **Correction**: Use dot notation to filter on associated values

```
// ✅ Good: Find goals that have todos with a specific title
const query = {
  goals: {
    $: {
      where: {
        'todos.title': 'Go running',
      },
    },
    todos: {},
  },
};
```

Use `or` inside of `where` to filter entities based on any criteria.

❌ **Common mistake**: Incorrect syntax for `or` and `and`

```typescript
// ❌ Bad: This will return an error!
const query = {
  todos: {
    $: {
      where: {
        or: { priority: 'high', dueDate: { $lt: tomorrow } }, // Wrong: 'or' takes an array
      },
    },
  },
};
```

✅ **Correction**: Use an array for `or` and `and` operators

```typescript
// ✅ Good: Find todos that are either high priority OR due soon
const query = {
  todos: {
    $: {
      where: {
        or: [{ priority: 'high' }, { dueDate: { $lt: tomorrow } }],
      },
    },
  },
};
```

Using `$gt`, `$lt`, `$gte`, or `$lte` is supported on indexed attributes with checked types:

❌ **Common mistake**: Using comparison on non-indexed attributes

```typescript
// ❌ Bad: Attribute must be indexed for comparison operators
const query = {
  todos: {
    $: {
      where: {
        nonIndexedAttr: { $gt: 5 }, // Will fail if attr isn't indexed
      },
    },
  },
};
```

✅ **Correction**: Use comparison operators on indexed attributes

```typescript
// ✅ Good: Find todos that take more than 2 hours
const query = {
  todos: {
    $: {
      where: {
        timeEstimate: { $gt: 2 },
      },
    },
  },
};

// Available operators: $gt, $lt, $gte, $lte
```

Use `limit` and/or `offset` for simple pagination:

❌ **Common mistake**: Using limit in nested namespaces

```typescript
// ❌ Bad: Limit only works on top-level namespaces. This will return an error!
const query = {
  goals: {
    todos: {
      $: { limit: 5 }, // This won't work
    },
  },
};
```

✅ **Correction**: Use limit on top-level namespaces

```typescript
// ✅ Good: Get first 10 todos
const query = {
  todos: {
    $: {
      limit: 10,
    },
  },
};

// ✅ Good: Get next 10 todos
const query = {
  todos: {
    $: {
      limit: 10,
      offset: 10,
    },
  },
};
```

Use the `order` operator to sort results.

❌ **Common mistake**: Using `orderBy` instead of `order`

```typescript
// ❌ Bad: `orderBy` is not a valid operator. This will return an error!
const query = {
  todos: {
    $: {
      orderBy: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

✅ **Correction**: Use `order` to sort results

```typescript
// ✅ Good: Sort by creation time in descending order
const query = {
  todos: {
    $: {
      order: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

❌ **Common mistake**: Ordering non-indexed fields

```typescript
// ❌ Bad: Field must be indexed for ordering
const query = {
  todos: {
    $: {
      order: {
        nonIndexedField: 'desc', // Will fail if field isn't indexed
      },
    },
  },
};
```

## Common mistakes with Instant on the backend

Use `db.query` in the Admin SDK instead of `db.useQuery`. It is an async API without loading states. We wrap queries in try-catch blocks to handle errors. Unlike the client SDK, queries in the Admin SDK bypass permission checks.

❌ **Common mistake**: Using `db.useQuery` in the admin SDK

```javascript
// ❌ Bad: Don't use useQuery on the server
const { data, isLoading, error } = db.useQuery({ todos: {} }); // Wrong approach!
```

✅ **Correction**: Use `db.query` in the admin SDK

```javascript
// ✅ Good: Server-side querying
const fetchTodos = async () => {
  try {
    const data = await db.query({ todos: {} });
    const { todos } = data;
    console.log(`Found ${todos.length} todos`);
    return todos;
  } catch (error) {
    console.error('Error fetching todos:', error);
    throw error;
  }
};
```

## Common mistakes with auth

InstantDB does not provide built-in username/password authentication.

❌ **Common mistake**: Using password-based authentication in client-side code

✅ **Correction**: Use Instant's magic code or OAuth flows in client-side code instead

If you need traditional password-based authentication, you must implement it as a custom auth flow using the Admin SDK.

## Common mistakes with storage

Files in Instant are first-class entities (`$files`), not URLs. You link them to your data via the schema and query through the relationship to get URLs.

❌ **Common mistake**: Forgetting to declare `$files` in schema entities

If you use Storage, you must include `$files` in your schema entities. Without it, you will get a runtime error.

```typescript
// ❌ Bad: Links reference $files but it's not declared in entities
const _schema = i.schema({
  entities: {
    posts: i.entity({
      caption: i.string(),
    }),
  },
  links: {
    postImage: {
      forward: { on: 'posts', has: 'one', label: 'image' },
      reverse: { on: '$files', has: 'many', label: 'posts' },
    },
  },
});
```

✅ **Correction**: Declare `$files` in your schema entities

```typescript
// ✅ Good: $files is declared in entities
const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    posts: i.entity({
      caption: i.string(),
    }),
  },
  links: {
    postImage: {
      forward: { on: 'posts', has: 'one', label: 'image' },
      reverse: { on: '$files', has: 'many', label: 'posts' },
    },
  },
});
```

❌ **Common mistake**: Storing image URLs as string attributes

Do not store URLs as string attributes on your entities. This includes using placeholder image URLs (e.g. picsum.photos) in seed scripts. In a real app, users upload files via Storage, so string URLs won't work.

```typescript
// ❌ Bad: Storing a URL string on the entity
const posts = [
  { id: id(), caption: "Golden hour", image: "https://picsum.photos/seed/pier/600/600" },
];
db.transact(posts.map(p => db.tx.posts[p.id].update({ caption: p.caption, image: p.image })));

// ❌ Also bad: querying the URL from a string attribute
<img src={post.image} />
```

✅ **Correction**: Link `$files` to your entity and query through the relationship

```typescript
// ✅ Good: Upload creates a $files entity, then link it
const postId = id();
const { data } = await db.storage.uploadFile(`posts/${postId}/${file.name}`, file);
db.transact(
  db.tx.posts[postId]
    .update({ caption })
    .link({ image: data.id })
);

// Query through the relationship to get the URL
const { data } = db.useQuery({ posts: { image: {} } });
<img src={post.image.url} />
```

❌ **Common mistake**: Creating `$files` via transactions

`$files` entities can only be created via `db.storage.uploadFile`. You cannot create them with `db.transact`, and you cannot set `url` via transactions.

```typescript
// ❌ Bad: $files cannot be created or updated this way
db.transact(
  db.tx.$files[id()].update({
    path: 'photos/test.jpg',
    url: 'https://picsum.photos/200',
  }),
);
```

✅ **Correction**: Use `db.storage.uploadFile` to create files

```typescript
// ✅ Good: Upload creates the $files entity
const { data } = await db.storage.uploadFile('photos/test.jpg', file);
// Then link it
db.transact(db.tx.posts[postId].link({ image: data.id }));
```


# Instant - The Modern Firebase.

How to use Instant with React

Instant is the easy-to-use backend for your frontend. With Instant you can build delightful apps in less than 10 minutes. Follow the quick start below to **build a live app!**

## Automatic Setup With Create Instant App

The fastest way to get started with Instant is to use `npx @interface-db/create-app` to scaffold a new project with Instant already set up.

To get started with Next.js run:

```bash 
npx @interface-db/create-app --next
```

To get started with Vite run:

```bash 
npx @interface-db/create-app --vite-react
```

## Manual Setup

To create a new Next project, fire up your terminal and run the following:

```shell 
npx create-next-app instant-demo --tailwind --yes
cd instant-demo
npm run dev
```

Add the InstantDB React Library:

```shell
npm i @interface-db/react
```

Set up and connect your Instant app.
This will log you in if you are not logged in already, then create schema and permissions files, and update your `.env` file.

```shell
npx @interface-db/cli init
```

Create a database client in `src/lib/db.ts`:



```ts
import { init } from '@interface-db/react';
import schema from '../instant.schema';

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to run queries and transactions against your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx @interface-db/cli push
```

Replace the content of `src/app/page.tsx` with the following:



```typescript 
"use client";

import schema from "@/instant.schema";
import { db } from "@/lib/db";
import { id, i, init, InstaQLEntity } from "@interface-db/react";

type Todo = InstaQLEntity<typeof schema, "todos", {}, undefined, true>;

function App() {
  // Read Data
  const { isLoading, error, data } = db.useQuery({ todos: {} });
  if (isLoading) {
    return;
  }
  if (error) {
    return <div className="text-red-500 p-4">Error: {error.message}</div>;
  }
  const { todos } = data;
  return (
    <div className="font-mono min-h-screen flex justify-center items-center flex-col space-y-4">
      <h2 className="tracking-wide text-5xl text-gray-300">todos</h2>
      <div className="border border-gray-300 max-w-xs w-full">
        <TodoForm todos={todos} />
        <TodoList todos={todos} />
        <ActionBar todos={todos} />
      </div>
      <div className="text-xs text-center">
        Open another tab to see todos update in realtime!
      </div>
    </div>
  );
}

// Write Data
// ---------
function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({
      text,
      done: false,
      createdAt: Date.now(),
    }),
  );
}

function deleteTodo(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteCompleted(todos: Todo[]) {
  const completed = todos.filter((todo) => todo.done);
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function toggleAll(todos: Todo[]) {
  const newVal = !todos.every((todo) => todo.done);
  db.transact(
    todos.map((todo) => db.tx.todos[todo.id].update({ done: newVal })),
  );
}

// Components
// ----------
function ChevronDownIcon() {
  return (
    <svg viewBox="0 0 20 20">
      <path
        d="M5 8 L10 13 L15 8"
        stroke="currentColor"
        fill="none"
        strokeWidth="2"
      />
    </svg>
  );
}

function TodoForm({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex items-center h-10 border-b border-gray-300">
      <button
        className="h-full px-2 border-r border-gray-300 flex items-center justify-center"
        onClick={() => toggleAll(todos)}
      >
        <div className="w-5 h-5">
          <ChevronDownIcon />
        </div>
      </button>
      <form
        className="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          const input = e.currentTarget.input as HTMLInputElement;
          addTodo(input.value);
          input.value = "";
        }}
      >
        <input
          className="w-full h-full px-2 outline-hidden bg-transparent"
          autoFocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}

function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <div className="divide-y divide-gray-300">
      {todos.map((todo) => (
        <div key={todo.id} className="flex items-center h-10">
          <div className="h-full px-2 flex items-center justify-center">
            <div className="w-5 h-5 flex items-center justify-center">
              <input
                type="checkbox"
                className="cursor-pointer"
                checked={todo.done}
                onChange={() => toggleDone(todo)}
              />
            </div>
          </div>
          <div className="flex-1 px-2 overflow-hidden flex items-center">
            {todo.done ? (
              <span className="line-through">{todo.text}</span>
            ) : (
              <span>{todo.text}</span>
            )}
          </div>
          <button
            className="h-full px-2 flex items-center justify-center text-gray-300 hover:text-gray-500"
            onClick={() => deleteTodo(todo)}
          >
            X
          </button>
        </div>
      ))}
    </div>
  );
}

function ActionBar({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex justify-between items-center h-10 px-2 text-xs border-t border-gray-300">
      <div>Remaining todos: {todos.filter((todo) => !todo.done).length}</div>
      <button
        className=" text-gray-300 hover:text-gray-500"
        onClick={() => deleteCompleted(todos)}
      >
        Delete Completed
      </button>
    </div>
  );
}

export default App;
```

Go to `localhost:3000`, and huzzah 🎉 You've got a fully functional todo list running!

## Next Steps

Want to dive deeper on how this todo app works? Check out our step-by-step [Todo List Tutorial](/examples/todos). In this tutorial we walk through how to build the above todo list app from scratch, and explain how the queries and transactions work in more detail.

You can also check out the [Working with data](/docs/init) section to learn more about Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/workflow) docs for using Instant in your projects.


# Getting started with React Native

How to use Instant with React Native

You can use Instant in React Native projects too! Below is an example using Expo.

Open up your terminal and do the following:

```shell 
# Create an app with expo
npx create-expo-app instant-rn-demo
cd instant-rn-demo

# Install instant
npm i @interface-db/react-native

# Install peer dependencies
npm i @react-native-async-storage/async-storage @react-native-community/netinfo react-native-get-random-values
```

Now open up `app/(tabs)/index.tsx` in your favorite editor and replace the entirety of the file with the following code.

```tsx 
import { init, i, InstaQLEntity } from '@interface-db/react-native';
import { View, Text, Button, StyleSheet } from 'react-native';

// Instant app
const APP_ID = '__APP_ID__';

// Optional: You can declare a schema!
const schema = i.schema({
  entities: {
    colors: i.entity({
      value: i.string(),
    }),
  },
});

type Color = InstaQLEntity<typeof schema, 'colors'>;

const db = init({ appId: APP_ID, schema });

const selectId = '4d39508b-9ee2-48a3-b70d-8192d9c5a059';

function App() {
  const { isLoading, error, data } = db.useQuery({
    colors: {
      $: { where: { id: selectId } },
    },
  });
  if (isLoading) {
    return (
      <View>
        <Text>Loading...</Text>
      </View>
    );
  }
  if (error) {
    return (
      <View>
        <Text>Error: {error.message}</Text>
      </View>
    );
  }

  return <Main color={data.colors[0]} />;
}

function Main(props: { color?: Color }) {
  const { value } = props.color || { value: 'lightgray' };

  return (
    <View style={[styles.container, { backgroundColor: value }]}>
      <View style={[styles.contentSection]}>
        <Text style={styles.header}>Hi! pick your favorite color</Text>
        <View style={styles.spaceX4}>
          {['green', 'blue', 'purple'].map((c) => {
            return (
              <Button
                title={c}
                onPress={() => {
                  db.transact(db.tx.colors[selectId].update({ value: c }));
                }}
                key={c}
              />
            );
          })}
        </View>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  spaceY4: {
    marginVertical: 16,
  },
  spaceX4: {
    flexDirection: 'row',
    justifyContent: 'space-between',
    marginHorizontal: 16,
  },
  contentSection: {
    backgroundColor: 'white',
    opacity: 0.8,
    padding: 12,
    borderRadius: 8,
  },
  header: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 16,
  },
});

export default App;
```

If you haven't already, install the Expo Go app on iOS or Android. Once you have that installed, you can run the app from your terminal.

```
npm run start
```

Scan the QR code with your phone and follow the instructions on the screen :)

Huzzah 🎉 You've got your first React Native Instant app running! Check out the [Working with data](/docs/init) section to learn more about how to use Instant!

## Using MMKV for faster storage (optional)

By default, Instant uses [AsyncStorage](https://react-native-async-storage.github.io/async-storage/) to persist data on the device. If you want faster read/write performance, you can use [MMKV](https://github.com/mrousavy/react-native-mmkv) instead.

### Install the MMKV package

```shell 
npm i @interface-db/react-native-mmkv

# Install MMKV peer dependencies
npx expo install react-native-mmkv react-native-nitro-modules
```

Note: MMKV requires native code, so you'll need to run a prebuild:

```shell 
npx expo prebuild
```

### Configure Instant to use MMKV

Import `Store` from `@interface-db/react-native-mmkv` and pass it to `init`:

```tsx 
import { init } from '@interface-db/react-native';
import Store from '@interface-db/react-native-mmkv';

const db = init({
  appId: APP_ID,
  Store: Store,
});
```

Then run your app on a device or simulator:

```shell 
npx expo run:ios # or npx expo run:android
```

That's it! Instant will now use MMKV for local persistence instead of AsyncStorage.

When you use a custom store, `@react-native-async-storage/async-storage` becomes optional, so you can remove it from your dependencies.

## Using expo-sqlite for storage (optional)

If your app already uses [expo-sqlite](https://docs.expo.dev/versions/latest/sdk/sqlite/), you can use it for Instant's local persistence too.

### Install the expo-sqlite package

```shell 
npm i @interface-db/expo-sqlite

# Install the expo-sqlite peer dependency
npx expo install expo-sqlite
```

Note: expo-sqlite is included in Expo Go, so no prebuild is needed to try it out. For development builds, run a prebuild as usual:

```shell 
npx expo prebuild
```

### Configure Instant to use expo-sqlite

Import `Store` from `@interface-db/expo-sqlite` and pass it to `init`:

```tsx 
import { init } from '@interface-db/react-native';
import Store from '@interface-db/expo-sqlite';

const db = init({
  appId: APP_ID,
  Store: Store,
});
```

Then run your app on a device or simulator:

```shell 
npx expo run:ios # or npx expo run:android
```

That's it! Instant will now use expo-sqlite for local persistence instead of AsyncStorage.

When you use a custom store, `@react-native-async-storage/async-storage` becomes optional, so you can remove it from your dependencies.

## Implementing your own store

You can also implement your own local cache interface by extending `StoreInterface` from `@interface-db/react-native`. Here's an example in-memory store implementation:

```tsx 
import {
  StoreInterface,
  StoreInterfaceStoreName,
} from '@interface-db/react-native';

class InMemoryStore extends StoreInterface {
  _map: Map<string, any>;

  constructor(appId: string, storeName: StoreInterfaceStoreName) {
    super(appId, storeName);
    this._map = new Map();
  }

  async getItem(key: string): Promise<any> {
    return this._map.get(key) ?? null;
  }

  async multiSet(keyValuePairs: Array<[string, any]>): Promise<void> {
    for (const [key, value] of keyValuePairs) {
      this._map.set(key, value);
    }
  }

  async removeItem(key: string): Promise<void> {
    this._map.delete(key);
  }

  async getAllKeys(): Promise<string[]> {
    return Array.from(this._map.keys());
  }
}
```

Then pass your custom store class to `init`:

```tsx 
import { init } from '@interface-db/react-native';

const db = init({
  appId: APP_ID,
  Store: InMemoryStore,
});
```

## Next Steps

Want a more in-depth tutorial on building an Expo app with Instant? Check out [Beto's](https://x.com/betomoedano) video on building a chat app below!

This video goes through core concepts of using Instant like setting up schema, writing queries, and using transactions!



For more advanced features, check out [Simon Grimm](https://x.com/schlimmson) building a mobile app builder with Instant!

In this video, Simon builds on top of the concepts from Beto's video and shows off how to use Storage for uploading assets and the Platform API for programmatically spinning up databases.



If you prefer reading docs, you can also check out the [Working with data](/docs/init) section to learn more about Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/workflow) docs for using Instant in your projects.


# Getting started with Vanilla JS

How to use Instant with Vanilla JS

You can use Instant with plain ol' JavaScript/TypeScript too. You may find this helpful to integrate Instant with a framework that doesn't have an official SDK yet.

To use Instant in a brand new project, fire up your terminal and set up a new project with Vite.

```shell 
npx create-vite@latest -t vanilla-ts instant-vanilla
cd instant-vanilla
npm i @interface-db/core
npm run dev
```

Now open up `src/main.ts` in your favorite editor and replace the entirety of the file with the following code.

```javascript 
import { init, i, id, InstaQLEntity } from "@interface-db/core";

// Instant app
const APP_ID = "__APP_ID__";

// Optional: Declare your schema!
const schema = i.schema({
  entities: {
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
});

type Todo = InstaQLEntity<typeof schema, "todos">;

// Initialize the database
// ---------
const db = init({ appId: APP_ID, schema });

// Subscribe to data
// ---------
db.subscribeQuery({ todos: {} }, (resp) => {
  if (resp.error) {
    renderError(resp.error.message); // Pro-tip: Check you have the right appId!
    return;
  }
  if (resp.data) {
    render(resp.data);
  }
});

// Write Data
// ---------
function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({
      text,
      done: false,
      createdAt: Date.now(),
    })
  );
  focusInput();
}

function deleteTodoItem(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteCompleted(todos: Todo[]) {
  const completed = todos.filter((todo) => todo.done);
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function toggleAllTodos(todos: Todo[]) {
  const newVal = !todos.every((todo) => todo.done);
  db.transact(
    todos.map((todo) => db.tx.todos[todo.id].update({ done: newVal }))
  );
}

// Styles
// ---------
const styles: Record<string, string> = {
  container: `
    box-sizing: border-box;
    background-color: #fafafa;
    font-family: code, monospace;
    height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
    flex-direction: column;
  `,
  header: `
    letter-spacing: 2px;
    font-size: 50px;
    color: lightgray;
    margin-bottom: 10px;
  `,
  form: `
    box-sizing: inherit;
    display: flex;
    border: 1px solid lightgray;
    border-bottom-width: 0px;
    width: 350px;
  `,
  toggleAll: `
    font-size: 30px;
    cursor: pointer;
    margin-left: 11px;
    margin-top: -6px;
    width: 15px;
    margin-right: 12px;
  `,
  input: `
    background-color: transparent;
    font-family: code, monospace;
    width: 287px;
    padding: 10px;
    font-style: italic;
  `,
  todoList: `
    box-sizing: inherit;
    width: 350px;
  `,
  checkbox: `
    font-size: 30px;
    margin-left: 5px;
    margin-right: 20px;
    cursor: pointer;
  `,
  todo: `
    display: flex;
    align-items: center;
    padding: 10px;
    border: 1px solid lightgray;
    border-bottom-width: 0px;
  `,
  todoText: `
    grow: 1;
    overflow: hidden;
  `,
  delete: `
    width: 25px;
    cursor: pointer;
    color: lightgray;
  `,
  actionBar: `
    display: flex;
    justify-content: space-between;
    width: 328px;
    padding: 10px;
    border: 1px solid lightgray;
    font-size: 10px;
  `,
  footer: `
    margin-top: 20px;
    font-size: 10px;
  `,
};

// Render
// ---------
const app = document.getElementById("app")!;
app.style.cssText = styles.container;

function render(data: { todos: Todo[] }) {
  app.innerHTML = "";

  const { todos } = data;

  const containerHTML = `
    <div style="${styles.container}">
      <div style="${styles.header}">todos</div>
      ${TodoForm()}
      ${TodoList(todos)}
      ${ActionBar(todos)}
      <div style="${
        styles.footer
      }">Open another tab to see todos update in realtime!</div>
    </div>
  `;

  app.innerHTML = containerHTML;

  // Attach event listeners
  document
    .querySelector(".toggle-all")
    ?.addEventListener("click", () => toggleAllTodos(todos));
  document.querySelector("form")?.addEventListener("submit", submitForm);
  todos.forEach((todo) => {
    document
      .getElementById(`toggle-${todo.id}`)
      ?.addEventListener("change", () => toggleDone(todo));
    document
      .getElementById(`delete-${todo.id}`)
      ?.addEventListener("click", () => deleteTodoItem(todo));
  });
  document
    .querySelector(".delete-completed")
    ?.addEventListener("click", () => deleteCompleted(todos));
}

function renderError(errorMessage: string) {
  app.innerHTML = `
    <div>${errorMessage}</div>
  `;
}

function TodoForm() {
  return `
    <div style="${styles.form}">
      <div class="toggle-all" style="${styles.toggleAll}">⌄</div>
      <form>
        <input style="${styles.input}" placeholder="What needs to be done?" type="text" autofocus>
      </form>
    </div>
  `;
}

function TodoList(todos: Todo[]) {
  return `
    <div style="${styles.todoList}">
      ${todos
        .map(
          (todo) => `
        <div style="${styles.todo}">
          <input id="toggle-${todo.id}" type="checkbox" style="${
            styles.checkbox
          }" ${todo.done ? "checked" : ""}>
          <div style="${styles.todoText}">
            ${
              todo.done
                ? `<span style="text-decoration: line-through;">${todo.text}</span>`
                : `<span>${todo.text}</span>`
            }
          </div>
          <span id="delete-${todo.id}" style="${styles.delete}">𝘟</span>
        </div>
      `
        )
        .join("")}
    </div>
  `;
}

function ActionBar(todos: Todo[]) {
  return `
    <div style="${styles.actionBar}">
      <div>Remaining todos: ${todos.filter((todo) => !todo.done).length}</div>
      <div class="delete-completed" style="cursor: pointer;">Delete Completed</div>
    </div>
  `;
}

function focusInput() {
  const input = document.querySelector<HTMLInputElement>('input[type="text"]');
  if (input) {
    input.focus();
  }
}

function submitForm(event: Event) {
  event.preventDefault();
  const input = (event.target as HTMLFormElement).querySelector("input");
  if (input && input.value.trim()) {
    addTodo(input.value);
    input.value = "";
  }
}
```

Go to `localhost:5173` and follow the final instruction to load the app!

Huzzah 🎉 You've got your first Instant web app running! Check out the [Working with data](/docs/init) section to learn more about how to use Instant :)


# Getting started with SolidJS

How to use Instant with SolidJS

## Automatic Setup With Create Instant App

The fastest way to get started with Instant and SolidJS is to use @interface-db/create-app to scaffold a new project with Instant already set up.

To get started, run:

```shell
npx @interface-db/create-app -b solidjs-vite
```

## Manual Setup

Create a blank Vite SolidJS App:

```shell
npx create-vite@latest -t solid-ts
```

Add the InstantDB SolidJS Library:

```shell
npm i @interface-db/solidjs
```

Use `@interface-db/cli` to set up a new Instant project. This will prompt you to log in if you haven't already. It will then create schema and permissions files and update your `.env` file.

```shell
npx @interface-db/cli init
```

Create a database client in `src/lib/db.ts`:



```ts
import { init } from '@interface-db/solidjs';
import schema from '../instant.schema';

export const db = init({
  appId: import.meta.env.VITE_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to run queries and transactions against your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@interface-db/solidjs';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx @interface-db/cli push
```

Replace the content of `src/App.tsx` with the following:



```typescript 
import { id, type InstaQLEntity } from "@interface-db/solidjs";
import { createSignal, For, Show, type Component } from "solid-js";
import { db } from "./lib/db";
import type { AppSchema } from "./instant.schema";

type Todo = InstaQLEntity<AppSchema, "todos">;

const App: Component = () => {
  const state = db.useQuery({ todos: {} });
  const todos = () => state().data?.todos ?? [];

  return (
    <Show when={!state().isLoading}>
      <Show
        when={!state().error}
        fallback={
          <div class="text-red-500 p-4">Error: {state().error?.message}</div>
        }
      >
        <div class="p-8 grid-cols-2 items-start gap-2 grid">
          <Welcome />
          <div class="bg-white rounded-lg p-6 border border-neutral-200 shadow flex flex-col">
            <h2 class="tracking-wide text-[#F54A00] text-2xl">Todos</h2>
            <div class="text-xs pb-4">
              Open another tab to see todos update in realtime!
            </div>
            <div class="border rounded border-neutral-300">
              <TodoForm />
              <TodoList todos={todos()} />
              <ActionBar todos={todos()} />
            </div>
          </div>
        </div>
      </Show>
    </Show>
  );
};

function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({
      text,
      done: false,
      createdAt: Date.now(),
    }),
  );
}

function deleteTodo(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteCompleted(todos: Todo[]) {
  const completed = todos.filter((todo) => todo.done);
  if (completed.length === 0) return;
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function TodoForm() {
  const [text, setText] = createSignal("");
  return (
    <div class="flex items-center h-10 border-neutral-300">
      <form
        class="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          if (!text()) return;
          addTodo(text());
          setText("");
        }}
      >
        <input
          value={text()}
          onInput={(e) => setText(e.currentTarget.value)}
          class="w-full h-full placeholder-neutral-300 px-2 outline-none bg-transparent"
          autofocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}

function TodoList(props: { todos: Todo[] }) {
  return (
    <div class="divide-y divide-neutral-300">
      <For each={props.todos}>
        {(todo) => (
          <div class="flex items-center h-10">
            <div class="h-full px-2 flex items-center justify-center">
              <div class="w-5 h-5 flex items-center justify-center">
                <input
                  type="checkbox"
                  class="cursor-pointer"
                  checked={todo.done}
                  onChange={() => toggleDone(todo)}
                />
              </div>
            </div>
            <div class="flex-1 px-2 overflow-hidden flex items-center">
              <span classList={{ "line-through": todo.done }}>{todo.text}</span>
            </div>
            <button
              class="h-full px-2 flex items-center justify-center text-neutral-300 hover:text-neutral-500"
              onClick={() => deleteTodo(todo)}
            >
              X
            </button>
          </div>
        )}
      </For>
    </div>
  );
}

function ActionBar(props: { todos: Todo[] }) {
  return (
    <div class="flex justify-between items-center h-10 px-2 text-xs border-t border-neutral-300">
      <div>
        Remaining todos: {props.todos.filter((todo) => !todo.done).length}
      </div>
      <button
        class=" text-neutral-300 hover:text-neutral-500"
        onClick={() => deleteCompleted(props.todos)}
      >
        Delete Completed
      </button>
    </div>
  );
}

function Welcome() {
  return (
    <div class="bg-white p-6 rounded-lg border border-neutral-200 shadow flex justify-center flex-col gap-2">
      <h2 class="tracking-wide text-[#F54A00] text-2xl text-center">
        Solid + Vite + InstantDB
      </h2>
      <div class="grid grid-cols-1 md:grid-cols-2 grow gap-2">
        <a
          href="https://docs.solidjs.com/"
          target="_blank"
          rel="noopener noreferrer"
          class="border hover:bg-neutral-100 py-8 shadow flex flex-col gap-2 items-center justify-center font-semibold border-neutral-200 rounded"
        >
          <img
            src="https://www.solidjs.com/img/logo/without-wordmark/logo.svg"
            width={34}
          />
          Solid Docs
        </a>
        <a
          target="_blank"
          href="https://www.instantdb.com/docs"
          rel="noopener noreferrer"
          class="border shadow flex flex-col py-8 gap-2 hover:bg-neutral-100 items-center justify-center font-semibold border-neutral-200 rounded"
        >
          <img
            src="https://www.instantdb.com/img/icon/logo-512.svg"
            width={34}
          />
          Instant Docs
        </a>
      </div>
    </div>
  );
}

export default App;
```

Go to `localhost:5173`, and huzzah 🎉 You've got a fully functional todo list running!

## Reactivity

In Solid, query results are returned as [Signals](https://docs.solidjs.com/concepts/signals). This means that they cannot be destructured without preserving reactivity.

Incorrect Usage:

```typescript
// ❌ Data cannot be destructured from an Accessor
const { data } = db.useQuery({ todos: {} });

// ❌ state().data() must be called from a Tracking Scope
const state = db.useQuery({ todos: {} });
const todos = state().data().todos;
```

Correct Usage:

```typescript
// ✅ state().data() can be called in JSX
const TodoCount = () => {
  const state = db.useQuery({ todos: {} });

  return (
    <div>{state().data()?.todos.length} todos</div>
  )
}
```

Alternatively:

```typescript
// ✅ Create a new signal for todos
const TodoCount = () => {
  const state = db.useQuery({ todos: {} });
  const todos = () => state().data?.todos ?? [];

  return (
    <div>{todos().length} todos</div>
  )
}
```

Transactions in Solid work the same way they do in React via `db.transact`. To learn more, see our [writing data](/docs/instaml) docs.


# Getting started with Svelte

How to use Instant with SvelteKit and Svelte 5

## Automatic Setup With Create Instant App

The fastest way to get started with Instant and SvelteKit is to use @interface-db/create-app to scaffold a new project with Instant already set up.

To get started, run:

```shell
npx @interface-db/create-app --sv
```

## Manual Setup

Create a blank SvelteKit app:

```shell
npx sv create my-app
```

Add the InstantDB Svelte Library:

```shell
npm i @interface-db/svelte
```

Use `@interface-db/cli` to set up a new Instant project. This will prompt you to log in if you haven't already. It will then create schema and permissions files and update your `.env` file.

```shell
npx @interface-db/cli init
```

Create a database client in `src/lib/db.ts`:



```ts
import { init } from '@interface-db/svelte';
import schema from '../instant.schema';

export const db = init({
  appId: import.meta.env.VITE_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to run queries and transactions against your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@interface-db/svelte';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx @interface-db/cli push
```

Instant doesn't support SSR with SvelteKit yet (let us know if you want this!)
so you need to disable SSR for routes that use Instant.



```ts 
export const ssr = false;
```

Replace the content of `src/routes/+page.svelte` with the following:



```svelte 
<script lang="ts">
  import { id, type InstaQLEntity } from '@interface-db/svelte';
  import { db } from '$lib/db';
  import type { AppSchema } from '../instant.schema';

  type Todo = InstaQLEntity<AppSchema, 'todos'>;

  const query = db.useQuery({ todos: {} });

  let text = $state('');

  function addTodo(todoText: string) {
    db.transact(
      db.tx.todos[id()].update({
        text: todoText,
        done: false,
        createdAt: Date.now(),
      }),
    );
  }

  function deleteTodo(todo: Todo) {
    db.transact(db.tx.todos[todo.id].delete());
  }

  function toggleDone(todo: Todo) {
    db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
  }

  function deleteCompleted(todos: Todo[]) {
    const completed = todos.filter((todo) => todo.done);
    if (completed.length === 0) return;
    const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
    db.transact(txs);
  }
</script>

{#if query.isLoading}
<div>Loading...</div>
{:else if query.error}
<div>Error: {query.error.message}</div>
{:else} {@const todos = query.data?.todos ?? []}
<div>
  <h2>Todos</h2>
  <div>
    <form onsubmit={(e) => {
      e.preventDefault(); if (!text) return; addTodo(text); text = '';
    }}>
      <input
        bind:value={text}
        autofocus
        placeholder="What needs to be done?"
        type="text"
      />
    </form>
    {#each todos as todo (todo.id)}
    <div>
      <input type="checkbox" checked={todo.done} onchange={() =>
        toggleDone(todo)} />
      <span class:line-through={todo.done}>{todo.text}</span>
      <button onclick={() => deleteTodo(todo)}>X</button>
    </div>
    {/each}
    <div>
      Remaining todos: {todos.filter((t) => !t.done).length}
      <button onclick={() =>
        deleteCompleted(todos)}> Delete Completed
      </button>
    </div>
  </div>
</div>
{/if}
```

Go to `localhost:5173`, and huzzah 🎉 You've got a fully functional todo list running!

## Reactivity

In Svelte 5, Instant's hooks return `$state` proxies. You read properties directly off the returned object, and Svelte automatically tracks them for re-rendering.

```svelte
<script lang="ts">
  const query = db.useQuery({ todos: {} });
  // query.isLoading, query.data, query.error are all reactive
</script>

{#if !query.isLoading}
<p>{query.data?.todos.length} todos</p>
{/if}
```

For primitive values like connection status and local IDs, hooks return a `{ current: value }` wrapper (since primitives cannot be `$state` proxies):

```svelte
<script lang="ts">
  const status = db.useConnectionStatus();
  // status.current is reactive
</script>

<p>Connection: {status.current}</p>
```

### Reactive and conditional queries

You can pass a function to `useQuery` to make queries reactive or conditional. The function will be re-evaluated whenever its dependencies change. Return `null` to skip the query:

```svelte
<script lang="ts">
  import { db } from '$lib/db';

  const auth = db.useAuth();

  // Only query when we have a logged-in user
  const query = db.useQuery(() =>
    auth.user ? { todos: {} } : null
  );
</script>

{#if auth.isLoading}
  <p>Loading...</p>
{:else if !auth.user}
  <p>Please log in.</p>
{:else if query.isLoading}
  <p>Loading todos...</p>
{:else}
  {@const todos = query.data?.todos ?? []}
  <p>{todos.length} todos</p>
{/if}
```

This also works for reactive parameters. Any `$state` variable read inside the function will automatically trigger a new query when it changes:

```svelte
<script lang="ts">
  import { db } from '$lib/db';

  let filter = $state<'all' | 'active' | 'done'>('all');

  const query = db.useQuery(() => {
    if (filter === 'all') return { todos: {} };
    return { todos: { $: { where: { done: filter === 'done' } } } };
  });
</script>

<button onclick={() => filter = 'all'}>All</button>
<button onclick={() => filter = 'active'}>Active</button>
<button onclick={() => filter = 'done'}>Done</button>
```

### Writing data

Transactions in Svelte work the same way they do in React via `db.transact`:

```svelte
<script lang="ts">
  import { id } from '@interface-db/svelte';
  import { db } from '$lib/db';

  function addTodo(text: string) {
    db.transact(db.tx.todos[id()].update({ text, done: false, createdAt: Date.now() }));
  }

  function toggleDone(todo: { id: string; done: boolean }) {
    db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
  }

  function deleteTodo(todoId: string) {
    db.transact(db.tx.todos[todoId].delete());
  }
</script>
```

To learn more, see our [writing data](/docs/instaml) docs.

## Auth

The Svelte SDK supports all of Instant's [auth methods](/docs/auth): [magic codes](/docs/auth/magic-codes), [guest auth](/docs/auth/guest-auth), [Google OAuth](/docs/auth/google-oauth), and more.

### useAuth

Use `db.useAuth()` to get the current auth state. This gives you full control over loading, error, and user states:

```svelte
<script lang="ts">
  import { db } from '$lib/db';

  const auth = db.useAuth();
</script>

{#if auth.isLoading}
  <div>Loading...</div>
{:else if auth.error}
  <div>Error: {auth.error.message}</div>
{:else if auth.user}
  <div>
    <p>Hello, {auth.user.isGuest ? 'Guest' : auth.user.email}!</p>
    <button onclick={() => db.auth.signOut()}>Sign out</button>
  </div>
{:else}
  <div>
    <p>Please log in.</p>
    <button onclick={() => db.auth.signInAsGuest()}>
      Try as guest
    </button>
  </div>
{/if}
```

### SignedIn / SignedOut

For simpler cases where you just need to gate content on auth state, you can use the `SignedIn` and `SignedOut` guard components instead:

```svelte
<script lang="ts">
  import { SignedIn, SignedOut } from '@interface-db/svelte';
  import { db } from '$lib/db';
</script>

<SignedIn {db}>
  <p>You are logged in!</p>
  <button onclick={() => db.auth.signOut()}>Sign out</button>
</SignedIn>

<SignedOut {db}>
  <p>Please log in.</p>
</SignedOut>
```

`useAuth` is better when you need access to `isLoading`, `error`, or `user.isGuest`. The guard components are simpler when you just need to show or hide content based on login state.

## Components

### Cursors

A multiplayer cursor component that tracks mouse positions via presence. Wrap any area where you want to show live cursors from other users:

```svelte
<script lang="ts">
  import { Cursors } from '@interface-db/svelte';
  import { db } from '$lib/db';

  const room = db.room('main', 'my-room-id');
</script>

<Cursors {room} userCursorColor="tomato">
  <div>Move your mouse around!</div>
</Cursors>
```

The `Cursors` component supports custom cursor rendering via a `renderCursor` snippet, a configurable wrapper element (`as`), and `className`/`style` props for styling. See the [Presence, Cursors, and Activity](/docs/presence-and-topics) docs for more details.


# Getting started with Vue

How to use Instant with Vue 3 and Vite

## Automatic Setup With Create Instant App

The fastest way to get started with Instant and Vue is to use @interface-db/create-app to scaffold a new project with Instant already set up.

To get started, run:

```shell
npx @interface-db/create-app --vue
```

## Manual Setup

Create a blank Vue + Vite app:

```shell
npm create vue@latest my-app
```

Add the InstantDB Vue Library:

```shell
npm i @interface-db/vue
```

Use `@interface-db/cli` to set up a new Instant project. This will prompt you to log in if you haven't already. It will then create schema and permissions files and update your `.env` file.

```shell
npx @interface-db/cli init
```

Create a database client in `src/lib/db.ts`:



```ts
import { init } from '@interface-db/vue';
import schema from '../instant.schema';

export const db = init({
  appId: import.meta.env.VITE_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to run queries and transactions against your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@interface-db/vue';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx @interface-db/cli push
```

Replace the content of `src/App.vue` with the following:



```vue 
<script setup lang="ts">
import { ref } from 'vue';
import { id, type InstaQLEntity } from '@interface-db/vue';
import { db } from './lib/db';
import type { AppSchema } from './instant.schema';

type Todo = InstaQLEntity<AppSchema, 'todos'>;

const { isLoading, error, data } = db.useQuery({ todos: {} });

const text = ref('');

function addTodo() {
  const value = text.value.trim();
  if (!value) return;
  db.transact(
    db.tx.todos[id()].update({
      text: value,
      done: false,
      createdAt: Date.now(),
    }),
  );
  text.value = '';
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteTodo(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}
</script>

<template>
  <div v-if="isLoading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <div v-else>
    <h2>Todos</h2>
    <form @submit.prevent="addTodo">
      <input v-model="text" placeholder="What needs to be done?" type="text" />
    </form>
    <div v-for="todo in data?.todos ?? []" :key="todo.id">
      <input type="checkbox" :checked="todo.done" @change="toggleDone(todo)" />
      <span :class="{ 'line-through': todo.done }">{{ todo.text }}</span>
      <button @click="deleteTodo(todo)">X</button>
    </div>
    <div>
      Remaining todos: {{ (data?.todos ?? []).filter((t) => !t.done).length }}
    </div>
  </div>
</template>
```

Go to `localhost:5173`, and huzzah 🎉 You've got a fully functional todo list running!

## Reactivity

Instant's hooks return an **object of refs**. This lets you destructure the result without losing reactivity, and refs auto-unwrap when you reference them in your template.

```vue
<script setup lang="ts">
const { isLoading, data, error } = db.useQuery({ todos: {} });
// isLoading.value, data.value, error.value are reactive refs
</script>

<template>
  <p v-if="!isLoading">{{ data?.todos.length }} todos</p>
</template>
```

Inside the script you access values via `.value`; inside the template Vue unwraps the ref automatically, so you can write `data?.todos` directly.

For hooks that return a single value (`useConnectionStatus`, `useLocalId`, `useUser`), you get a single `Ref` or `ComputedRef`:

```vue
<script setup lang="ts">
const status = db.useConnectionStatus();
// status.value is reactive
</script>

<template>
  <p>Connection: {{ status }}</p>
</template>
```

### Reactive and conditional queries

The first argument of `useQuery` accepts a `MaybeRefOrGetter<Q | null>`. That means you can pass a plain query object, a `ref` containing a query, a `computed`, or a getter function. Return `null` from a getter to skip the query:

```vue
<script setup lang="ts">
import { db } from './lib/db';

const { user } = db.useAuth();

// Only query when we have a logged-in user
const { isLoading, data } = db.useQuery(() =>
  user.value ? { todos: {} } : null,
);
</script>

<template>
  <p v-if="!user">Please log in.</p>
  <p v-else-if="isLoading">Loading todos...</p>
  <p v-else>{{ data?.todos.length }} todos</p>
</template>
```

Any reactive value read inside the getter automatically re-triggers the query when it changes:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { db } from './lib/db';

const filter = ref<'all' | 'active' | 'done'>('all');

const { data } = db.useQuery(() => {
  if (filter.value === 'all') return { todos: {} };
  return { todos: { $: { where: { done: filter.value === 'done' } } } };
});
</script>

<template>
  <button @click="filter = 'all'">All</button>
  <button @click="filter = 'active'">Active</button>
  <button @click="filter = 'done'">Done</button>
  <p>{{ data?.todos.length }} todos</p>
</template>
```

### Writing data

Transactions in Vue work the same way they do in React via `db.transact`:

```vue
<script setup lang="ts">
import { id } from '@interface-db/vue';
import { db } from './lib/db';

function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({ text, done: false, createdAt: Date.now() }),
  );
}

function toggleDone(todo: { id: string; done: boolean }) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteTodo(todoId: string) {
  db.transact(db.tx.todos[todoId].delete());
}
</script>
```

To learn more, see our [writing data](/docs/instaml) docs.

## Auth

The Vue SDK supports all of Instant's [auth methods](/docs/auth): [magic codes](/docs/auth/magic-codes), [guest auth](/docs/auth/guest-auth), [Google OAuth](/docs/auth/google-oauth), and more.

### useAuth

Use `db.useAuth()` to get the current auth state. This gives you full control over loading, error, and user states:

```vue
<script setup lang="ts">
import { db } from './lib/db';

const { isLoading, error, user } = db.useAuth();
</script>

<template>
  <div v-if="isLoading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <div v-else-if="user">
    <p>Hello, {{ user.isGuest ? 'Guest' : user.email }}!</p>
    <button @click="db.auth.signOut()">Sign out</button>
  </div>
  <div v-else>
    <p>Please log in.</p>
    <button @click="db.auth.signInAsGuest()">Try as guest</button>
  </div>
</template>
```

### SignedIn / SignedOut

For simpler cases where you just need to gate content on auth state, use the `SignedIn` and `SignedOut` guard components instead:

```vue
<script setup lang="ts">
import { SignedIn, SignedOut } from '@interface-db/vue';
import { db } from './lib/db';
</script>

<template>
  <SignedIn :db="db">
    <p>You are logged in!</p>
    <button @click="db.auth.signOut()">Sign out</button>
  </SignedIn>

  <SignedOut :db="db">
    <p>Please log in.</p>
  </SignedOut>
</template>
```

`useAuth` is better when you need access to `isLoading`, `error`, or `user.isGuest`. The guard components are simpler when you just need to show or hide content based on login state.

## Components

### Cursors

A multiplayer cursor component that tracks mouse positions via presence. Wrap any area where you want to show live cursors from other users:

```vue
<script setup lang="ts">
import { Cursors } from '@interface-db/vue';
import { db } from './lib/db';

const room = db.room('main', 'my-room-id');
</script>

<template>
  <Cursors :room="room" userCursorColor="tomato">
    <div>Move your mouse around!</div>
  </Cursors>
</template>
```

The `Cursors` component supports custom cursor rendering via a scoped `cursor` slot and a configurable wrapper element (`as`), and it inherits `class`/`style` from the parent. See the [Presence, Cursors, and Activity](/docs/presence-and-topics) docs for more details.

## Nuxt

The Vue SDK works with [Nuxt](https://nuxt.com/). Because Instant is a client-only library (it relies on browser APIs like `WebSocket` and `IndexedDB`), you'll want to either wrap Instant-using components with `<ClientOnly>` or disable SSR for the relevant routes via `routeRules` in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  routeRules: {
    '/my-route/**': { ssr: false },
  },
});
```

Server-side rendering with Instant is not yet supported (let us know if you want this!).


# Getting started with TanStack Start

How to use Instant with TanStack Start

## Automatic Setup With Create Instant App

The fastest way to get started with Instant on TanStack Start is to use npx @interface-db/create-app to scaffold a new project with Instant already set up.

To get started, run:

```shell
npx @interface-db/create-app -b tanstack-start
```

## Manual Setup

The following guide demonstrates the basics for manually scaffolding a new TanStack project with Instant and managing data. In general, we recommend the automatic setup above, which includes all of this, a basic auth flow, and other useful full-stack utilities.

Create a blank TanStack Start app:

```shell
npx @tanstack/cli create my-app
```

Add the InstantDB React Library:

```shell
npm i @interface-db/react
```

Use `@interface-db/cli` to set up a new Instant project. This will prompt you to log in if you haven't already. It will then create schema and permissions files and update your `.env` file.

```shell
npx @interface-db/cli init
```

Create a database client in `src/lib/db.ts`:



```ts
import { init } from '@interface-db/react';
import schema from '../instant.schema';

export const db = init({
  appId: import.meta.env.VITE_INSTANT_APP_ID!,
  schema,
  useDateObjects: true,
});
```

You're now ready to run queries and transactions against your database!

### Creating a To-Do List App

Let's add a "todo" entity to our schema file at `src/instant.schema.ts`:



```ts 
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed().optional(),
      imageURL: i.string().optional(),
      type: i.string().optional(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
    }),
  },
  links: {
    $usersLinkedPrimaryUser: {
      forward: {
        on: '$users',
        has: 'one',
        label: 'linkedPrimaryUser',
        onDelete: 'cascade',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'linkedGuestUsers',
      },
    },
  },
  rooms: {},
});

//...
```

Push the schema:

```shell 
npx @interface-db/cli push
```

Replace the content of `src/routes/index.tsx` with the following:



```typescript 
import { createFileRoute } from "@tanstack/react-router";
import { AppSchema } from "../instant.schema";
import { id, InstaQLEntity } from "@interface-db/react";
import { db } from "@/lib/db";

export const Route = createFileRoute("/")({
  component: App,
});

type Todo = InstaQLEntity<AppSchema, "todos">;

function App() {
  // Read Data
  const { isLoading, error, data } = db.useQuery({ todos: {} });

  if (isLoading) {
    return null;
  }
  if (error) {
    return <div className="text-red-500 p-4">Error: {error.message}</div>;
  }

  const { todos } = data;
  return (
    <div className="p-8 max-w-2xl">
      <div className="bg-white rounded-lg p-6 border border-neutral-200 shadow flex flex-col">
        <h2 className="tracking-wide text-[#F54A00] pb-2 text-2xl">Todos</h2>
        <div className="text-xs pb-4">
          Open another tab to see todos update in realtime!
        </div>
        <div className="border rounded border-neutral-300">
          <TodoForm />
          <TodoList todos={todos} />
          <ActionBar todos={todos} />
        </div>
      </div>
    </div>
  );
}

// Write Data
// ---------
function addTodo(text: string) {
  db.transact(
    db.tx.todos[id()].update({
      text,
      done: false,
      createdAt: Date.now(),
    }),
  );
}

function deleteTodo(todo: Todo) {
  db.transact(db.tx.todos[todo.id].delete());
}

function toggleDone(todo: Todo) {
  db.transact(db.tx.todos[todo.id].update({ done: !todo.done }));
}

function deleteCompleted(todos: Todo[]) {
  const completed = todos.filter((todo) => todo.done);
  if (completed.length === 0) return;
  const txs = completed.map((todo) => db.tx.todos[todo.id].delete());
  db.transact(txs);
}

function TodoForm() {
  return (
    <div className="flex items-center h-10 border-neutral-300">
      <form
        className="flex-1 h-full"
        onSubmit={(e) => {
          e.preventDefault();
          const input = e.currentTarget.input as HTMLInputElement;
          addTodo(input.value);
          input.value = "";
        }}
      >
        <input
          className="w-full h-full px-2 outline-none bg-transparent"
          autoFocus
          placeholder="What needs to be done?"
          type="text"
          name="input"
        />
      </form>
    </div>
  );
}

function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <div className="divide-y divide-neutral-300">
      {todos.map((todo) => (
        <div key={todo.id} className="flex items-center h-10">
          <div className="h-full px-2 flex items-center justify-center">
            <div className="w-5 h-5 flex items-center justify-center">
              <input
                type="checkbox"
                className="cursor-pointer"
                checked={todo.done}
                onChange={() => toggleDone(todo)}
              />
            </div>
          </div>
          <div className="flex-1 px-2 overflow-hidden flex items-center">
            {todo.done ? (
              <span className="line-through">{todo.text}</span>
            ) : (
              <span>{todo.text}</span>
            )}
          </div>
          <button
            className="h-full px-2 flex items-center justify-center text-neutral-300 hover:text-neutral-500"
            onClick={() => deleteTodo(todo)}
          >
            X
          </button>
        </div>
      ))}
    </div>
  );
}

function ActionBar({ todos }: { todos: Todo[] }) {
  return (
    <div className="flex justify-between items-center h-10 px-2 text-xs border-t border-neutral-300">
      <div>Remaining todos: {todos.filter((todo) => !todo.done).length}</div>
      <button
        className=" text-neutral-300 hover:text-neutral-500"
        onClick={() => deleteCompleted(todos)}
      >
        Delete Completed
      </button>
    </div>
  );
}
```

Go to `localhost:3000`, and huzzah 🎉 You've got a fully functional todo list running!

## Next Steps

Want to dive deeper on how this todo app works? Check out our step-by-step [Todo List Tutorial](/examples/todos). In this tutorial we walk through how to build a todo list app from scratch, and explain how the queries and transactions work in more detail.

For the advanced use case of integrating with TanStack Query and enabling SSR, refer to our [tanstack-start-with-tanstack-query](https://github.com/instantdb/instant/tree/main/examples/tanstack-start-with-tanstack-query) example. It can be scaffolded using `npx @interface-db/create-app -b tanstack-start-with-tanstack-query`.

You can also check out the [Working with data](/docs/init) section to learn more about Instant concepts.

As you get more familiar with Instant, check out our [Recommended Workflow](/docs/workflow) docs for using Instant in your projects.


# Getting started with Python

How to use Instant from Python with the admin SDK.

Instant offers a Python Admin SDK with an API that mirrors our JavaScript
Admin SDK. If you read the JS docs, you can mentally substitute Python syntax
and write working code.

## Install

```shell 
uv add instantdb
# or
pip install instantdb
```

Python 3.10+ is required.

To scaffold a new project:

```shell 
npx @interface-db/create-app --python my-app
cd my-app
uv sync
```

This creates a starter script with a `.env`, `main.py`,
`instant.schema.ts`, and `instant.perms.ts`. Schema and permission files are included so you can manage
your app with the Instant CLI.

## Usage

Our Python SDK mirrors the JS admin SDK's surface and behavior, with a few
Pythonic adjustments. A basic example looks like this:

```python 
from instantdb import Instant, id

db = Instant(
    # You can pass these explicitly; by default they fall back to
    # INSTANT_APP_ID and INSTANT_APP_ADMIN_TOKEN environment variables
    app_id="__APP_ID__",
    admin_token="__ADMIN_TOKEN__",
)

# Write data
goal_id = id()
db.transact(db.tx.goals[goal_id].update({"title": "Get fit"}))

# Read data
result = db.query({"goals": {}})
for goal in result["goals"]:
    print(goal["title"])
```



Exposing your `app_id` is fine, but the `admin_token` bypasses permission
checks. Keep it server-side and regenerate it from the dashboard if it
leaks.



## Async usage

Use `AsyncInstant` and `await` each call:

```python 
import asyncio
from instantdb import AsyncInstant, id

db = AsyncInstant()

async def main():
    goal_id = id()
    await db.transact(db.tx.goals[goal_id].update({"title": "Get fit"}))

    result = await db.query({"goals": {}})
    for goal in result["goals"]:
        print(goal["title"])

asyncio.run(main())
```

`subscribe_query` and `streams` are only available on `AsyncInstant`.
Everything else works on both the sync and async client.

## Schema and permissions

The Python starter includes `instant.schema.ts` and `instant.perms.ts`
so you can manage your app from your Python project. Push changes with
the Instant CLI as you would normally:

```shell 
npx @interface-db/cli push
```

## FastAPI with Pydantic

At the moment the SDK doesn't generate Python types from your schema file.
Query results are returned as dictionaries. If you want typed objects, define them in your
application and validate the returned data there.

Here's an example of how you can use Pydantic models in a FastAPI app:

```python 
from fastapi import FastAPI
from pydantic import BaseModel
from instantdb import AsyncInstant, id

db = AsyncInstant()
app = FastAPI()

class TodoIn(BaseModel):
    text: str
    done: bool = False

class Todo(TodoIn):
    id: str

@app.post("/todos", response_model=Todo)
async def create_todo(todo: TodoIn):
    todo_id = id()
    await db.transact(db.tx.todos[todo_id].update(todo.model_dump()))
    return Todo(id=todo_id, **todo.model_dump())
```

See [Modeling data](/docs/modeling-data) for the full schema reference.

## Reading data

`db.query` takes the same InstaQL dict shape as our JS SDK:

```python 
# Top-level fetch
result = db.query({"goals": {}, "todos": {}})

# Nested children
result = db.query({"goals": {"todos": {}}})

# Operators
db.query({"goals": {"$": {"where": {"title": {"$ne": "Get fit"}}}}})

# Pagination + ordering
db.query({"goals": {"$": {"limit": 10, "order": {"createdAt": "desc"}}}})
```

### Rule params

Use `rule_params` keyword argument to pass values for permission
rules.

```python 
db.query({"goals": {}}, rule_params={"region": "us"})
```

## Writing data

Mutations use the same InstaML proxy syntax.

```python 
from instantdb import Instant, id, lookup

db = Instant()

goal_id = id()
todo_id = id()

db.transact([
    db.tx.goals[goal_id].update({"title": "Get fit"}),
    db.tx.todos[todo_id].update({"title": "Run"}),
    db.tx.goals[goal_id].link({"todos": todo_id}),
    db.tx.users[lookup("email", "alyssa@instantdb.com")].update(
        {"name": "Alyssa"}
    ),
])
```

### Special namespaces

System namespaces like `$files` and `$users` aren't valid Python
attribute names. Use subscript access for those:

```python 
db.transact(db.tx["$files"][file_id].delete())
```

`db.tx.goals` and `db.tx["goals"]` are interchangeable for regular namespaces.

See [Writing data](/docs/instaml) for the full mutation reference.

## Subscribing to queries

`AsyncInstant.subscribe_query` opens an SSE stream and yields payloads as
the query result changes. This is similar to our JS SDK:

```python 
import asyncio
from instantdb import AsyncInstant

db = AsyncInstant()

async def main():
    async with db.subscribe_query({"todos": {}}) as sub:
        async for payload in sub:
            if payload["type"] == "error":
                print("error:", payload["error"])
                break
            print("data:", payload["data"])

asyncio.run(main())
```



Subscriptions keep a live connection open. Keep the `async with` block
alive as long as you need updates.



## Streams

Streams are also supported in the Python SDK, but only on the `AsyncInstant`
client. Writing and reading streams are similar to the JS SDK, but with Pythonic
async iterators and context managers.

### Writing

```python 
import asyncio
from instantdb import AsyncInstant

db = AsyncInstant()

async def main():
    async with db.streams.write(client_id="agent-completion-123") as writer:
        stream_id = await writer.stream_id

        async for chunk in claude_response:
            await writer.write(chunk)

asyncio.run(main())
```

### Reading

```python 
async with db.streams.read(stream_id="...") as reader:
    async for chunk in reader:
        print(chunk)
```

You can identify the stream by `stream_id=` or `client_id=`. Pass `byte_offset=`
to resume from a specific position after a disconnect.

### Querying stream metadata

The `$streams` namespace is queryable like any other:

```python 
result = db.query({
    "$streams": {
        "$": {"where": {"clientId": "agent-completion-123"}},
    },
})
```

See [Streams](/docs/streams) for the full reference.

## Logging

Pass `verbose=True` to `AsyncInstant` to log the realtime connection lifecycle
to the standard library `instantdb` logger. Pass a `logger` (any object with
`debug`, `info`, and `error`, such as a `logging.Logger`) to send it elsewhere.

```python 
import logging
from instantdb import AsyncInstant

logging.basicConfig(level=logging.DEBUG)

db = AsyncInstant(verbose=True)

# Or send logs to your own logger
db = AsyncInstant(verbose=True, logger=logging.getLogger("myapp"))
```

Only `AsyncInstant` has realtime, so the sync `Instant` has no `verbose` option.

## Auth

Mirrors the JS `db.auth` namespace.

### Magic codes

```python 
db.auth.send_magic_code("alyssa@instantdb.com")

# Or generate the code yourself for a custom email provider
code = db.auth.generate_magic_code("alyssa@instantdb.com")
print(code)

# Verify it
user, created = db.auth.check_magic_code(
    email="alyssa@instantdb.com",
    code="123456",
)
```

### Tokens

```python 
# Mint a token for a user (creates them if they don't exist)
token = db.auth.create_token(email="alyssa@instantdb.com")
# or
token = db.auth.create_token(id="...")

# Verify a refresh token (e.g. one passed in from a client)
user = db.auth.verify_token(token)
```

### Users

```python 
user = db.auth.get_user(email="alyssa@instantdb.com")
user = db.auth.get_user(id="...")
user = db.auth.get_user(refresh_token="...")

db.auth.delete_user(email="alyssa@instantdb.com")
db.auth.sign_out(email="alyssa@instantdb.com")
```

## Impersonation

You can also use the impersonation API to run queries and transactions as if you
were a specific user or guest.

```python 
# As a specific user
scoped = db.as_user(email="alyssa@instantdb.com")
goals_as_alyssa = scoped.query({"goals": {}})

# As a guest
guest = db.as_user(guest=True)
guest.query({"publicData": {}})

# Or with a refresh token
scoped = db.as_user(token="user-refresh-token")
```

`as_user` returns a new immutable client. The original `db` is unchanged.

### Without an admin token

You can construct a client without an admin token if you only impersonate.
Direct queries on the base `db` will fail, but `db.as_user(token=...)` and
`db.as_user(guest=True)` will work.

```python 
db = Instant(app_id="__APP_ID__")  # no admin_token

user_db = db.as_user(token="...")
user_db.query({"todos": {}})
```

## Storage

`db.storage.upload_file` accepts `bytes`, `pathlib.Path`, or a binary
file-like object.

```python 
from pathlib import Path

# From bytes
db.storage.upload_file(
    "photos/hello.txt",
    b"hello world",
    content_type="text/plain",
)

# From a Path (opened and closed by the SDK)
db.storage.upload_file(
    "photos/demo.png",
    Path("./demo.png"),
    content_type="image/png",
)

# From an open file (uploads from the current position; not closed)
with open("demo.png", "rb") as f:
    db.storage.upload_file("photos/demo.png", f, content_type="image/png")
```

Content length is computed automatically. Non-seekable streams need an
explicit `file_size` (bytes remaining):

```python 
db.storage.upload_file(
    "exports/data.jsonl",
    stream,
    content_type="application/jsonl",
    file_size=10_000_000,
)
```

To delete a file, use a transaction:

```python 
db.transact(db.tx["$files"][file_id].delete())
```

See [Storage](/docs/storage) for the broader storage model.

## Rooms

Read presence data for a room:

```python 
sessions = db.rooms.get_presence("chat", "room-123")
# {peer_id: {"data": ..., "peer-id": ..., "user": ...}}
```

`get_presence` is the only `rooms` method on the admin SDK. See
[Presence, Cursors, and Activity](/docs/presence-and-topics).

## Debug helpers

`debug_query` and `debug_transact` run an operation with a permission
check and return why the check passed or failed for every matching row.
They require an `as_user` context.

```python 
result = db.as_user(guest=True).debug_query({"goals": {}})
# {"result": ..., "check_results": [{"id": ..., "check": True}, ...]}

db.as_user(guest=True).debug_transact(
    db.tx.goals[id()].update({"title": "x"}),
)
```

## Webhooks

The Python SDK ships the same two-layer webhook surface as the JS SDK,
bundled as `instantdb.webhooks`.

- `db.webhooks.manager.*` for CRUD on subscriptions
- `db.webhooks.validate / fetch_payloads / process_payload` for receiving events

### Managing subscriptions

```python 
webhook = db.webhooks.manager.create(
    url="https://api.example.com/instant",
    namespaces=["goals", "todos"],
    actions=["create", "update", "delete"],
)

# Inspect
db.webhooks.manager.list()
event = db.webhooks.manager.get_event(webhook["id"], isn=42)
payload = db.webhooks.manager.get_payload(webhook["id"], isn=42)
events = db.webhooks.manager.list_events(webhook["id"])
next_page = db.webhooks.manager.list_events(
    webhook["id"], after=events["cursor"]
)

# Modify
db.webhooks.manager.update(
    webhook["id"],
    url="https://api.example.com/instant-v2",
    namespaces=["goals"],
)
db.webhooks.manager.enable(webhook["id"])
db.webhooks.manager.disable(webhook["id"], reason="Pausing for migration")
db.webhooks.manager.delete(webhook["id"])
db.webhooks.manager.resend_event(webhook["id"], isn=42)
```

Returned dicts keep camelCase wire-format keys (`webhookId`,
`idempotencyKey`, etc.) so they match the JS shape.

### Receiving webhooks

Three primitives compose into a framework integration:

```python
# 1. Verify the Ed25519 signature and parse the signed body
webhook_body = db.webhooks.validate(
    signature_header=request.headers["Instant-Signature"],
    body=raw_bytes,
    max_age_seconds=300,
)
# Raises InstantError on bad signature or stale timestamp

# 2. Exchange the payload reference for the full payload of records
payload = db.webhooks.fetch_payloads(webhook_body)

# 3. Dispatch records to handlers (most-specific-wins)
db.webhooks.process_payload(handlers, payload)
```

Handlers are a dict of dicts keyed by namespace and action, with
`$default` catch-alls at either level:

```python 
def on_goal_create(record):
    # record["after"] is the new entity; record["before"] is None on "create"
    save_to_search_index(record["after"])

handlers = {
    "goals": {
        "create": on_goal_create,
        "$default": lambda record: None,
    },
    "$default": lambda record: None,
}

db.webhooks.process_payload(handlers, payload)
```

### FastAPI example

```python 
from fastapi import FastAPI, Request, HTTPException
from instantdb import AsyncInstant, InstantError

app = FastAPI()
db = AsyncInstant()

async def on_goal_create(record):
    print("new goal:", record["after"])

handlers = {"goals": {"create": on_goal_create}}

@app.post("/webhooks/instant")
async def webhook_in(request: Request):
    body = await request.body()
    sig = request.headers.get("Instant-Signature", "")
    try:
        webhook_body = await db.webhooks.validate(signature_header=sig, body=body)
    except InstantError:
        raise HTTPException(401)

    payload = await db.webhooks.fetch_payloads(webhook_body)
    await db.webhooks.process_payload(handlers, payload)
    return {"ok": True}
```

`validate`, `fetch_payloads`, and `process_payload` are awaitable under
`AsyncInstant`. `validate` falls back to Instant's JWKS endpoint when a
signing key is not already cached or bundled. Handlers must match:
`async def` for `AsyncInstant`, plain `def` for `Instant`.

See [Webhooks](/docs/webhooks) for the broader webhook model.

## Errors

All errors raised by the SDK are subclasses of `InstantError`. The API
returns a non-2xx response as `InstantAPIError`, which carries `status`
and `body`:

```python 
from instantdb import Instant, InstantAPIError, id

db = Instant()

try:
    db.transact(db.tx.goals[id()].update({"title": "Get fit"}))
except InstantAPIError as e:
    if e.status == 429:
        print("Rate limited, backing off")
    else:
        raise
```


# Create Instant App

Use create-instant-app to scaffold a new Instant project

Once you know the basics of Instant, you may find it useful to be able to
quickly scaffold a new Instant project. We built `@interface-db/create-app` to do just
that.

We currently offer templates for Next.js, Vite + React, Expo, and Vanilla TypeScript. Follow the quick start below to give it a spin!

## Quick start

If you haven't already, authenticate with the [Instant CLI](/docs/cli) in your
terminal.

```shell 
npx @interface-db/cli login
```

This will open a browser window where you can log in or sign up for an account.
Once you've authenticated, any app you create with `@interface-db/create-app` will be
associated with your Instant account!

After authenticating, run the following command to scaffold a new Instant app.

```shell 
npx @interface-db/create-app instant-demo
```

Run the dev server to see your new app in action!

```shell
cd instant-demo
npm run dev
```

Huzzah! 🎉 You now have a brand new Instant project to play around with!

## One-shot with Claude Code

Got Claude Code? You can use it to one-shot a full-stack Instant app!

Use `@interface-db/create-app` with the `--ai` flag and you'll be prompted to describe the app you want to build. Give it a try!



You can think of this as a one-shot app builder in the terminal.


# Recommended Workflow

How to develop with Instant

At a high level, here is the recommended workflow for developing with Instant:

1. Authenticate with Instant in your terminal via `npx @interface-db/cli login`.
1. Create new projects via `npx @interface-db/create-app`.
1. Push changes to your schema and permissions via `npx @interface-db/cli push`.
1. Use the [Sandbox](https://www.instantdb.com/dash?t=sandbox) to debug queries,
   transactions, and permissions.
1. When you're ready for production, [restrict creating](/docs/patterns#restrict-creating-new-attributes) new attributes.
1. If you need more help, check out our [patterns page](/docs/patterns) for common
   recipes.



You can also drop us a line on our [Discord](https://discord.com/invite/VU53p7uQcE).



## Authenticating with Instant in your terminal

Use the [Instant CLI](/docs/instant-cli) to authenticate with Instant in your
terminal. After authenticating, you'll be able to create new projects
and have them associated with your Instant account. This will also enable you to
push and pull changes to your projects. To authenticate, run:

```
npx @interface-db/cli login
```

This will open a browser window where you can log in or sign up for an account.

## Starting a new project

After authenticating, you can create a new project with
[create-instant-app](/docs/create-instant-app). This will give you some starter code and set up rules for your LLM
agent. If your agent supports it, we also recommend setting up the [Instant MCP Server](/docs/using-llms#instant-mcp-server).

The default rules cover the basics of using InstantDB. But if you want to add
more docs for specific functionality, you can append `.md` to the end of any doc
page URL to get the raw Markdown. For example, here are the docs for
[adding auth](/docs/auth/magic-codes.md).

## Updating schema and permissions

As your project evolves, you'll likely need to update your schema and permissions. We
recommend using the Instant CLI to do this. You can make
edits to your local schema and permission files, and then run `npx @interface-db/cli push` to push changes to your project.

If you prefer a GUI, you can also make changes via the explorer in the [Instant
dashboard](https://www.instantdb.com/dash?t=explorer). To pull these changes
into your local files, run `npx @interface-db/cli pull`.

## Debugging queries, transactions, and permissions

If you're not sure why a query or transaction isn't working, or if you're
running into permission issues, you can use the
[Sandbox](https://www.instantdb.com/dash?t=sandbox) to help you debug.

The sandbox is a REPL-like environment that lets you run queries and
transactions against your project. It serves two goals:

1. Lets you run queries and transactions quickly.
2. Gives you debug info to inspect permission checks and performance.

Some examples of debug info you can see in the sandbox:

- Raw output from queries and transactions
- Permission check results for all entities returned by a query
- Permission check results for each tx operation in a transaction
- How long queries and transactions take to run

### Dealing with timeout errors

InstantDB has the following timeouts for queries and transactions:

- 5 seconds for queries and transactions with the client SDK.
- 30 seconds for queries and transactions in the Admin SDK and sandbox.

We set these timeouts intentionally for performance and reliability. We do not
allow timeouts to be configured. Sometimes fixing a timeout is as simple as
adding an index. Other times you'll need to iterate to identify the bottleneck. Some
common causes of timeouts:

- Missing an index
- Fetching or transacting too much data
- Expensive `where` clauses
- Expensive permission rules that traverse a lot of data

Set up test code in your sandbox and run experiments to get under the timeout limit.
From there you can apply the same changes to your app code.

### Dealing with permission errors

The sandbox is one of the best tools for debugging permission errors. Whenever
you run a query or transaction in the sandbox, you can see all the permission
checks that were run, and whether they passed or failed.

If it's unclear why a permission is returning false, re-run the transaction with the permission broken
down into smaller pieces. For example, if you have a permission rule like:

```
"view": "auth.id in data.ref('members.id')"
```

It can be helpful to re-run the sandbox with the permission rule changed to:

```
"view": "data.ref('members.id')"
```

This will show you the output of just that part of the rule. You can use this technique to
iterate on complex permission rules until you find the part that is causing the
permission to return false.

## Going to production

Huzzah, you're ready for prime time! When you go to production, be sure to [restrict creating](/docs/patterns#restrict-creating-new-attributes) new
attributes. You can also
consider setting up [separate apps](/docs/patterns#managing-local-vs-production-apps) for local development and
production.

## Best practices and getting help

We highly recommend going through our docs to understand how Instant works. We
tried our best to keep them delightful and example-driven!

We've also made a [patterns page](/docs/patterns) with common recipes for using
InstantDB.



If you still have questions, feel free to drop us a line on our
[Discord](https://discord.com/invite/VU53p7uQcE).




# Using Instant with LLMs

How to use Instant with LLMs

You can supercharge your Instant experience by using it with LLMs. Just add our Instant rules and you're off to the races!

## Instant Skill

The fastest way to add rules to your LLM tool is to add the Instant skill.

```text 
npx skills add instantdb/skills
```

This will give your agent the context it needs to work with InstantDB.

You can verify you set up the rules correctly by asking your LLM "How do you
make queries and transactions in InstantDB?" If everything is set up correctly,
you should see a response with information about `db.useQuery` and `db.transact`.

If you'd prefer to manually install the rules instead, see the section below.

## Instant Rules

We've created a set of rules to help LLMs understand how Instant works. If you
start a new project with `@interface-db/create-app` you'll get these rules
automatically. If you have an existing project you can add the rules manually.

[Save these rules](/llm-rules/AGENTS.md) at the root of your project as:

- `CLAUDE.md` for Claude Code
- `GEMINI.md` for Gemini
- `AGENTS.md` for Codex, Cursor, Windsurf, Zed, and other tools

You may need to restart your editor for the rules to take effect.

### Markdown Docs and llms.txt

You can attach `.md` to the end of any doc page URL to get raw Markdown. This can be helpful to paste into your LLM if you're stuck on
particular functionality. For example, here are the recommended docs for [adding auth](/docs/auth/magic-codes.md).

We recommend starting with the rules files above and adding more docs as needed.
If you want though you can get all our docs at once in markdown format via
[llms-full.txt](https://www.instantdb.com/llms-full.txt)

## Instant MCP Server

We built [`@interface-db/mcp`](https://github.com/instantdb/instant/tree/main/client/packages/mcp) to enable creating, managing, and updating your Instant apps.
Combine the MCP with our rules file to build full-stack apps directly in your editor.

The easiest way to get started is to use our hosted remote MCP server. Use the
instructions below to add the Instant MCP server to your favorite LLM editor or tool.



When you add the MCP server, you'll be sent through an OAuth flow to grant access to your Instant Account.



### Cursor

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=InstantDB&config=eyJ1cmwiOiJodHRwczovL21jcC5pbnN0YW50ZGIuY29tL21jcCJ9)

Or edit your `~/.cursor/mcp.json` directly:

```json 
{
  "mcpServers": {
    "instant": {
      "url": "https://mcp.instantdb.com/mcp"
    }
  }
}
```

### Claude Code

If you're on a paid Claude plan, you can add the server via the command line:

```text 
claude mcp add instant -s user -t http https://mcp.instantdb.com/mcp
```

Now you can run `claude` to start Claude Code and then run `/mcp` to see your list
of MCP servers. `instant` should be listed there. Select it and go through the
auth flow to enable the Instant MCP server in your Claude Code sessions!

### Codex

If you're on a paid OpenAI plan, you can add the server via the command line:

Edit your `~/.codex/config.toml` to include the [`rmcp_client` feature](https://developers.openai.com/codex/mcp/):

```toml 
[features]
rmcp_client = true
```

Tell Codex to add the MCP server:

```text 
codex mcp add instant --url "https://mcp.instantdb.com/mcp"
```

This should load a browser to authenticate with Instant.

Now run `codex` to start Codex. You can run `/mcp` to see Instant in your list.

### Gemini

If you're on a paid Google AI plan, you can add the server via the command line:

```text 
gemini mcp add --transport http instant https://mcp.instantdb.com/mcp
```

This should load a browser to authenticate with Instant.

Now run `gemini` to start Gemini. You can run `/mcp` to see Instant in your list.

### Windsurf

You can add the Instant MCP server through the Windsurf UI:

1. Open Windsurf Settings.
2. Under Cascade, you'll find Model Context Protocol Servers.
3. Select Add Server and paste the relevant snippet for your OS.

Alternatively, you can directly edit your `~/.codeium/windsurf/mcp_config.json`:

**macOS/Linux**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

**Windows**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

**Windows WSL**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "wsl",
      "args": ["npx", "-y", "mcp-remote", "https://mcp.instantdb.com/sse"]
    }
  }
}
```

### Zed

Open your Zed settings and add the following:

```json 
{
  "context_servers": {
    "instant": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.instantdb.com/mcp"],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

### Other Tools

For other tools that support MCP servers, you can configure Instant using either our streamable HTTP
endpoint (recommended if your tool supports it):

```text 
https://mcp.instantdb.com/mcp
```

or our SSE endpoint:

```text 
https://mcp.instantdb.com/sse
```

## Local MCP server

We recommend using our hosted MCP server, but we also support running [`@interface-db/mcp`](https://github.com/instantdb/instant/tree/main/client/packages/mcp) locally
via `stdio`. This will avoid OAuth but requires you to manage your personal
access token.

### Get your Personal Access Token

If you haven't already, make sure to get a personal access token from your
[Instant dashboard](https://www.instantdb.com/dash?s=personal-access-tokens)

Once you have your token, you can set up the local Instant MCP server in your
favorite editor with MCP support.

### Cursor/Windsurf/Cline

You can set up the Instant MCP server in Cursor, Windsurf, or Cline by adding
the following configuration to your MCP settings:

**macOS/Linux**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "@interface-db/mcp", "--token", "<token>"]
    }
  }
}
```

**Windows**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@interface-db/mcp", "--token", "<token>"]
    }
  }
}
```

**Windows WSL**

```json 
{
  "mcpServers": {
    "instant": {
      "command": "wsl",
      "args": ["npx", "-y", "@interface-db/mcp", "--token", "<token>"]
    }
  }
}
```

Replace `<token>` with your personal access token. Save the file and reload
the editor! You should now see the Instant MCP server active and enabled!

### Zed

Open your Zed settings and add the following:

```json 
{
  "context_servers": {
    "instant": {
      "command": {
        "path": "npx",
        "args": ["-y", "@interface-db/mcp", "--token", "<token>"],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

Replace `<token>` with your personal access token. Save the file and reload the editor.
You should now see the Instant MCP server active and enabled!

### Claude Desktop

You can set up the Instant MCP server in Claude Desktop by following these
steps:

1. Open the file `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add the following configuration to the `claude_desktop_config.json` file:

```json 
{
  "mcpServers": {
    "instant": {
      "command": "npx",
      "args": ["-y", "@interface-db/mcp", "--token", "<token>"]
    }
  }
}
```

Replace `<token>` with your personal access token. Save the file and restart
Claude Desktop. You should now see the Instant MCP server active and enabled!

## MCP Tools

Below is a list of the current tools we expose:

- `learn` Fetch rules files if needed to help the LLM understand InstantDB.
- `get-schema` Retrieves the schema for a specific app.
- `get-perms` Retrieves permission rules for an app.
- `push-schema` Applies schema changes to an app.
- `push-perms` Updates permission rules for an app.


# Initializing Instant

How to integrate Instant with your app.

## Basic Initialization

The first step to using Instant in your app is to call `init`. Here is a simple
example at the root of your app.

```javascript
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

function App() {
  return <Main />;
}
```

With that, you can use `db` to [write data](/docs/instaml), [make queries](/docs/instaql), [handle auth](/docs/auth), and more!

## Typesafety

If you're using TypeScript, `init` accepts a `schema` argument. Adding a schema provides auto-completion and typesafety for your queries and transactions.

```typescript
import { init, i } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';

const schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.any(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    todos: i.entity({
      text: i.string(),
      done: i.boolean(),
      createdAt: i.number(),
    }),
  },
});

const db = init({ appId: APP_ID, schema });
```

To learn more about writing schemas, head on over to the [Modeling your data](/docs/modeling-data) section.

## Flexible Initialization

Instant maintains a single connection regardless of where or how many times you
call `init` with the same app ID. This means you can safely call `init` multiple
times without worrying about creating multiple connections or
performance overhead. However, we do recommend the pattern of exporting a
reference from a utility file like so:

<!-- prettier-ignore-start -->
```typescript
// lib/db.ts
import { init } from '@interface-db/react';
import schema from '../instant.schema';

// Instant app
const APP_ID = '__APP_ID__';
export const db = init({ appId: APP_ID, schema });

// app/page.tsx
"use client";

import { db } from '../lib/db';

function App() {
  // do some instant magic 🪄
  db.useQuery({ todos: {} });
}

export default App;
```
<!-- prettier-ignore-end -->

## Configuration Options

`init` accepts a few options. For most use cases you'll want to provide `appId`
and `schema`. Here are all the options you can provide:

- **appId** (required): Your InstantDB application ID. This identifies your app and is used to connect to the correct backend.

- **schema?**: Instant schema export from your `instant.schema.ts` file. Provide this for typesafety and auto-completion in queries, transactions, and ephemeral features.

- **websocketURI?**: Custom WebSocket endpoint for real-time connections. Defaults to `'wss://api.interfacedb.com/runtime/session'`. Change this for connecting to development or self-hosted instances.

- **apiURI?**: Custom HTTP API endpoint for auth and storage operations. Defaults to `'https://api.interfacedb.com'`. Change this for connecting to development or self-hosted instances.

- **devtool?**: Controls the Instant dev tool. Defaults to `true` on localhost. Set to `false` to disable, or configure its `position`, `allowedHosts`, and `dashURI`. Set `dashURI` when using a self-hosted dashboard.

- **verbose?**: Enables detailed console logging for debugging. When `true`, logs WebSocket messages and internal operations. Helpful for troubleshooting connection and sync issues.

- **logger?**: Customize how `verbose` output is handled by passing an object with `debug`, `info`, and `error` methods (defaults to `console`). Useful for formatting logs (for example, JSON stringifying objects) or routing them somewhere other than the console. Only takes effect when `verbose` is `true`.

- **queryCacheLimit?**: Maximum number of query subscriptions to cache for offline mode. Defaults to `10`. Cached queries provide instant data on app reload while fresh data loads in the background.

- **useDateObjects?**: When `true`, all date columns in queries will return a JavaScript `Date` object. Disabled by default.


# Modeling data

How to model data with Instant's schema.

In this section we’ll learn how to model data using Instant's schema. By the end of this document you’ll know how to:

- Create namespaces and attributes
- Add indexes and unique constraints
- Model relationships
- Lock down your schema for production

We’ll build a micro-blog to illustrate; we'll have authors, posts, comments, and tags.

## Schema as Code

With Instant you can define your schema and your permissions in code. If you haven't already, use the [CLI](/docs/cli) to generate an `instant.schema.ts` and an `instant.perms.ts` file:

```shell 
npx @interface-db/cli@latest init
```

The CLI will guide you through picking an Instant app and generate these files for you.

## instant.schema.ts

Now we can define the data model for our blog!

Open `instant.schema.ts`, and paste the following:

```typescript 
// instant.schema.ts

import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    profiles: i.entity({
      nickname: i.string(),
      createdAt: i.date(),
    }),
    posts: i.entity({
      title: i.string(),
      body: i.string(),
      createdAt: i.date(),
    }),
    comments: i.entity({
      body: i.string(),
      createdAt: i.date(),
    }),
    tags: i.entity({
      title: i.string(),
    }),
  },
  links: {
    postAuthor: {
      forward: { on: 'posts', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' },
    },
    commentPost: {
      forward: { on: 'comments', has: 'one', label: 'post' },
      reverse: { on: 'posts', has: 'many', label: 'comments' },
    },
    commentAuthor: {
      forward: { on: 'comments', has: 'one', label: 'author' },
      reverse: { on: 'profiles', has: 'many', label: 'authoredComments' },
    },
    postsTags: {
      forward: { on: 'posts', has: 'many', label: 'tags' },
      reverse: { on: 'tags', has: 'many', label: 'posts' },
    },
    profileUser: {
      forward: { on: 'profiles', has: 'one', label: '$user' },
      reverse: { on: '$users', has: 'one', label: 'profile' },
    },
  },
});

// This helps TypeScript display better IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Let's unpack what we just wrote. There are three core building blocks to model data with Instant: **Namespaces**, **Attributes**, and **Links**.

## 1) Namespaces

Namespaces are equivalent to "tables" in relational databases or "collections" in NoSQL. In our case, these are: `$users`, `profiles`, `posts`, `comments`, and `tags`.

They're all defined in the `entities` section:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    posts: i.entity({
      // ...
    }),
  },
});
```

## 2) Attributes

Attributes are properties associated with namespaces. Each is equivalent to a "column" in relational databases or a "field" in NoSQL. For the `posts` entity, we have the `title`, `body`, and `createdAt` attributes:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      title: i.string(),
      body: i.string(),
      createdAt: i.date(),
    }),
  },
});
```

### Typing attributes

Attributes can be typed as `i.string()`, `i.number()`, `i.boolean()`, `i.date()`, `i.json()`, or `i.any()`.



`i.date()` accepts dates as either a numeric timestamp (in milliseconds) or an ISO 8601 string. `JSON.stringify(new Date())` will return an ISO 8601 string.



When you type `posts.title` as a `string`:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      title: i.string(),
      // ...
    }),
  },
});
```

Instant will _make sure_ that all `title` attributes are strings, and you'll get the proper TypeScript hints to boot!

### Required constraints

All attributes you define are considered _required_ by default. This constraint is enforced on the backend: Instant guarantees that every entity of that type will have a value and reports errors if you attempt to add an entity without a required attribute.

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string(), // <-- required
      published: i.date(), // <-- required
    }),
  },
});

db.transact(
  db.tx.posts[id()].update({
    title: 'abc', // <-- no published -- will throw
  }),
);
```

You can mark an attribute as optional by calling `.optional()`:

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string(), // <-- required
      published: i.date().optional(), // <-- optional
    }),
  },
});

db.transact(
  db.tx.posts[id()].update({
    title: 'abc', // <-- no published -- still okay
  }),
);
```

This will also reflect in types: query results containing `posts` will show `title: string` (non-nullable) and `published: string | number | null` (nullable).

You can set required on forward links, too:

```typescript
postAuthor: {
  forward: { on: 'posts', has: 'one', label: 'author', required: true },
  reverse: { on: 'profiles', has: 'many', label: 'authoredPosts' },
},
```

Finally, for legacy attributes that are treated as required on your front-end but you are not ready to enable back-end required checks yet, you can use `.clientRequired()`. That will produce a TypeScript type without `null` but will not add a back-end required check:

```typescript
const _schema = i.schema({
  entities: {
    posts: i.entity({
      title: i.string().clientRequired(),
      published: i.date().optional(),
    }),
  },
});
```

### Unique constraints

Sometimes you'll want to introduce a unique constraint. For example, say we wanted to add friendly URLs to posts. We could introduce a `slug` attribute:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    posts: i.entity({
      slug: i.string().unique(),
      // ...
    }),
  },
});
```

Since we're going to use post slugs in URLs, we'll want to make sure that no two posts can have the same slug. If we mark `slug` as `unique`, _Instant will guarantee this constraint for us_.

Unique attributes will also speed up queries that filter by that attribute.

```typescript
const query = {
  posts: {
    $: {
      where: {
        // Since `slug` is unique, this query is 🚀 fast
        slug: 'completing_sicp',
      },
    },
  },
};
```

### Indexing attributes

You can also use index attributes to speed up querying. An additional
benefit is that indexed attributes can be used with comparison operators for
where queries like `$gt`, `$lt`, `$gte`, and `$lte` and can be used in `order`
clauses.

Suppose we wanted to query for products less than $100 and order by price.

First we make sure that the `price` attribute is indexed:

```typescript
// instant.schema.ts

const _schema = i.schema({
  entities: {
    // ...
    products: i.entity({
      price: i.number().indexed(), // 🔥,
      // ...
    }),
  },
});
```

And now we can use `$lt` and `order` in our query:

```typescript
const query = {
  products: {
    $: {
      where: {
        price: { $lt: 100 },
      },
      order: {
        price: 'desc',
      },
    },
  },
};
```

Even if you're not using comparison operators or order clauses, indexing
attributes can still speed up queries that filter by that attribute.

## 3) Links

Links connect two namespaces together. When you define a link, you define it both in the 'forward', and the 'reverse' direction. For example:

```typescript
postAuthor: {
  forward: { on: "posts", has: "one", label: "author" },
  reverse: { on: "profiles", has: "many", label: "authoredPosts" },
}
```

This links `posts` and `profiles` together:

- `posts.author` links to _one_ `profiles` entity
- `profiles.authoredPosts` links back to _many_ `posts` entities.

Since links are defined in both directions, you can query in both directions too:

```typescript
// This queries all posts with their author
const query1 = {
  posts: {
    author: {},
  },
};

// This queries profiles, with all of their authoredPosts!
const query2 = {
  profiles: {
    authoredPosts: {},
  },
};
```

Links can have one of four relationship types: `many-to-many`, `many-to-one`, `one-to-many`, and `one-to-one`.

Our micro-blog example has the following relationship types:

- **One-to-one** between `profiles` and `$users`
- **One-to-many** between `posts` and `profiles`
- **One-to-many** between `comments` and `posts`
- **One-to-many** between `comments` and `profiles`
- **Many-to-many** between `posts` and `tags`

### Cascade Delete

Links defined with `has: "one"` can set `onDelete: "cascade"`. In this case, when the profile entity is deleted, all post entities will be deleted too:

```typescript
postAuthor: {
  forward: { on: "posts", has: "one", label: "author", onDelete: "cascade" },
  reverse: { on: "profiles", has: "many", label: "authoredPosts" },
}

// this will delete profile and all linked posts
db.tx.profiles[user_id].delete();
```

Without `onDelete: "cascade"`, deleting a profile would simply delete the links but not delete the underlying posts.

If you prefer to model links in the other direction, you can do it, too:

```
postAuthor: {
  forward: { on: "profiles", has: "many", label: "authoredPosts" },
  reverse: { on: "posts", has: "one", label: "author", onDelete: "cascade" },
}
```

## Publishing your schema

Now that you have your schema, you can use the CLI to `push` it to your app:

```shell 
npx @interface-db/cli@latest push schema
```

The CLI will look at your app in production, show you the new columns you'd create, and run the changes for you!



```
Checking for an Instant SDK...
Found @interface-db/react in your package.json.
Found NEXT_PUBLIC_INSTANT_APP_ID: *****
Planning schema...
The following changes will be applied to your production schema:
ADD ENTITY profiles.id
ADD ENTITY posts.id
ADD ENTITY comments.id
ADD ENTITY tags.id
ADD ATTR profiles.nickname :: unique=false, indexed=false
ADD ATTR profiles.createdAt :: unique=false, indexed=false
ADD ATTR posts.title :: unique=false, indexed=false
ADD ATTR posts.slug :: unique=true, indexed=false
ADD ATTR posts.body :: unique=false, indexed=false
ADD ATTR posts.createdAt :: unique=false, indexed=true
ADD ATTR comments.body :: unique=false, indexed=false
ADD ATTR comments.createdAt :: unique=false, indexed=false
ADD ATTR tags.title :: unique=false, indexed=false
ADD LINK posts.author <=> profiles.authoredPosts
ADD LINK comments.post <=> posts.comments
ADD LINK comments.author <=> profiles.authoredComments
ADD LINK posts.tags <=> tags.posts
ADD LINK profiles.$user <=> $users.profile
? OK to proceed? yes
Schema updated!
```



## Use schema for typesafety

You can also use your schema inside `init`:

```typescript
import { init } from '@interface-db/react';

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
});
```

When you do this, all [queries](/docs/instaql) and [transactions](/docs/instaml) will come with typesafety out of the box.



If you haven't used the CLI to push your schema yet, no problem. Any time you write `transact`, we'll automatically create missing entities for you.



## Update or Delete attributes

You can always modify or delete attributes after creating them. **You can't use the CLI to do this yet, but you can use the dashboard.**

Say we wanted to rename `posts.createdAt` to `posts.publishedAt`:

1. Go to your [Dashboard](https://instantdb.com/dash)
2. Click "Explorer"
3. Click "posts"
4. Click "Edit Schema"
5. Click `createdAt`

You'll see a modal that you can use to rename the attribute, index it, or delete it:



## Secure your schema with permissions

In the earlier sections we mentioned that new `entities` and `attributes` can be created on the fly when you call `transact`. This can be useful for development, but you may not want this in production.

To prevent changes to your schema on the fly, simply add these permissions to your app.

```typescript
// instant.perms.ts
import type { InstantRules } from '@interface-db/react';

const rules = {
  attrs: {
    allow: {
      $default: 'false',
    },
  },
} satisfies InstantRules;

export default rules;
```

Once you push these permissions to production:

```bash
npx @interface-db/cli@latest push perms
```



```
Checking for an Instant SDK...
Found @interface-db/react in your package.json.
Found NEXT_PUBLIC_INSTANT_APP_ID: *****
Planning perms...
The following changes will be applied to your perms:
-null
+{
+  attrs: {
+    allow: {
+      $default: "false"
+    }
+  }
+}
OK to proceed? yes[21
Permissions updated!
```



You'll still be able to make changes in the explorer or with the CLI, but client-side transactions that try to modify your schema will fail. This means your schema is safe from unwanted changes!

---

**If you've made it this far, congratulations! You should now be able to fully customize and lock down your data model. Huzzah!**


# Writing data

How to write data with Instant using InstaML.

Instant uses a **Firebase-inspired** interface for mutations. We call our mutation language **InstaML**.

## Creating data

We use the `create` action to create entities:

```typescript
import { init, id } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

// transact! 🔥
db.transact(db.tx.goals[id()].create({ title: 'eat' }));
```

This creates a new `goal` with the following properties:

- It's identified by a randomly generated id via the `id()` function.
- It has an attribute `title` with value `eat`.

You can store `strings`, `numbers`, `booleans`, `arrays`, and `objects` as values. You can also generate values via functions. Below is an example for picking a random goal title.

```javascript
db.transact(
  db.tx.goals[id()].create({
    title: ['eat', 'sleep', 'hack', 'repeat'][Math.floor(Math.random() * 4)],
  }),
);
```

## Update data

The `update` action is used for updating entities. Suppose we had created the following goal:

```javascript
const eatId = id();
db.transact(
  db.tx.goals[eatId].update({ priority: 'top', lastTimeEaten: 'Yesterday' }),
);
```

We eat some food and decide to update the goal. We can do that like so:

```javascript
db.transact(db.tx.goals[eatId].update({ lastTimeEaten: 'Today' }));
```

This will only update the value of the `lastTimeEaten` attribute for entity `eat`.

As with NoSQL, you don't need to use the same schema for each entity in a namespace. After creating the previous goal, you can run the following:

```javascript
db.transact(
  db.tx.goals[id()].update({
    priority: 'none',
    isSecret: true,
    value: 10,
    aList: [1, 2, 3],
    anObject: { foo: 'bar' },
  }),
);
```

The `update` function creates or updates an entity depending on whether it already exists (so-called "upsert" mode). If the entity doesn’t exist yet, calling `update` will create it; otherwise, it will update it.

To force “strict update” mode, pass the `{ upsert: false }` option:

```javascript
db.transact(
  db.tx.goals[eatId].update({ lastTimeEaten: 'Today' }, { upsert: false }),
);
```

## Merge data

When you `update` an attribute, you overwrite it. This is fine for updating
values of strings, numbers, and booleans. But if you use `update` to overwrite
JSON objects, you may encounter two problems:

1. You lose any data you didn't specify.
2. You risk clobbering changes made by other clients.

For example, imagine we had a `game` entity that stored a `state` of favorite colors:

```javascript
// User 1 saves {'0-0': 'red'}
db.transact(db.tx.games[gameId].update({ state: { '0-0': 'red' } }));

// User 2 saves {'0-1': 'blue'}
db.transact(db.tx.games[gameId].update({ state: { '0-1': 'blue' } }));

// 🤔 Uh oh! User 2 overwrites User 1's changes:
// Final State: {'0-1': 'blue' }
```

To make working with deeply nested, document-style JSON values a breeze, we created `merge`.
Similar to [lodash's `merge` function](https://lodash.com/docs/4.17.15#merge),
`merge` allows you to specify the slice of data you want to update:

```javascript
// User 1 saves {'0-0': 'red'}
db.transact(db.tx.games[gameId].merge({ state: { '0-0': 'red' } }));

// User 2 saves {'0-1': 'blue'}
db.transact(db.tx.games[gameId].merge({ state: { '0-1': 'blue' } }));

// ✅ Wohoo! Both states are merged!
// Final State: {'0-0': 'red', '0-1': 'blue' }
```

`merge` only merges objects. Calling `merge` on **arrays, numbers, or booleans** will overwrite the values.

Sometimes you may want to remove keys from a nested object. You can do so by calling `merge` with a key set to `null`. This will remove the corresponding property from the object.


Setting a key to `undefined` will have no effect. Set the key to `null` to remove the property.


```javascript
// State: {'0-0': 'red', '0-1': 'blue' }
db.transact(db.tx.games[gameId].merge({ state: { '0-1': null } }));
// New State! {'0-0': 'red' }
```

## Delete data

The `delete` action is used for deleting entities.

```javascript
db.transact(db.tx.goals[eatId].delete());
```

You can generate an array of `delete` txs to delete all entities in a namespace:

```javascript
const { isLoading, error, data } = db.useQuery({ goals: {} });
const { goals } = data;
// ...

db.transact(goals.map((g) => db.tx.goals[g.id].delete()));
```

Calling `delete` on an entity also deletes its associations. So no need to worry about cleaning up previously created links.

## Link data

`link` is used to create associations.

Suppose we create a `goal` and a `todo`.

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.goals[healthId].update({ title: 'Get fit!' }),
]);
```

We can associate `healthId` with `workoutId` like so:

```javascript
db.transact(db.tx.goals[healthId].link({ todos: workoutId }));
```

We could have done all this in one `transact` too via chaining transaction chunks.

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.goals[healthId]
    .update({ title: 'Get fit!' })
    .link({ todos: workoutId }),
]);
```

You can specify multiple ids in one `link` as well:

```javascript
db.transact([
  db.tx.todos[workoutId].update({ title: 'Go on a run' }),
  db.tx.todos[proteinId].update({ title: 'Drink protein' }),
  db.tx.todos[sleepId].update({ title: 'Go to bed early' }),
  db.tx.goals[healthId]
    .update({ title: 'Get fit!' })
    .link({ todos: [workoutId, proteinId, sleepId] }),
]);
```

Links are bi-directional. Say we link `healthId` to `workoutId`:

```javascript
db.transact(db.tx.goals[healthId].link({ todos: workoutId }));
```

We can query associations in both directions:

```javascript
const { isLoading, error, data } = db.useQuery({
  goals: { todos: {} },
  todos: { goals: {} },
});

const { goals, todos } = data;
console.log('goals with nested todos', goals);
console.log('todos with nested goals', todos);
```

## Unlink data

Links can be removed via `unlink`.

```javascript
db.transact(db.tx.goals[healthId].unlink({ todos: workoutId }));
```

This removes links in both directions. Unlinking can be done in either direction so unlinking `workoutId` from `healthId` would have the same effect.

```javascript
db.transact([db.tx.todos[workoutId].unlink({ goals: healthId })]);
```

We can `unlink` multiple ids too:

```javascript
db.transact([
  db.tx.goals[healthId].unlink({ todos: [workoutId, proteinId, sleepId] }),
  db.tx.goals[workId].unlink({ todos: [standupId, reviewPRsId, focusId] }),
]);
```

## Lookup by unique attribute

If your entity has a unique attribute, you can use `lookup` in place of the id to perform updates.

```javascript
db.transact(
  db.tx.profiles.lookup('email', 'eva_lu_ator@instantdb.com').update({
    name: 'Eva Lu Ator',
  }),
);
```

The `lookup` function takes the attribute as its first argument and the unique attribute value as its second argument.

When it is used in a transaction, the updates will be applied to the entity that has the unique value. If no entity has the value, then a new entity with a random id will be created with the value.

It can be used with `update`, `delete`, `merge`, `link`, and `unlink`.

## Lookups in links

When used with links, it can also be used in place of the linked entity's id.

```javascript
db.transact(
  db.tx.users.lookup('email', 'eva_lu_ator@instantdb.com').link({
    posts: lookup('number', 15), // using a lookup in place of the id
  }),
);
```

## Transacts are atomic

When you call `db.transact`, all the transactions are committed atomically. If
any of the transactions fail, none of them will be committed.

## Typesafety

By default, `db.transact` is permissive. When you save data, we'll create missing attributes for you:

```typescript
db.tx.todos[workoutId].update({
  // Instant will automatically create this attribute
  dueDate: Date.now() + 60 * 1000,
});
```

As your app grows, you may want to start enforcing types. When you're ready, you can start using a [schema](/docs/modeling-data). If your schema includes a `todos.dueDate` for example:

```typescript
// instant.schema.ts
const _schema = i.schema({
  entities: {
    todos: i.entity({
      // ...
      dueDate: i.date(),
    }),
  },
  // ...
});
// ...
```

Instant will enforce that `todos.dueDate` values are actually dates, and you'll get some nice IntelliSense to boot:



Instant also comes with a few utility types, which can help you write abstractions over `transact`. For example, say you wanted to write a custom `update` function:

```typescript
// Goal
myCustomUpdate('todos', { dueDate: Date.now() });
```

You can use the `UpdateParams` utility to make sure arguments follow the schema:

```typescript
import { UpdateParams } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';

type EntityTypes = keyof AppSchema['entities'];

function myCustomUpdate<EType extends EntityTypes>(
  etype: EType,
  args: UpdateParams<AppSchema, EType>,
) {
  // ..
}
```

And the `LinkParams` utility can do the same for links:

```typescript
import { LinkParams } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';

type EntityTypes = keyof AppSchema['entities'];

function myCustomLink<EType extends EntityTypes>(
  etype: EType,
  args: LinkParams<AppSchema, EType>,
) {
  // ..
}
```

To learn more about writing schemas, check out the [Modeling Data](/docs/modeling-data) section.

## Batching transactions

If you have a large number of transactions to commit, you'll want to batch them
to avoid hitting transaction limits and timeouts.

Suppose we want to create 3000 goals. Here's how we can batch them into 30 transactions of 100 goals each.

```javascript
const batchSize = 100; // doing 100 txs should be pretty safe
const createGoals = async (total) => {
  let goals = [];
  const batches = [];

  // iterate through all your goals and create batches
  for (let i = 0; i < total; i++) {
    const goalNumber = i + 1;
    goals.push(
      db.tx.goals[id()].update({ goalNumber, title: `Goal ${goalNumber}` }),
    );

    // We have enough goals to create a batch
    if (goals.length >= batchSize) {
      batches.push(goals);
      goals = []; // reset goals for the next batch
    }
  }

  // Add any remaining goals to the last batch
  if (goals.length) {
    batches.push(goals);
  }

  // Now that you have your batches, transact them
  for (const batch of batches) {
    await db.transact(batch);
  }
};
```

## Using the tx proxy object

`db.tx` is a [proxy object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) which creates transaction chunks to be committed via `db.transact`. It follows the format:

```
db.tx.NAMESPACE_LABEL[ENTITY_IDENTIFIER].ACTION(ACTION_SPECIFIC_DATA)
```

- `NAMESPACE_LABEL` refers to the namespace to commit (e.g. `goals`, `todos`)
- `ENTITY_IDENTIFIER` is the id to look up in the namespace. This id must be a uuid and unique to the namespace. You can use the `id()` function to generate a uuid for convenience.
- `ACTION` is one of `create`, `update`, `merge`, `delete`, `link`, `unlink`
- `ACTION_SPECIFIC_DATA` depends on the action
  - `create` and `update` take in an object of information to commit
  - `merge` takes in an object to deep merge with the existing data
  - `delete` is the only action that doesn't take in any data
  - `link` and `unlink` take an object of label-entity pairs to create/delete associations


# Reading data

How to read data with Instant using InstaQL.

Instant uses a declarative syntax for querying. It's like GraphQL without the configuration. Here's how you can query data with **InstaQL.**

## Fetch namespace

One of the simplest queries you can write is to simply get all entities of a namespace.

```javascript
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  // Queries! 🚀
  const query = { goals: {} };
  const { isLoading, error, data } = db.useQuery(query);
  // ...
}
```

Inspecting `data`, we'll see:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    },
    {
      "id": workId,
      "title": "Get promoted!"
    }
  ]
}
```

For comparison, the SQL equivalent of this would be something like:

```javascript
const data = { goals: doSQL('SELECT * FROM goals') };
```

## Fetch multiple namespaces

You can fetch multiple namespaces at once:

```javascript
const query = { goals: {}, todos: {} };
const { isLoading, error, data } = db.useQuery(query);
```

We will now see data for both namespaces.

```javascript
console.log(data)
{
  "goals": [...],
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": proteinId,
      "title": "Drink protein"
    },
    ...
  ]
}
```

The equivalent of this in SQL would be to write two separate queries.

```javascript
const data = {
  goals: doSQL('SELECT * from goals'),
  todos: doSQL('SELECT * from todos'),
};
```

## Fetch a specific entity

If you want to filter entities, you can use the `where` keyword. Here we fetch a specific goal.

```javascript
const query = {
  goals: {
    $: {
      where: {
        id: healthId,
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    }
  ]
}
```

The SQL equivalent would be:

```javascript
const data = { goals: doSQL("SELECT * FROM goals WHERE id = 'healthId'") };
```

## Fetch associations

We can fetch goals and their related todos.

```javascript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

`goals` would now include nested `todos`

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [...],
    },
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": [...],
    }
  ]
}
```

### Comparing with SQL

The SQL equivalent for this would be something along the lines of:

```javascript
const query = `
  SELECT g.*, gt.todos
  FROM goals g
  JOIN (
      SELECT g.id, json_agg(t.*) as todos
      FROM goals g
      LEFT JOIN todos t on g.id = t.goal_id
      GROUP BY 1
  ) gt on g.id = gt.id
`;
const data = { goals: doSQL(query) };
```

Notice the complexity of this SQL query. Although fetching associations in SQL is straightforward via `JOIN`, marshalling the results in a nested structure via SQL is tricky. An alternative approach would be to write two straight-forward queries and then marshall the data on the client.

```javascript
const _goals = doSQL("SELECT * from goals")
const _todos = doSQL("SELECT * from todos")
const data = {goals: _goals.map(g => (
  return {...g, todos: _todos.filter(t => t.goal_id === g.id)}
))
```

Now compare these two approaches with `InstaQL`:

```javascript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

Modern applications often need to render nested relations. `InstaQL` really starts to shine for these use cases.

## Fetch specific associations

### A) Fetch associations for filtered namespace

We can fetch a specific entity in a namespace as well as its related associations.

```javascript
const query = {
  goals: {
    $: {
      where: {
        id: healthId,
      },
    },
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

This returns:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [
        {
          "id": proteinId,
          "title": "Drink protein"
        },
        {
          "id": sleepId,
          "title": "Go to bed early"
        },
        {
          "id": workoutId,
          "title": "Go on a run"
        }
      ]
    }
  ]
}
```

### B) Filter namespace by associated values

We can filter namespaces **by their associations**:

```javascript
const query = {
  goals: {
    $: {
      where: {
        'todos.title': 'Code a bunch',
      },
    },
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

This returns:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": [
        {
          "id": focusId,
          "title": "Code a bunch"
        },
        {
          "id": reviewPRsId,
          "title": "Review PRs"
        },
        {
          "id": standupId,
          "title": "Do standup"
        }
      ]
    }
  ]
}
```

### C) Filter associations

We can also filter associated data.

```javascript
const query = {
  goals: {
    todos: {
      $: {
        where: {
          title: 'Go on a run',
        },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

This will return goals and filtered todos:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!",
      "todos": [
        {
          "id": workoutId,
          "title": "Go on a run"
        }
      ]
    },
    {
      "id": workId,
      "title": "Get promoted!",
      "todos": []
    }
  ]
}
```

---


Notice the difference between these three cases.

- A) Fetched all todos for goal with id `health`
- B) Filtered goals with at least one todo titled `Code a bunch`
- C) Fetched all goals and filtered associated todos by title `Go on a run`



---

## Inverse Associations

Associations are also available in the reverse order.

```javascript
const query = {
  todos: {
    goals: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch",
      "goals": [
        {
          "id": workId,
          "title": "Get promoted!"
        }
      ]
    },
    ...,
  ]
}
```

## Defer queries

You can also defer queries until a condition is met. This is useful when you
need to wait for some data to be available before you can run your query. Here's
an example of deferring a fetch for todos until a user is logged in.

```javascript
const { isLoading, user, error } = db.useAuth();

const {
  isLoading: isLoadingTodos,
  error,
  data,
} = db.useQuery(
  user
    ? {
        // The query will run once user is populated
        todos: {
          $: {
            where: {
              'owner.id': user.id,
            },
          },
        },
      }
    : // Otherwise skip the query, which sets `isLoading` to true
      null,
);
```

**NOTE:** Passing `null` to `db.useQuery` will result in `isLoading` being true. In the example above, this means that `isLoadingTodos` will _always be true_ if the user is not logged in.

## Pagination

You can limit the number of items from a top-level namespace by adding a `limit` to the option map:

```javascript
const query = {
  todos: {
    // limit is only supported for top-level namespaces right now
    // and not for nested namespaces.
    $: { limit: 10 },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);
```

Instant supports both offset-based and cursor-based pagination for top-level
namespaces.

### Offset

To get the next page, you can use an offset:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      // similar to `limit`, `offset` is only supported for top-level namespaces
      offset: 10,
    },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);
```

In a React application, your offset-based pagination code might look something like this:

```jsx
const [pageNumber, setPageNumber] = React.useState(1);

const pageSize = 10;

const query = {
  todos: {
    $: {
      limit: pageSize,
      offset: pageSize * (pageNumber - 1),
    },
  },
};

const { isLoading, error, data } = db.useQuery(query);

// Load the next page by increasing the page number, which will
// increase the offset by the page size.
const loadNextPage = () => {
  setPageNumber(pageNumber + 1);
};

// Load the previous page by decreasing the page number, which will
// decrease the offset by the page size.
const loadPreviousPage = () => {
  setPageNumber(pageNumber - 1);
};
```

### Cursors

You can also get the next page with the `endCursor` returned in the `pageInfo` map from the previous result:

```javascript
const query = {
  todos: {
    $: {
      // These also are only supported for top-level namespaces
      first: 10,
      after: pageInfo?.todos?.endCursor,
    },
  },
};
```

To get the previous page, use the `startCursor` in the `before` field of the option map and ask for the `last` items:

```javascript
const query = {
  todos: {
    $: {
      last: 10,
      before: pageInfo?.todos?.startCursor,
    },
  },
};
```

In a React application, your cursor-based pagination code might look something like this:

```jsx
const pageSize = 10;

const [cursors, setCursors] = React.useState({ first: pageSize });

const query = {
  todos: {
    $: {
      ...cursors,
    },
  },
};

const { isLoading, error, data, pageInfo } = db.useQuery(query);

const loadNextPage = () => {
  const endCursor = pageInfo?.todos?.endCursor;
  if (endCursor) {
    setCursors({ after: endCursor, first: pageSize });
  }
};

const loadPreviousPage = () => {
  const startCursor = pageInfo?.todos?.startCursor;
  if (startCursor) {
    setCursors({
      before: startCursor,
      // Ask for the `last` 10 items so that we get the items just
      // before our startCursor
      last: pageSize,
    });
  }
};
```

### Ordering

The default ordering is by the time the objects were created, in ascending order. You can change the order with the `order` key in the option map for namespaces:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      // Similar to limit, order is limited to top-level namespaces right now
      order: {
        serverCreatedAt: 'desc',
      },
    },
  },
};
```

The `serverCreatedAt` field is a reserved key that orders by the time that the object was first persisted on the Instant backend. It can take the value 'asc' (the default) or 'desc'.

You can also order by any attribute that is indexed and has a checked type.


Add indexes and checked types to your attributes from the [Explorer on the Instant dashboard](/dash?t=explorer) or from the [cli](/docs/cli).


```typescript
// Get the todos that are due next
const query = {
  todos: {
    $: {
      limit: 10,
      where: {
        dueDate: { $gt: Date.now() },
      },
      order: {
        dueDate: 'asc',
      },
    },
  },
};
```

You can use order in nested namespaces as well:

```typescript
// Get goals with their associated todos ordered by due date
const query = {
  goals: {
    todos: {
      $: {
        order: {
          dueDate: 'asc',
        },
      },
    },
  },
};
```

Order is not supported on nested attributes. So if todos had an owner you could
not order todos by "owner.name". This behavior is different from `where`,
which supports filtering on nested attributes.

```typescript
// ❌ Order does not support nested attributes
const query = {
  todos: {
    $: {
      order: {
        'owner.name': 'asc', // Cannot order by nested attributes
      },
    },
  },
};

// ✅ Where does support filtering on nested attributes
const query = {
  todos: {
    $: {
      where: {
        'owner.name': 'alyssa.p.hacker@instantdb.com',
      },
    },
  },
};
```

## Advanced filtering

### Multiple `where` conditions

The `where` clause supports multiple keys which will filter entities that match all of the conditions.

```javascript
const query = {
  todos: {
    $: {
      where: {
        completed: true,
        'goals.title': 'Get promoted!',
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch",
      "completed": true
    }
  ]
}
```

### And

The `where` clause supports `and` queries which are useful when you want to filter entities that match multiple associated values.

In this example, we want to find goals that have todos with the titles `Drink protein` and `Go on a run`:

```javascript
const query = {
  goals: {
    $: {
      where: {
        and: [
          { 'todos.title': 'Drink protein' },
          { 'todos.title': 'Go on a run' },
        ],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": healthId,
      "title": "Get fit!"
    }
  ]
}
```

### OR

The `where` clause supports `or` queries that will filter entities that match any of the clauses in the provided list:

```javascript
const query = {
  todos: {
    $: {
      where: {
        or: [{ title: 'Code a bunch' }, { title: 'Review PRs' }],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": reviewPRsId,
      "title": "Review PRs"
    },
  ]
}
```

### $in

The `where` clause supports `$in` queries that will filter entities that match any of the items in the provided list.
You can think of this as a shorthand for `or` on a single key.

```javascript
const query = {
  todos: {
    $: {
      where: {
        title: { $in: ['Code a bunch', 'Review PRs'] },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": focusId,
      "title": "Code a bunch"
    },
    {
      "id": reviewPRsId,
      "title": "Review PRs"
    }
  ]
}
```

### Comparison operators

The `where` clause supports comparison operators on fields that are indexed and have checked types.


Add indexes and checked types to your attributes from the [Explorer on the Instant dashboard](/dash?t=explorer) or from the [cli with Schema-as-code](/docs/modeling-data).


| Operator |       Description        | JS equivalent |
| :------: | :----------------------: | :-----------: |
|  `$gt`   |       greater than       |      `>`      |
|  `$lt`   |        less than         |      `<`      |
|  `$gte`  | greater than or equal to |     `>=`      |
|  `$lte`  |  less than or equal to   |     `<=`      |

```javascript
const query = {
  todos: {
    $: {
      where: {
        timeEstimateHours: { $gt: 24 },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": buildShipId,
      "title": "Build a starship prototype",
      "timeEstimateHours": 5000
    }
  ]
}
```

Dates can be stored as timestamps (milliseconds since the epoch, e.g. `Date.now()`) or as ISO 8601 strings (e.g. `JSON.stringify(new Date())`) and can be queried in the same formats:

```javascript
const now = '2024-11-26T15:25:00.054Z';
const query = {
  todos: {
    $: { where: { dueDate: { $lte: now } } },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data);
{
  "todos": [
    {
      "id": slsFlightId,
      "title": "Space Launch System maiden flight",
      "dueDate": "2017-01-01T00:00:00Z"
    }
  ]
}
```

If you try to use comparison operators on data that isn't indexed and type-checked, you'll get an error:

```javascript
const query = {
  todos: {
    $: { where: { priority: { $gt: 2 } } },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(error);
{
  "message": "Validation failed for query",
  "hint": {
    "data-type": "query",
    "errors": [
      {
        "expected?": "indexed?",
        "in": ["priority", "$", "where", "priority"],
        "message": "The `todos.priority` attribute must be indexed to use comparison operators."
      }
    ],
    "input": {
      "todos": {
        "$": {
          "where": {
            "priority": {
              "$gt": 2
            }
          }
        }
      }
    }
  }
}
```

### $ne

The `where` clause supports `$ne` queries that will return entities that don't
match the provided value for the field, including entities where the field is null or undefined.

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $ne: 'work' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": cookId,
      "title": "Cook dinner",
      "location": "home"
    },
    {
      "id": readId,
      "title": "Read",
      "location": null
    },
        {
      "id": napId,
      "title": "Take a nap"
    }
  ]
}
```

### $isNull

The `where` clause supports `$isNull` queries that will filter entities by whether the field value is either null or undefined.

Set `$isNull` to `true` to return entities where the field is null or undefined.

Set `$isNull` to `false` to return entities where the field is not null and not undefined.

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $isNull: false },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": cookId,
      "title": "Cook dinner",
      "location": "home"
    }
  ]
}
```

```javascript
const query = {
  todos: {
    $: {
      where: {
        location: { $isNull: true },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "todos": [
    {
      "id": readId,
      "title": "Read",
      "location": null
    },
    {
      "id": napId,
      "title": "Take a nap"
    }
  ]
}
```

### $like

The `where` clause supports `$like` on fields that are indexed with a checked `string` type.

`$like` queries will return entities that match a **case-sensitive** substring of the provided value for the field.

For **case-insensitive** matching, use `$ilike` in place of `$like`.

Here's how you can do queries like `startsWith`, `endsWith` and `includes`.

|          Example          |      Description      | JS equivalent |
| :-----------------------: | :-------------------: | :-----------: |
|    `{ $like: "Get%" }`    |   Starts with 'Get'   | `startsWith`  |
| `{ $like: "%promoted!" }` | Ends with 'promoted!' |  `endsWith`   |
|   `{ $like: "%fit%" }`    |    Contains 'fit'     |  `includes`   |

Here's how you can use `$like` to find all goals that end with the word
"promoted!"

```javascript
// Find all goals that end with the word "promoted!"
const query = {
  goals: {
    $: {
      where: {
        title: { $like: '%promoted!' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": workId,
      "title": "Get promoted!",
    }
  ]
}
```

You can use `$like` in nested queries as well:

```javascript
// Find goals that have todos with the word "standup" in their title
const query = {
  goals: {
    $: {
      where: {
        'todos.title': { $like: '%standup%' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

This returns:

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
    }
  ]
}
```

Case-insensitive matching with `$ilike`:

```javascript
const query = {
  goals: {
    $: {
      where: {
        'todos.title': { $ilike: '%stand%' },
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
    },
    {
      "id": standId,
      "title": "Stand up a food truck.",
    }
  ]
}
```

## Select fields

An InstaQL query will fetch all fields for each object.

If you prefer to select the specific fields that you want your query to return, use the `fields` param:

```javascript
const query = {
  goals: {
    $: {
      fields: ['status'],
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId, // id will always be returned even if not specified
      "status": "in-progress"
    },
    {
      "id": standId,
      "status": "completed"
    }
  ]
}
```

`fields` also works with nested relations:

```javascript
const query = {
  goals: {
    $: {
      fields: ['title'],
    },
    todos: {
      $: {
        fields: ['id'],
      },
    },
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "goals": [
    {
      "id": standupId,
      "title": "Perform standup!",
      "todos": [{"id": writeJokesId}, {"id": goToOpenMicId}]
    },
    {
      "id": standId,
      "title": "Stand up a food truck.",
      "todos": [{"id": learnToCookId}, {"id": buyATruckId}]
    }
  ]
}
```

Using `fields` can be useful for performance optimization. It reduces the
amount of data that needs to be transferred from the server and minimizes the
number of re-renders in your React application if there are no changes to your
selected fields.



Using `fields` doesn't restrict a client from doing a full query. If you have sensitive data on your entities that you
don't want to expose, you'll want to use [permissions](/docs/permissions#fields) to restrict access.



## Typesafety

By default, `db.useQuery` is permissive. You don't have to tell us your schema upfront, and you can write any kind of query:

```typescript
const query = {
  goals: {
    todos: {},
  },
};
const { isLoading, error, data } = db.useQuery(query);
```

As your app grows, you may want to start enforcing types. When you're ready you can write a [schema](/docs/modeling-data). If your schema includes `goals` and `todos` for example:

```typescript
// instant.schema.ts

import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    goals: i.entity({
      title: i.string(),
    }),
    todos: i.entity({
      title: i.string(),
      text: i.string(),
      done: i.boolean(),
      createdAt: i.date(),
      dueDate: i.date(),
    }),
  },
  links: {
    goalsTodos: {
      forward: { on: 'goals', has: 'many', label: 'todos' },
      reverse: { on: 'todos', has: 'many', label: 'goals' },
    },
  },
});

// This helps TypeScript display better IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Instant will start giving you IntelliSense for your queries. For example, if you're querying for goals, you'll see that only `todos` can be associated:



And if you hover over `data`, you'll see the actual typed output of your query:



### Utility Types

Instant also comes with some utility types to help you use your schema in TypeScript.

For example, you could define your `query` upfront:

```typescript
import { InstaQLParams } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';

// `query` typechecks against our schema!
const query = {
  goals: { todos: {} },
} satisfies InstaQLParams<AppSchema>;
```

Or you can define your result type:

```typescript
import { InstaQLResult } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';

type GoalsTodosResult = InstaQLResult<AppSchema, { goals: { todos: {} } }>;
```

Or you can extract a particular entity:

```typescript
import { InstaQLEntity } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';

type Todo = InstaQLEntity<AppSchema, 'todos'>;
```

You can specify links relative to your entity:

```typescript
type TodoWithGoals = InstaQLEntity<AppSchema, 'todos', { goals: {} }>;
```

To learn more about writing schemas, check out the [Modeling Data](/docs/modeling-data) section.

## Query once

Sometimes, you don't want a subscription and just want to fetch data once. For example, you might want to fetch data before rendering a page or check whether a username is available.

In these cases, you can use `queryOnce` instead of `useQuery`. `queryOnce` returns a promise that resolves with the data once the query is complete.

Unlike `useQuery`, `queryOnce` will throw an error if the user is offline. This is because `queryOnce` is intended for use cases where you need the most up-to-date data.

```javascript
const query = { todos: {} };
const { data } = await db.queryOnce(query);
// returns the same data as useQuery, but without the isLoading and error fields
```

You can also do pagination with `queryOnce`:

```javascript
const query = {
  todos: {
    $: {
      limit: 10,
      offset: 10,
    },
  },
};

const { data, pageInfo } = await db.queryOnce(query);
// pageInfo behaves the same as with useQuery
```


# Infinite Queries

How to subscribe to large amounts of data incrementally

It is a common pattern to show users a long list of items that gets larger as they interact. Instant supports this pattern with the `useInfiniteQuery` hook.

The useInfiniteQuery hook is designed to work just like the useQuery hook. You make the same kind of queries, and it returns the same kind of data. But now you get a canLoadNextPage variable and a loadNextPage function to load more items.

## Example

This example demonstrates a typical social media feed where the newest posts are at the top.

```ts
import { init } from '@interface-db/react';
import { db } from "../db"
import { Post } from "../components/Post"

function HomePage() {
  const { data, canLoadNextPage, loadNextPage, isLoading, error } =
    db.useInfiniteQuery({
      posts: {
        $: {
          limit: 50, // Load 50 posts at a time
          order: {
            createdAt: 'desc',
          },
        },
      },
    });

  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      {data.posts.map((post) => (
        <Post key={post.id} post={post} />
      ))}
      {canLoadNextPage && (
        <button onClick={loadNextPage}>Load More</button>
      )}
    </div>
  );
}
```

Any new posts that get created will automatically appear at the top, and as the user scrolls, the `loadNextPage` function can load older posts as needed.

## Reactivity

Just like `useQuery`, all data returned is fully reactive. Updates and deletions will appear immediately. New items added to the "start" of the query will show up automatically, as will items added anywhere in the middle. Items that _would_ be ordered at the very end of the results will show up if the limit for that page has not yet been reached.

For example, with `{todos: {$: {limit: 20, order: createdAt: "asc"}}}` (showing oldest todos first)

If there are already 19 todos in the database, an additional todo getting created will show up in the result automatically, and the next todo after that will set "canLoadNextPage" to true, requiring the `loadNextPage` function to be called.
When the new page is added, any newly created todos will show up at the end automatically until 40 total todos are shown.

Changing any part of the query will result in a full reset of all data, returning back to a state with only one page loaded.

## Vanilla JS

The `@interface-db/core` library also supports making infinite queries with the same syntax as `db.subscribeQuery()`.

Example:

```ts
const { unsubscribe, loadNextPage } = db.subscribeInfiniteQuery(
  {
    posts: {
      $: {
        limit: 20, // Load 20 posts at a time
        order: {
          createdAt: 'desc',
        },
      },
    },
  },
  (resp) => {
    console.log('Posts: ', resp.data.posts);
    console.log('Can Load More ?', resp.canLoadNextPage);
  },
);
```


# Instant on the Backend

How to use Instant on the server with the Admin SDK.

You can use Instant on the server as well! This can be especially useful for
running scripts, custom auth flows, or sensitive application logic.

We currently offer two server-side SDKs:

- **JavaScript:** `@interface-db/admin` — the focus of this page.
- **Python:** `instantdb` — see [Getting started with Python](/docs/start-python)
  for the equivalent surface in Python.

## Admin SDK

`@interface-db/admin` is the JavaScript Admin SDK for using Instant in a
non-browser context. This library is similar to our client SDK with a few
tweaks.

### init

```javascript
import { init, id } from '@interface-db/admin';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({
  appId: APP_ID,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
});
```

As with `@interface-db/react`, you must `init` before doing any queries or
writes. Running `init` authenticates you against our admin API. In addition to
providing your `appId`, you can provide your `adminToken`.



Whereas exposing your `appId` in source control is fine, it's not safe
to expose your `adminToken`. Permission checks will not run for queries and
writes from our admin API. Be sure to regenerate your token from your dashboard
if it accidentally leaks.



## Reading and Writing Data

`query` and `transact` let you read and write data as an admin.

### query

```javascript
const data = await db.query({ goals: {}, todos: {} });
const { goals, todos } = data;
```

In React we use `db.useQuery` to enable "live queries", queries that will
automatically update when data changes.

In the admin SDK we instead use an async `db.query` function that simply fires a
query once and returns a result.

### transact

```typescript 
const res = await db.transact([db.tx.todos[id()].update({ title: 'Get fit' })]);
console.log('New todo entry made for with tx-id', res['tx-id']);
```

`db.transact` is an async function that behaves nearly identically to `db.transact`
from `@interface-db/react`. It returns a `tx-id` on success.

## Subscriptions on the backend

You can use `db.subscribeQuery` to subscribe to queries on the backend. This can be useful if you have backend processes that react to database changes.

For example, let's say we wanted to subscribe to a `tasks` table.

### With callbacks

You could pass in a callback to `db.subscribeQuery` that gets called with newly updated query results:

```typescript 
const sub = db.subscribeQuery({ tasks: { $: { limit: 10 } } }, (payload) => {
  if (payload.type === 'error') {
    console.log('error', error);
    sub.close();
  } else {
    console.log('got data!', payload.data);
  }
});

// When you want to close the subscription:
sub.close();
```

### With async iterator

Or if you prefer, you can skip providing a callback and use async iterators:

```typescript 
const sub = db.subscribeQuery({ tasks: { $: { limit: 10 } } });

for await (const payload of sub) {
  if (payload.type === 'error') {
    console.log('error', error);
    sub.close();
  } else {
    console.log('data', payload.data);
  }
}

// When you want to close the subscription:
sub.close();
```


Subscriptions keep a live connection open on your backend. Be sure to close them when they’re no longer needed to avoid tying up resources unnecessarily.


## Schema

`init` also accepts a schema argument:

```typescript 
import { init, id } from '@interface-db/admin';
import schema from '../instant.schema.ts';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({
  appId: APP_ID,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
  schema,
});
```

If you add a schema, `db.query` and `db.transact` will come with autocompletion and typesafety out of the box. The backend will also use your schema to generate missing attributes.

To learn more about writing schemas, head on over to the [Modeling your data](/docs/modeling-data) section.

## Impersonating users

When you use the admin SDK, you can make _any_ query or transaction. As an admin, you bypass permissions.
But sometimes you want to make queries on behalf of your users and would like to respect permissions.

You can do this with the `db.asUser` function.

```typescript 
// Scope by their email
const scopedDb = db.asUser({ email: 'alyssa_p_hacker@instantdb.com' });
// Or with their auth token
const token = db.auth.createToken({ email: 'alyssa_p_hacker@instantdb.com' });
const scopedDb = db.asUser({ token });
// Or use the db as a guest!
const scopedDb = db.asUser({ guest: true });
// Queries and transactions will run with those permissions
await scopedDb.query({ logs: {} });
```

### Running the admin SDK in client environments

Impersonation can also let you run the Admin SDK _without_ exposing an admin token.

```javascript 
import { init } from '@interface-db/admin';

// If you only impersonate with a user token or as a guest,
// you can _skip_ admin credentials
const db = init({
  appId: process.env.INSTANT_APP_ID!
});

// Pass in a user token to run as a particular user
const userDB = db.asUser({
  token: "...",
});

// Or run as a guest
const guestDB = db.asUser({
  guest: true,
});

// Queries and transactions will work with the respective permissions
await userDB.query({ todos: {} });
await guestDB.query({ publicData: {} });
```

This approach is perfect for places where you need something like the Admin SDK, but don't want to expose admin credentials.

For example, what if you want to run a background daemon on a user's machine? You can't use the client SDK, because you don't need optimistic updates. You wouldn't want to provide the admin token, because this code runs on a user's machine. That's when impersonation really comes in handy.


Without an `adminToken`, you must use `.asUser({ token })` or `asUser({ guest: true })` for all operations. Direct queries and transactions on the base `db` instance will fail, and you won't be able to impersonate with `asUser({ email })`. In protected environments we definitely recommend including the `adminToken`.


## Retrieve a user

As an admin, you can retrieve an app user record by `email`, `id`, or `refresh_token`. You can do this with the `db.auth.getUser` function.

```typescript 
const user = await db.auth.getUser({ email: 'alyssa_p_hacker@instantdb.com' });
const user = await db.auth.getUser({
  id: userId,
});
const user = await db.auth.getUser({
  refresh_token: userRefreshToken,
});
```

## Delete a user

You can also delete an app user record by `email`, `id`, or `refresh_token`. You can do this with the `db.auth.deleteUser` function.

```typescript 
const deletedUser = await db.auth.deleteUser({
  email: 'alyssa_p_hacker@instantdb.com',
});
const deletedUser = await db.auth.deleteUser({
  id: userId,
});
const deletedUser = await db.auth.deleteUser({
  refresh_token: userRefreshToken,
});
```

Note that this _only_ deletes the user record and any associated data with cascade on delete. If there's additional data you need to clean up, you'll need to do it manually:

```typescript 
const { goals, todos } = await db.query({
  goals: { $: { where: { creator: userId } } },
  todos: { $: { where: { creator: userId } } },
});

await db.transact([
  ...goals.map((item) => db.tx.goals[item.id].delete()),
  ...todos.map((item) => tx.todos[item.id].delete()),
]);
// Now we can delete the user
await db.auth.deleteUser({ id: userId });
```

## Presence in the Backend

If you use [rooms & presence](/docs/presence-and-topics), you may want to query for the data currently in a room with the admin API. This can be especially useful if you are sending a notification, for example, and want to skip it if the user is already online.

To get room data from the admin API, use `db.rooms.getPresence`:

```typescript 
const data = await db.rooms.getPresence('chat', 'room-123');
console.log(Object.values(data));
// [{
//     'peer-id': '...',
//     user: { id: '...', email: 'foo@bar.com', ... },
//     data: { typing: true, ... },
//   },
// }];
```

## Sign Out

The `db.auth.signOut` method allows you to log out users. You can log a user out from every session by passing in their `email`, or `id`. Or you can log a user out from a particular session by passing in a `refresh_token`:

```typescript 
// All sessions for this email sign out
await db.auth.signOut({ email: 'alyssa_p_hacker@instantdb.com' });
// All sessions for this user id sign out
const user = await db.auth.signOut({
  id: userId,
});
// Just sign out the session for this refresh token
await db.auth.signOut({
  refresh_token: userRefreshToken,
});
```

## Custom Auth

You can use the Admin SDK to create your own authentication flows. To implement custom auth flows, you would make one change in your backend, and one change in your frontend. Here's how it would look:

### 1. Backend: db.auth.createToken

Create a new `sign-in` endpoint in your backend.

This endpoint will use `db.auth.createToken` to generate an authentication token for the user.

```typescript 
app.post('/sign-in', async (req, res) => {
  // your custom logic for signing users in
  // ...
  // on success, create and return a token
  const token = await db.auth.createToken({ email });
  return res.status(200).send({ token });
});
```

`db.auth.createToken` accepts either an email or a UUID. For the UUID variant:

```typescript 
const token = await db.auth.createToken({ id });
```

If a user with the provided id or email does not exist, `db.auth.createToken` will create the user for you.

### 2. Frontend: db.auth.signInWithToken

Once your frontend calls your `sign-in` endpoint, it can then use the generated token and sign a user in with `db.auth.signInWithToken`.

Here's a full example:

```typescript 
import React, { useState } from 'react';
import { init } from '@interface-db/react';

// Instant app
const APP_ID = "__APP_ID__";
const db = init({ appId: APP_ID });

async function customSignIn(
  email: string,
  password: string
): Promise<{ token: string }> {
  const response = await fetch('your-website.com/api/sign-in', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, password }),
  });
  const data = await response.json();
  return data;
}

function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Uh oh! {error.message}</div>;
  }
  if (user) {
    return <div>Hello {user.email}!</div>;
  }
  return <Login />;
}

function Login() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleEmailChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setEmail(event.target.value);
  };

  const handlePasswordChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setPassword(event.target.value);
  };

  const handleSignIn = async () => {
    const data = await customSignIn(email, password); // initiate your custom sign in flow
    db.auth.signInWithToken(data.token); // sign in with the token on success
  };

  return (
    <div>
      <input
        type="email"
        placeholder="Enter your email"
        value={email}
        onChange={handleEmailChange}
      />
      <input
        type="password"
        placeholder="Enter your password"
        value={password}
        onChange={handlePasswordChange}
      />
      <button onClick={handleSignIn}>Sign In</button>
    </div>
  );
}
```

## Custom magic codes

We support a [magic code flow](/docs/auth) out of the box. However, if you'd like to use your own email provider to send the code, you can do this with the `db.auth.generateMagicCode` function:

```typescript 
app.post('/custom-send-magic-code', async (req, res) => {
  const { code } = await db.auth.generateMagicCode(req.body.email);
  // Now you can use your email provider to send magic codes
  await sendMyCustomMagicCodeEmail(req.body.email, code);
  return res.status(200).send({ ok: true });
});
```

You can also use Instant's default email provider to send a magic code with `db.auth.sendMagicCode`:

```typescript 
// You can trigger a magic code email in your backend with `sendMagicCode`
const { code } = await db.auth.sendMagicCode(req.body.email);
```

Similarly, you can verify a magic code with `db.auth.checkMagicCode`. You can pass `extraFields` to set custom `$users` properties when the user is first created. The response includes a `created` boolean so you can distinguish new users from returning ones.

```typescript 
const { user, created } = await db.auth.checkMagicCode(
  req.body.email,
  req.body.code,
  { extraFields: { nickname: req.body.nickname } },
);
const token = user.refresh_token;

if (created) {
  // first-time signup
}
```

## Authenticated Endpoints

You can also use the Admin SDK to authenticate users in your custom endpoints. This would have two steps:

### 1. Frontend: user.refresh_token

In your frontend, the `user` object has a `refresh_token` property. You can pass this token to your endpoint:

```javascript
// client
import { init } from '@interface-db/react';

const db = init(/* ... */)

function App() {
  const { user } = db.useAuth();
  // call your api with `user.refresh_token`
  function onClick() {
    myAPI.customEndpoint(user.refresh_token, ...);
  }
}
```

### 2. Backend: auth.verifyToken

You can then use `auth.verifyToken` to verify the `refresh_token` that was passed in.

```typescript 
app.post('/custom_endpoint', async (req, res) => {
  // verify the token this user passed in
  const user = await db.auth.verifyToken(req.headers['token']);
  if (!user) {
    return res.status(401).send('Uh oh, you are not authenticated');
  }
  // ...
});
```

### Syncing Auth

Sometimes you want to get the logged in user in the backend without needing to explicitly pass in the refresh token from the frontend. Here's how you can do it.

Instant provides a `createInstantRouteHandler` function that generates a web standard endpoint that can be used to sync the refresh token to a cookie that your server can read.

To use it in Next.js:

```typescript 
// src/app/api/instant/route.ts
import { createInstantRouteHandler } from '@interface-db/react/nextjs';

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});
```

The GET and POST functions accept a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Request), so they should be able to be used in any framework.

Then, provide your mounted API URL to the `init` function.

```typescript 
import { init } from '@interface-db/react';

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  firstPartyPath: '/api/instant', // the endpoint that you registered the route handler at.
  schema,
  useDateObjects: true,
});
```

If using Next.js, you can call getUnverifiedUserFromInstantCookie with the app ID to retrieve the user in any server component or route handler.

```typescript
import { getUnverifiedUserFromInstantCookie } from "@interface-db/react/nextjs";

// This is a server component!
export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  // Get the instant user from the cookie
  const user = await getUnverifiedUserFromInstantCookie(process.env.NEXT_PUBLIC_INSTANT_APP_ID!);

  return (
    <html lang="en">
      <body>
        <AuthProvider user={user}>{children}</AuthProvider>
      </body>
    </html>
  );
}
```


# Patterns

Common patterns for working with InstantDB.

Below are some common patterns for working with InstantDB. We'll add more
patterns over time, and if you have a pattern you'd like to share, please feel
free to submit a PR for this page.

## You can expose your app id to the client.

As with Firebase, the app id is a unique identifier for your application.
If you want to secure your data, you'll want to add
[permissions](/docs/permissions) for the app.

## Restrict creating new attributes.

When you're ready to lock down your schema, you can restrict creating a new
attribute by adding this to your app's [permissions](/dash?t=perms)

```json
{
  "attrs": { "allow": { "$default": "false" } }
}
```

This will prevent any new attributes from being created.

## Attribute level permissions

When you query a namespace, it will return all the attributes for an entity.
You can use the [`fields`](/docs/instaql#select-fields) clause to restrict which attributes
are returned from the server, but this will not prevent a client from doing
another query to get the full entity.

You can set special permission rules for [`fields`](/docs/instaql#select-fields) to make sure only certain attributes
are visible to certain users.

## Find entities with no links.

If you want to find entities that have no links, you can use the `$isNull`
query filter. For example, if you want to find all posts that are not linked to
an author, you can do the following:

```javascript
const { isLoading, error, data } = db.useQuery({
  posts: {
    $: {
      where: {
        'author.id': {
          $isNull: true,
        },
      },
    },
  },
});
```

## Setting limits via permissions.

If you want to limit the number of entities a user can create, you can do so via
permissions. Here's an example of limiting a user to creating at most 2 todos.

First the [schema](/docs/modeling-data):

```typescript
// instant.schema.ts
// Here we define users, todos, and a link between them.
import { i } from '@interface-db/core';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    todos: i.entity({
      label: i.string(),
    }),
  },
  links: {
    userTodos: {
      forward: {
        on: 'todos',
        has: 'one',
        label: 'owner',
      },
      reverse: {
        on: '$users',
        has: 'many',
        label: 'ownedTodos',
      },
    },
  },
});

// This helps TypeScript display nicer IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Then the [permissions](/docs/permissions):

```typescript
import type { InstantRules } from '@interface-db/react';
// instant.perms.ts
// And now we reference the `owner` link for todos to check the number
// of todos a user has created.
// (Note): Make sure the `owner` link is already defined in the schema
// before you reference it in the permissions.
const rules = {
  todos: {
    allow: {
      create: "size(data.ref('owner.ownedTodos.id')) <= 2",
    },
  },
} satisfies InstantRules;

export default rules;
```

## Listen to InstantDB connection status.

Sometimes you want to let clients know when they are connected to or disconnected
from the DB. You can use `db.subscribeConnectionStatus` in vanilla JS or
`db.useConnectionStatus` in React to listen to connection changes.

```javascript
// Vanilla JS
const unsub = db.subscribeConnectionStatus((status) => {
  const statusMap = {
    connecting: 'authenticating',
    opened: 'authenticating',
    authenticated: 'connected',
    closed: 'closed',
    errored: 'errored',
  };

  const connectionState = statusMap[status] || 'unexpected state';
  console.log('Connection status:', connectionState);
});

// React/React Native
function App() {
  const statusMap = {
    connecting: 'authenticating',
    opened: 'authenticating',
    authenticated: 'connected',
    closed: 'closed',
    errored: 'errored',
  };
  const status = db.useConnectionStatus();

  const connectionState = statusMap[status] || 'unexpected state';
  return <div>Connection state: {connectionState}</div>;
}
```

## Using Instant via CDN

If you have a plain html page or avoid using a build step, you can use InstantDB
via a CDN through [unpkg](https://www.unpkg.com/@interface-db/core/).

```jsx 
<!-- Load Instant via unpkg -->
<!-- Consider replacing @latest with a specific package -->
<script src="https://www.unpkg.com/@interface-db/core@latest/dist/standalone/index.umd.cjs"></script>

<!-- Use Instant like normal -->
<script>
  const { init, id } = instant;
  // Instant app
  const APP_ID = '__APP_ID__';
  const db = init({ appId: APP_ID });

  async function createMessage() {
    await db.transact(
      db.tx.messages[id()].update({
        text: 'Hello world!'
      })
    );
  }
</script>
```

## Making Local ids

Sometimes you need an identifier that stays the same between refreshes. A "local id" of sorts.

Local ids are especially useful for features like "guest" mode. You need an identifier for the user who is accessing the service, but they haven't signed up yet. Well, you can use a `localId` for that. To generate one, use `db.getLocalId`:

```js
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

const id = await db.getLocalId('guest');

console.log(id, 'stays the same even if you refresh');
```

Or a handy hook if you're inside React:

```js
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  const id = db.useLocalId('guest');
  if (!id) return;
  console.log(id, 'stays the same even if you refresh');
}
```

Note: passing in different arguments will produce different ids:

```js
const id1 = db.useLocalId('device');
const id2 = db.useLocalId('session');
console.log(
  id1,
  id2,
  'are different. But each will stay the same even if you refresh',
);
```

Once you have an ID, you can pass it around in your transactions and queries and use it in [ruleParams](/docs/permissions#rule-params).

## Making admin queries work with Next.js caching

Next.js caches fetch requests and lets you revalidate them. [`adminDB.query`](/docs/backend#query) uses fetch under the hood, so Next.js caching will work by default.

If you want to finely control how the query caches, you can pass in the same kind of [fetch options](https://nextjs.org/docs/app/building-your-application/caching#fetch) for Next.js. For example, to revalidate a query every hour:

```js
await adminDB.query(
  { goals: {} },
  {
    fetchOpts: {
      next: { revalidate: 3600 },
    },
  },
);
```

Or to set a specific tag:

```js
await adminDB.query(
  { goals: {} },
  {
    fetchOpts: {
      next: { tags: ['goals:all'] },
    },
  },
);
```

## Composite keys

Sometimes an item is unique by two or more attributes. For example, consider a `location`: it's unique by `latitude` _and_ `longitude`.

How can you enforce this uniqueness in Instant?

We don't have composite keys built-in, but you can manage them by creating a composite column. For example, you can make sure `locations` are unique by adding a `latLong` column:

```js
import { i } from '@interface-db/core';
const _schema = i.schema({
  entities: {
    // ...
    locations: i.entity({
      latitude: i.number().indexed(),
      longitude: i.number().indexed(),
      latLong: i.string().unique() // <-- our composite column
    }),
  },
```

We can then set `latLong` in our updates:

```js
function createLocation({ latitude, longitude }) {
  db.transact(
    db.tx.locations[id()].update({
      latitude,
      longitude,
      latLong: `${latitude}_${longitude}`,
    }),
  );
}
```

Now, any locations with the same latitude and longitude will throw a uniqueness error.

To make sure that `latLong` _always_ matches `latitude` and `longitude`, you can add a rule in your permissions:

```js
const rules = {
  locations: {
    allow: {
      create: "(data.latitude + '_' + data.longitude) == data.latLong",
      update: "(newData.latitude + '_' + newData.longitude) == newData.latLong",
    },
  },
};
```

## Managing local vs production apps

You may want to have separate Instant apps for local development and production.
The way to do this right now is to have two separate apps, one for local and one
for production.

```javascript
// lib/db.ts
import { init } from '@interface-db/react';

const APP_ID = process.env.NEXT_PUBLIC_INSTANT_APP_ID;

export const db = init({ appId: APP_ID });
```

Then in your environment files:

```bash
# .env.local
NEXT_PUBLIC_INSTANT_APP_ID=your-local-app-id

# .env.production
NEXT_PUBLIC_INSTANT_APP_ID=your-production-app-id
```

When developing new features that require schema or permission changes, you can
follow this workflow:

1. **Push schema/perms changes locally first**

   ```bash
   npx @interface-db/cli push --app your-local-app-id
   ```

2. **Test code changes** - Verify your new code works as expected with your changes in your local environment and app.

3. **Push changes to production**

   ```bash
   npx @interface-db/cli push --app your-production-app-id
   ```

4. **Deploy code changes to prod!** - And that should be it!

## Dealing with timeouts

Complicated queries or large transactions may fail due to timeouts. Right now we
have a hard limit of 5 seconds for both queries and transactions. We do this to
ensure realtime updates don't suffer from long-running operations.

To get a sense for how long a query or transaction takes, you can use the
`Sandbox` tab in the dashboard. Using `await db.query` or `await db.transact` will
show you the time it took to run the operation in the console. Queries and
transactions in the sandbox can run for up to 30 seconds.

Once you have a sense of how long your queries and transactions take, you can
iteratively optimize them. For example, you can use pagination or add indexes
to speed up queries, or break up large transactions into smaller ones.

## Setting default values when making an attribute required

When converting an optional attribute to a required one, you'll need to
update existing entities with null values.

For example, if you try to make `done` required on `todos` but some
records have null values:

```
INVALID DATA adding required constraint to todos.done.
  First few examples:
  namespace       | id                                    | done
  ----------------|---------------------------------------|------
  todos           | 13a09c93-cee0-4e21-9e41-c7e08edd1649  | null
  todos           | 043eec60-d971-4689-8e4a-099e82c251a2  | null
```

The solution is to run an admin script to backfill the null values before pushing the schema change.

```typescript
// scripts/backfill-todos.ts
import { init, tx } from '@interface-db/admin';

const db = init({
  appId: process.env.INSTANT_APP_ID!,
  adminToken: process.env.INSTANT_ADMIN_TOKEN!,
});

async function backfillDefaults() {
  // Query for entities with null/missing done
  const { data } = await db.query({
    todos: {
      $: {
        where: {
          done: { $isNull: true },
        },
      },
    },
  });

  // Update them with a default value
  const updates = data.todos.map((todo) =>
    tx.todos[todo.id].update({ done: false }),
  );

  if (updates.length > 0) {
    await db.transact(updates);
    console.log(`Backfilled ${updates.length} records`);
  } else {
    console.log('No records to backfill');
  }
}

backfillDefaults();
```

Then run the script before pushing your schema:

```bash
npx tsx scripts/backfill-todos.ts && npx @interface-db/cli push
```

This pattern gives you full control over setting default values. You can set
static values as shown above, or use more complex logic to determine the default
based on other attributes.


# Auth

Instant supports magic code, OAuth, Clerk, and custom auth.

Instant comes with support for auth. We currently offer [Magic Codes](/docs/auth/magic-codes), [Guest Auth](/docs/auth/guest-auth), [Google OAuth](/docs/auth/google-oauth), [Sign In with Apple](/docs/auth/apple), [GitHub OAuth](/docs/auth/github-oauth), [LinkedIn OAuth](/docs/auth/linkedin-oauth), and [Clerk](/docs/auth/clerk). If you want to build your own flow, you can use the [Admin SDK](/docs/backend#custom-auth).

## Auth Overview

To get the current user in your application, you can use the `db.useUser` hook.

```tsx
import db from '../lib/db';

function Dashboard() {
  const user = db.useUser();

  return <div>Signed in as: {user.email}</div>;
}
```

The `useUser` hook will throw an error if it is accessed while the user is not logged in, so it should be gated behind `<db.SignedIn>`.

```tsx
import db from '../lib/db';

export default function App() {
  return (
    <div>
      <db.SignedIn>
        <Dashboard />
      </db.SignedIn>
      <db.SignedOut>
        <div>Log in to see the dashboard!</div>
      </db.SignedOut>
    </div>
  );
}

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

  return <div>Signed in as: {user.email}</div>;
}
```

Use `<db.SignedIn>` and `<db.SignedOut>` to conditionally render components
based on the user's authentication state.

You can then use `db.auth.signOut()` to sign a user out.

```tsx
import db from '../lib/db';

// ... Same app component from above

function Dashboard() {
  const user = db.useUser();

  return (
    <div>
      <div>Signed in as: {user.email}</div>
      <button onClick={() => db.auth.signOut()}>Sign out</button>
    </div>
  );
}
```

Putting it all together, you can conditionally render a login and dashboard component
like so:

```tsx
import db from '../lib/db';

export default function App() {
  return (
    <div>
      <db.SignedIn>
        <Dashboard />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </div>
  );
}

function Dashboard() {
  // This component will only render if the user is signed in
  // so it's safe to call useUser here!
  const user = db.useUser();

  return <div>Signed in as: {user.email}</div>;
}

function Login() {
  // Implement a login flow here via magic codes, OAuth, Clerk, etc.
}
```

To implement a login flow, use one of the authentication method guides below.

## Authentication Methods


- [Magic Codes](/docs/auth/magic-codes): Send login codes to your users via email. Removes the need for passwords.
- [Guest Auth](/docs/auth/guest-auth): Allow your users to try your app before they sign up.
- [Google OAuth](/docs/auth/google-oauth): We provide flows for Web and React Native to enable Google OAuth for your app.
- [Sign In with Apple](/docs/auth/apple): Sign In to native apps with Apple ID.
- [GitHub OAuth](/docs/auth/github-oauth): Log in with GitHub on both Web and React Native.
- [LinkedIn OAuth](/docs/auth/linkedin-oauth): Log in with LinkedIn on both Web and React Native.
- [Clerk](/docs/auth/clerk): Integrate Clerk's auth flow with Instant.
- [Firebase Auth](/docs/auth/firebase): Integrate Firebase's auth flow with Instant.
- [Custom Auth](/docs/backend#custom-auth): Integrate your own auth flow with the Admin SDK.



## Additional Auth APIs

Sometimes you need finer control over the state of auth in your application. In those cases, you can use some of the lower-level APIs.

### useAuth

Use `useAuth` to fetch the current user. In this example we guard against loading
our `Main` component until a user is logged in:

```javascript
function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return null; // or a loading spinner
  }
  if (error) {
    return <div className="p-4 text-red-500">Uh oh! {error.message}</div>;
  }
  if (user) {
    return <Main />;
  }
  return <Login />;
}
```

### Get auth

For scenarios where you want to know the current auth state without subscribing
to changes, you can use `getAuth`.

```javascript
const user = await db.getAuth();
console.log('logged in as', user.email);
```

### Setting custom properties at signup

If you want to set custom properties on `$users` at signup time, see [Setting properties at signup](/docs/users#setting-properties-at-signup).


# Magic Code Auth

How to add magic code auth to your Instant app.



Instant supports a "magic-code" flow for auth. Users provide their email, we send
them a login code on your behalf, and they authenticate with your app.

Choose the platform you're building for to see a full example.



- **Web**: For Next.js or other React frameworks
- **Mobile**: For Expo and React Native
- **Vanilla JS**: For non-React-based frameworks



## Full Magic Code Example



Here's a full example of magic code auth in a React app. Open up your `app/page.tsx` file, and replace the entirety of it with the following code:

```tsx 
'use client';

import React, { useState } from 'react';
import { init } from '@interface-db/react';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <Main />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function Main() {
  const user = db.useUser();
  return (
    <div className="space-y-4 p-4">
      <h1 className="text-2xl font-bold">Hello {user.email}!</h1>
      <button
        onClick={() => db.auth.signOut()}
        className="bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Sign out
      </button>
    </div>
  );
}

function Login() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
      </div>
    </div>
  );
}

function EmailStep({ onSendEmail }: { onSendEmail: (email: string) => void }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const email = inputEl.value;
    onSendEmail(email);
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh :' + err.body?.message);
      onSendEmail('');
    });
  };
  return (
    <form
      key="email"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Let's log you in</h2>
      <p className="text-gray-700">
        Enter your email, and we'll send you a verification code. We'll create
        an account for you too if you don't already have one.
      </p>
      <input
        ref={inputRef}
        type="email"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="Enter your email"
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Send Code
      </button>
    </form>
  );
}

function CodeStep({ sentEmail }: { sentEmail: string }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const code = inputEl.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      inputEl.value = '';
      alert('Uh oh :' + err.body?.message);
    });
  };

  return (
    <form
      key="code"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Enter your code</h2>
      <p className="text-gray-700">
        We sent an email to <strong>{sentEmail}</strong>. Check your email, and
        paste the code you see.
      </p>
      <input
        ref={inputRef}
        type="text"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="123456..."
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Verify Code
      </button>
    </form>
  );
}

export default App;
```





Here's a full example of magic code auth in a React Native app. Open up your `app/index.tsx` file, and replace the entirety of it with the following code:

```tsx 
import React, { useState } from 'react';
import { View, Text, TextInput, Button, Alert, StyleSheet } from 'react-native';
import { init } from '@interface-db/react-native';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  const { isLoading, user, error } = db.useAuth();
  if (isLoading) {
    return <Text>Loading...</Text>;
  }
  if (error) {
    return <Text>Uh oh! {error.message}</Text>;
  }
  if (user) {
    return <Main />;
  }
  return <Login />;
}

function Main() {
  const user = db.useUser();
  return (
    <View style={styles.container}>
      <Text style={styles.header}>Hello {user.email}!</Text>
      <Button title="Sign Out" onPress={() => db.auth.signOut()} />
    </View>
  );
}

function Login() {
  const [sentEmail, setSentEmail] = useState('');
  const [email, setEmail] = useState('');
  const [code, setCode] = useState('');

  if (!sentEmail) {
    return (
      <View style={styles.container}>
        <Text style={styles.title}>Let's log you in!</Text>
        <TextInput
          placeholder="Enter your email"
          value={email}
          onChangeText={setEmail}
          style={styles.input}
        />
        <Button
          title="Send Code"
          onPress={() => {
            setSentEmail(email);
            db.auth.sendMagicCode({ email }).catch((err) => {
              Alert.alert('Uh oh', err.body?.message);
              setSentEmail('');
            });
          }}
        />
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Enter your code</Text>
      <Text>
        We sent an email to {sentEmail}. Check your email, and enter the code
        you see.
      </Text>
      <TextInput
        placeholder="123456..."
        value={code}
        onChangeText={setCode}
        style={styles.input}
      />
      <Button
        title="Verify Code"
        onPress={() => {
          db.auth
            .signInWithMagicCode({ email: sentEmail, code })
            .catch((err) => {
              Alert.alert('Uh oh', err.body?.message);
              setCode('');
            });
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 16,
  },
  header: {
    fontSize: 24,
    fontWeight: 'bold',
  },
  title: {
    fontSize: 20,
    fontWeight: 'bold',
  },
  input: {
    borderWidth: 1,
    borderColor: '#ccc',
    padding: 8,
    marginVertical: 8,
  },
});

export default App;
```





Here's a full example of magic code auth with vanilla JavaScript. Open up your `src/main.ts` file, and replace the entirety of it with the following code:

```typescript 
import { init, type User } from '@interface-db/core';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

const app = document.getElementById('app')!;

let sentEmail = '';

function renderApp(user: User | undefined) {
  if (user) {
    renderMain(user);
  } else {
    renderLogin();
  }
}

function renderMain(user: User) {
  app.innerHTML = `
    <div>
      <h1>Hello ${user.email}!</h1>
      <button id="sign-out">Sign out</button>
    </div>
  `;
  document.getElementById('sign-out')!.addEventListener('click', () => {
    db.auth.signOut();
  });
}

function renderLogin() {
  if (!sentEmail) {
    renderEmailStep();
  } else {
    renderCodeStep();
  }
}

function renderEmailStep() {
  app.innerHTML = `
    <div>
      <h2>Let's log you in</h2>
      <p>
        Enter your email, and we'll send you a verification code.
        We'll create an account for you too if you don't already have one.
      </p>
      <form id="email-form">
        <input
          id="email-input"
          type="email"
          placeholder="Enter your email"
          required
        />
        <button type="submit">Send Code</button>
      </form>
    </div>
  `;
  document.getElementById('email-form')!.addEventListener('submit', (e) => {
    e.preventDefault();
    const email = (document.getElementById('email-input') as HTMLInputElement)
      .value;
    sentEmail = email;
    renderLogin();
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh: ' + err.body?.message);
      sentEmail = '';
      renderLogin();
    });
  });
}

function renderCodeStep() {
  app.innerHTML = `
    <div>
      <h2>Enter your code</h2>
      <p>
        We sent an email to <strong>${sentEmail}</strong>.
        Check your email, and paste the code you see.
      </p>
      <form id="code-form">
        <input
          id="code-input"
          type="text"
          placeholder="123456..."
          required
        />
        <button type="submit">Verify Code</button>
      </form>
    </div>
  `;
  document.getElementById('code-form')!.addEventListener('submit', (e) => {
    e.preventDefault();
    const codeInput = document.getElementById('code-input') as HTMLInputElement;
    const code = codeInput.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      alert('Uh oh: ' + err.body?.message);
      codeInput.value = '';
    });
  });
}

db.subscribeAuth((auth) => {
  renderApp(auth.user);
});
```

Make sure you have a `<div id="app"></div>` element in your HTML.



---

**Let's dig deeper.**

We created a login flow to handle magic code auth. Of note are `auth.sendMagicCode`
and `auth.signInWithMagicCode`.

On successful validation, Instant's backend will return a user object with a refresh token.
The client SDK will then restart the WebSocket connection with Instant's sync layer and provide the refresh token.

When doing queries or transactions, the refresh token will be used to hydrate `auth`
on the backend during permission checks.

On the client, auth will now be populated with a `user` -- huzzah!

## Send a Magic Code

```javascript
db.auth.sendMagicCode({ email }).catch((err) => {
  alert('Uh oh :' + err.body?.message);
  onSendEmail('');
});
```

Use `auth.sendMagicCode` to generate a magic code on Instant's backend and email it to the user.

## Sign in with Magic Code

```javascript
db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
  inputEl.value = '';
  alert('Uh oh :' + err.body?.message);
});
```

You can then use `auth.signInWithMagicCode` to authenticate the user with the magic code they provided.

## Setting properties at signup

Pass `extraFields` to `signInWithMagicCode` to set custom `$users` properties when a user is first created. Fields are only written on first signup; returning users are unaffected.

```javascript
const { user, created } = await db.auth.signInWithMagicCode({
  email: sentEmail,
  code,
  extraFields: { nickname: 'nezaj' },
});

if (created) {
  // Scaffold default data for new users
  db.transact([
    db.tx.settings[id()].update({ theme: 'light' }).link({ user: user.id }),
  ]);
}
```

The fields must be defined as optional attributes on `$users` in your schema. A `create` rule on `$users` is also required. See [Setting properties at signup](/docs/users#setting-properties-at-signup) for the full guide.

## Test users

If you need to create a user with a pre-defined code for app store review or testing, you can assign a magic code to an email from the Auth page of the Dashboard.

When a test user signs in, they can use the static code instead of receiving the code in an email. The static code will never expire and will always be valid until it is deleted from the dashboard.




# Guest Auth

Let your users try your app before creating an account

Instant supports guest authentication. This allows your users to try your app before signing up and ensures they can keep all their data when they decide to create a full account with their email.

## Signing in as a Guest

Use `db.auth.signInAsGuest()` to create a new guest user. This will create a new guest user with an ID but no email address.

You can set custom `$users` properties when creating the guest by passing `extraFields`:

```javascript
db.auth.signInAsGuest({
  extraFields: { nickname: 'nezaj' },
});
```

The fields must be optional attributes on `$users`, and `$users` must have a `create` rule. See [Setting properties at signup](/docs/users#setting-properties-at-signup) for details.

```tsx 
'use client';

import React, { useState } from 'react';
import { init, User } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <Main />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function Main() {
  const user = db.useUser();
  return (
    <div className="space-y-4 p-4">
      <h1 className="text-2xl font-bold">
        Hello {user.isGuest ? 'Guest' : user.email}!
      </h1>
      <button
        onClick={() => db.auth.signOut()}
        className="bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Sign out
      </button>
    </div>
  );
}

function Login() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        <button
          onClick={() => db.auth.signInAsGuest()}
          className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
        >
          Sign in as Guest
        </button>
      </div>
    </div>
  );
}

export default App;
```

## Upgrading to a full user

When a guest user is ready to create a permanent account, you can use any of Instant's sign-in methods. The guest user will be automatically upgraded to a full user.

Here is a full example using magic code auth:

```tsx 
'use client';

import React, { useState } from 'react';
import { init, User } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <Main />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function Main() {
  const user: User = db.useUser();
  return (
    <div className="space-y-4 p-4">
      <h1 className="text-2xl font-bold">
        Hello {user.isGuest ? 'Guest' : user.email}!
      </h1>
      <button
        onClick={() => db.auth.signOut()}
        className="bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Sign out
      </button>
      {user.isGuest && <Upgrade />}
    </div>
  );
}

function Upgrade() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
      </div>
    </div>
  );
}

function Login() {
  const [sentEmail, setSentEmail] = useState('');

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="max-w-sm">
        {!sentEmail ? (
          <EmailStep onSendEmail={setSentEmail} />
        ) : (
          <CodeStep sentEmail={sentEmail} />
        )}
        <button
          onClick={() => {
            db.auth
              .signInAsGuest()
              .catch((err) => alert('Uh oh: ' + err.body?.message));
          }}
          className="mt-4 w-full bg-gray-600 px-3 py-1 font-bold text-white hover:bg-gray-700"
        >
          Try before signing up
        </button>
      </div>
    </div>
  );
}

function EmailStep({ onSendEmail }: { onSendEmail: (email: string) => void }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const email = inputEl.value;
    onSendEmail(email);
    db.auth.sendMagicCode({ email }).catch((err) => {
      alert('Uh oh :' + err.body?.message);
      onSendEmail('');
    });
  };
  return (
    <form
      key="email"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Let's log you in</h2>
      <p className="text-gray-700">
        Enter your email, and we'll send you a verification code. We'll create
        an account for you too if you don't already have one.
      </p>
      <input
        ref={inputRef}
        type="email"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="Enter your email"
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Send Code
      </button>
    </form>
  );
}

function CodeStep({ sentEmail }: { sentEmail: string }) {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const inputEl = inputRef.current!;
    const code = inputEl.value;
    db.auth.signInWithMagicCode({ email: sentEmail, code }).catch((err) => {
      inputEl.value = '';
      alert('Uh oh :' + err.body?.message);
    });
  };

  return (
    <form
      key="code"
      onSubmit={handleSubmit}
      className="flex flex-col space-y-4"
    >
      <h2 className="text-xl font-bold">Enter your code</h2>
      <p className="text-gray-700">
        We sent an email to <strong>{sentEmail}</strong>. Check your email, and
        paste the code you see.
      </p>
      <input
        ref={inputRef}
        type="text"
        className="w-full border border-gray-300 px-3 py-1"
        placeholder="123456..."
        required
        autoFocus
      />
      <button
        type="submit"
        className="w-full bg-blue-600 px-3 py-1 font-bold text-white hover:bg-blue-700"
      >
        Verify Code
      </button>
    </form>
  );
}

export default App;
```

## Handling conflicting users

If a guest user signs up with an email that is not already associated with an existing account, their user `id` remains the same, and they retain access to all data they created as a guest.

However, if a user with that email already exists, the guest user's data may need to be merged.

You can fetch the list of guest users for a user with this query:

```ts
const query = {
  $users: {
    $: {
      where: {
        linkedPrimaryUser: user.id,
      },
    },
  },
};
```

The linked guest users are also available on the user itself:

```ts
const query = {
  $users: {
    $: {
      where: {
        id: user.id,
      },
      linkedGuestUsers: {},
    },
  },
};
```

You can then query for the data owned by those guest users and transfer it to the primary account. The specific implementation will depend on your application's data model.

To enable your user to access the data stored by the guest users, you can update your rules to grant access:

```diff
{
  "todos": {
   "bind": [
    "isOwner", "data.owner == auth.id",
+   "isGuestOwner", "data.owner in auth.ref('$user.linkedGuestUsers.id')"
   ],
    "allow": {
-     "view": "isOwner",
+     "view": "isOwner || isGuestOwner",
      "create": "isOwner",
-     "update": "isOwner",
+     "update": "isOwner || isGuestOwner",
      "delete": "isOwner"
    }
  }
}
```

Here's an example of how you might transfer `todos` from a guest account to the primary user:

```ts
function App() {
  const user = db.useUser();

  useEffect(() => {
    if (user.isGuest) return;

    const transferGuestData = async () => {
      // Get the linked guest user
      const {
        data: { $users },
      } = await db.queryOnce({
        $users: {
          $: {
            where: { linkedPrimaryUser: user.id },
            limit: 1,
            order: { serverCreatedAt: desc },
          },
        },
      });
      const guestId = $users[0]?.id;
      if (!guestId) return;

      // Get the data for the guest user
      const {
        data: { todos },
      } = await db.queryOnce({
        todos: {
          $: {
            where: { owner: guestId },
          },
        },
      });
      if (!todos.length) return;

      // Update owner on all of the guest's todo entities
      const txes = todos.map((todo) =>
        db.tx.todos[todo.id].update({ owner: user.id }),
      );
      await db.transact(txes);
    };

    transferGuestData();
  }, [user]);
}
```


# Google OAuth

How to add Google OAuth to your Instant app.



Instant supports logging users in with their Google account. There are a few ways to do this: it depends on whether you are building for web or React Native.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with Google to your app.




**Building for Web?**

- **Google Button**: Use Google's pre-styled button to sign in. This is what Google recommends.
- **Web Redirect**: Easier to integrate but requires a redirect rule to render your custom app name.



**Building for React Native?**

- **Native Auth**: Use react-native-google-signin to integrate with the native Google iOS and Android flows and render your custom app name in the consent screen.
- **Expo Web Auth**: Use Expo's auth session to integrate browser-based sign-in. Easier to implement, but doesn't let you render your custom app name.





## Overview

There are three main steps:

1. **Google Console**: Set up your consent screen and create an OAuth client.
2. **Instant Dashboard**: Connect your OAuth client to Instant
3. **Your app**: Add some code to log in with Google!

Let's dive deeper into each step:



## Quick start: developer credentials

If you're testing Google sign-in locally, we have a fast option for you. Instant provides developer credentials that you can use for local development.

You don't need to go to the Google Cloud Console, and you can log in within minutes.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Set up Google"
- Toggle "Use dev credentials"
- Give your client a name (e.g. `google-web`)
- Click "Add Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type google --app-type web --name google-web --dev-credentials
```





**And you're done. You can go [straight to code](#3-add-some-code).**



Developer credentials are meant only for local development. You're limited to 100 sign-ups. Once you're ready for production, follow the steps below.





## 1. Set up your consent screen and create an OAuth client

Head on over to [Google Console](https://console.cloud.google.com/apis/credentials). You should be in the "Credentials" section.

**Configure your Google OAuth consent screen**

- Click "CONFIGURE CONSENT SCREEN." If you already have a consent screen, you can skip to the next step.
- Select "External" and click "CREATE".
- Add your app's name, a support email, and developer contact information. Click "Save and continue".
- No need to add scopes or test users. Click "Save and continue" for the next screens. Until you reach the "Summary" screen, click "Back to dashboard".

**Create an OAuth client for Google**

<!-- prettier-ignore-start -->



- From Google Console, click "+ CREATE CREDENTIALS"
- Select "OAuth client ID"
- Select "Web application" as the application type.

- Add `https://api.interfacedb.com/runtime/oauth/callback` as an Authorized redirect URI.

- If you're testing from localhost, **add both `http://localhost`** and `http://localhost:3000` to "Authorized JavaScript origins", replacing `3000` with the port you use.
- For production, add your website's domain.

<!-- prettier-ignore-end -->

And with that you have your OAuth client!



Save your Client ID and your Client Secret -- you'll need them for the next step!







For native auth, each platform needs an OAuth Client. If you support both iOS and Android, for example, you'll create two clients. Here are the steps:

- From Google Console, click "+ CREATE CREDENTIALS"
- Select "OAuth client ID"
- Select "iOS" or "Android" as the application type.
- Fill in your bundle information.

And with that you're ready!



Save your Client IDs -- you'll need them for the next step!





## 2. Connect your OAuth client to Instant



**Add your OAuth Client on Instant**



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Set up Google"
- Enter your "Client ID"
- Enter your "Client Secret"
- Check "I added the redirect to Google" (make sure you actually did this!)
- Click "Add Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type google --app-type web --name google-web \
  --client-id <id> --client-secret <secret>
```









**Register your website with Instant**

If you're testing from localhost, add `http://localhost:3000` (replacing `3000` with the port you use). For production, add your website's domain.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add your URL to the **Redirect Origins** list.



**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type website --url <your-domain>
```









**Add your OAuth Client on Instant**

For each OAuth Client you created, add it to Instant:



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Set up Google"
- Enter your "Client ID"
- Click "Add Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type google --app-type ios --name google-ios --client-id <ios-id>
npx @interface-db/cli@latest auth client add \
  --type google --app-type android --name google-android --client-id <android-id>
```







## 3. Add some code!



**Method: Google Sign in Button for Web**

We'll use [Google's pre-built Sign in Button](https://developers.google.com/identity/gsi/web/guides/overview). The benefit of using Google's button is that you can display your app's name in the consent screen.

There are two steps to the code:

1. Use the Sign in Button to auth with Google and get an `idToken`
2. Pass the token on to `db.auth.signInWithIdToken`, and you are logged in!

Let's do that.

**Using React**

If you're using React, the easiest way to include the Sign in Button is through the [@react-oauth/google](https://github.com/MomenSherif/react-oauth) package:

```shell
npm install @react-oauth/google
```

Once you install it, include the button, and use `db.auth.signInWithIdToken` to complete sign in. Here's a full example:

```jsx 
'use client';

import React, { useState } from 'react';
import { init } from '@interface-db/react';
import { GoogleOAuthProvider, GoogleLogin } from '@react-oauth/google';

const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

// e.g. 89602129-cuf0j.apps.googleusercontent.com
const GOOGLE_CLIENT_ID = 'REPLACE_ME';

// Use the google client name in the Instant dashboard auth tab
const GOOGLE_CLIENT_NAME = 'REPLACE_ME';

function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}

function Login() {
  const [nonce] = useState(crypto.randomUUID());

  return (
    <GoogleOAuthProvider clientId={GOOGLE_CLIENT_ID}>
      <GoogleLogin
        nonce={nonce}
        onError={() => alert('Login failed')}
        onSuccess={({ credential }) => {
          db.auth
            .signInWithIdToken({
              clientName: GOOGLE_CLIENT_NAME,
              idToken: credential,
              // Make sure this is the same nonce you passed as a prop
              // to the GoogleLogin button
              nonce,
            })
            .catch((err) => {
              alert('Uh oh: ' + err.body?.message);
            });
        }}
      />
    </GoogleOAuthProvider>
  );
}
```

**Not using React?**

If you're not using React or prefer to embed the button yourself, refer to [Google's docs](https://developers.google.com/identity/gsi/web/guides/overview) on how to create the button and load their client library.

When creating your button, make sure to set the `data-ux_mode="popup"`. Your `data-callback` function should look like:

```jsx 
async function handleSignInWithGoogle(response) {
  await db.auth.signInWithIdToken({
    // Use the google client name in the Instant dashboard auth tab
    clientName: 'REPLACE_ME',
    idToken: response.credential,
    // make sure this is the same nonce you set in data-nonce
    nonce: 'REPLACE_ME',
  });
}
```





**Method: Web Redirect**

If you don't want to use the Google-styled buttons, you can use the redirect flow instead.

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the URL to create a link. Here's a full example:

```jsx 
'use client';

import React, { useState } from 'react';
import { init } from '@interface-db/react';

const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

const url = db.auth.createAuthorizationURL({
  // Use the google client name in the Instant dashboard auth tab
  clientName: 'REPLACE_ME',
  redirectURL: window.location.href,
});

import React from 'react';

export default function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}

function Login() {
  return <a href={url}>Log in with Google</a>;
}
```

When your users click on the link, they'll be redirected to Google to start the OAuth flow and then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with Google!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession [installation instructions](https://docs.expo.dev/versions/latest/sdk/auth-session/) from the Expo docs.

Next, add the following dependencies:

```shell 
npx expo install expo-auth-session expo-crypto
```

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have your App Scheme, it's time to tell Instant about it. For development with Expo, add `exp://` and your scheme (e.g. `mycoolredirect://`) as redirect origins.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add a redirect origin of type "App scheme".





**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme exp://
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme mycoolredirect://
```





**Use AuthSession to log in with Google!**

And from here you're ready to add a login button to your Expo app! Here's a full example:

```jsx 
import { View, Text, Button, StyleSheet } from 'react-native';
import { init } from '@interface-db/react-native';
import {
  makeRedirectUri,
  useAuthRequest,
  useAutoDiscovery,
} from 'expo-auth-session';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <Text>Hello {user.email}!</Text>;
}

function Login() {
  const discovery = useAutoDiscovery(db.auth.issuerURI());
  const [request, _response, promptAsync] = useAuthRequest(
    {
      // The unique name you gave the OAuth client when you
      // registered it on the Instant dashboard
      clientId: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );

  return (
    <Button
      title="Log in"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'error') {
            alert(res.error || 'Something went wrong');
          }
          if (res.type === 'success') {
            await db.auth
              .exchangeOAuthCode({
                code: res.params.code,
                codeVerifier: request.codeVerifier,
              })
              .catch((e) => alert(e.body?.message || 'Something went wrong'));
          } else {
          }
        } catch (e) {
          console.error(e);
        }
      }}
    ></Button>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;
```





**Method: Native Auth**

You can use [react-native-google-signin/google-signin](https://github.com/react-native-google-signin/google-signin) to authenticate natively on Google.

There are three steps:

1. Set up google-signin on Expo
1. Use the Sign in Button to auth with Google and get an `idToken`
1. Pass the token on to `db.auth.signInWithIdToken`, and you are logged in!

Let's do that.

**Set up google-signin on Expo**

First, let's install the package:

```
npx expo install @react-native-google-signin/google-signin
```

Then, follow the google-signin [installation instructions](https://react-native-google-signin.github.io/docs/setting-up/expo/) to set it up with Expo.

**Use google-signin to log in with Google!**

Now you're ready to add the Google sign-in button to your Expo app! Here's a full example:

```jsx 
import { View, Text, Button, StyleSheet } from 'react-native';
import { init } from '@interface-db/react-native';
import {
  GoogleSignin,
  GoogleSigninButton,
} from '@react-native-google-signin/google-signin';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

GoogleSignin.configure({
  // See https://react-native-google-signin.github.io/docs/original#configure
  iosClientId: 'YOUR_IOS_CLIENT_ID',
});

function App() {
  return (
    <>
      <db.SignedIn loading={<Text>Loading...</Text>}>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <Text>Hello {user.email}!</Text>;
}

function Login() {
  return (
    <GoogleSigninButton
      size={GoogleSigninButton.Size.Wide}
      color={GoogleSigninButton.Color.Dark}
      onPress={async () => {
        // 1. Sign in to Google
        await GoogleSignin.hasPlayServices();
        const userInfo = await GoogleSignin.signIn();
        const idToken = userInfo.data?.idToken;

        if (!idToken) {
          console.error('no ID token present!');
          return;
        }
        // 2. Use your token to sign in to InstantDB!
        try {
          const res = await db.auth.signInWithIdToken({
            // The unique name you gave the OAuth client when you
            // registered it on the Instant dashboard
            clientName: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
            idToken,
          });
          console.log('logged in!', res);
        } catch (error) {
          console.log('error signing in', error);
        }
      }}
    />
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;
```






# Sign In with Apple

How to add Sign In with Apple to your Instant app.



Instant supports Sign In with Apple on the Web and in native applications.


- **Web Popup (recommended)**: Use Apple-provided popup to authenticate users
- **Web Redirect**: Use redirect flow to authenticate users
- **React Native**: Authenticate in a React Native app


## Step 1: Create App ID

- Navigate to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list)
- Select _Identifiers_
- Click _+_
- _Register a new identifier_ → Select _App IDs_
- _Select a type_ → Select _App_
- _Capabilities_ → _Sign In with Apple_ → Check
- Fill in _Bundle ID_ and _Description_
- Click _Register_

## Step 2: Create Services ID

- Navigate to [Services IDs](https://developer.apple.com/account/resources/identifiers/list/serviceId)
- Click _+_
- _Register a new identifier_ → Select _Services IDs_
- Fill in _Description_ and _Identifier_. You’ll need this _Identifier_ later
- Click _Register_



## Step 3: Configure Services ID (Web Popup flow)

- Select the newly created Services ID
- Enable _Sign In with Apple_
- Click _Configure_
- Select _Primary App ID_ from Step 1
- To _Domains_, add your app domain (e.g. `myapp.com`)
- To _Return URLs_, add the URL of your app where authentication happens (e.g. `https://myapp.com/signin`)
- Click _Continue_ → _Save_





## Step 3: Configure Services ID (Web Redirect flow)

- Select the newly created Services ID
- Enable _Sign In with Apple_
- Click _Configure_
- Select _Primary App ID_ from Step 1
- To _Domains_, add `api.interfacedb.com`
- To _Return URLs_, add `https://api.interfacedb.com/runtime/oauth/callback`
- Click _Continue_ → _Save_

## Step 3.5: Generate Private Key (Web Redirect flow only)

- Navigate to [Keys](https://developer.apple.com/account/resources/authkeys/list)
- Click _+_
- Fill in _Name_ and _Description_
- Check _Sign in with Apple_
- Configure → select _App ID_ from Step 1
- _Continue_ → _Register_
- Download key file





## Step 3: Configure Services ID (React Native flow)

This step is not needed for Expo.


## Step 4: Register your OAuth client with Instant





**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Add Apple Client"
- Select a unique client name (`apple` by default, used in `db.auth` calls)
- Fill in your "Services ID" from Step 2
- Fill in your "Team ID" from [Membership details](https://developer.apple.com/account#MembershipDetailsCard)
- Fill in your "Key ID" from Step 3.5
- Fill in your "Private Key" by copying the file content from Step 3.5
- Click "Add Apple Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type apple --name apple \
  --services-id <services-id> \
  --team-id <team-id> --key-id <key-id> \
  --private-key-file <path-to-key.p8>
```









**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Add Apple Client"
- Select a unique client name (`apple` by default, used in `db.auth` calls)
- Fill in your "Services ID" from Step 2
- Click "Add Apple Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type apple --name apple --services-id <services-id>
```










## Step 4.5: Whitelist your domain in Instant (Web Redirect flow only)



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Redirect Origins" → "Add an origin"
- Add your app's domain (e.g. `myapp.com`)



**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type website --url myapp.com
```









## Step 5: Add Sign In code to your app (Web Popup flow)

Add Apple Sign In library to your app:

```
https://appleid.cdn-apple.com/appleauth/static/jsapi/appleid/1/en_US/appleid.auth.js
```

Initialize with `Services ID` from Step 2:

```jsx 
AppleID.auth.init({
  clientId: '<Services ID>',
  scope: 'name email',
  redirectURI: window.location.href,
});
```

Implement `signInPopup` using `clientName` from Step 4:

```jsx 
async function signInPopup() {
  let nonce = crypto.randomUUID();

  // authenticate with Apple
  let resp = await AppleID.auth.signIn({
    nonce: nonce,
    usePopup: true,
  });

  // authenticate with Instant
  await db.auth.signInWithIdToken({
    clientName: '<clientName>',
    idToken: resp.authorization.id_token,
    nonce: nonce,
  });
}
```

Add Sign In button:

```jsx 
<button onClick={signInPopup}>Sign In with Apple</button>
```





## Step 5: Add Sign In code to your app (Web Popup flow)

Create Sign In link using `clientName` from Step 4:

```
const authUrl = db.auth.createAuthorizationURL({
  clientName: '<clientName>',
  redirectURL: window.location.href,
});
```

Add a link that uses `authUrl`:

```
<a href={ authUrl }>Sign In with Apple</a>
```

That’s it!




## Step 5: Add Sign In code to your app (React Native flow)

Instant comes with support for the [Expo AppleAuthentication library](https://docs.expo.dev/versions/latest/sdk/apple-authentication/).

Add dependency:

```shell 
npx expo install expo-apple-authentication
```

Update `app.json` by adding:

```json 
{
  "expo": {
    "ios": {
      "usesAppleSignIn": true
    }
  }
}
```

Add `exp://` as a redirect origin for development with Expo:



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Redirect Origins" → "Add an origin"
- Add `exp://`



**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme exp://
```





Authenticate with Apple and then pass identityToken to Instant along with `clientName` from Step 4:

```jsx 
const [nonce] = useState('' + Math.random());
try {
  // sign in with Apple
  const credential = await AppleAuthentication.signInAsync({
    requestedScopes: [
      AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
      AppleAuthentication.AppleAuthenticationScope.EMAIL,
    ],
    nonce: nonce,
  });

  // pass identityToken to Instant
  db.auth
    .signInWithIdToken({
      clientName: '<clientName>',
      idToken: credential.identityToken,
      nonce: nonce,
    })
    .catch((err) => {
      console.log('Error', err.body?.message, err);
    });
} catch (e) {
  if (e.code === 'ERR_REQUEST_CANCELED') {
    // handle that the user canceled the sign-in flow
  } else {
    // handle other errors
  }
}
```

Sign out code:

```jsx 
<Button
  title="Sign Out"
  onPress={async () => {
    await db.auth.signOut();
  }}
/>
```

Full example:

```jsx 
import React, { useState } from 'react';
import { Button, View, Text, StyleSheet } from 'react-native';
import { init, tx } from '@interface-db/react-native';
import * as AppleAuthentication from 'expo-apple-authentication';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return (
    <View style={styles.container}>
      <Text>Hello {user.email}!</Text>
      <Button
        title="Sign Out"
        onPress={async () => {
          await db.auth.signOut();
        }}
      />
    </View>
  );
}

function Login() {
  const [nonce] = useState('' + Math.random());
  return (
    <View style={styles.container}>
      <AppleAuthentication.AppleAuthenticationButton
        buttonType={AppleAuthentication.AppleAuthenticationButtonType.SIGN_IN}
        buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
        cornerRadius={5}
        style={styles.button}
        onPress={async () => {
          try {
            const credential = await AppleAuthentication.signInAsync({
              requestedScopes: [
                AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
                AppleAuthentication.AppleAuthenticationScope.EMAIL,
              ],
              nonce: nonce,
            });
            // signed in
            db.auth
              .signInWithIdToken({
                clientName: 'apple',
                idToken: credential.identityToken,
                nonce: nonce,
              })
              .catch((err) => {
                console.log('Error', err.body?.message, err);
              });
          } catch (e) {
            if (e.code === 'ERR_REQUEST_CANCELED') {
              // handle that the user canceled the sign-in flow
            } else {
              // handle other errors
            }
          }
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  button: {
    width: 200,
    height: 44,
  },
});

export default App;
```






# GitHub OAuth

How to add GitHub OAuth to your Instant app.



Instant supports logging users in with their GitHub account. GitHub uses OAuth 2.0 for authentication, which provides a secure way for users to sign in without sharing their passwords.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with GitHub to your app.




**Building for Web?**

- **Web Redirect**: Standard OAuth flow with redirect-based authentication.



**Building for React Native?**

- **Expo Web Auth**: Use Expo's auth session for browser-based sign-in in mobile apps.





## Overview

There are three main steps:

1. **GitHub Developer Settings**: Create an OAuth App.
2. **Instant Dashboard**: Connect your OAuth App to Instant.
3. **Your app**: Add code to log in with GitHub!

Let's dive deeper into each step:

## 1. Create an OAuth App

1. Go to your GitHub account [Developer settings](https://github.com/settings/developers).
2. Click on "OAuth Apps" in the sidebar.
3. Click "New OAuth App" (or "Register a new application" if it's your first).
4. Fill in the application details:
   - **Application name**: Your app's name (users will see this)
   - **Homepage URL**: Your app's website
   - **Authorization callback URL**: `https://api.interfacedb.com/runtime/oauth/callback`
5. Click "Register application".
6. After creation, you'll see your **Client ID**.
7. Click "Generate a new client secret" to get your **Client Secret**.

## 2. Connect your OAuth App to Instant

**Add your OAuth App on Instant**



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Set up GitHub"
- Enter a unique name for your client (e.g., "github-web")
- Enter your "Client ID" from GitHub
- Enter your "Client Secret" from GitHub
- Click "Add Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type github --name github-web \
  --client-id <id> --client-secret <secret>
```







**Register your website with Instant**

If you're testing from localhost, add `http://localhost:3000` (replacing `3000` with the port you use). For production, add your website's domain.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add your URL to the **Redirect Origins** list.



**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type website --url <your-domain>
```







And voila, you are connected!

## 3. Add some code!



**Method: Web Redirect**

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the URL to create a link. Here's a full example:

```jsx 
'use client';

import React from 'react';
import { init } from '@interface-db/react';

const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

export default function App() {
  const url = db.auth.createAuthorizationURL({
    // Use the GitHub client name from the Instant dashboard auth tab
    clientName: 'github-web',
    redirectURL: window.location.href,
  });

  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login url={url} />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}

function Login({ url }) {
  return <a href={url}>Log in with GitHub</a>;
}
```

When your users click on the link, they'll be redirected to GitHub to authorize your app, then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with GitHub!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession [installation instructions](https://docs.expo.dev/versions/latest/sdk/auth-session/) from the Expo docs.

Next, add the following dependencies:

```shell 
npx expo install expo-auth-session expo-crypto
```

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have your App Scheme, it's time to tell Instant about it. For development with Expo, add `exp://` and your scheme (e.g. `mycoolredirect://`) as redirect origins.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add a redirect origin of type "App scheme".





**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme exp://
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme mycoolredirect://
```





**Use AuthSession to log in with GitHub!**

And from here you're ready to add a login button to your Expo app! Here's a full example:

```jsx 
import { View, Text, Button } from 'react-native';
import { init } from '@interface-db/react-native';
import {
  makeRedirectUri,
  useAuthRequest,
  useAutoDiscovery,
} from 'expo-auth-session';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return (
    <View>
      <Text>Hello {user.email}!</Text>
      <Button title="Log out" onPress={() => db.auth.signOut()}></Button>
    </View>
  );
}

function Login() {
  const discovery = useAutoDiscovery(db.auth.issuerURI());

  const [request, _response, promptAsync] = useAuthRequest(
    {
      // The unique name you gave the OAuth client when you
      // registered it on the Instant dashboard
      clientId: 'github-web',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );

  return (
    <Button
      title="Log in with GitHub"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'success') {
            await db.auth.exchangeOAuthCode({
              code: res.params.code,
              codeVerifier: request?.codeVerifier,
            });
          }
        } catch (e) {
          console.error(e);
        }
      }}
    />
  );
}

export default App;
```



## Scopes

GitHub uses OAuth scopes to control access. The basic scopes Instant requests are:

- `read:user` - Read access to profile information
- `user:email` - Read access to email addresses


# LinkedIn OAuth

How to add LinkedIn OAuth to your Instant app.



Instant supports logging users in with their LinkedIn account. There are a few ways to do this: it depends on whether you are building for web or React Native.

Choose the option that sounds best to you, and the rest of the document will show you how to add Sign in with LinkedIn to your app.




**Building for Web?**

- **Web Redirect**: Easier to integrate, but doesn't let you render your custom app name.



**Building for React Native?**

- **Expo Web Auth**: Use Expo's auth session to integrate browser-based sign-in. Easier to implement, but doesn't let you render your custom app name.





## Overview

There are three main steps:

1. **LinkedIn Developer Console**: Create an OAuth client.
2. **Instant Dashboard**: Connect your OAuth client to Instant
3. **Your app**: Add some code to log in with LinkedIn!

Let's dive deeper into each step:

## 1. Create an OAuth client

1. Head to the [LinkedIn developer portal](https://www.linkedin.com/developers/apps) and create a new application (or open an existing one).
2. In the **Auth** tab enable **Sign In with LinkedIn**.
3. Add the following redirect URI to your application:

```text
https://api.interfacedb.com/runtime/oauth/callback
```



Save your Client ID and your Client Secret -- you'll need them for the next step!



## 2. Connect your OAuth client to Instant

**Add your OAuth Client on Instant**



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard:

- Click "Set up LinkedIn"
- Enter a unique name for your client (e.g., "linkedin-web")
- Enter your "Client ID"
- Enter your "Client Secret"
- Click "Add Client"



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type linkedin --name linkedin-web \
  --client-id <id> --client-secret <secret>
```







**Register your website with Instant**

If you're testing from localhost, add `http://localhost:3000` (replacing `3000` with the port you use). For production, add your website's domain.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add your URL to the **Redirect Origins** list.



**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type website --url <your-domain>
```







And voila, you are connected!

## 3. Add some code!



**Method: Web Redirect**

Create an authorization URL via `db.auth.createAuthorizationURL` and then use the URL to create a link. Here's a full example:

```jsx 
'use client';

import React, { useState } from 'react';
import { init } from '@interface-db/react';

const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

const url = db.auth.createAuthorizationURL({
  // Use the linkedin client name in the Instant dashboard auth tab
  clientName: 'REPLACE_ME',
  redirectURL: window.location.href,
});

import React from 'react';

export default function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <h1>Hello {user.email}!</h1>;
}

function Login() {
  return <a href={url}>Log in with LinkedIn</a>;
}
```

When your users click on the link, they'll be redirected to LinkedIn to start the OAuth flow and then back to your site.

Instant will automatically log them in to your app when they are redirected!





**Method: Expo Web Auth**

Instant comes with support for Expo's AuthSession library. To use it, you need to:

1. Set up AuthSession
2. Register your app with Instant
3. Use AuthSession to log in with LinkedIn!

Let's do that.

**Set up AuthSession**

If you haven't already, follow the AuthSession [installation instructions](https://docs.expo.dev/versions/latest/sdk/auth-session/) from the Expo docs.

Next, add the following dependencies:

```shell 
npx expo install expo-auth-session expo-crypto
```

Update your app.json with your scheme:

```json 
{
  "expo": {
    "scheme": "mycoolredirect"
  }
}
```

**Register your app with Instant**

Now that you have your App Scheme, it's time to tell Instant about it. For development with Expo, add `exp://` and your scheme (e.g. `mycoolredirect://`) as redirect origins.



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add a redirect origin of type "App scheme".





**From the terminal**


```shell
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme exp://
npx @interface-db/cli@latest auth origin add --type custom-scheme --scheme mycoolredirect://
```





**Use AuthSession to log in with LinkedIn!**

And from here you're ready to add a login button to your Expo app! Here's a full example:

```jsx 
import { View, Text, Button, StyleSheet } from 'react-native';
import { init } from '@interface-db/react-native';
import {
  makeRedirectUri,
  useAuthRequest,
  useAutoDiscovery,
} from 'expo-auth-session';

const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

function App() {
  return (
    <>
      <db.SignedIn>
        <UserInfo />
      </db.SignedIn>
      <db.SignedOut>
        <Login />
      </db.SignedOut>
    </>
  );
}

function UserInfo() {
  const user = db.useUser();
  return <Text>Hello {user.email}!</Text>;
}

function Login() {
  const discovery = useAutoDiscovery(db.auth.issuerURI());
  const [request, _response, promptAsync] = useAuthRequest(
    {
      // The unique name you gave the OAuth client when you
      // registered it on the Instant dashboard
      clientId: 'YOUR_INSTANT_AUTH_CLIENT_NAME',
      redirectUri: makeRedirectUri(),
    },
    discovery,
  );

  return (
    <Button
      title="Log in"
      disabled={!request}
      onPress={async () => {
        try {
          const res = await promptAsync();
          if (res.type === 'error') {
            alert(res.error || 'Something went wrong');
          }
          if (res.type === 'success') {
            await db.auth
              .exchangeOAuthCode({
                code: res.params.code,
                codeVerifier: request.codeVerifier,
              })
              .catch((e) => alert(e.body?.message || 'Something went wrong'));
          } else {
          }
        } catch (e) {
          console.error(e);
        }
      }}
    ></Button>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default App;
```






# Clerk

How to integrate Clerk's auth flow with Instant.

Instant supports auth with Clerk.

## Setup

**Step 1: Configure Clerk**

Go to your Clerk dashboard, navigate to [`Sessions`](https://dashboard.clerk.com/last-active?path=sessions), then click the `Edit` button in the `Customize session token` section.

Add the email and email_verified claims to your session token:

```json 
{
  "email": "{{user.primary_email_address}}",
  "email_verified": "{{user.email_verified}}"
}
```

You can have additional claims as long as the `email` claim is set to `{{user.primary_email_address}}` and the `email_verified` claim is set to `{{user.email_verified}}`.

![Clerk token form](/img/docs/clerk-token-form.png)

**Step 2: Get your Clerk Publishable key**

On the Clerk dashboard, navigate to [`API keys`](https://dashboard.clerk.com/last-active?path=api-keys), then copy the `Publishable key`. It should start with `pk_`.

**Step 3: Register your Clerk Publishable key with your Instant app**



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add a new Clerk client with the publishable key you copied.



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type clerk --name clerk --publishable-key <publishable-key>
```





## Usage

Use Clerk's `getToken` helper to get a session JWT for your signed-in user. Then call Instant's `db.auth.signInWithIdToken` with the JWT and the client name you set on the Instant dashboard.

When you call `db.auth.signInWithIdToken`, Instant will verify that the JWT was signed by your Clerk app. If verified, Instant will use the email in the JWT's claims to look up your user or create a new one and create a long-lived session. Be sure to call Instant's `db.auth.signOut` when you want to sign the user out.

Here is a full example using Clerk's Next.js library:

```javascript 
'use client';

import {
  useAuth,
  ClerkProvider,
  SignInButton,
  SignedIn,
  SignedOut,
} from '@clerk/nextjs';
import { init } from '@interface-db/react';
import { useEffect } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

// Use the clerk client name you set in the Instant dashboard auth tab
const CLERK_CLIENT_NAME = 'REPLACE_ME';

function ClerkSignedInComponent() {
  const { getToken, signOut } = useAuth();

  const signInToInstantWithClerkToken = async () => {
    // getToken gets the jwt from Clerk for your signed in user.
    const idToken = await getToken();

    if (!idToken) {
      // No jwt, can't sign in to instant
      return;
    }

    // Create a long-lived session with Instant for your clerk user
    // It will look up the user by email or create a new user with
    // the email address in the session token.
    db.auth.signInWithIdToken({
      clientName: CLERK_CLIENT_NAME,
      idToken: idToken,
    });
  };

  useEffect(() => {
    signInToInstantWithClerkToken();
  }, []);

  const { isLoading, user, error } = db.useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }
  if (error) {
    return <div>Error signing in to Instant! {error.message}</div>;
  }
  if (user) {
    return (
      <div>
        <p>Signed in with Instant through Clerk!</p>{' '}
        <button
          onClick={() => {
            // First sign out of Instant to clear the Instant session.
            db.auth.signOut().then(() => {
              // Then sign out of Clerk to clear the Clerk session.
              signOut();
            });
          }}
        >
          Sign out
        </button>
      </div>
    );
  }
  return (
    <div>
      <button onClick={signInToInstantWithClerkToken}>
        Sign in to Instant
      </button>
    </div>
  );
}

function App() {
  return (
    <ClerkProvider>
      <SignedOut>
        <SignInButton />
      </SignedOut>
      <SignedIn>
        <ClerkSignedInComponent />
      </SignedIn>
    </ClerkProvider>
  );
}

export default App;
```


# Firebase Auth

How to integrate Firebase's auth flow with Instant.

Instant supports delegating auth to Firebase Auth.

## Setup

**Step 1: Get your Firebase Project ID**

On the [Firebase dashboard](https://console.firebase.google.com/), open your project and navigate to `Project Overview` > `⚙` > `Project Settings`, then copy the `Project ID`.

**Step 2: Register your Firebase Project ID with your Instant app**



**From the dashboard**


From the [Auth](/dash?s=main&t=auth) tab on the Instant dashboard, add a new Firebase client with the Project ID you copied.



**From the terminal**


```shell
npx @interface-db/cli@latest auth client add \
  --type firebase --name firebase --project-id <project-id>
```





## Usage

Use Firebase's `getIdToken` helper to get a JWT for your signed-in user. Then call Instant's `db.auth.signInWithIdToken` with the JWT and the client name you set on the Instant dashboard.

When you call `db.auth.signInWithIdToken`, Instant will verify that the JWT was signed by your Firebase app. If verified, Instant will use the email in the JWT's claims to look up your user or create a new one and create a long-lived session. Be sure to call Instant's `db.auth.signOut` when you want to sign the user out.

Here is a full example:

```tsx
'use client';

import { init } from '@interface-db/react';
import { initializeApp } from 'firebase/app';
import {
  getAuth,
  signInWithEmailAndPassword,
  createUserWithEmailAndPassword,
  onAuthStateChanged,
} from 'firebase/auth';
import { useEffect, useState } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

// Use the firebase client name you set in the Instant dashboard auth tab
const FIREBASE_CLIENT_NAME = 'REPLACE_ME';

const firebaseConfig = {
  // Use the same Project ID you set in the Instant dashboard auth tab
  projectId: 'REPLACE_ME',
  apiKey: 'REPLACE_ME',
};

const firebaseApp = initializeApp(firebaseConfig);
const firebaseAuth = getAuth(firebaseApp);

function App() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  useEffect(() => {
    const unsubscribe = onAuthStateChanged(firebaseAuth, (user) => {
      if (user) {
        user.getIdToken().then((idToken) => {
          db.auth.signInWithIdToken({
            idToken,
            clientName: FIREBASE_CLIENT_NAME,
          });
        });
      } else {
        db.auth.signOut();
      }
    });
    return () => unsubscribe();
  }, []);

  const handleSignIn = async (e) => {
    e.preventDefault();
    try {
      await signInWithEmailAndPassword(firebaseAuth, email, password);
    } catch (error) {
      console.error('Sign in error:', error);
    }
  };

  const handleSignUp = async (e) => {
    e.preventDefault();
    try {
      await createUserWithEmailAndPassword(firebaseAuth, email, password);
    } catch (error) {
      console.error('Sign up error:', error);
    }
  };

  return (
    <>
      <db.SignedOut>
        <form onSubmit={handleSignIn}>
          <input
            type="email"
            placeholder="Email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
          />
          <input
            type="password"
            placeholder="Password"
            value={password}
            onChange={(e) => setPassword(e.target.value)}
          />
          <button type="submit">Sign In</button>
          <button type="button" onClick={handleSignUp}>
            Sign Up
          </button>
        </form>
      </db.SignedOut>
      <db.SignedIn>
        <SignedInComponent />
      </db.SignedIn>
    </>
  );
}

function SignedInComponent() {
  const user = db.useUser();

  const handleSignOut = async () => {
    await firebaseAuth.signOut();
  };

  return (
    <div>
      <div>Signed in as {user.email}!</div>
      <button onClick={handleSignOut}>Sign Out</button>
    </div>
  );
}

export default App;
```


# Permissions

How to secure your data with Instant's Rule Language.

To secure user data, you can use Instant's Rule Language. Our rule language
takes inspiration from Rails' ActiveRecord, Google's CEL, and JSON.
Here's an example ruleset below.

<!-- prettier-ignore-start -->
```tsx 
// instant.perms.ts
import type { InstantRules } from '@interface-db/react';

const rules = {
  "todos": {
    "allow": {
      "view": "auth.id != null",
      "create": "isOwner",
      "update": "isOwner && isStillOwner",
      "delete": "isOwner",
    },
    "bind": {
      "isOwner": "auth.id != null && auth.id == data.creatorId",
      "isStillOwner": "auth.id != null && auth.id == newData.creatorId"
    }
  }
} satisfies InstantRules;

export default rules;
```
<!-- prettier-ignore-end -->

You can manage permissions via configuration files or through the Instant dashboard.

You can also add [rate limits](/docs/rate-limits) to your rules to control how often users can perform actions.

## Permissions as code

With Instant you can define your permissions in code. If you haven't already, use the [CLI](/docs/cli) to generate an `instant.perms.ts` file:

```shell 
npx @interface-db/cli@latest init
```

The CLI will guide you through picking an Instant app and generate this file for you. Once you've made changes to `instant.perms.ts`, you can use the CLI to push those changes to production:

```shell 
npx @interface-db/cli@latest push perms
```

## Permissions in the dashboard

For each app in your dashboard, you’ll see a permissions editor. Permissions are expressed as JSON. Each top-level key represents one of your namespaces — for example `goals`, `todos`, and the like. There is also a special top-level key `attrs` for defining permissions for creating new types of namespaces and attributes.

## Namespaces

For each namespace you can define `allow` rules for `view`, `create`, `update`, `delete`, as well as special rules for fields. Rules must be boolean expressions.

If a rule is not set then by default it evaluates to true. The following three rulesets are all equivalent:

In this example we explicitly set each action for `todos` to true:

```json
{
  "todos": {
    "allow": {
      "view": "true",
      "create": "true",
      "update": "true",
      "delete": "true"
    }
  }
}
```

In this example we explicitly set `view` to be true. However, all the remaining
actions for `todos` also default to true.

```json
{
  "todos": {
    "allow": {
      "view": "true"
    }
  }
}
```

In this example we set no rules, and thus all permission checks pass.

```json
{}
```



When you start developing you probably won't worry about permissions. However, once you start shipping your app to users you will want to secure their data!



### View

`view` rules are evaluated when doing `db.useQuery`. On the backend every object
that satisfies a query will run through the `view` rule before being passed back
to the client. This means as a developer you can ensure that no matter what query
a user executes, they’ll _only_ see data that they are allowed to see.

### Create, Update, Delete

Similarly, for each object in a transaction, we make sure to evaluate the respective `create`, `update`, and `delete` rule.

Transactions will fail if a user does not have adequate permission.

### Fields

You can also define field-level permissions. For example, you may want to make the `$users` table public, but hide email addresses. Here's how you could do that:

```json
{
  "$users": {
    "allow": {
      "view": "true"
    },
    "fields": {
      "email": "auth.id == data.id"
    }
  }
}
```

### Default permissions

By default, all permissions are considered to be `"true"`. To change that, use the `"$default"` key. This:

```json
{
  "todos": {
    "allow": {
      "$default": "false"
    }
  }
}
```

is equivalent to this:

```json
{
  "todos": {
    "allow": {
      "view": "false",
      "create": "false",
      "update": "false",
      "delete": "false"
    }
  }
}
```

Specific keys can override defaults:

```json
{
  "todos": {
    "allow": {
      "$default": "false",
      "view": "true"
    }
  }
}
```

You can use `$default` as the namespace:

```json
{
  "$default": {
    "allow": {
      "view": "false"
    }
  },
  "todos": {
    "allow": {
      "view": "true"
    }
  }
}
```

Finally, the ultimate default:

```json
{
  "$default": {
    "allow": {
      "$default": "false"
    }
  }
}
```

## Attrs

Attrs are a special kind of namespace for creating new types of data on the fly.
Currently we only support create rules on attrs. During development you likely don't
need to lock this rule down, but once you ship you will likely want to set this
permission to `false`.

Suppose our data model looks like this:

```json
{
  "goals": { "id": UUID, "title": string }
}
```

And we have rules defined as:

```json
{
  "attrs": { "allow": { "create": "false" } }
}
```

Then we could create goals with existing attr types:

```javascript
db.transact(db.tx.goals[id()].update({title: "Hello World"})
```

But we would not be able to create goals with new attr types:

```javascript
db.transact(db.tx.goals[id()].update({title: "Hello World", priority: "high"})
```

## CEL expressions

Inside each rule, you can write CEL code that evaluates to either `true` or `false`.

```json
{
  "todos": {
    "allow": {
      "view": "auth.id != null",
      "create": "auth.id in data.ref('creator.id')",
      "update": "!(newData.title == data.title)",
      "delete": "'joe@instantdb.com' in data.ref('users.email')"
    }
  }
}
```

The above example shows a taste of the kind of rules you can write :)

### data

`data` refers to the object you have saved. This will be populated when used for `view`, `create`, `update`, `delete` rules.

### newData

In `update`, you'll also have access to `newData`. This refers to the changes that are being made to the object.

### bind

`bind` allows you to alias logic. The following are equivalent:

```json
{
  "todos": {
    "allow": {
      "create": "isOwner"
    },
    "bind": { "isOwner": "auth.id != null && auth.id == data.creatorId" }
  }
}
```

```json
{
  "todos": {
    "allow": {
      "create": "auth.id != null && auth.id == data.creatorId"
    }
  }
}
```

`bind` is useful for not repeating yourself and tidying up rules.

```json
{
  "todos": {
    "allow": {
      "create": "isOwner || isAdmin"
    },
    "bind": {
      "isOwner": "auth.id != null && auth.id == data.creatorId",
      "isAdmin": "auth.email in ['joe@instantdb.com', 'stopa@instantdb.com']"
    }
  }
}
```

### ref

You can also refer to relations in your permission checks. This rule restricts
delete to only succeed on todos associated with a specific user email.

```json
{
  "todos": {
    "allow": {
      "delete": "'joe@instantdb.com' in data.ref('users.email')"
    }
  }
}
```

`ref` works on the `auth` object too. Here's how you could restrict `deletes` to users with the 'admin' role:

```json
{
  "todos": {
    "allow": {
      "delete": "'admin' in auth.ref('$user.role.type')"
    },
  },
};
```

See [managing users](/docs/users) to learn more about that.

### ruleParams

Imagine you have a `documents` namespace and want to implement a rule like _"Only people who know my document's id can access it."_

You can use `ruleParams` to write that rule. `ruleParams` let you pass extra options to your queries and transactions.

For example, pass a `knownDocId` param to our query:

```javascript
// You could get your doc's id from the URL for example
const myDocId = getId(window.location);

const query = {
  docs: {},
};
const { data } = db.useQuery(query, {
  ruleParams: { knownDocId: myDocId }, // Pass the id to ruleParams!
});
```

Or to your transactions:

```js
db.transact(
  db.tx.docs[id].ruleParams({ knownDocId: id }).update({ title: 'eat' }),
);
```

And then use it in your permission rules:

```json
{
  "documents": {
    "allow": {
      "view": "data.id == ruleParams.knownDocId",
      "update": "data.id == ruleParams.knownDocId",
      "delete": "data.id == ruleParams.knownDocId"
    }
  }
}
```

With that, you've implemented the rule _"Only people who know my document's id can access it."_!

### request.time

The timestamp when the rules are run. You might use this in an update or create rule to ensure that a time is valid:

```json
{
  "documents": {
    "allow": {
      "update": "math.abs((request.time - timestamp(data.updatedAt)).getMinutes()) <= 1"
    }
  }
}
```

### request.origin

The origin that made the request, as a string, e.g. `https://example.com`. This may be null if the request was not made by a browser.

### request.ip

The IP address of the originating request as a string, e.g. `192.251.68.254` or `2a03:2880:2110:df07:face:b00c::1`.

### request.modifiedFields

In `create` and `update` rules, you have access to `request.modifiedFields` — a list of field names being set in the transaction. This is useful when you want to control which fields can be set by whom.

#### Restricting fields on create

You can use `request.modifiedFields` to prevent certain fields from being set on creation. For example, only admins should be able to set the `featured` field:

```json
{
  "posts": {
    "allow": {
      "create": "isAdmin || !('featured' in request.modifiedFields)"
    },
    "bind": {
      "isAdmin": "'admin' in auth.ref('$user.role.type')"
    }
  }
}
```

This allows anyone to create posts, but only admins can set the `featured` field.

#### Restricting fields on update

You might want only the owner to edit a post's title and content, but allow anyone to increment a `likes` counter:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || onlyModifiesLikes"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesLikes": "request.modifiedFields.all(field, field in ['likes'])"
    }
  }
}
```

This rule allows the owner to update any field, but non-owners can only update the `likes` field.

Since a transaction can update multiple fields at once, `request.modifiedFields` is a list. We use `.all(field, field in ['likes'])` to check that _every_ field being modified is in our allowed list. This prevents someone from sneaking in an unauthorized field change alongside an allowed one.

You can allow multiple public fields:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || onlyModifiesPublicFields"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesPublicFields": "request.modifiedFields.all(field, field in ['likes', 'viewCount'])"
    }
  }
}
```

You can combine `modifiedFields` checks with other conditions. For example, require users to be logged in before updating public fields:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || (isLoggedIn && onlyModifiesLikes)"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "isLoggedIn": "auth.id != null",
      "onlyModifiesLikes": "request.modifiedFields.all(field, field in ['likes'])"
    }
  }
}
```

You can also add value validation that only runs when a specific field is being modified. Use `'fieldName' in request.modifiedFields` to check if a field is being changed:

```json
{
  "posts": {
    "allow": {
      "update": "isOwner || (onlyModifiesPublicFields && likesValid && titleValid)"
    },
    "bind": {
      "isOwner": "auth.id == data.ownerId",
      "onlyModifiesPublicFields": "request.modifiedFields.all(field, field in ['likes', 'title'])",
      "likesValid": "!('likes' in request.modifiedFields) || newData.likes >= 0",
      "titleValid": "!('title' in request.modifiedFields) || size(newData.title) <= 100"
    }
  }
}
```

This rule allows non-owners to update `likes` and `title`, but only if `likes` is non-negative and `title` is at most 100 characters. The `!('field' in request.modifiedFields) || condition` pattern means "either this field isn't being modified, or if it is, it must satisfy the condition."

**Here are some more patterns**

If you want to access a document and _all related comments_ with one `knownDocId`:

```json
{
  "docs": {
    "view": "data.id == ruleParams.knownDocId"
  },
  "comment": {
    "view": "ruleParams.knownDocId in data.ref('parent.id')"
  }
}
```

Or, if you want to allow multiple documents:

```js
db.useQuery(..., { knownDocIds: [id1, id2, ...] })
```

```json
{
  "docs": {
    "view": "data.id in ruleParams.knownDocIds"
  }
}
```

To create a “share links” feature, where you have multiple links to the same doc, you can create a separate namespace:

```json
{
  "docs": {
    "view": "ruleParams.secret in data.ref('docLinks.secret')"
  }
}
```

Or if you want to separate “view links” from “edit links”, you can use two namespaces like this:

```json
{
  "docs": {
    "view": "hasViewerSecret || hasEditorSecret",
    "update": "hasEditorSecret",
    "delete": "hasEditorSecret",
    "bind": {
      "hasViewerSecret": "ruleParams.secret in data.ref('docViewLinks.secret')",
      "hasEditorSecret": "ruleParams.secret in data.ref('docEditLinks.secret')"
    }
  }
}
```


# Rate Limits

How to add rate limiting to your Instant app with permission rules.

You can add rate limiting to your app with the `rateLimit` object in the [permission rules](/docs/permissions). Rate limits let you control how often users can perform actions like creating records or querying data.

## Defining rate limits

Rate limits are configured in the `$rateLimits` key of your permissions. Each rate limit has a name and a configuration with a `limits` array.

```tsx 
// instant.perms.ts
import type { InstantRules } from '@interface-db/react';

const rules = {
  todos: {
    allow: {
      create: 'rateLimit.createTodos.limit(auth.id)',
    },
  },
  $rateLimits: {
    createTodos: {
      limits: [
        {
          capacity: 10,
          refill: {
            amount: 10,
            period: '1 hour',
          },
        },
      ],
    },
  },
} satisfies InstantRules;

export default rules;
```

In this example, each user can create at most 10 todos per hour. Once they hit the limit, further creates will be rejected until tokens refill.

## How it works

Rate limits use a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) algorithm. Each bucket starts full at its `capacity`. Every time a rule calls `rateLimit.bucketName.limit(key)`, one token is consumed from the bucket for that key. When the bucket is empty, the request is rejected with a 429 error. Tokens refill over time based on your configuration.

The `key` argument (e.g. `auth.id`) determines _who_ the limit applies to. Different keys get independent buckets. For example, `rateLimit.createTodos.limit(auth.id)` gives each user their own rate limit. To rate-limit by IP address, use `rateLimit.createTodos.limit(request.ip)`.

### Rate limits are per entity

Rate limit rules are evaluated per entity, just like other permission rules. For `create`, `update`, and `delete`, the rule runs once for each entity in the transaction. For `view`, the rule runs once for each entity in the query result.

This means a query that returns 50 rows will consume 50 tokens. Keep this in mind when setting your `capacity` — it should account for the number of entities your queries typically return, not just the number of requests.

## Configuration

Each entry in the `limits` array accepts:

| Field           | Required | Default            | Description                                                                                                                    |
| --------------- | -------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `capacity`      | Yes      |                    | Maximum number of tokens in the bucket.                                                                                        |
| `refill.amount` | No       | Same as `capacity` | Number of tokens added per refill.                                                                                             |
| `refill.period` | No       | `"1 hour"`         | How often tokens refill. Accepts durations like `"30 minutes"`, `"1 day"`, `"2 hours"`. Must be between 1 second and 24 hours. |
| `refill.type`   | No       | `"greedy"`         | Either `"greedy"` (tokens refill continuously) or `"interval"` (tokens refill all at once at the end of each period).          |

### Greedy vs interval refill

With **greedy** refill (the default), tokens trickle in continuously. If your capacity is 60 with a period of `"1 hour"`, you get roughly one token per minute.

With **interval** refill, all tokens are added at once when the period elapses. If your capacity is 60 with a period of `"1 hour"`, you get all 60 tokens back at the end of one hour.

## Using rate limits in rules

### Basic usage

Call `rateLimit.bucketName.limit(key)` in any `allow` rule. It consumes a token and returns `true` if the request is allowed, or throws a rate limit error if the bucket is empty. You can optionally pass a second argument to consume multiple tokens: `rateLimit.bucketName.limit(key, 5)`.

```json 
{
  "messages": {
    "allow": {
      "create": "rateLimit.sendMessage.limit(auth.id)"
    }
  },
  "$rateLimits": {
    "sendMessage": {
      "limits": [
        {
          "capacity": 5,
          "refill": { "period": "1 minute" }
        }
      ]
    }
  }
}
```

### Combining with other rules

Since `limit` returns `true` on success, you can combine it with other permission checks using `&&`:

```json 
{
  "messages": {
    "allow": {
      "create": "auth.id != null && rateLimit.sendMessage.limit(auth.id)"
    }
  },
  "$rateLimits": {
    "sendMessage": {
      "limits": [
        {
          "capacity": 20,
          "refill": { "period": "1 hour" }
        }
      ]
    }
  }
}
```



Put `rateLimit.limit(...)` last in your `&&` chain. CEL short-circuits, so if an earlier check fails, no token is consumed.



### Rate limiting queries

You can rate limit `view` rules the same way:

```json 
{
  "messages": {
    "allow": {
      "view": "rateLimit.readMessages.limit(auth.id)"
    }
  },
  "$rateLimits": {
    "readMessages": {
      "limits": [
        {
          "capacity": 100,
          "refill": { "period": "1 hour" }
        }
      ]
    }
  }
}
```

### Consuming multiple tokens

You can consume more than one token per request by passing a second argument:

```json 
{
  "uploads": {
    "allow": {
      "create": "rateLimit.uploadLimit.limit(auth.id, 5)"
    }
  },
  "$rateLimits": {
    "uploadLimit": {
      "limits": [
        {
          "capacity": 100,
          "refill": { "period": "1 day" }
        }
      ]
    }
  }
}
```

### Multiple limits

You can apply multiple limits to the same bucket. For example, a burst limit and a sustained limit:

```json 
{
  "$rateLimits": {
    "sendMessage": {
      "limits": [
        {
          "capacity": 5,
          "refill": { "period": "1 minute", "type": "interval" }
        },
        {
          "capacity": 100,
          "refill": { "period": "1 day" }
        }
      ]
    }
  }
}
```

This allows a burst of 5 messages per minute, but no more than 100 per day.

### Rate limiting by different keys

The key you pass to `limit` determines the granularity. Here are some common patterns:

```json 
{
  "posts": {
    "allow": {
      "create": "rateLimit.createPosts.limit(auth.id)"
    }
  }
}
```

Rate limit per user with `auth.id`. Each user gets their own bucket.

```json 
{
  "posts": {
    "allow": {
      "create": "rateLimit.createPosts.limit(request.ip)"
    }
  }
}
```

Rate limit by IP address with `request.ip`. Useful for limiting unauthenticated requests.

## Error handling

When a rate limit is exceeded, Instant returns an error with `type: "rate-limited"` and a `hint` containing `retry-after` (seconds until the bucket refills):

```json
{
  "type": "rate-limited",
  "message": "Your request exceeded the rate limit.",
  "hint": {
    "retry-at": "2026-04-14T12:01:00Z",
    "retry-after": 12,
    "remaining-tokens": 0
  }
}
```

For transactions, the error is thrown as an `InstantAPIError`. You can catch it and show a message to the user:

```js 
try {
  await db.transact(db.tx.messages[id()].update({ text: 'hello' }));
} catch (e) {
  if (e.body?.type === 'rate-limited') {
    const retryAfter = e.body.hint['retry-after'];
    alert(`Too fast! Try again in ${retryAfter} seconds.`);
  }
}
```

For queries, rate limit errors will appear in the `error` field returned by `useQuery`:

```js 
const { data, error } = db.useQuery({ messages: {} });

if (error?.body?.type === 'rate-limited') {
  // handle rate limit
}
```


# Managing users

How to manage users in your Instant app.

## See users in your app

You can manage users in your app using the `$users` namespace. This namespace is
automatically created when you create an app.

You'll see the `$users` namespace in the `Explorer` tab with all
the users in your app!

## Querying users

The `$users` namespace can be queried like any normal namespace. However, we've
set some default permissions.

```javascript
// instant.perms.ts
import type { InstantRules } from "@interface-db/react";

const rules = {
  $users: {
    allow: {
      view: 'auth.id == data.id', // users can only see themselves by default
      create: 'true', // signups are open by default
      delete: 'false', // users can only be deleted via the dashboard or admin SDK
      update: 'false', // users can't update by default
    },
  },
} satisfies InstantRules;

export default rules;
```

Since `$users` is a managed namespace, you can override `view`, `update`, and `create` rules, but not `delete`. The `create` rule runs during signup (not via `transact`) and can be used to restrict who can sign up or validate `extraFields`. See [Signup rules](#signup-rules) for details.

## Sharing user data

If you want to make the users table public, you can always change the `view` permission. If you do this, be sure to write an appropriate `field` permission on `emails` so that those columns don't leak.

```javascript
// instant.perms.ts
import type { InstantRules } from "@interface-db/react";

const rules = {
  $users: {
    allow: {
      view: 'true', // anyone can see users
    },
    fields: {
      email: "auth.id == data.id" // but only the logged in user can see their own email.
    }
  },
} satisfies InstantRules;

export default rules;
```

## Adding properties

You can add optional properties on the `$users` table. Here is an example of a schema for a todo app where users have nicknames and roles:

```javascript
// instant.schema.ts
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.any().unique().indexed(),
      nickname: i.string().optional(), // Users now have a `nickname` property
    }),
    roles: i.entity({
      type: i.string().indexed(),
    }),
    todos: i.entity({
      text: i.string(),
      completed: i.boolean(),
    }),
  },
  links: {
    userRoles: {
      forward: { on: '$users', has: 'many', label: 'roles' },
      reverse: { on: 'roles', has: 'many', label: 'users' },
    },
    todoOwner: {
      forward: { on: 'todos', has: 'one', label: 'owner' },
      reverse: { on: '$users', has: 'many', label: 'todos'},
    },
  },
});

// This helps TypeScript display nicer IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

### Links

We created two links, `userRoles` and `todoOwner`:

```typescript
// instant.schema.ts
import { i } from '@interface-db/react';

const _schema = i.schema({
  // ..
  links: {
    userRoles: {
      forward: { on: '$users', has: 'many', label: 'roles' },
      reverse: { on: 'roles', has: 'many', label: 'users' },
    },
    todoOwner: {
      forward: { on: 'todos', has: 'one', label: 'owner' },
      reverse: { on: '$users', has: 'many', label: 'todos' },
    },
  },
});
```

Notice that none of the links are required. You can't require links for `$users`.

### Attributes

Now look at the `nickname` attribute we just added:

```typescript
// instant.schema.ts
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $users: i.entity({
      email: i.any().unique().indexed(),
      nickname: i.string().optional(), // Users now have a `nickname` property
    }),
  },
  // ...
});
```

Note that `nickname` is optional too. Custom columns on `$users` have to be optional.

---

Once done, you can include user information in the client like so:

```javascript
// Creates a todo and links the current user as an owner
const addTodo = (newTodo, currentUser) => {
  const newId = id();
  db.transact(
    db.tx.todos[newId]
      .update({ text: newTodo, completed: false })
      // Link the todo to the user with the `owner` label we defined in the schema
      .link({ owner: currentUser.id }),
  );
};

// Creates or updates a user profile with a nickname and links it to the
// current user
const updateNick = (newNick, currentUser) => {
  db.transact([db.tx.$users[currentUser.id].update({ nickname: newNick })]);
};
```

At the moment you can only use `transact` to update the custom properties you added. Changing default columns like `email` would cause the transaction to fail.

## Setting properties at signup

You can set custom `$users` properties at the moment a user is created by passing `extraFields` to your sign-in method. Fields are only written when the user is first created. Returning users are unaffected.

The fields you pass must be defined in your schema as optional attributes on `$users`.

**Guest auth**

```javascript
db.auth.signInAsGuest({
  extraFields: { nickname: 'nezaj' },
});
```

**Magic codes**

```javascript
db.auth.signInWithMagicCode({
  email: sentEmail,
  code,
  extraFields: { nickname: 'nezaj' },
});
```

**OAuth with ID token** (Google Button, Apple, Clerk, Firebase)

```javascript
db.auth.signInWithIdToken({
  clientName: 'google',
  idToken,
  nonce,
  extraFields: { nickname: 'nezaj' },
});
```

**OAuth with web redirect** (Google, GitHub, LinkedIn)

For the redirect flow, pass `extraFields` when creating the authorization URL. Instant stores them and applies them when the user is created after the redirect.

```javascript
const url = db.auth.createAuthorizationURL({
  clientName: 'google',
  redirectURL: window.location.href,
  extraFields: { nickname: 'nezaj' },
});
```

**OAuth with code exchange** (Expo, React Native)

```javascript
db.auth.exchangeOAuthCode({
  code: res.params.code,
  codeVerifier: request.codeVerifier,
  extraFields: { nickname: 'nezaj' },
});
```

All sign-in methods return a `created` boolean so you can distinguish new users from returning ones. This is useful for scaffolding initial data when a user first signs up:

```javascript
const { user, created } = await db.auth.signInWithMagicCode({
  email,
  code,
  extraFields: { nickname },
});

if (created) {
  // Create default data for the new user
  db.transact([
    db.tx.settings[id()]
      .update({ theme: 'light', notifications: true })
      .link({ user: user.id }),
  ]);
}
```

When using `extraFields`, a `create` rule on `$users` is required. Signup will fail if no rule is defined. This ensures you explicitly opt in to accepting custom fields. A rule of `"true"` allows any values through. See [Signup rules](#signup-rules) for more examples.

## Signup rules

You can write a `create` rule on `$users` to control who can sign up and what fields they can set. This rule runs during the auth signup flow (magic codes, OAuth, guest sign-in) but does not apply to `transact`.

By default, anyone can sign up. If you set a `create` rule, it must pass for signup to succeed. If it fails, no user is created and magic codes are not consumed.

The `create` rule has access to `data` (the user being created, including email and any `extraFields`) and `auth` (set to the same value as `data`). Note that `ref()` is not available since the user has no relationships yet.

**Restrict signups to a domain**

```javascript
{
  "$users": {
    "allow": {
      "create": "data.email.endsWith('@mycompany.com')"
    }
  }
}
```

**Validate extraFields values**

```javascript
{
  "$users": {
    "allow": {
      "create": "data.username == null || data.username.size() >= 3"
    }
  }
}
```

**Disable all signups (waitlist mode)**

```javascript
{
  "$users": {
    "allow": {
      "create": "false"
    }
  }
}
```

## User permissions

You can reference the `$users` namespace in your permission rules just like a
normal namespace. For example, you can restrict a user to only update their own
todos like so:

```javascript
export default {
  // users perms...
  todos: {
    allow: {
      // owner is the label from the todos namespace to the $users namespace
      update: "auth.id in data.ref('owner.id')",
    },
  },
};
```

You can also traverse the `$users` namespace directly from the `auth` object via
`auth.ref`. When using `auth.ref`, the arg must start with `$user`. Here's the
equivalent rule to the one above using `auth.ref`:

```javascript
export default {
  // users perms...
  todos: {
    allow: {
      // We traverse the users links directly from the auth object
      update: "data.id in auth.ref('$user.todos.id')",
    },
  },
};
```

By creating links to `$users` and leveraging `auth.ref`, you can expressively build
more complex permission rules.

```javascript
export default {
  // users perms...
  todos: {
    bind: {
      isAdmin: "'admin' in auth.ref('$user.roles.type')",
      isOwner: "data.id in auth.ref('$user.todos.id')",
    },
    allow: {
      // We traverse the users links directly from the auth object
      update: 'isAdmin || isOwner',
    },
  },
};
```


# Presence, Cursors, and Activity

How to add ephemeral features like presence and cursors to your Instant app.

Sometimes you want to show real-time updates to users without persisting the
data to your database. Common scenarios include:

- Shared cursors in a collaborative whiteboard like Figma
- Who's online in a document editor like Google Docs
- Typing indicators in chat apps like Discord
- Live reactions in a video streaming app like Twitch

Instant provides three primitives for quickly building these ephemeral experiences: rooms, presence, and topics.

**Rooms**

A room represents a temporary context for realtime events. Users in the same room will receive updates from every other user in that room.

**Presence**

Presence is an object that each peer shares with every other peer. When a user updates their presence, it's instantly replicated to all users in that room. Presence persists throughout the remainder of a user's connection and is automatically cleaned up when a user leaves the room.

You can use presence to build features like "who's online." Instant's cursor and typing indicator are both built on top of the presence API.

**Topics**

Topics have "fire-and-forget" semantics and are better suited for data that doesn't need any sort of persistence. When a user publishes a topic, a callback is fired for every other user in the room listening for that topic.

You can use topics to build features like "live reactions." The real-time emoji button panel on Instant's homepage is built using the topics API.

**Transact vs. Ephemeral**

You may be thinking: when would I use `transact` vs `presence` vs `topics`? Here's a simple breakdown:

- Use `transact` when you need to persist data to the db. For example, when a user sends a message in a chat app.
- Use `presence` when you need to persist data in a room but not to the db. For example, showing
  who's currently viewing a document.
- Use `topics` when you need to broadcast data to a room, but don't need to persist it. For example, sending a live reaction to a video stream.

## Setup

To obtain a room reference, call `db.room(roomType, roomId)`:

```typescript
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';

// db will export all the presence hooks you need!
const db = init({ appId: APP_ID });

// Specifying a room type and room id gives you the power to
// restrict sharing to a specific room. However you can also just use
// `db.room()` to share presence and topics to an Instant generated default room
const roomId = 'hacker-chat-room-id';
const room = db.room('chat', roomId);
```

## Typesafety

By default rooms accept any kind of data. However, you can enforce typesafety with a schema:

```typescript
import { init } from '@interface-db/react';
import schema from '../instant.schema.ts';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID, schema });

const roomId = 'hacker-chat-room-id';
// The `chat` room is typed automatically from schema!
const room = db.room('chat', roomId);
```

Here's how we could add typesafety to our `chat` rooms:

```typescript
// instant.schema.ts

import { i } from '@interface-db/core';

const _schema = i.schema({
  // ...
  rooms: {
    // 1. `chat` is the `roomType`
    chat: {
      // 2. Choose what presence looks like here
      presence: i.entity({
        name: i.string(),
        status: i.string(),
      }),
      topics: {
        // 3. You can define payloads for different topics here
        sendEmoji: i.entity({
          emoji: i.string(),
        }),
      },
    },
  },
});

// This helps TypeScript display better IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Once you've updated your schema, you'll start seeing types in your IntelliSense:



## Presence

One common use case for presence is to show who's online.

Instant's `usePresence` is similar in feel to `useState`. It returns an object containing the current user's presence state, the presence state of every other user in the room, and a function (`publishPresence`) to update the current user's presence. `publishPresence` is similar to React's `setState` and will merge the current and new presence objects.

```tsx
import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';
const db = init({ appId: APP_ID });

const room = db.room('chat', 'hacker-chat-room-id');
const randomId = Math.random().toString(36).slice(2, 6);
const user = {
  name: `User#${randomId}`,
};

function App() {
  const {
    user: myPresence,
    peers,
    publishPresence,
  } = db.rooms.usePresence(
    room,
    // Publish your presence when you join the room
    { initialPresence: { name: user.name } },
  );

  // Update your presence when your name changes
  useEffect(() => {
    publishPresence({ name: user.name });
  }, [user.name]);

  if (!myPresence) {
    return <p>App loading...</p>;
  }

  return (
    <div>
      <h1>Who's online?</h1>
      <p>You are: {myPresence.name}</p>
      <h2>Others:</h2>
      <ul>
        {/* Loop through all peers and render their names. Peers will have the
          same properties as what you publish to the room. In this case, `name`
          is the only property we're publishing. Use RoomSchema to get type
          safety for your presence object.
      */}
        {Object.entries(peers).map(([peerId, peer]) => (
          <li key={peerId}>{peer.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

`usePresence` accepts a second parameter to select specific slices of the user's presence object.

```typescript
const room = db.room('chat', 'hacker-chat-room-id');

// We only return the `status` value for each peer
// We will _only_ trigger an update when a user's `status` value changes
const { user, peers, publishPresence } = db.rooms.usePresence(room, {
  keys: ['status'],
});
```

You may also specify an array of `peers` and a `user` flag to further constrain the output. If you wanted a "write-only" hook, it would look like this:

```typescript
// Will not trigger re-renders on presence changes
const room = db.room('chat', 'hacker-chat-room-id');

const { publishPresence } = db.rooms.usePresence(room, {
  peers: [],
  user: false,
});
```

## Topics

Instant provides 2 hooks for sending and handling events for a given topic. `usePublishTopic` returns a function you can call to publish an event, and `useTopicEffect` will be called each time a peer in the same room publishes a topic event.

Here's a live reaction feature using topics. You can also play with it live on [our recipes page](https://www.instantdb.com/recipes?#5-reactions)

```tsx 
'use client';

import { init } from '@interface-db/react';
import { RefObject, createRef, useRef } from 'react';

// Instant app
const APP_ID = '__APP_ID__';

// Set up room schema
const emoji = {
  fire: '🔥',
  wave: '👋',
  confetti: '🎉',
  heart: '❤️',
} as const;

type EmojiName = keyof typeof emoji;

const db = init({
  appId: APP_ID,
});

const room = db.room('main');

export default function InstantTopics() {
  // Use publishEmoji to broadcast to peers listening to `emoji` events.
  const publishEmoji = db.rooms.usePublishTopic(room, 'emoji');

  // Use useTopicEffect to listen for `emoji` events from peers
  // and animate their emojis on the screen.
  db.rooms.useTopicEffect(
    room,
    'emoji',
    ({ name, directionAngle, rotationAngle }) => {
      if (!emoji[name]) return;

      animateEmoji(
        { emoji: emoji[name], directionAngle, rotationAngle },
        elRefsRef.current[name].current,
      );
    },
  );

  const elRefsRef = useRef<{
    [k: string]: RefObject<HTMLDivElement>;
  }>(refsInit);

  return (
    <div className={containerClassNames}>
      <div className="flex gap-4">
        {emojiNames.map((name) => (
          <div className="relative" key={name} ref={elRefsRef.current[name]}>
            <button
              className={emojiButtonClassNames}
              /* We sent an emoji! Let's animate and broadcast it! */
              onClick={() => {
                const params = {
                  name,
                  rotationAngle: Math.random() * 360,
                  directionAngle: Math.random() * 360,
                };

                /* Animate the emoji on our screen */
                animateEmoji(
                  {
                    emoji: emoji[name],
                    rotationAngle: params.rotationAngle,
                    directionAngle: params.directionAngle,
                  },
                  elRefsRef.current[name].current,
                );

                /* Broadcast our emoji to our peers! */
                publishEmoji(params);
              }}
            >
              {emoji[name]}
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

// Below are helper functions and styles used to animate the emojis

const emojiNames = Object.keys(emoji) as EmojiName[];

const refsInit = Object.fromEntries(
  emojiNames.map((name) => [name, createRef<HTMLDivElement>()]),
);

const containerClassNames =
  'flex h-screen w-screen items-center justify-center overflow-hidden bg-gray-200 select-none';

const emojiButtonClassNames =
  'rounded-lg bg-white p-3 text-3xl shadow-lg transition duration-200 ease-in-out hover:-translate-y-1 hover:shadow-xl';

function animateEmoji(
  config: { emoji: string; directionAngle: number; rotationAngle: number },
  target: HTMLDivElement | null,
) {
  if (!target) return;

  const rootEl = document.createElement('div');
  const directionEl = document.createElement('div');
  const spinEl = document.createElement('div');

  spinEl.innerText = config.emoji;
  directionEl.appendChild(spinEl);
  rootEl.appendChild(directionEl);
  target.appendChild(rootEl);

  style(rootEl, {
    transform: `rotate(${config.directionAngle * 360}deg)`,
    position: 'absolute',
    top: '0',
    left: '0',
    right: '0',
    bottom: '0',
    margin: 'auto',
    zIndex: '9999',
    pointerEvents: 'none',
  });

  style(spinEl, {
    transform: `rotateZ(${config.rotationAngle * 400}deg)`,
    fontSize: `40px`,
  });

  setTimeout(() => {
    style(directionEl, {
      transform: `translateY(40vh) scale(2)`,
      transition: 'all 400ms',
      opacity: '0',
    });
  }, 20);

  setTimeout(() => rootEl.remove(), 800);
}

function style(el: HTMLElement, styles: Partial<CSSStyleDeclaration>) {
  Object.assign(el.style, styles);
}
```

## Cursors and Typing Indicators (React only)

We wanted to make adding real-time features to your apps as simple as possible, so we shipped our React library with 2 drop-in utilities: `Cursors` and `useTypingIndicator`.

### Cursors

Adding multiplayer cursors to your app is as simple as importing our `<Cursors>` component!

```tsx 
'use client';

import { init, Cursors } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

const room = db.room('chat', 'main');

export default function App() {
  return (
    <Cursors room={room} className="h-full w-full" userCursorColor="tomato">
      <div style={{ width: '100vw', height: '100vh' }}>
        Open two tabs, and move your cursor around!
      </div>
    </Cursors>
  );
}
```

You can provide a `renderCursor` function to return your own custom cursor component.

```tsx
<Cursors
  room={room}
  className="cursors"
  userCursorColor="papayawhip"
  renderCursor={renderCoolCustomCursor}
/>
```

You can render multiple cursor spaces. For instance, imagine you're building a screen with multiple tabs. You want to only show cursors on the same tab as the current user. You can provide each `<Cursors />` element with their own `spaceId`.

```tsx
<Tabs>
  {tabs.map((tab) => (
    <Tab>
      <Cursors room={room} spaceId={`tab-${tab.id}`} className="tab-cursor">
        {/* ... */}
      </Cursors>
    </Tab>
  ))}
</Tabs>
```

### Typing indicators

`useTypingIndicator` is a small utility useful for building inputs for chat-style apps. You can use this hook to show things like "<user> is typing..." in your chat app.

```tsx 
'use client';

import { init } from '@interface-db/react';

// Instant app
const APP_ID = '__APP_ID__';

const db = init({ appId: APP_ID });

const randomId = Math.random().toString(36).slice(2, 6);
const user = {
  name: `User#${randomId}`,
};

const room = db.room('chat', 'hacker-chat-room-id');

export default function InstantTypingIndicator() {
  // 1. Publish your presence in the room.
  db.rooms.useSyncPresence(room, user);

  // 2. Use the typing indicator hook
  const typing = db.rooms.useTypingIndicator(room, 'chat');

  const onKeyDown = (e) => {
    // 3. Render typing indicator
    typing.inputProps.onKeyDown(e);

    // 4. Optionally run your own onKeyDown logic
    if (e.key === 'Enter' && !e.shiftKey) {
      e.preventDefault();
      console.log('Message sent:', e.target.value);
    }
  };

  return (
    <div className="flex h-screen gap-3 p-2">
      <div key="main" className="flex flex-1 flex-col justify-end">
        <textarea
          onBlur={typing.inputProps.onBlur}
          onKeyDown={onKeyDown}
          placeholder="Open two tabs and start typing..."
          className="w-full rounded-md border-gray-300 p-2 text-sm"
        />
        <div className="truncate text-xs text-gray-500">
          {typing.active.length ? typingInfo(typing.active) : <>&nbsp;</>}
        </div>
      </div>
    </div>
  );
}

function typingInfo(users) {
  if (users.length === 0) return null;
  if (users.length === 1) return `${users[0].name} is typing...`;
  if (users.length === 2)
    return `${users[0].name} and ${users[1].name} are typing...`;

  return `${users[0].name} and ${users.length - 1} others are typing...`;
}
```

## PresencePeer Type

When working with presence, you can use `PresencePeer` for typing `user` and `peers`
values returned from `db.rooms.usePresence`.

```typescript
import { PresencePeer } from '@interface-db/react';
import { AppSchema } from '../instant.schema.ts';
import { db } from '../lib/db.ts';

type ChatPeer = PresencePeer<AppSchema, 'chat'>;
// Result: { peerId: string; avatar: string; name: string }

const room = db.room('chat')

function UserAvatar({ peer }: { peer: ChatPeer }) {
  return (
    <div>
      <img src={peer.avatar} alt={peer.name} />
    </div>
  );
}

function OnlineAvatars({ name, avatar }: { name: string; avatar: string }) {
  // Subscribe and publish initial presence
  const { user: myPresence, peers } = db.rooms.usePresence(room, {
    initialPresence: { name, avatar },
  });

  // Render my avatar and all peer avatars
  return (
    <div>
      {myPresence && <UserAvatar key={myPresence.peerId} peer={myPresence} />}
      {Object.values(peers).map((peer: ChatPeer) => (
        <UserAvatar key={peer.peerId} peer={peer} />
      ))}
    </div>
  );
}
```


# Instant CLI

How to use the Instant CLI to manage schema and permissions.

The Instant CLI was designed to drive your Instant application entirely from a project's codebase. You can create apps, define your data model, and update your permissions, **all through your terminal**.

## Login

To get started, you need to log in to your Instant account. You can do this by running:

```shell 
npx @interface-db/cli@latest login
```

This will open a browser window where you can authenticate with your Instant account. Once authenticated, you'll be able to run commands that interact with your Instant apps!

## Logout

To log out of your Instant account and remove your authentication token from your local device, run:

```shell 
npx @interface-db/cli@latest logout
```

This will clear your stored credentials. You'll need to log in again to interact with your Instant apps.

## Init

After logging in, head on over to your project's root repository, and write:

```shell 
npx @interface-db/cli@latest init
```

This will guide you through picking an Instant app and generate two files for you:

- `instant.schema.ts` defines your application's data model.
- `instant.perms.ts` defines your permission rules.

If you want to quickly spin up a temporary app (for experiments or testing), you can use the `--temp` flag:

```shell 
npx @interface-db/cli@latest init --temp
```

This will create an ephemeral app that automatically deletes itself after 24 hours. You can later transfer a temporary app to your account with `instant-cli claim`.

To learn how to change `instant.schema.ts`, check out our [Modeling Data](/docs/modeling-data). For `instant.perms.ts`, check out the [permissions](/docs/permissions) page.

## Push

When you're ready to publish your changes to `instant.schema.ts`, run:

```shell 
npx @interface-db/cli@latest push schema
```

This will evaluate your schema, compare it with production, and migrate your data model.

Similarly, when you change `instant.perms.ts`, you can run:

```shell 
npx @interface-db/cli@latest push perms
```

## Renaming fields

When you rename an attribute or link in your `instant.schema.ts` and push, the CLI needs to know whether you intend to **rename** the existing field or **delete** the old one and **create** a new one. By default, `push` will prompt you interactively:

```
Is posts.creator created or renamed from another attr?
  ~ posts.author › posts.creator    rename attr
  + posts.creator                   create attr
```

Use the arrow keys to select whether the field is a rename or a new creation.

### Renaming in CI

If you're running `push` in a non-interactive environment (e.g. CI), you can pass the `--rename` flag to specify renames explicitly:

```shell
npx @interface-db/cli@latest push schema --rename posts.author:posts.creator
```

The format is `oldName:newName`. You can rename multiple fields at once:

```shell
npx @interface-db/cli@latest push schema --rename posts.author:posts.creator stores.owner:stores.manager
```

This is especially useful when combined with `--yes` to skip confirmation prompts:

```shell
npx @interface-db/cli@latest push schema --yes --rename posts.author:posts.creator
```

## Pull

Sometimes, you change your schema or rules from your Explorer. If you want to `pull` the latest version of schema and perms for production, write:

```shell 
npx @interface-db/cli@latest pull
```

This will generate new `instant.schema.ts` and `instant.perms.ts` files, based on your production state.

## Query

You can run InstaQL queries against your app directly from the terminal:

```shell 
npx @interface-db/cli@latest query '{ posts: { comments: {} } }'
```

This outputs clean JSON to stdout, making it easy to pipe into `jq` or use in scripts. It supports JSON5 syntax, so you don't need to quote your keys.

Each query requires an auth context flag:

- `--admin` bypasses permissions (default)
- `--as-email <email>` runs the query as a specific user with permissions applied
- `--as-guest` runs the query as an unauthenticated guest
- `--as-token <refresh-token>` runs the query as a user identified by their refresh token

For example, to see what a specific user can access:

```shell 
npx @interface-db/cli@latest query --as-email alice@example.com '{ posts: {} }'
```

The results match what your client queries return, including cardinality. If your schema defines a relationship as `has: "one"`, you'll get back a single object instead of an array.

## App ID

Whenever you run a CLI command, we look up your app ID. You can either provide an app ID as an option:

```shell
  npx @interface-db/cli@latest init --app $MY_APP_ID
```

Or store it in your `.env` file:

```yaml
INSTANT_APP_ID=*****
```

As a convenience, apart from `INSTANT_APP_ID`, we also check for:

- `NEXT_PUBLIC_INSTANT_APP_ID` for next apps,
- `PUBLIC_INSTANT_APP_ID` for svelte apps,
- `VITE_INSTANT_APP_ID` for vite apps
- `NUXT_PUBLIC_INSTANT_APP_ID` for nuxt apps
- `EXPO_PUBLIC_INSTANT_APP_ID` for expo apps

## Where to save files

By default, Instant will search for your `instant.schema.ts` and `instant.perms.ts` files in:

1. The `root` directory: `./`
2. The `src` directory: `./src`
3. The `app` directory: `./app`

If you'd like to save them in a custom location, you can set the following environment variables:

- `INSTANT_SCHEMA_FILE_PATH` sets the location for your `instant.schema.ts` file.
- `INSTANT_PERMS_FILE_PATH` sets the location for your `instant.perms.ts` file.

```yaml
# in your .env file
INSTANT_SCHEMA_FILE_PATH=./src/db/instant.schema.ts
INSTANT_PERMS_FILE_PATH=./src/db/instant.perms.ts
```

## Authenticating in CI

In CI or similar environments, you may want to handle authentication without having to go through a web-based validation step each time.

In these cases, you can provide an `INSTANT_CLI_AUTH_TOKEN` environment variable.

To obtain a token for later use, run:

```shell 
npx @interface-db/cli@latest login -p
```

Instead of saving the token to your local device, the CLI will print it to your console. You can copy this token and provide it as `INSTANT_CLI_AUTH_TOKEN` later in your CI tool.

## Init without creating files

Sometimes you want to create an Instant app without generating `instant.schema.ts` and `instant.perms.ts` or modifying your .env files. You can do this by running:

```shell 
npx @interface-db/cli@latest init-without-files --title "Hello World"
```

The app's ID and admin token are outputted to stdout as JSON:

```shell
{
  "app": {
    "appId": "4f1e575c-6c00-44dd-bc69-004e89b9d788",
    "adminToken": "67ce37cb-aa47-468d-9c54-99efcf40497f"
  },
  "error": null
}
```

You can also make ephemeral apps that will clean themselves up after more than 24 hours
via the `--temp` flag:

```shell 
npx @interface-db/cli@latest init-without-files --title "Hello World" --temp
```

You can also pipe the output of this command to `jq` to extract the app information for use in scripts:

```shell 
output=$(npx @interface-db/cli@latest init-without-files --title "Hello World" --temp)
if echo "$output" | jq -e '.error' > /dev/null; then
  echo "Error: $(echo "$output" | jq -r '.error')"
  exit 1
fi
appId=$(echo "$output" | jq -r '.appId')
adminToken=$(echo "$output" | jq -r '.adminToken')
```

## OAuth clients and redirect origins

You can manage OAuth clients and redirect origins from the CLI in addition to the dashboard. Run `--help` on any subcommand for the full list of provider-specific flags.

```shell
# Add a Google web client using Instant's dev credentials
npx @interface-db/cli@latest auth client add \
  --type google --app-type web \
  --name google-web --dev-credentials

# List existing clients
npx @interface-db/cli@latest auth client list

# Upgrade a Google dev client to your own credentials
npx @interface-db/cli@latest auth client update \
  --name google-web \
  --client-id <id> --client-secret <secret>

# Add a redirect origin
npx @interface-db/cli@latest auth origin add \
  --type website --url <your-domain>
```

## Magic Code Templates

You can manage your email templates for sending magic codes by using an `instant.email.ts` file in your codebase.

To create the file and pull in the current configuration:

```shell
npx @interface-db/cli@latest auth email pull
```

It will create a file like this:

```typescript
// We provide a few dynamic variables for you to use in your email:
// {code}, the magic code e.g. 123456
// {app_title}, your app's title, i.e. test-fresh
// {user_email}, the user's email address, e.g. happyuser@gmail.com
// {expiration}, the magic code expiration, e.g. 10 minutes
// Note: {code} is required in both the subject and body.
const email = {
  authEmail: {
    subject: '{code} is your verification code for {app_title}',
    senderName: 'test-fresh',
    senderEmail: 'verify@drewh.cloud',
    body: `<div style="background: #f6f6f6; font-family: Helvetica, Arial, sans-serif; line-height: 1.6; font-size: 18px;">
      <div style="max-width: 650px; margin: 0 auto; background: white; padding: 20px;">
        <p><strong>Welcome,</strong></p>
        <p>
          You asked to join {app_title}. To complete your registration, use this
          verification code:
        </p>
        <h2 style="text-align: center"><strong>{code}</strong></h2>
        <p>
          Copy and paste this into the confirmation box, and you'll be on your way.
        </p>
        <p>
          Note: This code will expire in {expiration} and can only be used once. If
          you didn't request this code, please reply to this email.
        </p>
      </div>
    </div>
`,
  },
};
```

Just like on the dashboard, you can use the [variables available for the subject line and body](/docs/emails#variables)

Note: {code} is required in both the subject and body.

Commands to manage the email template:

```shell
# Save your changes to `instant.email.ts`
npx @interface-db/cli@latest auth email push

# View the status of the email configuration and verification
npx @interface-db/cli@latest auth email status

# Reset your email template to the Instant default template (only updates the file, requires push)
npx @interface-db/cli@latest auth email reset

# Verify a custom email address using the code sent to the email.
npx @interface-db/cli@latest auth email verify <code>

# Resend the custom address verification email
npx @interface-db/cli@latest auth email resend
```


# Devtool

Use the Instant devtool to inspect your app in development.

When you load your app in development, you'll notice a little "Instant" icon show up:



This is your handy `devtool` shortcut. Once you click it, you'll see a widget that lets you make changes to your app.

Use the `Explorer` to change up your data and schema:



Or the `Sandbox` to try out different queries and transactions:



## Changing Positions

You can choose where to position your devtool as well. Pass in the `devtool` configuration in `init`:

```typescript
import { init } from '@interface-db/react';

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: {
    position: 'bottom-right',
  },
});
```

You can set it to `bottom-left`, `top-left`, `top-right`, or `bottom-right`.

## Custom Hosts

By default, the devtool only shows up on `localhost`. But you can decide which hosts to show it on too. Pass in the `allowedHosts` option:

```typescript
import { init } from '@interface-db/react';

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: {
    allowedHosts: ['localhost', 'site.local'],
  },
});
```

## Self-hosted dashboards

When connecting to a self-hosted Instant deployment, set `dashURI` to the
deployment's dashboard URL:

```typescript
import { init } from '@interface-db/react';

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  apiURI: 'https://api.myinstant.com',
  websocketURI: 'wss://api.myinstant.com/runtime/session',
  devtool: {
    dashURI: 'https://dash.myinstant.com',
  },
});
```

The devtool will use your self-hosted dashboard for authentication and app
management.

## Disabling the devtool

If you would like to hide the devtool completely, you can add `devtool: false` in `init`:

```typescript
import { init } from '@interface-db/react';

import schema from '../instant.schema.ts';

const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  devtool: false,
});
```

## Shortcuts

To quickly toggle the window, you can use the shortcut `ctrl` + `shift` + `0` (zero).



## Feedback?

If you have any feedback, let us know on [Discord](https://discord.com/invite/VU53p7uQcE).




# Platform API

Spin up Instant apps on demand and manage schema with the Platform API.

You can use Instant to programmatically create apps, push schemas and manage permissions. This is particularly powerful in two scenarios:

- **App Builders**: If you're an app builder, you can give your customers a backend. It takes only an hour to set up the platform, and every app your users create gets a full backend as a result. LLMs are great at using Instant: they can make more progress with fewer tokens and fewer mistakes.
- **Software teams**: If you're a software team, you can improve your development workflows: create apps for different pull requests, or spin up temporary apps for tests.

In this document, we'll show you:

1. The tools at your disposal
2. How to create temporary apps
3. How to create long-lived apps
4. How to manage schemas and permissions

Let's get into it!

## CLI & SDK

To manage apps, you have two main tools at your disposal.

You can either use the Instant CLI:

```bash
npx @interface-db/cli
```

Or if you are running a backend server, the Platform SDK:

```bash
npm install @interface-db/platform
```

Let's see how to use them.

## Temporary Apps

First things first, let's create a temporary app.

A temporary app is an Instant app that deletes itself in 2 weeks. You can use it to run quick experiments or spin apps up for tests.

You don't need to authenticate to create temporary apps, so they're a great way to get a sense of our tools.

**Here's how to make a temporary app with the CLI:**

```bash
npx @interface-db/cli init-without-files --title my-new-app --temp
```

And voila, you have a temporary app:

```bash
Successfully created new app!

{
  "app": {
    "appId": "...",
    "adminToken": "..."
  },
  "error": null
}
```

**And here's how to make a temporary app with the Platform SDK:**

```typescript
import { PlatformApi, i } from '@interface-db/platform';

const api = new PlatformApi({});

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
    }),
  },
});

const perms = {
  todos: {
    allow: {
      $default: 'true',
    },
  },
};

const app = await api.createTemporaryApp({
  title: 'my-new-app',
  schema: schema,
  rules: { code: perms },
});

console.log('app ->', app);
```

```bash
app -> {
  app: {
    id: '....',
    adminToken: '...'
    title: 'my-new-app',
    createdAt: '...'
    orgId: null,
  },
  ...
}
```

You can use this app `id` and `adminToken` in Instant SDKs.

Temporary apps are great, but they only last 2 weeks. What if you want to make apps that last forever?

## Long-lived apps

To create long-lived apps, you'll need to authenticate first.

### Authentication for creating apps

You have two options to authenticate and create long-lived apps:

**Option 1: Personal Access Tokens**

The quickest way to get started is to create a Personal Access Token. You can create Personal Access Tokens by going to user settings in "Dashboard -> Settings -> New Access Token". Here's a direct [link](https://www.instantdb.com/dash/user-settings).

Once you click "New Access Token", you'll get a token that looks like this:

```bash
per_xxx11x1xxx1xx1x11x1x1111xxx1xx11x11xxxx1x1x1x1111xxx11111xxx111x
```

When you use this token to create apps, they will get associated with the account where you created the token.

**Option 2: Let users Sign in with Instant**

Alternatively, you can create a "Sign in with Instant" button in your app. This button would let end-users provide their own Instant accounts and give you permissions to manage apps on their behalf.

To do this, you can use the Platform SDK and set up OAuth. Follow the tutorial in the [Platform OAuth Guide](https://github.com/instantdb/instant/tree/main/client/packages/platform#oauth-flow) to see how to do that.

When you're done and a user clicks "Sign in with Instant" in your app, you'll get a token that looks like this:

```bash
prt_xxx11x1xxx1xx1x11x1x1111xxx1xx11x11xxxx1x1x1x1111xxx11111xxx111x
```

When you use this token to create apps, they will get associated with that user's account.

### Create long-lived apps

Now that we have auth tokens, let's use them to create an app.

**To create a long-lived app with the CLI:**

```bash
npx @interface-db/cli init-without-files --title my-long-lived-app --token YOUR_TOKEN
```

Pretty nice!

**And similarly, for the platform API:**

```javascript
import { PlatformApi } from '@interface-db/platform';

const api = new PlatformApi({
  auth: { token: 'YOUR_TOKEN' } })
});

const app = await api.createApp({
  title: 'my-new-app'
})
```

With that, you'll have long-lived apps!

## Managing schemas and permissions

Now that you have an app, you can change schemas and permissions too.

**To change schemas and perms with the CLI:**

If you are using the CLI, you'll have your `instant.schema.ts` and `instant.perms.ts` files in your directory. Run the [standard](/docs/cli) CLI push command with your token:

```ts
// src/instant.schema.ts
import { i } from '@interface-db/react';

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
      completedAt: i.date().optional(),
    }),
  },
});
```

```bash
npx @interface-db/cli push schema --token YOUR_TOKEN
```

**To change schemas and perms with the platform SDK:**

For the platform SDK, you can use the corresponding `schemaPush` command.

Here's a snippet for schema push:

```typescript
import { PlatformApi, i } from '@interface-db/platform';

const schema = i.schema({
  entities: {
    todos: i.entity({
      title: i.string().indexed(),
      done: i.boolean(),
      completedAt: i.date().optional(),
    }),
  },
});

await api.schemaPush(YOUR_APP_ID, {
  overwrite: true,
  schema: schema,
  renames: ['todos.name:todos.title'],
});
```

To see more examples, check out the [Platform SDK reference](https://github.com/instantdb/instant/tree/main/client/packages/platform#making-api-requests).

### Note: scoping tokens per app

You can always use the access tokens you created to change schemas and permissions, but you may not always want to, especially from the CLI.

For example, if you're an app builder, you may create a sandbox that lets an agent change schemas and permissions. If you gave the agent access to these tokens, they could change _any_ app associated with the token.

What you really want in those cases is to get a token _scoped_ to a particular app.

**You can use admin tokens this way.** Simply provide the admin token as auth, and the CLI will only have access to change schema and perms just on that app.

```bash
npx @interface-db/cli push schema --token YOUR_ADMIN_TOKEN
```

### Questions?



This is a living document. If you have any questions, reach out to us on [Discord](https://discord.com/invite/VU53p7uQcE)!




# Explorer Component

Use the Explorer Component in your own apps

The explorer page from the Instant Dashboard is available as an installable React component that you can use in your own apps. This is especially useful if you're building **a platform or app builder** powered by Instant.

```tsx
import './App.css';
import { Explorer, Toaster } from '@interface-db/components';

function App() {
  return (
    <>
      <Explorer
        className="h-full"
        useShadowDOM={false}
        darkMode={false}
        appId={import.meta.env.VITE_INSTANT_APP_ID}
        adminToken={import.meta.env.VITE_INSTANT_ADMIN_TOKEN}
      />
      <Toaster position="top-right" />
    </>
  );
}
```

The Toaster component is required for pop-up alerts, unless you are already using [Sonner](https://sonner.emilkowal.ski/) in your project.


The component accepts `explorerState` and `setExplorerState` props for manual control over the state of the Explorer.


# CSS

## Projects Using Tailwind

For projects using Tailwind, add the component library to your Tailwind configuration.

Tailwind V3:

```js
// tailwind.config.js
module.exports = {
  content: [
    './lib/**/*.{js,ts,jsx,tsx}',
    './pages/**/*.{js,ts,jsx,tsx,md}',
    './_posts/**/*.{js,ts,jsx,tsx,md}',
    './components/**/*.{js,ts,jsx,tsx}',
    './utils/**/*.{js,ts,jsx,tsx}',
    './node_modules/@interface-db/components/src/**/*.{js,ts,jsx,tsx,md}',
  ],
};
```

Tailwind V4:

```css
@import 'tailwindcss';
@source '../node_modules/@interface-db/components';
```

---

## Projects Without Tailwind

For projects without Tailwind, to avoid CSS conflicts, the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) is used to isolate styles of the explorer.

```tsx
import './App.css';
import { Explorer, Toaster } from '@interface-db/components';

function App() {
  return (
    <>
      <Explorer
        className="h-full"
        useShadowDOM // this prop automatically applies styles
        appId={import.meta.env.VITE_INSTANT_APP_ID}
        adminToken={import.meta.env.VITE_INSTANT_ADMIN_TOKEN}
      />
      <Toaster position="top-right" />
    </>
  );
}
```


# Custom email templates and senders

How to customize magic code emails.

You can customize all aspects of your Instant app's "magic code" email: the body (plain text or HTML), subject, sender name, and even the `from` address.

## Dashboard

To start, go to your Dashboard's [auth tab](https://instantdb.com/dash?s=main&t=auth). Click "Custom Magic Code Email", and you're ready to go.

### Variables

We provide a handful of variables you can use in both your subject line and body template:

- `{code}`, the magic code, e.g. _123456_. Note, this variable is required in both the subject and body.
- `{user_email}`, the recipient user's email address, e.g. *happyuser@gmail.com*
- `{app_title}`, your app's name

Using a variable is as easy as adding the variable's name in curly brackets, e.g. `{variable_name}`.

```html
<p>Hi {user_email}, here's your code for {app_title}:</p>

<strong>{code}</strong>
```

## Custom sender addresses

You can also set the `from` and `reply-to` fields on Instant's emails to an address on your own domain.

If you provide a custom sender address, you'll need to confirm it before we can start delivering from it.

Our email partner, Postmark, will send a confirmation to the provided address with a link to verify it. Until the address is verified, emails will continue to be sent from Instant's default auth sender (`auth@pm.instantdb.com`).


# App teams (Pro)

How to manage your Instant app's team members and their roles.

Apps with a Pro subscription can be managed by multiple users. To add team members to your app, head on over to the [Dashboard Admin tab](https://instantdb.com/dash?s=main&t=admin).

## Roles

App team members can have one of three roles: collaborator, admin or owner.

#### Collaborators

- Can view the Explorer, update Permissions, and configure Auth.

#### Admins

- Can invite other team members.

#### Owners (i.e., an app's creator)

- Can access the Billing tab.
- Can regenerate the app's admin tokens.
- Can delete their app.

## Invites

#### Inviting a team member

A Pro app's admin or owner simply needs to navigate to the [Dashboard Admin tab](https://instantdb.com/dash?s=main&t=admin) and click "Invite a team member". This will open a dialog that accepts an email address and a role. This will send an email with instructions to the specified address.

#### Accepting an invite

Once an invited user signs up for Instant, they can access the [Dashboard Invites section](https://instantdb.com/dash?s=invites) where they can accept or decline the invite.


# Storage

How to upload and serve files with Instant.

Instant Storage makes it simple to upload and serve files for your app.
You can store images, videos, documents, and any other file type.

## Storage quick start

Let's build a full example of how to upload and display a grid of images:

```shell 
npx create-next-app instant-storage --tailwind --yes
cd instant-storage
npm i @interface-db/react
```

Initialize your schema and permissions via the [CLI tool](/docs/cli):

```
npx @interface-db/cli@latest init
```

Now open `instant.schema.ts` and replace the contents with the following code.

```javascript 
import { i } from "@interface-db/react";

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
  },
  links: {},
  rooms: {},
});

// This helps TypeScript display nicer IntelliSense
type _AppSchema = typeof _schema;
interface AppSchema extends _AppSchema {}
const schema: AppSchema = _schema;

export type { AppSchema };
export default schema;
```

Similarly, open `instant.perms.ts` and replace the contents with the following:

```javascript 
import type { InstantRules } from "@interface-db/react";

// Not recommended for production since this allows anyone to
// upload/delete, but good for getting started
const rules = {
  "$files": {
    "allow": {
      "view": "true",
      "create": "true",
      "delete": "true"
    }
  }
} satisfies InstantRules;

export default rules;
```

Push up both the schema and permissions to your Instant app with the following command:

```shell 
npx @interface-db/cli@latest push
```

And then replace the contents of `app/page.tsx` with the following code.

```javascript 
'use client';

import { init, InstaQLEntity } from '@interface-db/react';
import schema, { AppSchema } from '../instant.schema';
import React from 'react';

type InstantFile = InstaQLEntity<AppSchema, '$files'>

const APP_ID = process.env.NEXT_PUBLIC_INSTANT_APP_ID;

const db = init({ appId: APP_ID, schema });

// `uploadFile` is what we use to do the actual upload!
// The `$files` query will automatically update once the upload is complete
async function uploadImage(file: File) {
  try {
    // Optional metadata you can set for uploads
    const opts = {
      // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
      // Default: 'application/octet-stream'
      contentType: file.type,
      // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
      // Default: 'inline'
      contentDisposition: 'attachment',
    };
    await db.storage.uploadFile(file.name, file, opts);
  } catch (error) {
    console.error('Error uploading image:', error);
  }
}

function App() {
  // $files is the special namespace for querying storage data
  const { isLoading, error, data } = db.useQuery({
    $files: {
      $: {
        order: { serverCreatedAt: 'asc' },
      },
    },
  });

  if (isLoading) {
    return null;
  }

  if (error) {
    return <div>Error fetching data: {error.message}</div>;
  }

  // The result of a $files query will contain objects with
  // metadata and a download URL you can use for serving files!
  const { $files: images } = data
  return (
    <div className="box-border bg-gray-50 font-mono min-h-screen p-5 flex items-center flex-col">
      <div className="tracking-wider text-5xl text-gray-300 mb-8">
        Image Feed
      </div>
      <ImageUpload />
      <div className="text-xs text-center py-4">
        Upload some images and they will appear below! Open another tab and see
        the changes in real-time!
      </div>
      <ImageGrid images={images} />
    </div>
  );
}

interface SelectedFile {
  file: File;
  previewURL: string;
}

function ImageUpload() {
  const [selectedFile, setSelectedFile] = React.useState<SelectedFile | null>(null);
  const [isUploading, setIsUploading] = React.useState(false);
  const fileInputRef = React.useRef<HTMLInputElement>(null);
  const { previewURL } = selectedFile || {};

  const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      const previewURL = URL.createObjectURL(file);
      setSelectedFile({ file, previewURL });
    }
  };

  const handleUpload = async () => {
    if (selectedFile) {
      setIsUploading(true);

      await uploadImage(selectedFile.file);

      URL.revokeObjectURL(selectedFile.previewURL);
      setSelectedFile(null);
      fileInputRef.current?.value && (fileInputRef.current.value = '');
      setIsUploading(false);
    }
  };

  return (
    <div className="mb-8 p-5 border-2 border-dashed border-gray-300 rounded-lg">
      <input
        ref={fileInputRef}
        type="file"
        accept="image/*"
        onChange={handleFileSelect}
        className="font-mono"
      />
      {isUploading ? (
        <div className="mt-5 flex flex-col items-center">
          <div className="w-8 h-8 border-2 border-t-2 border-gray-200 border-t-green-500 rounded-full animate-spin"></div>
          <p className="mt-2 text-sm text-gray-600">Uploading...</p>
        </div>
      ) : previewURL && (
        <div className="mt-5 flex flex-col items-center gap-3">
          <img src={previewURL} alt="Preview" className="max-w-xs max-h-xs object-contain" />
          <button onClick={handleUpload} className="py-2 px-4 bg-green-500 text-white border-none rounded-sm cursor-pointer font-mono">
            Upload Image
          </button>
        </div>
      )}
    </div>
  );
}

function ImageGrid({ images }: { images: InstantFile[] }) {
  // Use `db.transact` to delete files
  const handleDelete = async (image: InstantFile) => {
    db.transact(db.tx.$files[image.id].delete());
  }

  return (
    <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-5 w-full max-w-6xl">
      {images.map((image) => {
        return (
          <div key={image.id} className="border border-gray-300 rounded-lg overflow-hidden">
            <div className="relative">
              {/* $files entities come with a `url` property */}
              <img src={image.url} alt={image.path} className="w-full h-64 object-cover" />
            </div>

            <div className="p-3 flex justify-between items-center bg-white">
              <span>{image.path}</span>
              <span onClick={() => handleDelete(image)} className="cursor-pointer text-gray-300 px-1">
                𝘟
              </span>
            </div>
          </div>
        )
      })}
    </div>
  );
}

export default App;
```

With your schema, permissions, and application code set, you can now run your app!

```shell 
npm run dev
```

Go to `localhost:3000`, and you should see a simple image feed where you can
upload and delete images!

## Storage client SDK

Below you'll find a more detailed guide on how to use the Storage API from
React.

### Upload files

Use `db.storage.uploadFile(path, file, opts?)` to upload a file.

- `path` determines where the file will be stored and can be used with permissions to restrict access to certain files.
- `file` should be a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) type, which will likely come from a [file-type input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file).
- `opts` can be used to set additional metadata like `contentType` and `contentDisposition`

```javascript
// use the file's current name as the path
await db.storage.uploadFile(file.name, file);

// or, give the file a custom name
const path = `${user.id}/avatar.png`;
await db.storage.uploadFile(path, file);

// or, set the content type and content disposition
const path = `${user.id}/orders/${orderId}.pdf`;
await db.storage.uploadFile(path, file, {
  contentType: 'application/pdf',
  contentDisposition: `attachment; filename="${orderId}-confirmation.pdf"`,
});
```

### Overwrite files

If the `path` already exists in your storage directory, it will be overwritten!

```javascript
// Uploads a file to 'demo.png'
await db.storage.uploadFile('demo.png', file);

// Overwrites the file at 'demo.png'
await db.storage.uploadFile('demo.png', file);
```

If you don't want to overwrite files, you'll need to ensure that each file has a unique path.

### View files

You can retrieve files by querying the `$files` namespace.

```javascript
// Fetch all files from earliest to latest upload
const query = {
  $files: {
    $: {
      order: { serverCreatedAt: 'asc' },
    },
  },
});
const { isLoading, error, data } = db.useQuery(query);
```

```javascript
console.log(data)
{
  "$files": [
    {
      "id": fileId,
      "path": "demo.png"
      // You can use this URL to serve the file
      "url": "https://instant-storage.s3.amazonaws.com/...",
      "content-type": "image/png",
      "content-disposition": "attachment; filename=\"demo.png\"",
    },
    // ...
  ]
}
```

You can use query filters and associations as you would with any other namespace
to filter and sort your files.

```javascript 
// instant.schema.ts
// ---------------
import { i } from '@interface-db/core';
const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      url: i.string(),
    }),
    $users: i.entity({
      email: i.string().unique().indexed(),
    }),
    profiles: i.entity({
      nickname: i.string(),
      createdAt: i.date(),
    }),
  },
  links: {
    profileUser: {
      forward: { on: 'profiles', has: 'one', label: '$user' },
      reverse: { on: '$users', has: 'one', label: 'profile' },
    },
    profileUploads: {
      forward: { on: 'profiles', has: 'many', label: '$files' },
      reverse: { on: '$files', has: 'one', label: 'profile' },
    },
  },
});
```

```javascript 
// app/page.tsx
// ---------------
// Find files associated with a profile
const { user } = db.useAuth();
const query = {
  profiles: {
    $: {
      where: {"$user.id": user.id}
    },
    $files: {},
  },
});
// Defer until we've fetched the user and then query associated files
const { isLoading, error, data } = db.useQuery(user ? query : null);
```

### Delete files

Use `db.transact` to delete files.

```javascript
// Delete by id
db.transact(db.tx.$files[fileId].delete());

// Delete by path
db.transact(db.tx.$files[lookup('path', 'photos/demo.png')].delete());

// Delete multiple files
db.transact(fileIds.map((id) => db.tx.$files[id].delete()));
```

### Update files

You can use `db.transact` to update file paths, as well as any custom columns you've added to files.

So if your schema looked like this:

```javascript
import { i } from "@interface-db/react";

const _schema = i.schema({
  entities: {
    $files: i.entity({
      path: i.string().unique().indexed(),
      isFavorite: i.boolean().optional()
      url: i.string(),
    }),
  },
});
```

You could run a transaction like this:

```javascript
// Move all files under 'documents/my-video-project/' to 'videos/my-video-project/' and make them favorites

const { data } = await db.query({
  $files: { $: { where: { path: { $like: 'documents/my-video-project/%' } } } },
});

await db.transact(
  data.$files.map((file) =>
    db.tx.$files[file.id].update({
      path: file.path.replace(
        'documents/my-video-project/',
        'videos/my-video-project/',
      ),
      isFavorite: true,
    }),
  ),
);
```

`path` is a unique attribute, so if another file exists with that path, then the transaction
will fail.

At the moment we only allow updating the `path` attribute of `$files`, as well as any custom columns you've created. If you
try to update another attribute like `content-type` the transaction will fail.

### Link files

When the upload succeeds, `uploadFile` returns a `data` object containing a file ID associated with the uploaded file. You can use this ID to link the file to other namespaces.

```javascript
async function uploadImage(file: File) {
  try {
    const path = `${user.id}/avatar`;
    const { data } = await db.storage.uploadFile(path, file);
    await db.transact(db.tx.profiles[profileId].link({ avatar: data.id }));
  } catch (error) {
    console.error('Error uploading image:', error);
  }
}
```

[Check out this repo](https://github.com/jsventures/instant-storage-avatar-example)
for a more detailed example showing how you may leverage links to implement an avatar upload feature.

## Using Storage with React Native

`db.storage.uploadFile` expects a `File` or `Blob`.

On Expo SDK 56 and above, `expo/fetch` is the global `fetch` and reads local
files directly, so hand it a `File` from `expo-file-system`:

```typescript
import { File } from 'expo-file-system';

const localFilePath = 'file:///var/mobile/Containers/Data/my_file.m4a';
const file = new File(localFilePath);

await db.storage.uploadFile('my_file.m4a', file, {
  contentType: 'audio/x-m4a',
});
```

On Expo SDK 55 and below (or bare React Native), the built-in `fetch` returns a
native `Blob` you can wrap in a `File`:

```typescript
const localFilePath = 'file:///var/mobile/Containers/Data/my_file.m4a';
const res = await fetch(localFilePath);
const blob = await res.blob();
const file = new File([blob], 'my_file.m4a', { type: 'audio/x-m4a' });

await db.storage.uploadFile('my_file.m4a', file);
```

## Storage Admin SDK

The Admin SDK offers a similar API for managing storage on the server. Permission
checks are not enforced when using the Admin SDK, so you can use it to manage
files without worrying about authentication.

### Uploading files

`db.storage.uploadFile(path, file, opts?)` is also available to upload a file
on the backend. In the Admin SDK, the `file` argument must either be a buffer
or a stream.

```tsx
import fs from 'fs';

const fp = 'path/to/your/file.png';
const dest = 'images/demo.png';

// Upload a file from a buffer
const buffer = fs.readFileSync(filepath);
const { data } = await db.storage.uploadFile(dest, buffer);

// Upload a file from a stream
// IMPORTANT: You must provide `fileSize` as an option when uploading via stream
const stream = fs.createReadStream(fp);
const fileSize = fs.statSync(fp).size;
const { data } = await db.storage.uploadFile(dest, stream, {
  contentType: contentType,
  fileSize,
});
```

### View Files

Retrieving files is similar to the client SDK, but we use `db.query()` instead
of `db.useQuery()`.

```ts
const query = {
  $files: {
    $: {
      order: { serverCreatedAt: 'asc' },
    },
  },
});
const data = db.query(query);
```

### Delete files

Use `db.transact` to delete files.

```ts
// Delete by id
await db.transact(db.tx.$files[fileId].delete());

// Delete by path
await db.transact(db.tx.$files[lookup('path', 'photos/demo.png')].delete());

// Delete multiple files
await db.transact(fileIds.map((id) => db.tx.$files[id].delete()));
```

### Link files

As with the client SDK, you can use the response after uploading a file to link
the upload to other entities.

```typescript
// Assume we have a user ID and a buffer for the file
const { data } = await db.storage.uploadFile('images/demo.png', buffer);
db.transact([db.tx.$users[userId].link({ avatar: data.id })]);
```

## Permissions

By default, Storage permissions are disabled. This means that until you explicitly set permissions, no uploads or downloads will be possible.

- _create_ permissions enable uploading `$files`
- _view_ permissions enable viewing `$files`
- _update_ permissions enable updating `$files`
- _delete_ permissions enable deleting `$files`
- _view_ permissions on `$files` and _update_ permissions on the forward entity enable linking and unlinking `$files`

In your permissions rules, you can use `auth` to access the currently authenticated user, and `data` to access the file metadata.

At the moment, the only available file metadata is `data.path`, which represents the file's path in Storage. Here are some example permissions:

Allow anyone to upload and retrieve files (easy to play with but not recommended for production):

```json
{
  "$files": {
    "allow": {
      "view": "true",
      "create": "true"
    }
  }
}
```

Allow all authenticated users to view and upload files:

```json
{
  "$files": {
    "allow": {
      "view": "isLoggedIn",
      "create": "isLoggedIn"
    },
    "bind": ["isLoggedIn", "auth.id != null"]
  }
}
```

Authenticated users may only upload, view, and update files from their own subdirectory:

```json
{
  "$files": {
    "allow": {
      "view": "isOwner",
      "update": "isOwner",
      "create": "isOwner"
    },
    "bind": ["isOwner", "data.path.startsWith(auth.id + '/')"]
  }
}
```


# Streams

How to stream and persist data with Instant.

Instant Streams provide a simple way to build durable, real-time data flows. They are excellent for LLM-native applications, making it easy to stream AI chat completions.

## How Streams work

Instant streams implement the standard [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). When you create a write stream, the most recent data is buffered in memory on Instant's servers. The stream is periodically flushed to [Storage](/docs/storage) and is fully flushed to storage when finished.

Because streams are backed by storage, they never expire. A reader can pick up from any point in the stream, and resume if the connection is lost.

## Streams client SDK

### Creating a Write Stream

Use `const stream = db.streams.createWriteStream({ clientId })` to create a new writable stream.

- `clientId`: A unique ID for your stream. If the `clientId` is already taken, the stream will enter an error state and `await stream.streamId()` will throw an error. There can only be one writer per `clientId`.

```javascript 
const stream = db.streams.createWriteStream({ clientId: 'my-unique-stream' });
const writer = stream.getWriter();

writer.write('First chunk\n');
writer.write('Second chunk\n');

// Get the persistent ID of the stream
const streamId = await stream.streamId();

await writer.close();
```

### Creating a Read Stream

Use `db.streams.createReadStream({ clientId })` or `db.streams.createReadStream({ streamId })` to read from a stream.

- `clientId`: Find the stream by the client-provided ID.
- `streamId`: Find the stream by the server-generated UUID that Instant assigns when the stream is created.
- `byteOffset`: Optionally start reading from a specific offset.

If the stream does not exist, the stream will enter an error state and return an error from `read()`.

```javascript 
const stream = db.streams.createReadStream({ clientId: 'my-unique-stream' });
const reader = stream.getReader();

try {
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    console.log('Received:', value);
  }
} catch (error) {
  console.error('Error reading stream:', error);
} finally {
  reader.releaseLock();
}
```

### Querying Stream Metadata

You can retrieve stream metadata by querying the `$streams` namespace.

```javascript 
const { data } = db.useQuery({
  $streams: {
    $: {
      where: { clientId: 'my-unique-stream' },
    },
  },
});
```

The `$streams` entity contains useful information:

- `id`: The persistent stream ID, assigned by the server.
- `clientId`: The ID you provided when creating the stream.
- `done`: A boolean indicating if the stream has been closed.
- `size`: The total number of bytes written to the stream. This will be `null` until `done` is true.
- `abortReason`: A string describing why the stream was aborted, if applicable.

### Customizing Stream Metadata

You can add your own custom columns to the `$streams` table and update them with `db.transact` just like any other entity.

However, all system columns (like `clientId`, `done`, and `size`) are read-only and cannot be edited. If you try to update them directly, the transaction will fail.

### Linking Streams to Entities

When a stream is created, you can get its ID and link it to other entities in your schema. This is useful for associating a stream with a specific user, chat, or project.

First, define the link in your schema:

```ts 
// instant.schema.ts
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    $streams: i.entity({
      abortReason: i.string().optional(),
      clientId: i.string().unique().indexed(),
      done: i.boolean().optional(),
      size: i.number().optional(),
    }),
    chats: i.entity({
      title: i.string().optional(),
    }),
  },
  links: {
    chatStream: {
      forward: { on: 'chats', has: 'one', label: 'stream' },
      reverse: { on: '$streams', has: 'one', label: 'chat' },
    },
  },
});

export default _schema;
```

Then link the stream after creating it:

```javascript 
const stream = db.streams.createWriteStream({ clientId: 'my-chat-session' });
const streamId = await stream.streamId();

// Link the stream to a chat entity
db.transact(db.tx.chats[chatId].link({ stream: streamId }));
```

### Permissions

By default, all rules for streams are set to `"false"`. This means that until you explicitly set rules, non-admins won't be able to view or modify streams.

You control access to streams in `instant.perms.ts` under the `$streams` namespace.

- `create`: Controls who can create and write to streams (this is used by `createWriteStream`). For `create` rules, only `data.clientId` is available.
- `view`: Controls who can read and query streams (this is used by `createReadStream`).
- `update`: Controls updates to stream metadata.
- `delete`: Controls stream deletion.

```javascript 
const rules = {
  $streams: {
    allow: {
      view: 'auth.id != null',
      create: 'auth.id != null',
      update: 'false',
      delete: 'false',
    },
  },
};
```

## Admin SDK and Serverless

Streams are fully supported in the Admin SDK for use in backends or serverless environments like Next.js API routes or Edge Functions.

### `waitUntil`

In serverless environments, the process might be shut down before the stream has finished flushing to the server. You can use the `waitUntil` option to ensure the stream is fully persisted.

```javascript 
// Next.js API Route example
import { after } from 'next/server';
import { init, id } from '@interface-db/admin';

const db = init({
  appId: process.env.INSTANT_APP_ID,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
});

export async function POST(req) {
  const stream = db.streams.createWriteStream({
    clientId: id(),
    waitUntil: after,
  });

  // ... write to stream
}
```

## Building LLM chat apps with the Vercel AI SDK

### resumable-stream

[`@interface-db/resumable-stream`](https://www.npmjs.com/package/@interface-db/resumable-stream) is a drop-in replacement for Vercel's `resumable-stream` library that supports resuming ongoing streams after page reloads. It requires no Redis instance, and your streams never expire.

#### Client-side: Enable stream resumption

Use the `resume` option in the `useChat` hook to enable stream resumption. When `resume` is true, the hook automatically attempts to reconnect to any active stream for the chat on mount:

```tsx 
'use client';

import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport, type UIMessage } from 'ai';
import { id as generateId } from '@interface-db/react';

export function Chat({
  chatData,
}: {
  chatData: { id: string; messages: UIMessage[] };
}) {
  const { messages, sendMessage, status } = useChat({
    id: chatData.id,
    messages: chatData.messages,
    resume: true, // Enable automatic stream resumption
    generateId,
    transport: new DefaultChatTransport({
      // You must send the id of the chat
      prepareSendMessagesRequest: ({ id, messages }) => {
        return {
          body: {
            id,
            message: messages[messages.length - 1],
          },
        };
      },
    }),
  });

  return <div>{/* Your chat UI */}</div>;
}
```

#### Server-side: Create the POST handler

The POST handler creates resumable streams using the `consumeSseStream` callback:

```ts 
// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { readChat, saveChat } from '@util/chat-store';
import { convertToModelMessages, streamText, type UIMessage } from 'ai';
import { after } from 'next/server';
import { createResumableStreamContext } from '@interface-db/resumable-stream';
import { id as generateId } from '@interface-db/admin';

export async function POST(req: Request) {
  const {
    message,
    id,
  }: {
    message: UIMessage | undefined;
    id: string;
  } = await req.json();

  if (!message) return new Response(null, { status: 400 });

  const chat = await readChat(id);
  const messages = [...chat.messages, message];

  // Clear any previous active stream and save the user message
  await saveChat({ id, messages: [message], activeStreamId: null });

  const result = streamText({
    model: openai('gpt-4o'),
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    originalMessages: messages,
    generateMessageId: generateId,
    onFinish: ({ messages: finalMessages }) => {
      // Clear the active stream when finished
      saveChat({ id, messages: finalMessages, activeStreamId: null });
    },
    async consumeSseStream({ stream }) {
      const streamId = generateId();

      // Create a resumable stream from the SSE stream
      const streamContext = createResumableStreamContext({
        waitUntil: after,
        appId: process.env.INSTANT_APP_ID,
        adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
      });
      await streamContext.createNewResumableStream(streamId, () => stream);

      // Update the chat with the active stream ID
      await saveChat({ id, activeStreamId: streamId });
    },
  });
}
```

#### Server-side: Create the GET handler for resumption

```ts 
// app/api/chat/[id]/stream/route.ts
import { readChat } from '@util/chat-store';
import { UI_MESSAGE_STREAM_HEADERS } from 'ai';
import { after } from 'next/server';
import { createResumableStreamContext } from '@interface-db/resumable-stream';

export async function GET(
  _: Request,
  { params }: { params: Promise<{ id: string }> },
) {
  const { id } = await params;

  const chat = await readChat(id);

  if (chat.activeStreamId == null) {
    // no content response when there is no active stream
    return new Response(null, { status: 204 });
  }

  const streamContext = createResumableStreamContext({
    waitUntil: after,
    appId: process.env.INSTANT_APP_ID,
    adminToken: process.env.INSTANT_APP_ADMIN_TOKEN,
  });

  return new Response(
    await streamContext.resumeExistingStream(chat.activeStreamId),
    { headers: UI_MESSAGE_STREAM_HEADERS },
  );
}
```

## Resume directly from the client

The key advantage of Instant is that the client can reconnect to the stream **directly from the browser** without hitting your backend again.

By implementing a custom `DefaultChatTransport`, the Vercel AI SDK will automatically use Instant to resume any interrupted streams.

```tsx 
import { useMemo } from 'react';
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport, type UIMessage, type UIMessageChunk } from 'ai';
import { id as generateId } from '@interface-db/react';
import { db } from '@/lib/db';

class InstantChatTransport extends DefaultChatTransport<UIMessage> {
  async reconnectToStream(
    options: { chatId: string } & Record<string, unknown>,
  ): Promise<ReadableStream<UIMessageChunk> | null> {
    try {
      // 1. Find the active stream for this chat
      const { data } = await db.queryOnce({
        $streams: { $: { where: { chat: options.chatId } } },
      });
      const $stream = data.$streams?.[0];
      if (!$stream || $stream.done) return null;

      // 2. Connect to the read stream directly from the browser
      const readStream = db.streams.createReadStream({ streamId: $stream.id });

      // 3. Convert to byte stream for the AI SDK
      const byteStream = readStream.pipeThrough(new TextEncoderStream());
      return this.processResponseStream(byteStream);
    } catch {
      return null;
    }
  }
}

function Chat() {
  const transport = useMemo(
    () =>
      new InstantChatTransport({
        api: '/api/chat',
      }),
    [],
  );

  const { messages, sendMessage, status } = useChat({
    transport,
    generateId,
    resume: true,
  });

  return <>{/* Your chat UI */}</>;
}
```

Below is a full example that includes storing chat data in Instant and uses Instant auth for authorization.

If you want to jump into building an app, `@interface-db/create-app` has a working template that uses this pattern:

```sh 
npx @interface-db/create-app@latest --base ai-chat
```

### Setup

We'll start with a simple schema for our chats:

```ts 
// src/instant.schema.ts
import { i } from '@interface-db/react';

const _schema = i.schema({
  entities: {
    chats: i.entity({
      title: i.string().optional(),
    }),
    messages: i.entity({
      role: i.string(),
      parts: i.any().optional(),
      metadata: i.any().optional(),
    }),
    $streams: i.entity({
      clientId: i.string().unique().indexed(),
    }),
  },
  links: {
    chatOwner: {
      forward: { on: 'chats', has: 'one', label: 'owner' },
      reverse: { on: '$users', has: 'many', label: 'chats' },
    },
    chatMessages: {
      forward: { on: 'chats', has: 'many', label: 'messages' },
      reverse: { on: 'messages', has: 'one', label: 'chat' },
    },
    chatStream: {
      forward: { on: 'chats', has: 'one', label: 'stream' },
      reverse: { on: '$streams', has: 'one', label: 'chat' },
    },
  },
});

export default _schema;
```

And we'll set permissions so that the user can read their own chats. We'll handle all writes, except for creating the initial chat, from the server:

```ts 
// src/instant.perms.ts
import type { InstantRules } from '@interface-db/react';

const rules = {
  $default: {
    allow: {
      $default: 'false',
    },
  },
  $users: {
    allow: {
      view: 'auth.id != null && auth.id == data.id',
    },
  },
  chats: {
    allow: {
      view: 'auth.id != null && auth.id == data.owner',
      create: 'auth.id != null && auth.id == data.owner',
    },
  },
  messages: {
    allow: {
      view: "auth.id != null && auth.id in data.ref('chat.owner.id')",
    },
  },
  $streams: {
    allow: {
      view: "auth.id != null && auth.id in data.ref('chat.owner.id')",
    },
  },
} satisfies InstantRules;

export default rules;
```

### Sync auth

We'll set up auth syncing so that the backend that talks to the LLM can authenticate the current user.

```typescript 
// src/lib/db.ts
import { init } from '@interface-db/react/nextjs';
import schema from '@/instant.schema';

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  firstPartyPath: '/api/instant',
});
```

```typescript 
// src/app/api/instant/route.ts
import { createInstantRouteHandler } from '@interface-db/react/nextjs';

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});
```

```ts 
// src/lib/adminDb.ts
import { init } from '@interface-db/admin';
import schema from '@/instant.schema';

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN!,
  schema,
});
```

### Client components

By implementing a custom `DefaultChatTransport`, the Vercel AI SDK will automatically use Instant to resume any interrupted streams directly from the browser without hitting your backend again.

```tsx 
'use client';

import React, { useState, useMemo, useEffect, useRef } from 'react';
import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport, type UIMessage, type UIMessageChunk } from 'ai';
import { db } from '@/lib/db';
import { id as generateId } from '@interface-db/react';

class InstantChatTransport extends DefaultChatTransport<UIMessage> {
  async reconnectToStream(
    options: { chatId: string } & Record<string, unknown>,
  ): Promise<ReadableStream<UIMessageChunk> | null> {
    try {
      // 1. Find the active stream for this chat
      const { data } = await db.queryOnce({
        $streams: { $: { where: { chat: options.chatId } } },
      });
      const $stream = data.$streams?.[0];
      if (!$stream) return null;

      // 2. Connect to the read stream directly from the browser
      const readStream = db.streams.createReadStream({ streamId: $stream.id });

      // 3. Convert to byte stream for the AI SDK
      const byteStream = readStream.pipeThrough(new TextEncoderStream());
      return this.processResponseStream(byteStream);
    } catch {
      return null;
    }
  }
}

function ChatInner({
  id,
  initialMessages,
}: {
  id: string;
  initialMessages: UIMessage[];
}) {
  const transport = useMemo(
    () =>
      new InstantChatTransport({
        api: '/api/chat',
        // Send the id of the chat and the last message
        prepareSendMessagesRequest: ({ id, messages }) => {
          return {
            body: {
              id,
              message: messages[messages.length - 1],
            },
          };
        },
      }),
    [],
  );

  const { messages, sendMessage, status } = useChat({
    id,
    messages: initialMessages,
    generateId,
    resume: true, // Enable automatic stream resumption
    transport,
  });

  return <div>{/* Your chat UI */}</div>;
}

export function Chat({ id }: { id: string }) {
  // Fetch messages from Instant
  const {
    isLoading: isLoadingData,
    error: queryError,
    data,
  } = db.useQuery({
    chats: { $: { where: { id } } },
    messages: {
      $: {
        where: { chat: id },
        order: { serverCreatedAt: 'asc' },
      },
    },
  });

  const { isLoading: isLoadingUser, error: authError, user } = db.useAuth();

  const [createError, setCreateError] = useState<string | null>(null);
  const error = queryError || authError;
  const isLoading = isLoadingUser || isLoadingData;
  const createdChatId = useRef<string | null>(null);

  // Insert the chat into the db if it doesn't already exist.
  useEffect(() => {
    if (
      !isLoading &&
      !error &&
      !data?.chats?.[0] &&
      user?.id &&
      createdChatId.current !== id
    ) {
      createdChatId.current = id;
      db.transact(db.tx.chats[id].update({}).link({ owner: user.id })).catch(
        (err) => setCreateError(err.message || 'Failed to create chat'),
      );
    }
  }, [isLoading, error, user?.id, data?.chats, id]);

  if (createError) {
    return <div>Error: {createError}</div>;
  }

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  if (!user) {
    return <div>Log in</div>;
  }

  const messages = (data?.messages || []) as UIMessage[];

  return <ChatInner id={id} initialMessages={messages} />;
}
```

### Server-side: Create the POST handler

The POST handler saves the user message and pipes the AI completion to an Instant write stream.

```ts 
// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { convertToModelMessages, streamText, type UIMessage } from 'ai';
import { after, NextResponse } from 'next/server';
import { id as generateId } from '@interface-db/admin';
import { db } from '@/lib/adminDb';

async function saveChat({
  id,
  messages,
  activeStreamId,
  inactiveStreamId,
}: {
  id: string;
  messages?: UIMessage[];
  activeStreamId?: string | null;
  inactiveStreamId?: string | null;
}): Promise<void> {
  const txs = [];
  if (activeStreamId) {
    txs.push(db.tx.chats[id].link({ stream: activeStreamId }));
  }
  if (inactiveStreamId) {
    txs.push(db.tx.chats[id].unlink({ stream: inactiveStreamId }));
  }

  if (messages) {
    for (const message of messages) {
      txs.push(
        db.tx.messages[message.id]
          .update({
            role: message.role,
            parts: message.parts,
            metadata: message.metadata,
          })
          .link({ chat: id }),
      );
    }
  }

  if (txs.length) {
    await db.transact(txs);
  }
}

export async function POST(req: Request) {
  const {
    message,
    id,
  }: {
    message: UIMessage | undefined;
    id: string;
  } = await req.json();

  const user = await db.auth.getUserFromRequest(req);
  if (!user) return new NextResponse(null, { status: 401 });

  const { chats, messages: existingMessages } = await db.query({
    chats: {
      $: { where: { id, owner: user.id } },
      stream: {},
    },
    messages: {
      $: {
        where: { chat: id },
        order: { serverCreatedAt: 'asc' },
      },
    },
  });

  const chat = chats[0];
  if (!chat) return new NextResponse(null, { status: 404 });
  if (!message) return new NextResponse(null, { status: 400 });

  const history = (existingMessages || []) as UIMessage[];

  const messages = [...history, message];

  // Save the new user message and unlink any stale stream
  await saveChat({
    id,
    messages: [message],
    inactiveStreamId: chat.stream?.id,
  });

  const result = streamText({
    model: openai('gpt-4o'),
    messages: await convertToModelMessages(messages),
  });

  return result.toUIMessageStreamResponse({
    originalMessages: messages,
    generateMessageId: generateId,
    onFinish: ({ messages: finalMessages }) => {
      // Save completion and clear active stream
      saveChat({ id, messages: finalMessages });
    },
    async consumeSseStream({ stream }) {
      const writeStream = db.streams.createWriteStream({
        clientId: generateId(),
        waitUntil: after,
      });

      stream.pipeTo(writeStream).catch((err) => {
        console.error('Failed to pipe SSE stream', err);
      });

      // Link the stream to the chat so the client can find it
      const streamId = await writeStream.streamId();
      await saveChat({ id, activeStreamId: streamId });
    },
  });
}
```


# Webhooks

How to receive, verify, and manage Instant webhooks.

Webhooks allow you to subscribe to changes to your entities via POST requests to your server.

## How webhooks work

A webhook subscribes to one or more **namespaces** and **actions** (`create`, `update`, `delete`). Whenever a matching write commits, Instant queues an event and POSTs it to your endpoint.

Each request carries an `Instant-Signature` header and a small body. The body holds a short-lived URL and a JWT — you exchange them for the full payload of records:

```json
{
  "data": [
    {
      "namespace": "posts",
      "id": "<entity-id>",
      "action": "update",
      "before": { "id": "<entity-id>", "title": "Old title" },
      "after": { "id": "<entity-id>", "title": "New title" },
      "idempotencyKey": "<per-record-key>"
    }
  ],
  "idempotencyKey": "<batch-key>"
}
```

`before` is `null` on `create`; `after` is `null` on `delete`. The `idempotencyKey` is stable across redeliveries — use it to dedupe if your handler isn't idempotent on its own.

The `before` and `after` fields include all of the data attributes on an entity, but none of its links.

### Delivery and retries

Instant retries failed deliveries with backoff. An event moves through these stages:

- `pending` — queued, not yet attempted
- `processing` — a sender is actively trying to deliver
- `success` — receiver returned `2xx`
- `error` — an attempt failed; another retry is scheduled
- `failed` — all retries exhausted; will not be retried automatically

Each delivery attempt has a **15-second timeout** — if your endpoint hasn't responded by then, the attempt is recorded as a `timeout` error and Instant retries. Do any slow work (sending emails, calling third-party APIs, etc.) asynchronously, and respond with `2xx` as soon as you've durably enqueued the work.

A webhook that fails too many times in a row is automatically disabled. You can re-enable it from the dashboard or via the SDK once you've fixed the receiver.

## Setting up a webhook

The easiest way to create a webhook is from the **Webhooks** tab in the dashboard: pick the namespaces, the actions, and the URL Instant should POST to.

You can also manage webhooks programmatically with `npx @interface-db/cli webhook` or through the Admin SDK:

```ts 
// scripts/create-webhook.ts
import { init } from '@interface-db/admin';
import schema from './instant.schema';

const db = init({
  appId: process.env.INSTANT_APP_ID!,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN!,
  schema,
});

const webhook = await db.webhooks.manager.create({
  url: 'https://example.com/api/instant-webhook',
  namespaces: ['posts', 'comments'],
  actions: ['create', 'update'],
});
```

The URL must be `https` and resolve to a public host. An app can have up to **100 active webhooks** at a time.

## Receiving webhooks

`db.webhooks.processRequest` is the one-liner for handling incoming events. It verifies the signature, fetches the payload, and dispatches each record to your code.

### Next.js (App Router)

```ts 
// app/api/instant-webhook/route.ts
import { init } from '@interface-db/admin';
import { sendNewPostEmail } from '@/lib/emails';
import schema from '@/instant.schema';

const db = init({
  appId: process.env.INSTANT_APP_ID!,
  schema,
});

const { typedHandlers, combineHandlers } = db.webhooks.helpers();

const handlers = combineHandlers(
  typedHandlers('posts', 'create', async (record) => {
    await sendNewPostEmail(record.after);
  }),
  typedHandlers('posts', 'update', (record) => {
    console.log('post %s changed', record.id, record.before, record.after);
  }),
  typedHandlers('$default', (record) => {
    console.log('unhandled record', record);
  }),
);

export async function POST(req: Request) {
  await db.webhooks.processRequest(handlers, req);
  return new Response('ok');
}
```

`Webhooks.helpers<typeof schema>()` gives you `typedHandlers` and `combineHandlers`. Inside each handler, `record.before` and `record.after` are typed according to your schema — TypeScript will autocomplete fields and narrow on `action`.

Handler resolution is most-specific-wins: `namespace` + `action`, then the `namespace`'s `$default`, then the top-level `$default`. Records with no matching handler are skipped.

Handlers run concurrently. `processRequest` resolves once every handler resolves or a handler rejects; if any handler rejects, the call rejects too — return a non-2xx response so Instant retries.

### Next.js (Pages Router)

The Pages Router gives you a Node-style request, so use `processNodeRequest`. You also need to disable Next's body parser so the raw bytes are available for signature verification:

```ts 
// pages/api/instant-webhook.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { init, Webhooks } from '@interface-db/admin';
import { sendNewPostEmail } from '@/lib/emails';
import schema from '@/instant.schema';

// Signature verification requires the raw bytes
export const config = { api: { bodyParser: false } };

const db = init({
  appId: process.env.INSTANT_APP_ID!,
  adminToken: process.env.INSTANT_APP_ADMIN_TOKEN!,
  schema,
});

const { typedHandlers, combineHandlers } = Webhooks.helpers<typeof schema>();

const handlers = combineHandlers(
  typedHandlers('posts', 'create', async (record) => {
    await sendNewPostEmail(record.after);
  }),
);

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
    await db.webhooks.processNodeRequest(handlers, req);
    res.status(200).end();
  } catch (e) {
    res.status(400).json({ error: String(e) });
  }
}
```

### Express / other Node frameworks

Anywhere you have a Web `Request`, `processRequest` works directly. For frameworks that hand you a Node request, either bridge it to a `Request` yourself or read the raw body and call `validate` / `fetchPayloads` / `processPayload`:

```ts 
import express from 'express';
import { init, Webhooks } from '@interface-db/admin';
import schema from './instant.schema';

const { typedHandlers, combineHandlers } = Webhooks.helpers<typeof schema>();

const handlers = combineHandlers(
  typedHandlers('$default', (record) => console.log(record)),
);

const app = express();

app.post(
  '/api/instant-webhook',
  express.raw({ type: '*/*' }),
  async (req, res) => {
    const db = init({
      appId: process.env.INSTANT_APP_ID!,
      schema,
    });

    const signature = req.header('instant-signature')!;
    const body = req.body.toString('utf8');
    try {
      const webhookBody = await db.webhooks.validate(signature, body);
      const payload = await db.webhooks.fetchPayloads(webhookBody);
      await db.webhooks.processPayload(handlers, payload);
      res.status(200).send('ok');
    } catch (e) {
      res.status(400).send(String(e));
    }
  },
);
```

## Verifying signatures manually

If you'd rather not use the handler dispatch, you can stop after verification. `validate` parses and checks the `Instant-Signature` header against the body and returns the `{ payloadUrl, token }` you'd use to fetch records:

```ts 
const { payloadUrl, token } = await db.webhooks.validate(
  signatureHeader,
  rawBody,
  { tolerance: 300 }, // max signature age in seconds; default 300
);

// Or, if you already have a Web Request:
const body = await db.webhooks.validateRequest(req);

const payload = await db.webhooks.fetchPayloads({ payloadUrl, token });
```

`validate` rejects requests whose signature is older than `tolerance` (default: 5 minutes) — this is what protects against replays, so don't crank it up without thinking about it.

## Managing webhooks programmatically

`db.webhooks.manager` exposes CRUD on webhooks and access to their delivery history. Use it from the Admin SDK when you want to provision webhooks from code (e.g. during onboarding) rather than from the dashboard.

```ts 
// List
const webhooks = await db.webhooks.manager.list();

// Create
const hook = await db.webhooks.manager.create({
  url: 'https://example.com/instant',
  namespaces: ['posts'],
  actions: ['create', 'update', 'delete'],
});

// Update — pass only the fields you want to change
await db.webhooks.manager.update(hook.id, {
  actions: ['create', 'update'],
});

// Disable / re-enable
await db.webhooks.manager.disable(hook.id, { reason: 'paused for migration' });
await db.webhooks.manager.enable(hook.id);

// Delete
await db.webhooks.manager.delete(hook.id);
```

`update` is a patch — omitted fields keep their current value. `disable` and `enable` don't change the config, only whether new events are queued. Events that occurred while a webhook was disabled are **not** retroactively delivered when you re-enable it.

## Inspecting events

Every delivery attempt is recorded for ~60 days and is queryable through the manager. This is useful when a downstream system seems out of sync, or when you want to replay a missed event.

```ts 
// Page through events, newest first
let cursor: string | null = null;
do {
  const { events, pageInfo } = await db.webhooks.manager.listEvents(hook.id, {
    after: cursor,
  });
  for (const event of events) {
    console.log(event.isn, event.status, event.attempts);
  }
  cursor = pageInfo.hasNextPage ? pageInfo.endCursor : null;
} while (cursor);

// Fetch one event by its ISN (Instant Sequence Number)
const event = await db.webhooks.manager.getEvent(hook.id, isn);

// Fetch the full payload for an event
const payload = await db.webhooks.manager.getPayload(hook.id, isn);

// Force a redelivery (works on success, error, or failed)
await db.webhooks.manager.resendEvent(hook.id, isn);
```

Each `event.attempts` entry records the HTTP status, response body (first 256 bytes), duration, and an `errorType` tag (`timeout`, `dns`, `connect`, `tls`, `protocol`, `network`, `unknown`) when delivery failed — usually enough to tell whether the receiver is the problem or the network is.

`resendEvent` is rate-limited per event; if you call it twice in quick succession, the second call will return a validation error and ask you to wait about a minute.

## Verifying and fetching from any language

The `@interface-db/admin` SDK is the easiest way to receive webhooks, but the protocol is plain HTTP + Ed25519 — you can implement a receiver in any language. The steps below are what `validate` and `fetchPayloads` do under the hood.

### 1. The request

Every webhook arrives as a `POST` with two things you care about:

- The `Instant-Signature` header, a comma-separated list of `key=value` pairs:

  ```http
  Instant-Signature: t=1715551200,kid=1034696293,v1=4a8f...
  ```

  - `t` — Unix timestamp (seconds) of when Instant signed the request
  - `kid` — ID of the signing key
  - `v1` — hex-encoded Ed25519 signature

- A JSON body containing a short-lived URL and JWT:

  ```json
  { "payloadUrl": "https://api.interfacedb.com/...", "token": "eyJ..." }
  ```

### 2. Verify the signature

The signed message is `t` + `.` + the raw request body, as UTF-8 bytes. Verify the `v1` signature against the Ed25519 public key whose `kid` matches the header. The public keys are published as a JWK Set at:

```text
https://api.interfacedb.com/.well-known/webhooks/jwks.json
```

Reject requests where `t` is older than a few minutes (the SDK defaults to 300 seconds) to prevent replays.



```python 
# pip install pynacl requests
import base64, json, time, requests
from nacl.signing import VerifyKey

JWKS_URL = "https://api.interfacedb.com/.well-known/webhooks/jwks.json"
TOLERANCE_SECONDS = 300

def _b64url_decode(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

def _verify_key_for(kid: str) -> VerifyKey:
    for k in requests.get(JWKS_URL).json()["keys"]:
        if k["kid"] == kid and k["kty"] == "OKP" and k["crv"] == "Ed25519":
            return VerifyKey(_b64url_decode(k["x"]))
    raise ValueError(f"unknown kid {kid}")

def verify_webhook(signature_header: str, raw_body: bytes) -> dict:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, kid, v1 = parts["t"], parts["kid"], parts["v1"]

    if int(time.time()) - int(t) > TOLERANCE_SECONDS:
        raise ValueError("signature too old")

    message = t.encode("ascii") + b"." + raw_body
    _verify_key_for(kid).verify(message, bytes.fromhex(v1))  # raises BadSignatureError
    return json.loads(raw_body)  # {"payloadUrl": ..., "token": ...}
```

```go 
package webhook

import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const (
	jwksURL          = "https://api.interfacedb.com/.well-known/webhooks/jwks.json"
	toleranceSeconds = 300
)

type WebhookBody struct {
	PayloadURL string `json:"payloadUrl"`
	Token      string `json:"token"`
}

func verifyKeyFor(kid string) (ed25519.PublicKey, error) {
	resp, err := http.Get(jwksURL)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	var ks struct {
		Keys []struct{ Kid, Kty, Crv, X string }
	}
	if err := json.NewDecoder(resp.Body).Decode(&ks); err != nil {
		return nil, err
	}
	for _, k := range ks.Keys {
		if k.Kid == kid && k.Kty == "OKP" && k.Crv == "Ed25519" {
			return base64.RawURLEncoding.DecodeString(k.X)
		}
	}
	return nil, fmt.Errorf("unknown kid %s", kid)
}

func VerifyWebhook(signatureHeader string, rawBody []byte) (*WebhookBody, error) {
	parts := map[string]string{}
	for _, p := range strings.Split(signatureHeader, ",") {
		if kv := strings.SplitN(p, "=", 2); len(kv) == 2 {
			parts[kv[0]] = kv[1]
		}
	}
	t, kid, v1 := parts["t"], parts["kid"], parts["v1"]

	ts, _ := strconv.ParseInt(t, 10, 64)
	if time.Now().Unix()-ts > toleranceSeconds {
		return nil, fmt.Errorf("signature too old")
	}

	sig, err := hex.DecodeString(v1)
	if err != nil {
		return nil, err
	}
	pub, err := verifyKeyFor(kid)
	if err != nil {
		return nil, err
	}
	if !ed25519.Verify(pub, append([]byte(t+"."), rawBody...), sig) {
		return nil, fmt.Errorf("invalid signature")
	}

	var body WebhookBody
	return &body, json.Unmarshal(rawBody, &body)
}
```

```ruby 
# gem install ed25519
require "ed25519"
require "base64"
require "json"
require "net/http"

JWKS_URL = "https://api.interfacedb.com/.well-known/webhooks/jwks.json"
TOLERANCE_SECONDS = 300

def verify_key_for(kid)
  keys = JSON.parse(Net::HTTP.get(URI(JWKS_URL)))["keys"]
  jwk = keys.find { |k| k["kid"] == kid && k["kty"] == "OKP" && k["crv"] == "Ed25519" }
  raise "unknown kid #{kid}" unless jwk
  Ed25519::VerifyKey.new(Base64.urlsafe_decode64(jwk["x"]))
end

def verify_webhook(signature_header, raw_body)
  parts = signature_header.split(",").map { |p| p.split("=", 2) }.to_h
  t, kid, v1 = parts["t"], parts["kid"], parts["v1"]

  raise "signature too old" if Time.now.to_i - t.to_i > TOLERANCE_SECONDS

  message = "#{t}.#{raw_body}"
  verify_key_for(kid).verify([v1].pack("H*"), message)  # raises Ed25519::VerifyError
  JSON.parse(raw_body)  # => {"payloadUrl" => ..., "token" => ...}
end
```

```java 
// deps: org.bouncycastle:bcprov-jdk18on, com.fasterxml.jackson.core:jackson-databind
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.HexFormat;
import java.util.HashMap;
import java.util.Map;
import org.bouncycastle.crypto.params.Ed25519PublicKeyParameters;
import org.bouncycastle.crypto.signers.Ed25519Signer;

public class WebhookVerifier {
  static final String JWKS_URL = "https://api.interfacedb.com/.well-known/webhooks/jwks.json";
  static final long TOLERANCE_SECONDS = 300;
  static final ObjectMapper JSON = new ObjectMapper();

  public record WebhookBody(String payloadUrl, String token) {}

  static byte[] b64urlDecode(String s) {
    return Base64.getUrlDecoder().decode(s + "=".repeat((4 - s.length() % 4) % 4));
  }

  static Ed25519PublicKeyParameters verifyKeyFor(String kid) throws Exception {
    var resp = HttpClient.newHttpClient().send(
        HttpRequest.newBuilder(URI.create(JWKS_URL)).build(),
        HttpResponse.BodyHandlers.ofString());
    for (var k : JSON.readTree(resp.body()).get("keys")) {
      if (k.get("kid").asText().equals(kid)
          && k.get("kty").asText().equals("OKP")
          && k.get("crv").asText().equals("Ed25519")) {
        return new Ed25519PublicKeyParameters(b64urlDecode(k.get("x").asText()), 0);
      }
    }
    throw new IllegalStateException("unknown kid " + kid);
  }

  public static WebhookBody verify(String signatureHeader, byte[] rawBody) throws Exception {
    Map<String, String> parts = new HashMap<>();
    for (String p : signatureHeader.split(",")) {
      var kv = p.split("=", 2);
      if (kv.length == 2) parts.put(kv[0], kv[1]);
    }
    String t = parts.get("t"), kid = parts.get("kid"), v1 = parts.get("v1");

    if (Instant.now().getEpochSecond() - Long.parseLong(t) > TOLERANCE_SECONDS) {
      throw new IllegalStateException("signature too old");
    }

    var prefix = (t + ".").getBytes(StandardCharsets.UTF_8);
    var message = new byte[prefix.length + rawBody.length];
    System.arraycopy(prefix, 0, message, 0, prefix.length);
    System.arraycopy(rawBody, 0, message, prefix.length, rawBody.length);

    var signer = new Ed25519Signer();
    signer.init(false, verifyKeyFor(kid));
    signer.update(message, 0, message.length);
    if (!signer.verifySignature(HexFormat.of().parseHex(v1))) {
      throw new IllegalStateException("invalid signature");
    }
    return JSON.readValue(rawBody, WebhookBody.class);
  }
}
```



### 3. Fetch the payload

Once the signature checks out, parse the body as JSON and `GET` `payloadUrl` with the JWT in the `Authorization` header:

```http
GET <payloadUrl>
Authorization: Bearer <token>
Accept: application/json
```

The response contains a `data` array of records, plus a top-level `idempotencyKey`. The `token` is short-lived and will only fetch the single payload.

Respond `2xx` once you've durably enqueued the records. Anything else (or no response within 15 seconds) is treated as a failure and the event is retried.


# Backups

How Instant creates backups, how to download them, and what a backup archive contains.

Instant automatically generates a nightly backup that contains all of the data from your app.

You can view backups for the last 7 days from the `Backups` page on the dashboard, or with the cli:

```sh 
npx @interface-db/cli@latest backup list
```

## Downloading backups

You can download the backup as a zip file from the dashboard or through the cli:

```sh 
npx @interface-db/cli@latest backup download --latest
```

The backup contains your app's schema, rules, magic code email template, entities, and files.



A backup contains all of your app's data, including user records like email addresses. Store the downloaded zip somewhere secure and treat it as sensitive.



## Anatomy of an Instant backup

A backup is a zip file with this layout:

```text
instant-backup-<timestamp>.zip
├── config.json          # schema, rules, magic code email template, entity counts
├── entities/            # one .jsonl file per table with data
│   ├── $users.jsonl
│   ├── $files.jsonl
│   └── posts.jsonl
└── files/               # raw blobs for $files, named by location-id
    ├── 30b051b6-cc5d-41ce-8538-8302d6fa2695
    └── 770755e9-5cf0-41d2-b1cc-6552255d2ba3
```

The backup contains a `config.json` file that contains the schema, rules, and magic code email template. It also includes the number of entities for each table.

### Entities directory

The `entities` directory contains an NDJSON file for each table in your schema that has at least one entity.

The files are named after the table name, e.g. `$users.jsonl`.

Each JSON line includes a `createdAt` field, formatted as a Unix timestamp in milliseconds.

The `entity` field holds the key-value map with all of the fields for the entity.

If the key in the entity map represents a has-one link, the value will be the entity id of the entity in the linked table. If it is a has-many link, then it will be a JSON array of entity ids in the linked table.



```json
{"entity":{"email":"dww@instantdb.com","id":"81d4e04d-4057-4fc0-92f7-d99618fd540a","type":"user"},"createdAt":1772650963417}
{"entity":{"id":"0e212052-a4ba-4d3c-a679-3812ba22cde2","type":"guest"},"createdAt":1776458067727}
```

### Files directory

The `files` directory contains all of the file blobs for your app's `$files`.

Each listing in the `files` directory will be a `UUID` that will match the `location-id` field of a JSON line in the `entities/$files.jsonl` entry.



```json
{"entity":{"size":37240,"location-id":"30b051b6-cc5d-41ce-8538-8302d6fa2695","path":"profile.png","content-type":"image/png","id":"fd3a3356-f8d6-46cc-b56f-d3f470b44fbc"},"createdAt":1772604198270}
{"entity":{"size":13768,"location-id":"770755e9-5cf0-41d2-b1cc-6552255d2ba3","path":"cat.png","content-type":"image/png","id":"fda17e15-ba53-4a9e-9e9e-75e25c031191"},"createdAt":1773774285029}
```

```shell
$ ls -l files/
size   name
37240  30b051b6-cc5d-41ce-8538-8302d6fa2695
13768  770755e9-5cf0-41d2-b1cc-6552255d2ba3
```

## Restore a backup

You can restore a backup zipfile that you downloaded from the dashboard or through the cli into a self-hosted Instant instance.

Read the [Self hosting](/docs/self-hosting) guide for more information on how to set up a self-hosted instance.

Ensure that you've set the [deployment superuser](/docs/self-hosting#configure-the-deployment-superuser) via the `INSTANT_SUPERUSER_EMAIL` environment variable.

Sign in to the dashboard with your superuser email, then visit `${your-selfhosted-dashboard-url}/intern/restore` to restore the app into your new self-hosted instance.

If you have any OAuth clients set up with client secrets, go to the Auth dashboard for the restored app and update the secrets. The secrets will not carry over to the restored app.

## CLI reference

```shell
# List the downloadable backups for your app
npx @interface-db/cli@latest backup list

# Output the list as JSON
npx @interface-db/cli@latest backup list --json

# Download a backup (interactive picker when no backup is given)
npx @interface-db/cli@latest backup download

# Download the most recent backup
npx @interface-db/cli@latest backup download --latest

# Download a specific backup to a path of your choosing
npx @interface-db/cli@latest backup download <backup-id> --out my-backup.zip
```

All commands read the app ID from your `.env` file (`INSTANT_APP_ID`, or a framework-specific variant like `NEXT_PUBLIC_INSTANT_APP_ID`; see [App ID](/docs/cli#app-id)). Pass `--app <app-id>` to target a different one, and run `--help` on any command for the full list of flags.


# Stripe Payments

How to add payments to your Instant app with Stripe.

The quickest way to add Stripe to your Instant app is to tell your LLM to do it. Just say "add Stripe payments" and follow along step by step.

For more guidance we've put together three reference examples with tutorials you
can follow along with. Each example also has additional docs you can copy and paste for your agent.

## Stripe Examples

All three patterns share the same core idea: **Stripe handles payment, Instant
handles data and access control.** When a
payment completes, Stripe's webhook writes to Instant via the
[Admin SDK](/docs/backend), and any queries on the client get updated
instantly.

### One-off purchase

This example is for a wallpaper store where users buy a pack and get immediate
access to high-resolution downloads. It's a one-off payment, and no user accounts are required to minimize friction.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-one-off) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-one-off/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-one-off/stripe-strategy.md) and [payment flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-one-off/purchase.md) docs to help your agent implement the pattern

**How it works:**

1. User clicks "Buy" — a UUID token is generated and saved to `localStorage`
   _before_ redirecting to Stripe Checkout
2. The token is passed to Stripe via session metadata
3. On payment, a webhook creates a `purchase` record in Instant linked to that
   token
4. Permissions gate the protected content — only queries that include a valid purchase token
   (via `ruleParams`) can see the full-resolution URLs
5. Bonus: Uses [magic code auth](/docs/auth/magic-codes) to let users sign in
   and retrieve past purchases

### Subscription

This example is for a blog where free users see teasers and subscribers get full
articles. It uses recurring billing with Stripe and auth-based access control.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-subscription) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-subscription/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-subscription/stripe-strategy.md) and [subscription flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-subscription/subscription.md) docs to help your agent implement the pattern

**How it works:**

1. User signs in via magic code auth
2. Checkout creates or reuses a Stripe customer linked to the Instant user
3. Stripe webhooks sync `subscriptionStatus` to the `$users` record whenever
   the subscription changes (created, updated, canceled, deleted)
4. Permissions gate premium content — the `content` field is
   simply omitted from query results for non-subscribers
5. Stripe's Billing Portal handles cancellation and payment method updates

### Credits

This example is for a haiku generator where each generation costs one credit.
Users buy packs of 10 credits for $2. It's a pay-per-use model with real-time balance updates.

- [Example repo](https://github.com/instantdb/instant/tree/main/examples/stripe-credits) with [step-by-step tutorial](https://github.com/instantdb/instant/tree/main/examples/stripe-credits/tutorial.md)
- [Strategy](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-credits/stripe-strategy.md) and [credit flow](https://raw.githubusercontent.com/instantdb/instant/main/examples/stripe-credits/credits.md) docs to help your agent implement the pattern

**How it works:**

1. User signs in via magic code auth
2. Checkout creates a Stripe customer and processes a one-time payment for a
   credit pack
3. The webhook adds credits to the user's `credits` field, with idempotency
   protection via Stripe session metadata to prevent double-crediting on retries
4. A server-side API route verifies the user has enough credits, then
   atomically deducts a credit and creates the result in a single
   transaction
5. Instant's real-time subscriptions keep the credit balance and history
   updated in the UI instantly


# Admin HTTP API

Direct HTTP access to Instant's admin API for non-JavaScript environments.

If your backend is written in JavaScript, you can use the [`@interface-db/admin`](/docs/backend) SDK to connect your server to Instant.

But what if your backend isn't written in JavaScript? That's where the HTTP API comes in.

You can use the HTTP API in your favorite backend language to run scripts, create custom auth flows, or evaluate sensitive app logic.



If you give this documentation to your AI agent, it can create a custom SDK for your backend language. Here's the [Markdown](/docs/http-api.md).



## Auth

First and foremost, grab your app's `APP_ID` and `ADMIN_TOKEN`. You can get them by going to your
[dashboard](https://instantdb.com/dash). To authenticate requests, include them in your HTTP headers:

```shell 
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{}}}'
```

## Reading and Writing Data

`POST /admin/query` and `POST /admin/transact` let you read and write data as an admin.

### query

To make queries, run `POST /admin/query` with an InstaQL query:

```shell
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"goals":{},"todos":{}}}'
```

If you need [rule params](/docs/permissions#rule-params), include `$$ruleParams` at the top-level:

```json
{
  "$$ruleParams": { "knownGoalId": "..." },
  "query": { "goals": {} }
}
```

As a refresher, you can learn about InstaQL queries
[here](/docs/instaql).

### transact

To make transactions, send `POST /admin/transact` with `steps`:

```shell
curl -X POST "https://api.interfacedb.com/admin/transact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"steps":[["update","todos","<a-todo-uuid>",{"title":"Get fit"}]]}'
```

`steps` is the internal representation of Instant transactions. Here's how they
map to the [Instant transactions](/docs/instaml) you know:

```javascript
[
  // tx.goals[goalId1].update({title: "moop"})
  [
      "update",
      "goals",
      goalId1,
      {
          "title": "moop"
      }
  ],
  // tx.goals[goalId1].link({todos: todoId1})
  [
      "link",
      "goals",
      goalId1,
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].unlink({todos: todoId1})
  [
      "unlink",
      "goals",
      goalId1
      {
          "todos": todoId1
      }
  ],
  // tx.goals[goalId1].delete()
  [
      "delete",
      "goals",
      goalId1
  ],
]
```

## Subscriptions on the backend

You can subscribe to queries over SSE with `POST /admin/subscribe-query`.

The connection stays open and streams updates.

```shell
curl -N -X POST "https://api.interfacedb.com/admin/subscribe-query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"tasks":{}}}'
```


Subscriptions keep a live connection open on your backend. Be sure to close them
when they are no longer needed.


## Impersonating users

When you use the admin API, you can make _any_ query or transaction. As an admin, you bypass permissions.

But sometimes you want to make requests on behalf of a
user and respect permissions. You can do this by passing the `As-Email`, `As-Token`, or `As-Guest` headers.

```shell 
# Scoped by their email
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Email: alyssa_p_hacker@instantdb.com" \
  -d '{"query":{"goals":{}}}'

# Or with their auth token
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Token: $REFRESH_TOKEN" \
  -d '{"query":{"goals":{}}}'

# Or use the db as a guest
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "As-Guest: true" \
  -d '{"query":{"goals":{}}}'
```


`As-Email` requires an `ADMIN_TOKEN`. For `As-Token` and `As-Guest`, you could skip the
`Authorization` if you want to.


## Retrieve a user

Use `GET /admin/users` to fetch an app user by `email`, `id`, or `refresh_token`.

```shell
# By email!
curl -X GET "https://api.interfacedb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# By id
curl -X GET "https://api.interfacedb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# Or by a refresh token
curl -X GET "https://api.interfacedb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Delete a user

Use `DELETE /admin/users` to delete an app user by `email`, `id`, or `refresh_token`.

```shell
# By email
curl -X DELETE "https://api.interfacedb.com/admin/users?email=alyssa_p_hacker@instantdb.com" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# By id
curl -X DELETE "https://api.interfacedb.com/admin/users?id=$USER_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"

# Or by an auth token
curl -X DELETE "https://api.interfacedb.com/admin/users?refresh_token=$REFRESH_TOKEN" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Presence in the Backend

If you use [rooms & presence](/docs/presence-and-topics), you may want to query for the data currently in a room. This can be especially useful if you are sending a notification, for example, and want to skip it if the user is already online. To get room data, use `GET /admin/rooms/presence`. Make sure to pass in a `room-type` and a `room-id`:

```shell
curl -X GET "https://api.interfacedb.com/admin/rooms/presence?room-type=chat&room-id=room-123" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

## Sign Out

`POST /admin/sign_out` allows you to log out users. You can log a user out from every session by passing in their `email` or `id`. Or you can log a user out from a particular session by passing in a `refresh_token`:

```shell 
# All sessions for this email sign out
curl -X POST "https://api.interfacedb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

# All sessions for this user id sign out
curl -X POST "https://api.interfacedb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"

# Just sign out the session for this refresh token
curl -X POST "https://api.interfacedb.com/admin/sign_out" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}"
```

## Custom Auth

You can use `POST /admin/refresh_tokens` to generate auth tokens for your users.

Pass in an `email` or an `id` to create a refresh token:

```shell 
# By email
curl -X POST "https://api.interfacedb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'

# Or by ID
curl -X POST "https://api.interfacedb.com/admin/refresh_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d "{\"id\":\"$USER_ID\"}"
```

If a user with the given `id` or `email` does not exist, Instant will create the
user for you. You can pass `extra-fields` to set custom `$users` properties on creation. The response includes `user.refresh_token` and `"created": true` when a new user is created. You can pass this token on to your client and use it to [log in](/docs/backend#2-frontend-db-auth-sign-in-with-token).

## Custom magic codes

We support a [magic code flow](/docs/auth) out of the box. However, if you'd like to use your own email provider to send the code, you can create a magic code with `POST /admin/magic_code`:

```shell
curl -X POST "https://api.interfacedb.com/admin/magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
```

You can also use Instant's default email provider to send a magic code:

```shell
curl -X POST "https://api.interfacedb.com/admin/send_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com"}'
```

Similarly, you can verify a magic code too. Like `refresh_tokens`, you can pass `extra-fields` to set custom `$users` properties on creation.

```shell
curl -X POST "https://api.interfacedb.com/admin/verify_magic_code" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"email":"alyssa_p_hacker@instantdb.com","code":"123456","extra-fields":{"nickname":"alyssa"}}'
```

## Authenticated Endpoints

To authenticate users, have your frontend pass in a refresh token. Then use `POST /runtime/auth/verify_refresh_token` to verify it:

```shell
curl -X POST "https://api.interfacedb.com/runtime/auth/verify_refresh_token" \
  -H "Content-Type: application/json" \
  -d "{\"app-id\": \"$APP_ID\", \"refresh-token\": \"$REFRESH_TOKEN\"}"
```

## Storage

You can also manage your app's [storage](/docs/storage) with the HTTP API.

### Upload Files

Upload a file with `PUT /admin/storage/upload`:

```shell
curl -X PUT "https://api.interfacedb.com/admin/storage/upload" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -H "Path: snippets/demo.txt" \
  -H "Content-Type: text/plain" \
  --data-binary "@demo.txt"
```

### Delete Files

Delete a file by path:

```shell
curl -X DELETE "https://api.interfacedb.com/admin/storage/files?filename=snippets/demo.txt" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID"
```

Delete multiple files by path:

```shell
curl -X POST "https://api.interfacedb.com/admin/storage/files/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"filenames":["snippets/1.txt","snippets/2.txt"]}'
```

### List Files

List files by querying `$files`:

```shell
curl -X POST "https://api.interfacedb.com/admin/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "App-Id: $APP_ID" \
  -d '{"query":{"$files":{}}}'
```


# (Experimental) Next.js SSR

Use server-side rendering with InstantDB and Next.js.

If you use Next.js and want to do server-side rendering, we have an experimental library for you.

`@interface-db/react/nextjs` can let you run Instant queries both on the server and the client, and for the first time, _share caches between them_. (If you don’t get what this means yet, no worries, we’ll explain in detail in the document! Suffice it to say it’s pretty cool.)

This is an experimental feature, and you may not need SSR for many applications. But when you do, you can get some exceptional UX from it.

In this essay we’ll cover:

1. What server-side rendering is
2. When SSR is a good idea
3. How Instant works over SSR, particularly on caches
4. And how to add SSR in your projects

## What is server-side rendering?

Server-side rendering lets you run your JavaScript code in two environments.

First, the server renders your React component. So as soon as a browser sees your website, your React component is there.

Once the browser loads JavaScript, the same component runs on the client once more. This way, if you have hover effects or other logic that needs to attach to your component, it can do that in the browser.

To get a sense for how this all works, imagine loading a todo app:

![SSR diagram](/img/docs/next-ssr-diagram.png)

Without SSR, when you first loaded the site, you’d see a blank page. Once JavaScript loaded, React would kick in and you’d see your todos show up.

With SSR, your todo component would render on the server first. The _very_ first load in the browser would already show todos. Once JavaScript loaded, the todo component would reattach and all the click handlers and effects would work.

## When is server-side rendering a good idea?

At first glance, server-side rendering can sound great. Why not run your code right away on the server? Well, there are two costs:

### The costs

**The biggest cost is complexity**: Your code runs in two environments. Once on the server, and once on the client. Next.js and Instant can do a good job of hiding the difference, but sometimes those differences leak out (as a basic example, there’s no `window` on the server). For many applications, you may not want the added complexity.

**The second cost relates to client-heavy applications:** If you want your application to _feel_ like a desktop app, you’ll want to reduce the number of times your application pauses while navigating. This means that you have to be proactive with fallback states when using `<Suspense />`, or prefetch anticipated queries more aggressively.



Tip: You can prefetch queries by `db.queryOnce()` from anywhere, or by using `db.useQuery()` in a component and ignoring the result.



### The Benefits

But there are also some clear benefits.

**SSR can be great for search engines.** Web crawlers are getting better with JavaScript, but they generally do the best job at indexing websites when the content is there on the first load. SSR can do this for you.

**SSR can remove loading screens, especially if you use Next.js Routes.** Sometimes you load an app and see _lots_ of loading spinners. SSR can help you remove those spinners. Since there’s content on the first load, you can often ignore loading states completely. You may wonder, won’t the first load be slower if you’re fetching data? Not by much, for two reasons. First, if you use Next.js routing, it will try to pre-fetch as much as possible. By the time a user clicks a link, the data is often already there. Second, if you use Vercel, their servers are close to Instant servers, which means queries often take milliseconds to transfer.

Put these benefits together, and sometimes SSR really is worth it.

## How Instant works with SSR

So, if the benefits are worth it for you, how can you use Instant with SSR? That’s where `@interface-db/react/nextjs` comes in.

With `@interface-db/react/nextjs` you get a special package with a new hook: `db.useSuspenseQuery`:

![useSuspenseQuery diagram](/img/docs/next-ssr-suspense-query.png)

When you use `db.useSuspenseQuery`, (1) it will run a query once and get data on the server. When loaded in the browser, (2) it will reconnect and subscribe to changes on the same query. **This means on the first load you have data, _and_ it becomes real-time in the browser.**

### What about offline caches?

There's nothing faster than local data. If `useSuspenseQuery` is running on the client, it will use the local data and websocket connection instead.

In addition, when the page first loads from SSR, it will update the local cache with the most up-to-date results.


Using SSR can make data fetching slower in one specific case: If you are using `useSuspenseQuery` and there is not a `<Suspense>` anywhere higher in the component tree, the server will not send any HTML/JS at all until the query has resolved and the page has rendered. In some cases, this is desirable for things like SEO, but if the user already has the query result in their local cache, the page load is blocked, and they won't get a chance to load it and will have to wait.

If the component that calls `useSuspenseQuery` is wrapped in a `<Suspense/>`, then the data will be fetched at the same time on both the client and server, and the user will see whichever result loads fastest. For returning users, this usually ends up being the local data, but for non-cached queries, the server is often faster.


## Adding SSR to your projects

If this all sounds good to you, you can add SSR to your projects today.

Here’s the step-by-step guide.

### 1. Replace your `db` client

First things first, we’ll want to replace our db client to work with SSR.

Instead of importing from `@interface-db/react`, you’ll import from `@interface-db/react/nextjs`:

```typescript 
// src/lib/db.ts
import { init } from '@interface-db/react/nextjs';
import schema from '../instant.schema';

export const db = init({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
  schema,
  firstPartyPath: '/api/instant',
});
```

Note that we also included `firstPartyPath`. This lets us sync auth between client and server.

### 2. Sync auth

Syncing auth is covered in more detail [here](/docs/backend#syncing-auth), but we'll reproduce the main steps to make this tutorial easy to follow.

Let's create a route handler under `app/api/instant/route.ts`:

```typescript 
// src/app/api/instant/route.ts
import { createInstantRouteHandler } from '@interface-db/react/nextjs';

export const { POST } = createInstantRouteHandler({
  appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID!,
});
```

Once we do this, Instant can start to detect the logged-in user both in the browser and on the server.

### 3. Create an InstantProvider

SSR relies on suspense. To support that we’ll need to make an `InstantProvider` component:

```typescript 
// src/InstantProvider.tsx
"use client";
import { db } from "@/app/lib/db";
import { type User } from "@interface-db/react";
import { InstantSuspenseProvider } from "@interface-db/react/nextjs";
import React from "react";

export const InstantProvider = ({
  children,
  user,
}: {
  children: React.ReactNode;
  user: User;
}) => (
  <InstantSuspenseProvider user={user} db={db}>
    {children}
  </InstantSuspenseProvider>
);
```

### 4. Update layout.tsx

Now we’ll want to use our InstantProvider in a server component, usually `app/layout.tsx`:

```typescript 
// src/app/layout.tsx
import { getUnverifiedUserFromInstantCookie } from "@interface-db/react/nextjs";
import { InstantProvider } from "@/InstantProvider";

export default async function RootLayout({ children }) {
  const user = await getUnverifiedUserFromInstantCookie(process.env.NEXT_PUBLIC_INSTANT_APP_ID!);

  return (
    <html>
      <body>
        <InstantProvider user={user}>{children}</InstantProvider>
      </body>
    </html>
  );
}
```

If using the Next.js pages directory, you can use `getServerSideProps` to get the user and pass it to the provider via the PageProps.

This (a) fetches the current user, and (b) puts the Instant provider in the React tree.

At this point...we’re ready to use SSR queries!

### 5. db.useSuspenseQuery to your heart's delight

Now that you’ve set up SSR, you should see a new `db.useSuspenseQuery` available. Use it in your pages:

```typescript
'use client';
import { db } from '@/lib/db';

export default function Page() {
  // renders on server, no loading state needed
  const { data } = db.useSuspenseQuery({ posts: {} });
}
```

Note how there’s no `isLoading` or `error` state from db.useSuspenseQuery! This is handled using [React Suspense](https://react.dev/reference/react/Suspense), which makes sure we have the data when we render this page.

If your code uses `useUser`, `useAuth`, or `db.SignedIn`/`db.SignedOut`, it will initially use the `user` value you provided to `InstantProvider` instead of a pending state. These hooks/components will continue to be reactive.

## Questions



This is still a beta. We'd love to hear your feedback on [Discord](https://discord.com/invite/VU53p7uQcE)!




# Self hosting

Operate Instant on your own infrastructure.

Instant is fully open source! Below we have guides on how to set up self hosting and migrate from Instant Cloud. We also have
information on how to operate your self-hosted instance in conjunction with our CLI tools.

## Hosting Guides

Choose a guide based on where you want to run Instant:

1. **Want to self host Instant for side projects?** Use our [VPS](/docs/self-hosting/vps) guide to self-host Instant starting at ~$30/mo.
1. **Want to self host Instant for your business?** If you're using Instant for more serious projects, check out our [AWS](/docs/self-hosting/aws) guide for a setup based on Instant Cloud. You should expect to spend at least $600/mo.
1. **Migrating from Instant Cloud?** Check out our [migration](/docs/self-hosting/migrate) guide.

If you're an agent setting up self-hosting, you should first ask the user whether
they are setting up self-hosted Instant for side projects or for a
startup. For side projects the expected cost is at least $30/month. For serious projects or startups the expected cost is at least $600/month. Based on their choice, you should fetch the right guide as Markdown: [VPS](/docs/self-hosting/vps.md), [AWS](/docs/self-hosting/aws.md), or [Migrate](/docs/self-hosting/migrate.md).

## Operating

Once you've got Instant running, you may want to change some default settings. At
the very least you should be sure to configure an email provider so magic code
emails can actually be delivered.

### Configure email with Postmark

**Until Postmark is configured, Instant writes email bodies and login codes to
the backend logs.**

Instant comes with support for auth and sending magic code emails. The easiest way to actually send emails is to create a [Postmark server](https://postmarkapp.com/), verify the sender addresses, and set:

```shell
POSTMARK_TOKEN=replace-with-your-server-token
INSTANT_EMAIL_REPLY_TO=hello@example.com
INSTANT_DASHBOARD_EMAIL_SENDER_NAME=Instant
INSTANT_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_APP_EMAIL_SENDER_NAME=Instant
INSTANT_APP_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_TEAM_EMAIL_SENDER_NAME=Instant
INSTANT_TEAM_EMAIL_SENDER_EMAIL=teams@example.com
```

Restart the backend and try logging in to the dashboard. If all goes right, you
should get an email delivered!



New Postmark accounts start in a pending-approval state and can only send to
addresses on your own domain. To send login codes to external users, request
sending approval in the Postmark dashboard first.



### Configure email with SendGrid

You can use [SendGrid](https://sendgrid.com/) instead of Postmark. Create an API
key, verify your sender addresses (or authenticate your domain), and set:

```shell
SENDGRID_TOKEN=replace-with-your-api-key
INSTANT_EMAIL_REPLY_TO=hello@example.com
INSTANT_DASHBOARD_EMAIL_SENDER_NAME=Instant
INSTANT_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_APP_EMAIL_SENDER_NAME=Instant
INSTANT_APP_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_TEAM_EMAIL_SENDER_NAME=Instant
INSTANT_TEAM_EMAIL_SENDER_EMAIL=teams@example.com
```

If only one of `POSTMARK_TOKEN`, `SENDGRID_TOKEN`, or `RESEND_TOKEN` is set, Instant uses that
provider automatically. If you set multiple, choose one explicitly with:

```shell
INSTANT_EMAIL_PROVIDER=sendgrid
```

Restart the backend and try logging in to the dashboard to confirm delivery.

### Configure email with Resend

You can also use [Resend](https://resend.com/) to send emails. Create an API key,
verify your domain in Resend, and set:

```shell
RESEND_TOKEN=replace-with-your-api-key
INSTANT_EMAIL_REPLY_TO=hello@example.com
INSTANT_DASHBOARD_EMAIL_SENDER_NAME=Instant
INSTANT_DASHBOARD_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_APP_EMAIL_SENDER_NAME=Instant
INSTANT_APP_EMAIL_SENDER_EMAIL=verify@example.com
INSTANT_TEAM_EMAIL_SENDER_NAME=Instant
INSTANT_TEAM_EMAIL_SENDER_EMAIL=teams@example.com
```

You can also set `INSTANT_EMAIL_PROVIDER=resend` to explicitly select Resend.
Restart the backend and try logging in to confirm delivery.

### Configure Google dashboard login

The dashboard also allows for login via Google. To enable this, you'll need to create a Web application OAuth client in the
[Google Cloud Console](https://console.cloud.google.com/apis/credentials).

Add an authorized redirect URI matching your backend URL:

```text
${INSTANT_BACKEND_URL}/dash/oauth/callback
```

Set credentials in your `.env` or secrets manager to enable Google login.

```shell
INSTANT_DASHBOARD_GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
INSTANT_DASHBOARD_GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
```

Restart the backend and try logging in via Google!

### Configure the Deployment Superuser

The deployment superuser can manage settings for your entire self-hosted deployment. Set `INSTANT_SUPERUSER_EMAIL` to the email address of the person who should administer it:

```shell
INSTANT_SUPERUSER_EMAIL=admin@example.com
```

Instant creates this dashboard user when the server starts. Log in with this email and open **Deployment Settings** from the account menu to manage your deployment. If you change the email, restart the server to transfer superuser access.

### Restrict Dashboard Signups

By default, anyone can create a dashboard account. To limit access, open **Deployment Settings** and set **Who can sign up?**:

- **Open**: Anyone can sign up.
- **Restricted**: Only email addresses you add can sign up.
- **Closed**: No new dashboard accounts can sign up.

Existing dashboard users can always sign in.

### Temporary Apps

Instant supports spinning up temporary apps without authentication. Because these apps do not require a dashboard account, the signup restrictions above do not apply to them. Anyone who can reach your backend API can create temporary apps by default.

To disable temporary app creation, open **Deployment Settings** and turn off **Allow temporary app creation** under **Temporary apps**.

### Configure the Instant CLI

Instant comes with CLI tools for creating and managing your Instant apps. By
default, `@interface-db/cli` and `@interface-db/create-app` use the Instant Cloud API. To
use them with your self-hosted Instant:

- Log into your self-hosted Instant via `@interface-db/cli`
- Use your self-hosted auth token with `@interface-db/create-app`

Set `INSTANT_CLI_API_URI` to your backend URL and `INSTANT_CLI_DASH_URI` to your
dashboard URL with `@interface-db/cli`:

```shell
INSTANT_CLI_API_URI=https://api.myinstant.com \
INSTANT_CLI_DASH_URI=https://dash.myinstant.com \
npx @interface-db/cli@latest login
```

After authenticating, provide both URLs when running `@interface-db/create-app`:

```shell
# Run this from your terminal
INSTANT_CLI_API_URI=https://api.myinstant.com \
INSTANT_CLI_DASH_URI=https://dash.myinstant.com \
npx @interface-db/create-app@latest
```

This connects the generated app to your self-hosted
deployment and saves the configuration in `instant.config.ts`:

```ts
// instant.config.ts
export default {
  apiURI: 'https://api.myinstant.com',
  dashURI: 'https://dash.myinstant.com',
};
```

### View health

Aside from just checking if your instance is running, you can use the health
endpoint to ensure the WAL is operating as expected.

```shell
curl -fsS https://api.myinstant.com/health/system
```

A healthy backend returns `{"wal":"ok"}`. Alert on non-200 responses and any
other body.

### Horizontal scaling

A multi-server Instant deployment requires more than increasing the number of containers. Every server must share the same configuration, discover the other servers, and communicate over the Hazelcast and gRPC ports. Docker Swarm provides this through its built-in service discovery. Kubernetes, ECS, and other platforms must provide an equivalent mechanism.

### Memory Limits

By default, the backend server container can use a lot of resources. Set a
maximum heap size with `JAVA_OPTS` and leave memory for the operating system and
other containers. On the 4 GB VPS from this guide, start with a 2 GB heap:

```yaml 
server:
  environment:
    JAVA_OPTS: -Xmx2g -Xms2g
```

This sets both the minimum and maximum JVM heap to 2 GB. Larger, dedicated
backend containers can use a larger heap, but should still leave memory outside
the JVM.


# Self hosting on VPS

Run Instant on a VPS.

You can run the Instant backend, dashboard, PostgreSQL, MinIO, and Caddy on a
single VPS. A server with 2 vCPUs and 4 GB of RAM is enough to get started and
usually costs around $30 per month.

Already have a VPS and domain? Continue with the server's SSH address and the
hostnames you want to use.

Starting from scratch? Ask your agent for guided help creating the VPS and
setting up DNS.

Any provider that offers a recent Ubuntu image will work. We've tested this
setup with [DigitalOcean](https://www.digitalocean.com/pricing/droplets/) and
[Hetzner](https://www.hetzner.com/cloud/).

## Create the server

Start with:

- Ubuntu 24.04 LTS
- 2 vCPUs
- 4 GB of RAM

You will also need a domain where you can create DNS records. This guide uses:

```text
dash.myinstant.com
api.myinstant.com
files.myinstant.com
```

Point each hostname to the server.

Allow inbound HTTP, HTTPS, and administrator access to the server. PostgreSQL
and MinIO only need to be reachable by the other containers on the host.

## Install Docker

Skip this section if Docker and the Compose plugin are already installed. These
commands come from Docker's [Ubuntu installation guide](https://docs.docker.com/engine/install/ubuntu/):

```sh 
sudo apt update
sudo apt install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

```sh 
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

## Configure Instant

Clone Instant and copy the example environment file:

```sh 
git clone https://github.com/instantdb/instant.git
cd instant/self-hosting
cp .env.example .env
nano .env
```

Set the public URLs and the domains Caddy should use:

```shell 
INSTANT_BACKEND_URL=https://api.myinstant.com
INSTANT_DASHBOARD_URL=https://dash.myinstant.com
S3_PUBLIC_ENDPOINT=https://files.myinstant.com

DASHBOARD_DOMAIN=dash.myinstant.com
BACKEND_DOMAIN=api.myinstant.com
STORAGE_DOMAIN=files.myinstant.com
```

The `_DOMAIN` variables are only used by Caddy. You can ignore them if you use a
different reverse proxy.

`S3_PUBLIC_ENDPOINT` must be an origin without a path, such as
`https://files.myinstant.com`. MinIO cannot serve its S3 API from a path such as
`/storage`.

Review the rest of `.env` and replace the default PostgreSQL and MinIO
credentials. The MinIO bucket is private and Instant serves files with signed
URLs.

## Start Instant

Once the DNS records resolve to the server, run:

```sh 
sudo docker compose -f docker-compose.with-caddy.yml --env-file .env up -d
```

Caddy will request TLS certificates for the three domains. Check the containers
and backend health:

```sh 
sudo docker compose -f docker-compose.with-caddy.yml --env-file .env ps
curl -fsS https://api.myinstant.com/health/system
```

A healthy backend returns `{"wal":"ok"}`. Open the dashboard and create an app
to check queries, writes, and file uploads.

Until an email provider is configured, login codes are written to the backend
logs. Tail them with:

```sh 
sudo docker compose -f docker-compose.with-caddy.yml --env-file .env logs --follow server
```

## Scale the server

As your apps grow, watch CPU, memory, disk usage, and query latency. Moving to a
larger VPS is usually the simplest way to add capacity. A common next step is 4
vCPUs and 8 GB of RAM, but you can size the server to match your workload.

If you want to scale application servers and PostgreSQL independently, use the
[AWS guide](/docs/self-hosting/aws).

Once Instant is running, see [Operating Instant](/docs/self-hosting#operating)
to configure email, dashboard access, the CLI, and health checks.


# Self Hosting Instant on AWS

Run Instant with multiple backend servers and Aurora PostgreSQL.

For more serious projects where you need higher availability and point-in-time
restores, we recommend starting with two backend servers and
Aurora PostgreSQL. This is the same general architecture Instant Cloud uses and
lets you scale the backend and database separately.

The resources and instance types are up to you. The important parts are how the
Instant containers connect to PostgreSQL, object storage, and each other.

## Architecture

Instant does not require a particular AWS container platform. Your deployment
needs:

- HTTPS traffic routed to every healthy backend
- At least two backend tasks for redundancy
- Private DNS resolving `tasks.<service-name>` to all backend tasks
- Shared environment variables, secrets, and `override.edn`
- Aurora PostgreSQL 17 with logical replication
- Private S3 object storage
- A separately deployed dashboard

Set `SWARM_SERVICE_NAME` to the service name used in private DNS. Backend tasks
must be able to communicate over ports 5701–5708 and 5801–5808.

Do not set `PRODUCTION=true`; that selects Instant Cloud configuration rather
than self-hosted configuration.

## Configure AWS access

Before creating resources, choose an AWS CLI profile and Region, then confirm
that they point to the account where you intend to deploy:

```
aws sts get-caller-identity --profile your-profile
aws configure get region --profile your-profile
```

If AWS is not configured yet, use any AWS-supported authentication method to
create a CLI profile. An agent can help with this process. Use the selected
profile and Region consistently throughout the deployment.

## Configure Aurora PostgreSQL

Instant requires PostgreSQL 17 with logical replication and `pg_hint_plan`.
Create an Aurora PostgreSQL 17 cluster and apply these settings in a custom DB
cluster parameter group:

```text
rds.logical_replication = 1
shared_preload_libraries = pg_stat_statements,pg_hint_plan
max_replication_slots = 10
max_wal_senders = 10
random_page_cost = 1.1
rds.force_ssl = 0
```

Keep any existing entries in `shared_preload_libraries`. The replication
settings require a reboot.


Instant opens its migration connection without TLS, so Aurora PostgreSQL 17
requires `rds.force_ssl = 0`. Restrict port 5432 to the backend servers.


Create a database and login for Instant. The login needs the RDS replication
role:

```sql
CREATE ROLE instant LOGIN PASSWORD 'replace-with-a-generated-password';
GRANT rds_replication TO instant;
CREATE DATABASE instant OWNER instant;
```

Use the Aurora writer endpoint in `DATABASE_URL`:

```shell
DATABASE_URL=postgresql://instant:PERCENT_ENCODED_PASSWORD@WRITER_ENDPOINT:5432/instant
```

Each backend opens `CONNECTION_POOL_SIZE` database connections. Make sure
Aurora's `max_connections` can support every backend instance with room for
migrations and administration. Increase `max_replication_slots` and
`max_wal_senders` if you run more than ten backend instances.

## Configure S3

Create a private S3 bucket for Instant Storage. The backend needs permission to
list the bucket and to read, write, delete, and manage multipart uploads for its
objects.

Set these values on every backend server:

```shell
AWS_REGION=your-region
S3_BUCKET=instant-bucket
AWS_ACCESS_KEY_ID=replace-with-the-storage-access-key
AWS_SECRET_ACCESS_KEY=replace-with-the-storage-secret-key
```

Be sure to configure CORS on the bucket so Instant apps can upload files directly from the browser.

Leave `S3_ENDPOINT` and `S3_PUBLIC_ENDPOINT` unset when using AWS S3. Instant
currently needs static IAM credentials to sign S3 URLs, so provide an access
key even when the application servers also have an instance role.

## Share the encryption configuration

Every backend instance must use the same `override.edn`. Instant uses this file
to encrypt secrets and sign webhooks. Generate it once:

```sh 
mkdir instant-config
docker run --rm \
  -v "$PWD/instant-config:/out" \
  ghcr.io/instantdb/server:latest \
  /app/start.sh generate-override-config /out/override.edn
```

Store it with your other deployment secrets and mount it at
`/app/resources/config/override.edn` on every backend. Do not generate a
different file for each server.

## Deploy Instant

### Run the backend servers

Deploy the backend image on your preferred container platform:

```
ghcr.io/instantdb/server:latest
```

Start with two backend tasks in the same Availability Zone as the Aurora writer.
Route public backend traffic through the load balancer and use `/health/system`
for health checks.

Every backend task must use the same environment variables and the same
`override.edn`. Mount it at:

```
/app/resources/config/override.edn
```

At minimum, configure:

```
WAL_HISTORY_STORAGE=pg
DATABASE_URL=postgresql://instant:PERCENT_ENCODED_PASSWORD@WRITER_ENDPOINT:5432/instant
CONNECTION_POOL_SIZE=20

INSTANT_BACKEND_URL=https://api.myinstant.com
INSTANT_DASHBOARD_URL=https://dash.myinstant.com

AWS_REGION=your-region
S3_BUCKET=instant-bucket
AWS_ACCESS_KEY_ID=replace-with-the-storage-access-key
AWS_SECRET_ACCESS_KEY=replace-with-the-storage-secret-key

JAVA_OPTS=-Xmx4g -Xms4g
```

Leave `S3_ENDPOINT` and `S3_PUBLIC_ENDPOINT` unset when using AWS S3.

### Configure backend discovery

Multiple backend tasks must form a single Hazelcast cluster for presence, topics, and distributed state to work correctly.

Set a service name on every backend:

```
SWARM_SERVICE_NAME=server
```

Configure private DNS so that `tasks.server` resolves to the private IP address
of every backend task. Each task must be able to reach the others over TCP ports
5701–5708 and 5801–5808.

ECS with AWS Cloud Map, Docker Swarm DNSRR, or another scheduler that provides
equivalent private DNS can satisfy this requirement.

Keep `PRODUCTION` unset. Setting `PRODUCTION=true` selects Instant Cloud's
production configuration rather than the mounted self-hosted `override.edn`.

A successful `/health/system` response verifies the database WAL but does not
verify backend clustering. After deployment, test presence and realtime updates
while requests are distributed across both backend tasks.

### Run the dashboard

Deploy the dashboard image separately:

```
ghcr.io/instantdb/dashboard:latest
```

Set its public backend URL:

```
INSTANT_BACKEND_URL=https://api.myinstant.com
```

Route the dashboard hostname to port 3000:

```
https://dash.myinstant.com
```

The dashboard does not participate in backend service discovery.

## Verify the deployment

The load balancer should only send traffic to backends where
`/health/system` returns `{"wal":"ok"}`. Open the dashboard and create an app to
check queries, writes, realtime updates, and file uploads.

Until an email provider is configured, login codes are written to the backend
logs. For an ECS deployment using CloudWatch Logs, tail the log group configured
on the backend task definition:

```shell 
aws logs tail /your/backend/log-group \
  --follow \
  --region your-region \
  --profile your-profile
```

Send application logs and infrastructure metrics wherever your team normally
monitors AWS services. At a minimum, watch request errors and latency, backend
health, server CPU and memory, Aurora connections and query latency, and S3
errors.

## Scale the deployment

Add backend servers when CPU, memory, or request latency stays high.
Resize the Aurora writer when database CPU, memory, connections, or query
latency becomes the bottleneck. Revisit the connection pool and replication
settings whenever you add backend servers.

Currently Instant Cloud runs on:

| Tier                | Capacity                                                                                       |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Application servers | 3 x `m6a.16xlarge` (64 vCPUs and 256 GiB each)                                                 |
| PostgreSQL          | `db.r8gd.16xlarge` (64 vCPUs and 512 GiB) with Aurora I/O-Optimized                            |
| Workload            | 10,000+ concurrent connections, 10,000+ queries per second, and 1,000+ transactions per second |

Most deployments should start much smaller and scale each part from observed usage.

Once Instant is running, see [Operating Instant](/docs/self-hosting#operating)
to configure email, dashboard access, the CLI, and health checks.


# Migrate from Instant Cloud

Move an Instant Cloud app to self-hosted Instant.

Migrating from Instant Cloud happens in two phases:

1. **Rehearse the migration:** Set up self-hosted Instant and restore a test backup. This confirms that everything works and gives you an estimate for downtime.
2. **Cut over:** Pause writes, restore a fresh backup, and point your app at your self-hosted Instant.

## Rehearse the migration

### Set up self-hosted Instant

If you haven't already, set up self-hosting with our [VPS](/docs/self-hosting/vps) or
[AWS](/docs/self-hosting/aws) guide. Make sure you can log in to the dashboard,
create an app, query it, and write data.

Before restoring your app:

- [Configure an email provider](/docs/self-hosting#configure-email-with-postmark) so magic code emails work.
- [Restrict dashboard signups](/docs/self-hosting#restrict-dashboard-signups) and [disable temporary apps](/docs/self-hosting#temporary-apps) to prevent unwanted app creation.
- Configure webhooks for your self-hosted app if your app uses them.

If your app uses OAuth for end-user sign-in, recreate each OAuth provider on
the restored app. Copy its client ID, client secret, and any other provider
settings. Then add the self-hosted callback URL to the provider:

```text
https://api.myinstant.com/runtime/oauth/callback
```

Keep the Instant Cloud callback configured until the migration is complete.

### Restore a test backup

Migrating without data loss will require some downtime. To get a sense of how
much time it will take, first [restore a backup from Instant Cloud](/docs/backups#restore-a-backup).

After restoring, verify that the following look correct:

- Schema and permissions
- Application data
- Files
- Magic code and each OAuth provider your app uses
- Email templates

### Prepare the client change

After successfully restoring the test backup, we can put up a PR to update our
clients to point to our new self-hosted Instant app.

Choose a new app ID for the self-hosted app. The ID must be a valid UUID. You
can generate one in the terminal with:

```sh 
uuidgen
```

This will be your app ID going forward.

Create a PR that points your app at self-hosted Instant, but do not merge it
yet. Update the app ID, API URL, and WebSocket URL in every client `init` call:

```ts
const db = init({
  appId: 'YOUR_NEW_APP_ID',
  apiURI: 'https://api.myinstant.com',
  websocketURI: 'wss://api.myinstant.com/runtime/session',
  devtool: {
    dashURI: 'https://dash.myinstant.com',
  },
});
```

If you use the Admin SDK, update its app ID, admin token, and `apiURI` too. Keep
the PR ready to merge as soon as the final restore finishes.

## Cut over

### Pause writes on Instant Cloud

Open the app's **Admin** page in the Instant Cloud dashboard. Turn on
**Read-only mode**, then wait 30 seconds for in-flight mutations to finish.

Reads, live queries, and presence will keep working. New writes will be
rejected, including offline writes queued on user devices. We do this to ensure
there is no data loss during the cutover.

### Restore the final backup

Create an on-demand backup of the Instant Cloud app and restore it into self-hosted
Instant using the app ID from the rehearsal.

Before merging our earlier PR to switch clients over:

- Check that `/health/system` returns `{"wal":"ok"}`.
- Check the restored schema, permissions, data, and files.
- Make sure **Read-only mode** is off on the self-hosted app.
- Test magic code and OAuth login if your app uses them.

### Switch to self-hosted Instant

Merge and deploy the PR you prepared earlier. New client connections will now
use the restored app on self-hosted Instant. Users may need to sign in again.

Watch the deployment and verify queries, writes, authentication, and file
uploads. Once clients begin writing to self-hosted Instant, the Instant Cloud
copy is no longer current. If you use OAuth, you can remove the Instant Cloud
callback URL from each OAuth provider.

The migration should now be complete. Huzzah! 🎉