forge-sql-orm-cli
Version:
CLI tool for Forge SQL ORM
249 lines (173 loc) • 8.69 kB
Markdown
# forge-sql-orm-cli
[](https://www.npmjs.com/package/forge-sql-orm-cli)
[](https://www.npmjs.com/package/forge-sql-orm-cli)
[](https://github.com/forge-sql-orm/forge-sql-orm/blob/master/LICENSE)
[](https://github.com/forge-sql-orm/forge-sql-orm/actions/workflows/node.js.yml)
[[](https://deepscan.io/dashboard#view=project&tid=26652&pid=29272&bid=940614)
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
### Setup npm Scripts
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
### 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.
```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
### 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.
```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.
### 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.
```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)
### 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.
```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
### Setup
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"
```
### Generate Drizzle Models for Atlassian Forge SQL
```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.
### Create Atlassian Forge SQL Migration
```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.
### Update Atlassian Forge SQL Migration
```bash
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
```bash
npm run migration:drop
```
This will create a migration to drop specified tables from your Atlassian Forge SQL database.
## Development
### Running Tests
```bash
npm test
```
### Running Tests with Coverage
```bash
npm run test:coverage
```
### Linting
```bash
npm run lint
```
### Formatting
```bash
npm run format
```