Skip to main content
Use this page to add supaschema to a project. Install from the package or workspace that owns your schema workflow, not from a clone of the supaschema source repository. Use the project’s package manager; do not create a second lockfile. For npm, the complete zero-config setup is a durable project install followed by local initialization:
Package installation downloads the CLI, config schema, and agent bundle. init then detects the consuming project and installs or merges the active config, directories, scripts, and AI-agent surfaces. It is safe to rerun after upgrades. supaschema is a runtime project dependency because the CLI, config schema, generated-output workflow, and coding-agent enforcement bundle are part of the consuming repo’s migration workflow. For workspaces, run both install and setup from the package directory that owns supaschema.config.json and the schema files. Dependency-targeting flags such as npm --workspace, pnpm --filter, or Yarn workspace can update the member manifest while setup still runs from the command’s current directory. Use root-level workspace flags only when the workspace root owns the schema workflow. For pnpm, pnpm add supaschema adds the dependency to the package in the current directory. Run pnpm add -w supaschema only when the workspace root owns the schema workflow. pnpm v11 defaults minimumReleaseAge to one day; keep that supply-chain protection for normal installs. Use --config.minimumReleaseAge=0 only when troubleshooting an immediate install of a just-published supaschema version. Stop before installing if package-manager signals conflict, the workspace owner is unclear, or Node is below 22.12.

​
Agent install prompt

Use this prompt when asking an AI coding agent to install supaschema.

Copy install prompt for a coding agent

​
Verify

Run setup explicitly through the matching local runner after install. It is idempotent, so it is safe to rerun when config or directories need repair:

​
Database URLs

Database URLs are only needed for commands that inspect, compare, or directly sync a live database. init does not write credential values. Supabase projects use the configured Supabase CLI runner. Other PostgreSQL projects reuse existing database URL variable names from .env* files in sync.targets when present.
Use named environments only when you need an additional named target. Do not create a second credential variable just for supaschema when an application database URL variable already exists.
A database URL does not authorize an apply. supaschema keeps apply fail-closed until workflow.migration_sync permits it, exactly one configured sync target selects apply mode, verification succeeds, and any remote approval variable is present. Without that explicit policy, sync remains a dry run.

​
Next steps

Setup

Confirm detected paths, install output, and environment checks.

Quickstart

Generate and check one migration.

Coding agents

Review the installed agent enforcement bundle.

Configuration

Review persistent paths, sources, workflow, and environments.
Last modified on July 24, 2026