Supabase Dart Exporter

A powerful CLI tool for exporting Supabase database schema to Dart models for Flutter applications.

Features

Export Supabase database schema to SQL files
Generate Dart models from database schema with freezed support
Support for all PostgreSQL constraints and types
Automatic documentation generation
Support for both local and remote Supabase instances
Full freezed integration with immutable models
Proper handling of default values and required fields
Enhanced enum support with JsonValue annotations

Installation

Global Installation (Recommended)

npm install -g supabase-dart-exporter

Project Installation

npm install --save-dev supabase-dart-exporter

Flutter Project Setup

Add these dependencies to your pubspec.yaml:

dependencies:
  freezed_annotation: ^2.4.1
  json_annotation: ^4.9.0

dev_dependencies:
  build_runner: ^2.4.15
  freezed: ^2.4.7
  json_serializable: ^6.7.1

Configuration

Create a .env file in your project root:

# For Supabase API access
SUPABASE_URL=http://localhost:54321        # Your Supabase project URL
SUPABASE_SERVICE_KEY=your-service-key      # Your service role key

# For PostgreSQL direct connection (required for Dart export)
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

Usage

Basic Usage

Export both SQL schema and Dart models (recommended):

supabase-dart-exporter

This will:

Export SQL schema to ./exported_database/
Generate Dart models in ./lib/models/

Export SQL schema only:

supabase-dart-exporter --output ./my-schema

Generate Dart models only:

supabase-dart-exporter --dart --dart-output ./my-models

Advanced Options

Options:
  --export-data            Export table data as SQL insert statements
  --data-dir <dir>         Directory for data SQL files (default: "data")
  -o, --output <dir>           Output directory for SQL exports (default: "./exported_database")
  -e, --env <path>            Path to .env file (default: ".env")
  -v, --verbose               Enable verbose logging
  --url <url>                 Supabase project URL (overrides .env)
  --key <key>                 Supabase service role key (overrides .env)
  --schema-only              Export schema without data
  --tables <tables>          Comma-separated list of tables to export
  --install-functions        Install required database functions
  --dart                     Export database schema to Dart models
  --dart-output <dir>        Output directory for Dart models (default: "./lib/models")
  --dart-no-docs            Disable documentation generation for Dart models
  --dart-no-equality        Disable equality methods for Dart models
  --connection-string <str>  PostgreSQL connection string (overrides .env)

Examples

Export specific tables:

supabase-dart-exporter --tables users,profiles,posts

Custom output directories:

supabase-dart-exporter --output ./db/schema --dart --dart-output ./src/models

Minimal Dart models:

supabase-dart-exporter --dart --dart-no-docs --dart-no-equality

Using with remote Supabase:

supabase-dart-exporter --url https://your-project.supabase.co --key your-service-key

Generated Files

SQL Schema Export

The tool generates SQL files in the output directory:

02_tables.sql: Table definitions with all constraints

Dart Models

For each table, a corresponding Dart model is generated with:

Full freezed integration for immutable data classes
Proper nullability based on constraints
Smart handling of default values with @Default annotations
Enhanced enum support with @JsonValue annotations
Documentation of constraints and relationships
JSON serialization/deserialization
Automatic copyWith functionality
Deep equality comparison
toString implementation
Pattern matching support

Example Dart model:

/// Users model representing the users table in the database
@freezed
class Users with _$Users {
  const factory Users({
    /// Primary key
    @JsonKey(name: 'user_id')
    required String userId,

    /// Foreign key reference to profiles(id)
    @JsonKey(name: 'profile_id')
    String? profileId,

    /// Default: now()
    @JsonKey(name: 'created_at')
    @Default(DateTime.now()) DateTime createdAt,

    /// User status with predefined values
    @JsonKey(name: 'status')
    UserStatusType status,
  }) = _Users;

  factory Users.fromJson(Map<String, dynamic> json) => 
    _$UsersFromJson(json);
}

enum UserStatusType {
  @JsonValue('active')
  active,
  @JsonValue('inactive')
  inactive,
}

After Generation

After generating the models, run:

dart run build_runner build --delete-conflicting-outputs

This will generate the necessary freezed and JSON serialization code.

Best Practices

Always use version control and commit generated files
Review generated models before using in production
Keep your database schema clean and well-documented
Use meaningful constraint names in your database
Run the exporter whenever your schema changes
Run build_runner after generating new models
Take advantage of freezed's pattern matching features
Use the generated copyWith methods for immutable updates

Troubleshooting

Common Issues

Connection Failed
- Verify your Supabase URL and service key
- Check if your database is running
- Ensure your firewall allows the connection
Permission Denied
- Verify your service role key has sufficient permissions
- Check database user permissions
Type Mapping Issues
- Ensure custom types are properly defined
- Check for unsupported PostgreSQL types

Getting Help

Open an issue on GitHub
Check existing issues for solutions
Include verbose logs with your reports: --verbose

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT License - see LICENSE file for details