Docs/Reference

#The Supabase migration report (JSON), version 2

fz import supabase inspect --json writes this document; the later importer steps (#659, #660, #661) and the dashboard read it. The Rust types are cratefield_import_supabase::Report and its fields (crates/import-supabase/src/report.rs), which are the definition; this page is the reader's guide. supabase.md explains the command.

#Stability rules

• report_version is 2. It changes when a field is removed or renamed, or changes meaning — 1 → 2 (issue #723) because a section the role cannot see is null where it used to be 0, and storage.counts_exact is gone. Adding a field does not change it: a reader ignores fields it does not know.
• Every list is sorted — by schema, then name, then whatever makes the key unique; findings by id — so two inspections of an unchanged project produce the same bytes. There is no timestamp: when it ran is the run directory's business, not the report's.
• Enumerations are lower-case snake_case strings.
• Nothing secret is in it: no credential, no password hash, no email, no row data. The connection is named by host, port and database alone, and every free-text SQL fragment (policy expressions, column defaults, check constraints, cron commands) has passed through the harness's log scrubber.
• An optional fact is null when it was not inspected or the role cannot see it — never a 0 or an empty list, which would claim a fact the report does not have.

#Top level

#read_only

#coverage.sections[]

One entry per row-read section: auth, storage.buckets, storage.objects, cron (only when cron.job exists) and schema:<name> for each user schema.

not_visible means the role lacks a privilege the read needs — USAGE, SELECT, or a way past row-level security. The section's data is then null, never 0 or []: a wrong zero would be believed, an absent fact cannot. Each not_visible section also adds a visibility blocker finding carrying the same reason and fix, so ready is false.

#summary

#tables[]

schema, name, kind (table or partitioned_table), estimated_rows (null when never analyzed), data_bytes, index_bytes, rls_enabled, rls_forced, primary_key (column names in key order; empty when none), columns (name, data_type, nullable, default, identity — always/by_default/null — and generated), constraints (name, kind — primary_key, foreign_key, unique, check, exclusion, trigger — definition, and references as schema.table for a foreign key), indexes (name, unique, primary, definition). Tables owned by an extension (PostGIS's spatial reference table) are not listed.

#policies[]

#dispositions

fz import supabase inspect --dispositions <FILE> applies a TOML file of per-item decisions (ADR 0026, Decision 5; docs/import/supabase.md). Without one, every needs-work and blocker item is undecided: decided and stale are empty and by_kind lists them all as undecided.

A policy on a Supabase-managed schema never appears here. One on storage.objects or storage.buckets is attached to its bucket instead (see storage). Everything else on a managed schema is in managed_policies.

#managed_policies[]

schema, table, name, command, roles (sorted), using, with_check. Policies on Supabase's own schemas (auth, cron, vault, net, storage tables other than objects/buckets, …) are the platform's: audited, but never classified, copied or a finding — so never in summary.needs_work.

#auth

present, users, users_without_password, users_unconfirmed, anonymous_users, identities_by_provider (provider, identities), mfa_factors, sso_providers, and from the Management API enabled_providers and enabled_mfa (null when not inspected). A count is null, never 0, when the role cannot see auth.users or auth.identities.

#storage

present; buckets: id, name, public, file_size_limit, allowed_mime_types, objects, bytes, objects_over_blob_cap (objects over the Blob port's 10 MiB put cap), and policies; plus unattached_policies. buckets is null, never [], and a bucket's objects, bytes and objects_over_blob_cap are each null, when the role cannot see storage.buckets or storage.objects.

Each bucket's policies holds the storage.objects/storage.buckets policies that name it (or, with all_buckets, apply to every bucket): table (storage.objects or storage.buckets), name, command, roles (sorted), using, with_check, all_buckets (the expression named no bucket that exists, so the policy applies to every bucket — and to any added later), suggested_equivalent (a route that checks the expression and hands out a signed URL, or a public URL for a public read — advice, never enforcement code) and disposition (undecided; per policy before cutover, ADR 0026 Decision 5). Bucket ids are parsed as pg_policies renders them (bucket_id = 'x', 'x'::text = bucket_id, or bucket_id = ANY (ARRAY['a', 'b']); on storage.buckets the column is id or name). unattached_policies holds the same shape when the project has no buckets at all, or the bucket list is not visible, where there is nothing to attach them to.

#findings[]

A later step looks up its own items by kind and phase; the dashboard groups by classification. Every needs_work finding needs a disposition before cutover (ADR 0026, Decision 5).

rls_no_policy is automatic, phase code: a table with RLS enabled and no policy denies every client, so nothing is ported (its cratefield_equivalent says service_role_only); it does not inflate needs_work. storage_policy is needs_work, phase storage: one finding per storage.objects / storage.buckets policy however many buckets it landed on, its reason naming the bucket(s). Such a policy is never in policies and never a phase-code finding; the policy itself is on its bucket (or in unattached_policies).

Mirrored from docs/import/supabase-report.md at b6f50cd. The harness is the source of truth: a correction goes there first.