JAO CLI #

Command-line interface for JAO ORM. Manage migrations, generate schemas, and interact with your database.

Installation #

Global Installation #

dart pub global activate jao_cli

Project Dependency #

dev_dependencies:
  jao_cli: ^0.2.0

Quick Start #

Initialize a New Project #

jao init

This creates:

• jao.yaml - Paths configuration
• lib/config/database.dart - Database configuration (single source of truth)
• lib/migrations/ - Migrations directory
• lib/migrations/migrations.dart - Migration registry
• bin/migrate.dart - Migration CLI entry point

Create a Migration #

jao makemigrations

Run Migrations #

jao migrate

Commands #

init #

Initialize JAO in your project.

jao init

Creates project structure with centralized database config in lib/config/database.dart.

make #

Create a new empty migration file.

jao make [options]

Options:
  -n, --name=<name>   Migration name (required)
  -p, --path=<path>   Output path (default: lib/migrations)

Examples:
  jao make -n=create_users_table
  jao make --name=add_email_to_users
  jao make create_posts  # name as positional argument

makemigrations #

Auto-generate migrations from model changes.

jao makemigrations [options]

Options:
  -n, --name=<name>   Custom migration name
  -p, --path=<path>   Output path
  --dry-run, -n       Show changes without creating files
  --empty             Create empty migration

migrate #

Apply pending migrations.

jao migrate [options]

Options:
  --dry-run, -n   Show SQL without executing
  -v, --verbose   Show detailed output

rollback #

Rollback the last migration(s).

jao rollback [options]

Options:
  -s, --step=<n>  Number of migrations to rollback (default: 1)
  --dry-run, -n   Show SQL without executing
  -v, --verbose   Show detailed output

status #

Show migration status.

jao status [options]

Options:
  -v, --verbose   Show detailed output

reset #

Rollback all migrations.

jao reset [options]

Options:
  -f, --force     Skip confirmation prompt
  --dry-run, -n   Show SQL without executing

refresh #

Reset and re-run all migrations.

jao refresh [options]

Options:
  -f, --force     Skip confirmation prompt
  --dry-run, -n   Show SQL without executing

sql #

Show SQL for migrations without executing.

jao sql [options]

Options:
  -m, --migration=<name>   Show specific migration
  --down                   Show rollback SQL

Configuration #

jao.yaml #

Paths configuration only:

migrations_path: lib/migrations
models_path: lib/models

lib/config/database.dart #

Database configuration (single source of truth for both migrations and runtime):

import 'package:jao/jao.dart';

final databaseConfig = DatabaseConfig.sqlite('app.db');
const databaseAdapter = SqliteAdapter();

// PostgreSQL:
// final databaseConfig = DatabaseConfig.postgres(
//   database: 'myapp',
//   username: 'postgres',
//   password: 'password',
// );
// const databaseAdapter = PostgresAdapter();

// MySQL:
// final databaseConfig = DatabaseConfig.mysql(
//   database: 'myapp',
//   username: 'root',
//   password: 'password',
// );
// const databaseAdapter = MySqlAdapter();

Environment Variables #

Connection URLs #

# PostgreSQL
DATABASE_URL=postgres://user:pass@localhost:5432/mydb

# MySQL
DATABASE_URL=mysql://user:pass@localhost:3306/mydb

# SQLite
DATABASE_URL=sqlite:///path/to/database.db

Project Setup #

bin/migrate.dart #

import 'dart:io';
import 'package:jao_cli/jao_cli.dart';

import '../lib/config/database.dart';
import '../lib/migrations/migrations.dart';

void main(List<String> args) async {
  final config = MigrationRunnerConfig(
    database: databaseConfig,
    adapter: databaseAdapter,
    migrations: allMigrations,
    verbose: args.contains('-v') || args.contains('--verbose'),
  );

  final cli = JaoCli(config);
  exit(await cli.run(args));
}

Examples #

Full Workflow #

# Initialize project
jao init

# Configure database in lib/config/database.dart

# Either manually create a migration:
jao make -n=create_users_table
# Edit the migration file...

# Or auto-generate from models:
jao makemigrations

# Apply migrations
jao migrate

# Check status
jao status

# Rollback if needed
jao rollback

# Reset everything
jao reset --force

# Refresh (reset + migrate)
jao refresh --force

Preview SQL #

# Show all pending migration SQL
jao sql

# Show rollback SQL
jao sql --down

# Show specific migration
jao sql -m=20240101120000_create_users

Related Packages #

• jao - Core ORM package
• jao_generator - Code generator

License #

MIT License - see LICENSE for details.