Skip to main content
Use this page to confirm paths and setup output after install. Command examples show supaschema as CLI syntax. In a project install, run it through the local runner from Installation. After installing the package, run init through the local runner for your package manager: 
supaschema init

​
Path selection

Install scans the repository before writing config:
  • one detected schema folder and one detected migrations folder are used automatically;
  • provider markers seed default folders when no existing folders are found;
  • Supabase projects use Supabase CLI sync targets by default;
  • non-Supabase projects reuse existing database URL environment variable names from .env* files when present;
  • generic PostgreSQL projects use database/schemas and database/migrations;
  • multiple candidates that still need confirmation are recorded in .supaschema/install.json;
  • interactive terminals can confirm paths immediately.
Do not run the first diff from a guessed path. If .supaschema/install.json says pathConfirmationNeeded: true, config validate, doctor, and zero-source diff block until supaschema.config.json explicitly sets schemaPaths, sources.to, and migrationsDir.
Provider markerSchema pathMigrations path
supabase/config.tomlsupabase/schemassupabase/migrations
neon.toml, .neon/project.json, .neon/config.json, or Neon references in drizzle.config.*neon/schemasneon/migrations
RDS/Aurora markers in Terraform, CloudFormation/SAM, CDK, SST, or Serverless configaws-postgresql/schemasaws-postgresql/migrations
Cloud SQL markers in Terraform, Cloud Build, or App Engine configcloud-sql/schemascloud-sql/migrations
AlloyDB markers in Terraform, Cloud Build, or App Engine configalloydb/schemasalloydb/migrations
Azure PostgreSQL markers in Terraform, Bicep, ARM, or Azure Developer CLI configazure-postgresql/schemasazure-postgresql/migrations
Commit supaschema.config.json after confirming paths. It keeps humans, CI, and coding agents on the same schema tree and migration directory. Resolved installs do not create .supaschema/ or supaschema-only credential files; supaschema.config.json is the durable project state.

​
Agent addendum

Default install does not update AGENTS.md or CLAUDE.md. The optional AI-agent bundle updates AGENTS.md only inside this managed block: 
<!-- supaschema:agent-guidance:start -->
<!-- supaschema:agent-guidance:end -->
Content outside the markers is preserved. CLAUDE.md stays a pointer entrypoint (@AGENTS.md) when the project uses AGENTS.md as the canonical brief.

​
Check setup

Run doctor when setup behaves unexpectedly: 
supaschema doctor
doctor checks Node, parser load, config validity, database URL resolution, optional database reachability, CREATEDB, migration history, and declarative schema paths.

​
Configuration

Config file

Review paths, migrations, type outputs, validators, and planner policies.

Environments

Configure named targets and database URL resolution.

Hints

Approve reviewed destructive changes and renames.
Last modified on June 19, 2026