supabase/supabase-flutter/supabase-typegen-generate

Generating the typed Supabase schema

The supabase_typegen package turns a Supabase database schema into the Dart types that client.table() and the typed client.rpc methods use. It is never run by hand: the Supabase CLI introspects the database and runs dart run supabase_typegen --output - in the current directory with the schema on stdin, and the generated code arrives on stdout.

Rules

• Generate with the Supabase CLI, version 2.122.0 or newer. Check with

supabase --version, or npx supabase --version when the project pins the CLI in package.json.

• Never edit the generated file. Change the database and regenerate instead.
• Regenerate after every database migration, before writing code against the

new schema.

• Commit the generated file, so the app builds without a database.
• Run the command from the directory of the app's pubspec.yaml. The CLI

finds the supabase/ folder in that directory or any parent, and runs the generator where it was started.

Setup

dart pub add dev:supabase_typegen

Use flutter pub add in a Flutter app. The generator must be a dev dependency of the package the file is written into, since the CLI runs it with dart run there.

Generating

Pick the database to read from:

Prefer --local when the project keeps its schema as migrations, so the SQL in supabase/migrations stays the source of truth. --local needs Docker and a running stack.

Without --schema, the CLI generates public plus the schemas listed in api.schemas of supabase/config.toml. Pass --schema once per schema to choose them yourself:

supabase gen types --lang dart --local --schema public --schema inventory > lib/supabase_schema.g.dart

Only schemas exposed through the Data API can be queried at runtime. A table in a schema other than public carries the schema as a prefix, inventory.books becomes InventoryBooks, and its table definition carries the schema, so no .schema() call is needed.

After generating, analyze the file, with flutter analyze in a Flutter app. It must be clean:

dart analyze lib/supabase_schema.g.dart

The file is already formatted for the project's language version, so dart format leaves it unchanged.

What the file contains

For a table books in public:

final List<BooksRow> books = await supabase
    .table(Books.table)
    .select()
    .where(Books.mood.eq(Mood.happy));
 
final BooksRow? book = await supabase.rpc.bookById(bookId: 1);

Read-only relations, such as materialized views, get a row type and column constants but no insert or update type, so writes to them do not compile.

When something is missing

• A table is missing. Its schema was not generated: add --schema, or

add the schema to api.schemas. A table without columns is skipped, and the CLI says so in its summary.

• A relation constant is missing. Foreign keys into another schema and

self-referencing foreign keys get no relation, since PostgREST cannot embed them. Query those through a second request.

• A name has a suffix. A name the generated code itself uses, such as

String, gets $.

• A function has no method. The generated file has a comment where the

method would be, explaining why. Call it untyped with supabase.rpc('fn', params: {...}).

• A column has an unexpected type. numeric maps to num, date to

PostgresDate, interval to PostgresInterval, and array elements are assumed non-null. The full list is in the `supabase_typegen` README.

Errors

The CLI reports a generator failure as failed to generate dart types: dart run supabase_typegen exited with code N: …, followed by the generator's own message.