Schema Definition
The projects table stores information about code projects in Polaris.
Fields
Unique project identifier
User ID of the project owner
Unix timestamp (in milliseconds) of last update
Status of project import operation
"importing" - Import in progress"completed" - Import completed successfully"failed" - Import failed
Status of project export operation
"exporting" - Export in progress"completed" - Export completed successfully"failed" - Export failed"cancelled" - Export cancelled
URL of the exported repository (set after successful export)
Project configuration settings
Custom install command (e.g., npm install, yarn install)
Custom dev server command (e.g., npm run dev, yarn dev)
Indexes
Index on ownerId field for efficient user project queriesFields: ["ownerId"]
Queries
get
Retrieve all projects owned by the authenticated user.
import { api } from "@/convex/_generated/api";
import { useQuery } from "convex/react";
function MyProjects() {
const projects = useQuery(api.projects.get);
return projects?.map(p => <div key={p._id}>{p.name}</div>);
}
getPartial
Retrieve a limited number of projects owned by the authenticated user.
Maximum number of projects to return
import { api } from "@/convex/_generated/api";
import { useQuery } from "convex/react";
function RecentProjects() {
const projects = useQuery(api.projects.getPartial, { limit: 5 });
return projects?.map(p => <div key={p._id}>{p.name}</div>);
}
limit), ordered by most recent first
getById
Retrieve a specific project by ID.
import { api } from "@/convex/_generated/api";
import { useQuery } from "convex/react";
function ProjectDetails({ projectId }) {
const project = useQuery(api.projects.getById, { id: projectId });
return <h1>{project?.name}</h1>;
}
"Project not found" - Project doesn’t exist"Unauthorized access to this project" - User is not the owner
Mutations
create
Create a new project.
import { api } from "@/convex/_generated/api";
import { useMutation } from "convex/react";
function CreateProject() {
const createProject = useMutation(api.projects.create);
const handleCreate = async () => {
const projectId = await createProject({ name: "My New Project" });
console.log("Created project:", projectId);
};
return <button onClick={handleCreate}>Create Project</button>;
}
Id<'projects'> - ID of the newly created project
rename
Rename an existing project.
import { api } from "@/convex/_generated/api";
import { useMutation } from "convex/react";
function RenameProject({ projectId }) {
const renameProject = useMutation(api.projects.rename);
const handleRename = async () => {
await renameProject({
id: projectId,
name: "Updated Project Name"
});
};
return <button onClick={handleRename}>Rename</button>;
}
"Project not found" - Project doesn’t exist"Unauthorized access to this project" - User is not the owner
updateSettings
Update project configuration settings.
Project settings object
Custom dev server command
import { api } from "@/convex/_generated/api";
import { useMutation } from "convex/react";
function ProjectSettings({ projectId }) {
const updateSettings = useMutation(api.projects.updateSettings);
const handleUpdate = async () => {
await updateSettings({
id: projectId,
settings: {
installCommand: "npm install",
devCommand: "npm run dev"
}
});
};
return <button onClick={handleUpdate}>Save Settings</button>;
}
"Project not found" - Project doesn’t exist"Unauthorized to update this project" - User is not the owner
Source Reference
- Schema definition:
convex/schema.ts:5-31
- Queries and mutations:
convex/projects.ts