forge-sql-orm-cli

[

A command-line interface tool for managing Atlassian Forge SQL migrations and model generation with Drizzle ORM integration.

About

forge-sql-orm-cli is a new package that provides a command-line interface for managing database migrations and models in Atlassian Forge SQL applications. It integrates with Drizzle ORM to provide type-safe database operations and schema management.

Features

• Generate Drizzle ORM models from your Atlassian Forge SQL database schema
• Create and manage Atlassian Forge SQL migrations
• Automatic version tracking for schema changes
• Support for MySQL databases in Atlassian Forge environment
• Environment-based configuration

Installation

The CLI tool must be installed as a local development dependency and used via npm scripts:

npm install forge-sql-orm-cli -D

Basic installation for UI-Kit projects

npm install forge-sql-orm-cli -D --legacy-peer-deps

Setup npm Scripts

Add the following scripts to your package.json:

npm pkg set scripts.models:create="forge-sql-orm-cli generate:model --output src/entities --saveEnv"
npm pkg set scripts.migration:create="forge-sql-orm-cli migrations:create --force --output src/migration --entitiesPath src/entities"
npm pkg set scripts.migration:update="forge-sql-orm-cli migrations:update --entitiesPath src/entities --output src/migration"

Note: The CLI tool is designed to work as a local dependency through npm scripts. Configuration is saved to .env file using the --saveEnv flag, so you only need to provide database credentials once.

Available Commands

Generate Models

Generate Drizzle ORM models and version metadata from your Atlassian Forge SQL database schema. This command will create TypeScript files with Drizzle table definitions and schema types compatible with Atlassian Forge SQL.

forge-sql-orm-cli generate:model [options]

Options:

• --saveEnv - Save the configuration to a .env file
• --host - Database host (default: localhost)
• --port - Database port (default: 3306)
• --user - Database user
• --password - Database password
• --dbName - Database name
• --output - Output directory for generated models (default: ./database/entities)
• --versionField - Name of the version field (default: version)

The generated models will include:

• Drizzle table definitions compatible with Atlassian Forge SQL
• TypeScript types for your database schema
• Version metadata for tracking schema changes

Create Migration

Create a new Atlassian Forge SQL migration file based on your current database schema. This will generate SQL statements that can be used to update your Atlassian Forge SQL database schema.

forge-sql-orm-cli migrations:create [options]

Options:

• --saveEnv - Save the configuration to a .env file
• --host - Database host (default: localhost)
• --port - Database port (default: 3306)
• --user - Database user
• --password - Database password
• --dbName - Database name
• --output - Output directory for migrations (default: ./database/migration)
• --entitiesPath - Path to entity files (default: ./database/entities)
• --force - Force overwrite existing migrations. Without this parameter, the command will fail if migrations already exist.

Update Migration

Update an existing Atlassian Forge SQL migration with the latest schema changes. This command will compare your current database schema with the Drizzle models and generate the necessary SQL statements for Atlassian Forge SQL.

forge-sql-orm-cli migrations:update [options]

Options:

• --saveEnv - Save the configuration to a .env file
• --host - Database host (default: localhost)
• --port - Database port (default: 3306)
• --user - Database user
• --password - Database password
• --dbName - Database name
• --output - Output directory for migrations (default: ./database/migration)
• --entitiesPath - Path to entity files (default: ./database/entities)

Drop Migration

Create an Atlassian Forge SQL migration to drop tables from the database. This is useful when you need to remove tables or reset your database schema in Atlassian Forge environment.

forge-sql-orm-cli migrations:drop [options]

Options:

• --saveEnv - Save the configuration to a .env file
• --host - Database host (default: localhost)
• --port - Database port (default: 3306)
• --user - Database user
• --password - Database password
• --dbName - Database name
• --output - Output directory for migrations (default: ./database/migration)
• --entitiesPath - Path to entity files (default: ./database/entities)

Atlassian Forge SQL Integration

This CLI tool is designed to work seamlessly with Atlassian Forge SQL and Drizzle ORM. It provides the following features:

1. Model Generation

   • Creates Drizzle table definitions compatible with Atlassian Forge SQL
   • Generates TypeScript types for your schema
   • Supports all Drizzle column types
   • Maintains relationships between tables
   • Ensures compatibility with Atlassian Forge SQL constraints

2. Migration Management

   • Generates Atlassian Forge SQL-compatible migrations
   • Tracks schema versions
   • Supports incremental updates
   • Handles table creation, modification, and deletion
   • Ensures migrations follow Atlassian Forge SQL best practices

3. Type Safety

   • Full TypeScript support
   • Type-safe database operations
   • Automatic type generation from schema
   • Validation against Atlassian Forge SQL requirements

Environment Variables

The CLI supports loading configuration from environment variables. You can either:

1. Use the --saveEnv flag to save your configuration to a .env file
2. Create a .env file manually with the following variables:

FORGE_SQL_ORM_HOST=localhost
FORGE_SQL_ORM_PORT=3306
FORGE_SQL_ORM_USER=your_user
FORGE_SQL_ORM_PASSWORD=your_password
FORGE_SQL_ORM_DB_NAME=your_database
FORGE_SQL_ORM_OUTPUT=./database/entities
FORGE_SQL_ORM_ENTITIES_PATH=./database/entities
FORGE_SQL_ORM_VERSION_FIELD=version

Examples

Setup

First, install the CLI and setup npm scripts:

npm install forge-sql-orm-cli -D
npm pkg set scripts.models:create="forge-sql-orm-cli generate:model --output src/entities --saveEnv"
npm pkg set scripts.migration:create="forge-sql-orm-cli migrations:create --force --output src/migration --entitiesPath src/entities"
npm pkg set scripts.migration:update="forge-sql-orm-cli migrations:update --entitiesPath src/entities --output src/migration"
npm pkg set scripts.migration:drop="forge-sql-orm-cli migrations:drop --entitiesPath src/entities --output src/migration"

Generate Drizzle Models for Atlassian Forge SQL

npm run models:create

On first run, you'll be prompted for database credentials (host, port, user, password, dbName). These will be saved to .env file for subsequent runs.

This will generate Drizzle table definitions and TypeScript types compatible with Atlassian Forge SQL in the specified output directory.

Create Atlassian Forge SQL Migration

npm run migration:create

This will create a new Atlassian Forge SQL migration file with SQL statements to update your database schema. The --force flag allows overwriting existing migrations.

Update Atlassian Forge SQL Migration

npm run migration:update

This will update an existing migration with the latest schema changes for Atlassian Forge SQL.

Drop Tables with Atlassian Forge SQL Migration

npm run migration:drop

This will create a migration to drop specified tables from your Atlassian Forge SQL database.

Development

Running Tests

npm test

Running Tests with Coverage

npm run test:coverage

Linting

npm run lint

Formatting

npm run format