Skip to content

v0.4.0 - Schema Management CLI

Choose a tag to compare

View all tags
@pillowsoft pillowsoft released this 03 Jan 12:34
· 3 commits to main since this release
v0.4.0
3a9b552

✨ InstantDB Schema Management CLI

This release adds a comprehensive CLI tool for managing InstantDB schemas directly from Dart/Flutter projects. The CLI wraps the official InstantDB Node.js CLI and provides seamless integration for schema synchronization.

🚀 New Features

Built-in Schema CLI

Manage InstantDB schemas from any Dart/Flutter project:

# Available in any project that depends on instantdb_flutter
dart run instantdb_flutter:schema pull      # Pull from cloud
dart run instantdb_flutter:schema push      # Push to cloud  
dart run instantdb_flutter:schema status    # Show status
dart run instantdb_flutter:schema validate  # Validate schema
dart run instantdb_flutter:schema diff      # Compare (coming soon)
dart run instantdb_flutter:schema help      # Show help

Features

  • ✅ Pull schemas from cloud - Download TypeScript schemas from InstantDB
  • ✅ Push schemas to cloud - Upload TypeScript schemas to InstantDB
  • ✅ Schema status - View local schema files and CLI availability
  • ✅ Schema validation - Validate Dart schema file syntax
  • ✅ Color-coded output - Info, success, warnings, and errors
  • ✅ Interactive confirmations - Safe operations with user prompts
  • ✅ Custom locations - --schema-file flag for custom paths
  • ✅ App ID override - --app-id flag for multi-environment support
  • ✅ Verbose logging - --verbose flag for detailed output

📦 Integration Options

Direct CLI Usage

# Works from any project with instantdb_flutter dependency
dart run instantdb_flutter:schema pull

Just/Make Integration

Add to your justfile:

schema-pull:
    dart run instantdb_flutter:schema pull

schema-push:
    dart run instantdb_flutter:schema push

schema-status:
    dart run instantdb_flutter:schema status

Then use: just schema-pull, just schema-push, etc.

NPM Scripts

Add to package.json:

{
  "scripts": {
    "schema:pull": "dart run instantdb_flutter:schema pull",
    "schema:push": "dart run instantdb_flutter:schema push"
  }
}

📖 Documentation

Quick Start

  1. Install Node.js and npx (required for InstantDB CLI)
  2. Authenticate: npx instant-cli@latest login
  3. Set app ID: export INSTANT_APP_ID=your-app-id
  4. Run commands: dart run instantdb_flutter:schema help

Comprehensive Guides

  • README.md - Schema Management section with quick start
  • SCHEMA_MANAGEMENT.md - Complete guide including:
    • All CLI commands with examples
    • Integration patterns (CLI, justfile, npm scripts)
    • Current workflow (manual conversion)
    • Future workflow (automated conversion - planned)
    • Best practices and troubleshooting
    • Roadmap and planned features

🔧 Technical Details

New Files:

  • bin/schema.dart - CLI implementation (374 lines)
  • SCHEMA_MANAGEMENT.md - Documentation (390 lines)

Modified Files:

  • pubspec.yaml - Added args: ^2.6.0 dependency + executable
  • justfile - Added schema management commands
  • README.md - Added Schema Management section
  • CHANGELOG.md - Full release notes

CLI Features:

  • Color-coded output (blue=info, green=success, yellow=warning, red=error)
  • Interactive confirmations for destructive operations
  • Custom schema file locations
  • App ID override support
  • Verbose logging mode

⚠️ Current Limitations

Manual Conversion Required:

  • TypeScript → Dart schema conversion is manual (for now)
  • Dart → TypeScript schema conversion is manual (for now)

You need to maintain both instant.schema.ts (TypeScript) and your Dart schema definitions in sync manually.

🗺️ Roadmap

Planned Enhancements:

  • Automatic TypeScript ↔ Dart schema conversion
  • Visual schema diff with highlighting
  • Schema migration generation
  • Schema backup and restore
  • Multi-environment management (dev/staging/prod)
  • Schema snapshots with rollback support

📋 Migration Guide

No breaking changes - this is a pure feature addition. Existing code continues to work unchanged.

To start using schema management:

  1. Ensure Node.js and npx are installed
  2. Authenticate with InstantDB: npx instant-cli@latest login
  3. Set your app ID: export INSTANT_APP_ID=your-app-id
  4. Run: dart run instantdb_flutter:schema help

🎯 Use Cases

Team Collaboration

  • Pull latest schema before starting work
  • Push schema changes for team review
  • Validate schemas in CI/CD pipelines

Multi-Environment Deployment

# Development
INSTANT_APP_ID=dev-app-123 dart run instantdb_flutter:schema push

# Production  
INSTANT_APP_ID=prod-app-456 dart run instantdb_flutter:schema push

CI/CD Integration

# .github/workflows/test.yml
- name: Validate Schema
  run: dart run instantdb_flutter:schema validate

📚 Resources

🙏 Feedback Welcome

This is the first release of the schema management CLI. We'd love to hear your feedback and suggestions!

⬆️ Upgrading

Update your pubspec.yaml:

dependencies:
  instantdb_flutter: ^0.4.0

Then run:

flutter pub get

The schema CLI will be immediately available:

dart run instantdb_flutter:schema help
Assets 2
Loading