Skip to main content

​
Overview

The Convex database schema defines the structure of your application’s data. It includes tables for users, messages, presence tracking, and file uploads.

​
Schema Definition

Location: convex/schema.ts:6 
export default defineSchema({
  ...authTables,
  users: defineTable({...}),
  messages: defineTable({...}),
  presence: defineTable({...}),
  files: defineTable({...}),
});

​
Tables

​
users

Stores user profile information with authentication support. Location: convex/schema.ts:10

​
Fields

​
name
string
User’s display name
​
email
string
User’s email address
​
image
string
URL to user’s profile image
​
emailVerificationTime
number
Timestamp when email was verified
​
isAnonymous
boolean
Whether this is an anonymous user account

​
Indexes

  • by_email - Index on [email] field for email lookups
  • by_anonymous - Index on [isAnonymous] field for filtering anonymous users

​
Example

const user = {
  name: "Alice Johnson",
  email: "[email protected]",
  image: "https://example.com/avatar.jpg",
  isAnonymous: false
};

​
messages

Stores chat messages for realtime chat functionality. Supports both authenticated and demo mode. Location: convex/schema.ts:21

​
Fields

​
roomId
string
required
Identifier for the chat room
​
userId
Id<'users'>
Reference to the user who sent the message. Optional for demo mode.
​
content
string
required
Message text content
​
userName
string
required
Display name of the message sender
​
sessionId
string
Session identifier for tracking demo sessions

​
Indexes

  • by_room - Index on [roomId] field for efficient room-based queries

​
Example

const message = {
  roomId: "general",
  userId: "j97abc123...",
  content: "Hello, world!",
  userName: "Alice",
  sessionId: "session_xyz"
};

​
presence

Tracks real-time user presence for features like cursors and avatar stacks. Location: convex/schema.ts:31

​
Fields

​
roomId
string
required
Identifier for the room/space
​
userId
Id<'users'>
Reference to the user. Optional for demo mode.
​
sessionId
string
Session identifier for tracking demo sessions
​
data
object
required
Presence data object containing user state
​
data.cursor
{x: number, y: number}
Cursor position coordinates
​
data.position
{x: number, y: number}
Position coordinates (alias for cursor)
​
data.status
string
User status text
​
data.userName
string
User’s display name
​
data.userImage
string
URL to user’s avatar image
​
data.color
string
Color code for user’s cursor/avatar
​
data.name
string
Alternative name field
​
lastSeen
number
required
Timestamp of last presence update

​
Indexes

  • by_room - Index on [roomId] for room-based queries
  • by_user_and_room - Index on [userId, roomId] for user-specific presence lookups
  • by_session_and_room - Index on [sessionId, roomId] for session-based presence lookups
  • by_last_seen - Index on [lastSeen] for cleanup of stale presence entries

​
Example

const presence = {
  roomId: "canvas-1",
  userId: "j97abc123...",
  sessionId: "session_xyz",
  data: {
    cursor: { x: 150, y: 200 },
    userName: "Alice",
    userImage: "https://example.com/avatar.jpg",
    color: "#FF6B6B",
    status: "active"
  },
  lastSeen: 1709251200000
};

​
files

Tracks file uploads with references to Convex storage. Location: convex/schema.ts:52

​
Fields

​
storageId
Id<'_storage'>
required
Reference to the file in Convex storage
​
userId
Id<'users'>
Reference to the user who uploaded the file. Optional for demo mode.
​
sessionId
string
Session identifier for tracking demo uploads
​
name
string
required
Original filename
​
type
string
required
MIME type of the file
​
size
number
required
File size in bytes

​
Indexes

  • by_user - Index on [userId] for user-specific file queries
  • by_session - Index on [sessionId] for session-based file queries

​
Example

const file = {
  storageId: "kg2abc123...",
  userId: "j97abc123...",
  sessionId: "session_xyz",
  name: "document.pdf",
  type: "application/pdf",
  size: 2048576
};

​
Auth Tables

The schema also includes authentication tables from @convex-dev/auth/server: 
import { authTables } from "@convex-dev/auth/server";

export default defineSchema({
  ...authTables,
  // ... other tables
});
These tables handle authentication sessions, tokens, and provider-specific data.

Build docs developers (and LLMs) love

Get started for freeTalk to us