forge-sql-orm-cli 1.0.0

package/README.md

@@ -0,0 +1,202 @@
+# 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
+
+```bash
+npm install -g forge-sql-orm-cli
+```
+
+## 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
+
+### Generate Drizzle Models for Atlassian Forge SQL
+
+```bash
+forge-sql-orm-cli generate:model --host localhost --port 3306 --user root --password secret --dbName myapp --output ./database/entities --saveEnv
+```
+
+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
+forge-sql-orm-cli migrations:create --host localhost --port 3306 --user root --password secret --dbName myapp --output ./database/migration --entitiesPath ./database/entities --saveEnv
+```
+
+This will create a new Atlassian Forge SQL migration file with SQL statements to update your database schema.
+
+### Update Atlassian Forge SQL Migration
+
+```bash
+forge-sql-orm-cli migrations:update --host localhost --port 3306 --user root --password secret --dbName myapp --output ./database/migration --entitiesPath ./database/entities --saveEnv
+```
+
+This will update an existing migration with the latest schema changes for Atlassian Forge SQL.
+
+### Drop Tables with Atlassian Forge SQL Migration
+
+```bash
+forge-sql-orm-cli migrations:drop --host localhost --port 3306 --user root --password secret --dbName myapp --output ./database/migration --entitiesPath ./database/entities --saveEnv
+```
+
+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
+```

package/dist-cli/actions/generate-models.d.ts

@@ -0,0 +1,19 @@
+import "reflect-metadata";
+/**
+ * Options for model generation
+ */
+interface GenerateModelsOptions {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    dbName: string;
+    output: string;
+    versionField: string;
+}
+/**
+ * Generates models for all tables in the database using drizzle-kit
+ * @param options - Generation options
+ */
+export declare const generateModels: (options: GenerateModelsOptions) => Promise<never>;
+export {};

package/dist-cli/actions/migrations-create.d.ts

@@ -0,0 +1,46 @@
+import "reflect-metadata";
+/**
+ * Options for migration creation
+ */
+export interface CreateMigrationOptions {
+    output: string;
+    entitiesPath: string;
+    force?: boolean;
+}
+/**
+ * Loads the current migration version from `migrationCount.ts`.
+ * @param migrationPath - Path to the migration folder.
+ * @returns The latest migration version.
+ */
+export declare const loadMigrationVersion: (migrationPath: string) => Promise<number>;
+/**
+ * Cleans SQL statements by removing unnecessary database options.
+ * @param sql - The raw SQL statement.
+ * @returns The cleaned SQL statement.
+ */
+export declare function cleanSQLStatement(sql: string): string;
+/**
+ * Generates a migration file using the provided SQL statements.
+ * @param createStatements - Array of SQL statements.
+ * @param version - Migration version number.
+ * @returns TypeScript migration file content.
+ */
+export declare function generateMigrationFile(createStatements: string[], version: number): string;
+/**
+ * Saves the generated migration file along with `migrationCount.ts` and `index.ts`.
+ * @param migrationCode - The migration code to be written to the file.
+ * @param version - Migration version number.
+ * @param outputDir - Directory where the migration files will be saved.
+ */
+export declare function saveMigrationFiles(migrationCode: string, version: number, outputDir: string): void;
+/**
+ * Extracts only the relevant SQL statements for migration.
+ * @param schema - The full database schema as SQL.
+ * @returns Filtered list of SQL statements.
+ */
+export declare const extractCreateStatements: (schema: string) => string[];
+/**
+ * Creates a full database migration.
+ * @param options - Database connection settings and output paths.
+ */
+export declare const createMigration: (options: CreateMigrationOptions) => Promise<never>;

package/dist-cli/actions/migrations-drops.d.ts

@@ -0,0 +1,6 @@
+import "reflect-metadata";
+/**
+ * Creates a full database migration.
+ * @param options - Database connection settings and output paths.
+ */
+export declare const dropMigration: (options: any) => Promise<never>;

package/dist-cli/actions/migrations-update.d.ts

@@ -0,0 +1,6 @@
+import "reflect-metadata";
+/**
+ * Updates an existing database migration by generating schema modifications.
+ * @param options - Database connection settings and output paths.
+ */
+export declare const updateMigration: (options: any) => Promise<never>;

package/dist-cli/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+export declare const program: Command;