introspection library

Introspects a Postgres database into the GeneratorMetadata document of @supabase/postgrest-typegen through supabase db query, so types can be generated before supabase gen types produces the document itself.

This is a port of the introspection of that package, pinned to postgrestTypegenRevision. It exists until supabase gen types ships a Dart path and can be removed as a whole once it does.

Classes

DatabaseTarget

The database supabase db query connects to.

DatabaseUrl

Any Postgres database, by connection string.

LinkedProject

The database of the project linked with supabase link, or of projectRef, reached through the Management API with the credentials of supabase login.

LocalDatabase

The database of the local Supabase stack started with supabase start.

Queryable

The single database operation the introspection needs: run a set of named queries and return the rows of each.

SupabaseCliQueryable

A Queryable that runs its queries through supabase db query, so the Supabase CLI resolves and authenticates the connection.

Constants

generatorMetadataVersion → const int

The version field of the emitted GeneratorMetadata document.

postgrestTypegenRevision → const String

The supabase/sdk revision of @supabase/postgrest-typegen whose introspection this library ports, a commit or a postgrest-typegen-v* tag. tool/check_introspection_drift.ts compares the SQL of the port against it and tool/regenerate_fixture.ts expects a checkout of it.

Functions

combineQueries(Map<String, String> queries) → String

Folds queries into one SELECT with a json_agg column per query, so a single supabase db query call returns every result set.

describeFailure(String rawOutput, {DatabaseTarget? target}) → String

Turns the output of a failed supabase db query into the message shown to the user, with dedicated wording for the setup problems the tool can name. Passwords of connection strings echoed by the CLI are redacted.

introspect(Queryable database, {List<String> includedSchemas = const [], List<String> excludedSchemas = const []}) → Future<Map<String, dynamic>>

Introspects the database behind database into the GeneratorMetadata document, in query order. Apply sortGeneratorMetadata before generating from it.

introspectDatabase(DatabaseTarget target, {List<String> includedSchemas = const [], List<String> excludedSchemas = const []}) → Future<Map<String, dynamic>>

Introspects the database target through supabase db query and returns the GeneratorMetadata document in canonical order, equal to sortGeneratorMetadata(await introspect(pool)) of @supabase/postgrest-typegen at postgrestTypegenRevision up to the order of keys within a record.

sortGeneratorMetadata(Map<String, dynamic> document) → Map<String, dynamic>

Returns a copy of the GeneratorMetadata document with every collection in the canonical order of sortGeneratorMetadata of @supabase/postgrest-typegen: relations and types by schema and name, columns by schema, table and name, primary keys grouped by table with their declared column order kept, relationships by foreign key name, referenced relation and referenced columns, functions by schema, name and signature with their arguments by name. Names compare with localeCompare. The sort is stable, so ties keep the introspection order.

Exceptions / Errors

SupabaseCliException

Thrown when supabase db query cannot run or fails, with a message that tells the user what to do.