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:

``bash
npm install forge-sql-orm-cli -D
`

Basic installation for UI-Kit projects

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

$3

Add the following scripts to your package.json:

`bash
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"
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

$3

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.

`bash
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

$3

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.

`bash
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.

$3

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.

`bash
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)

$3

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.

`bash
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:

`env
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

$3

First, install the CLI and setup npm scripts:

`bash
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"
`

$3

`bash
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.

$3

`bash
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.

$3

`bash
npm run migration:update
`

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

$3

`bash
npm run migration:drop
`

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

Development

$3

`bash
npm test
`

$3

`bash
npm run test:coverage
`

$3

`bash
npm run lint
`

$3

`bash
npm run format
``