appbuild-oceanbase-console 1.10.2

package/types/migrations.d.ts

@@ -0,0 +1,240 @@
+import { TablesDB } from './services/tables-db';
+/**
+ * Database Schema Migration Tool
+ *
+ * This module provides a tool for managing database schema migrations in Appwrite.
+ * It compares the current database state with a target schema definition and generates
+ * migration operations to synchronize them.
+ *
+ * Usage example:
+ * ```typescript
+ * import { sdk } from 'appwrite-console-sdk';
+ *
+ * // Get project-level SDK
+ * const projectSdk = sdk.forProject('region', 'project-id');
+ *
+ * // Define your schema
+ * const schema: SchemaDefinition = {
+ *   databaseId: 'my-database',
+ *   collections: [{
+ *     name: 'memos',
+ *     _description: '备忘录集合',
+ *     documentSecurity: true,
+ *     attributes: [
+ *       { key: 'id', type: 'string', size: 36, required: true },
+ *       { key: 'title', type: 'string', size: 255, required: true },
+ *       { key: 'content', type: 'string', size: 65535, required: true },
+ *       { key: 'userId', type: 'string', size: 36, required: true },
+ *       { key: 'createdAt', type: 'datetime', required: true },
+ *       { key: 'updatedAt', type: 'datetime', required: false },
+ *       { key: 'isPinned', type: 'boolean', default: false, required: false }
+ *     ],
+ *     indexes: [
+ *       { key: 'user_idx', type: 'index', attributes: ['userId'] },
+ *       { key: 'created_at_idx', type: 'index', attributes: ['createdAt'] }
+ *     ]
+ *   }]
+ * };
+ *
+ * // Generate migration plan
+ * const migration = projectSdk.schemaMigration;
+ * const plan = await migration.generatePlan(schema);
+ *
+ * // Preview changes (dry run)
+ * await migration.execute(plan, schema, { dryRun: true });
+ *
+ * // Execute migration
+ * await migration.execute(plan, schema);
+ * ```
+ */
+/**
+ * Schema definition types
+ */
+export interface SchemaAttribute {
+    key: string;
+    type: 'string' | 'integer' | 'float' | 'boolean' | 'datetime' | 'email' | 'enum' | 'url' | 'ip' | 'point' | 'line' | 'polygon' | 'relationship';
+    size?: number;
+    required: boolean;
+    default?: any;
+    array?: boolean;
+    elements?: string[];
+    min?: number;
+    max?: number;
+    encrypt?: boolean;
+    relatedCollectionId?: string;
+    relationshipType?: 'oneToOne' | 'oneToMany' | 'manyToOne' | 'manyToMany';
+    twoWay?: boolean;
+    twoWayKey?: string;
+    onDelete?: 'cascade' | 'restrict' | 'setNull';
+}
+export interface SchemaIndex {
+    key: string;
+    type: 'index' | 'unique' | 'fulltext';
+    attributes: string[];
+    orders?: string[];
+    lengths?: number[];
+}
+export interface SchemaCollection {
+    _description?: string;
+    name: string;
+    documentSecurity?: boolean;
+    enabled?: boolean;
+    permissions?: string[];
+    attributes: SchemaAttribute[];
+    indexes?: SchemaIndex[];
+}
+export interface SchemaDefinition {
+    databaseId: string;
+    collections: SchemaCollection[];
+}
+/**
+ * Migration operation types
+ */
+export declare type MigrationOperationType = 'createCollection' | 'updateCollection' | 'deleteCollection' | 'createAttribute' | 'updateAttribute' | 'deleteAttribute' | 'createIndex' | 'deleteIndex';
+export interface MigrationOperation {
+    type: MigrationOperationType;
+    databaseId: string;
+    collectionId: string;
+    collectionName?: string;
+    attribute?: SchemaAttribute;
+    index?: SchemaIndex;
+    attributeKey?: string;
+    indexKey?: string;
+    reason?: string;
+}
+export interface MigrationPlan {
+    operations: MigrationOperation[];
+    summary: {
+        collectionsToCreate: number;
+        collectionsToUpdate: number;
+        collectionsToDelete: number;
+        attributesToCreate: number;
+        attributesToUpdate: number;
+        attributesToDelete: number;
+        indexesToCreate: number;
+        indexesToDelete: number;
+    };
+}
+/**
+ * Database Schema Migration Tool
+ *
+ * This tool helps manage database schema migrations by:
+ * 1. Comparing current database state with target schema
+ * 2. Generating migration operations
+ * 3. Executing migration operations
+ */
+export declare class SchemaMigration {
+    private databases;
+    constructor(databases: TablesDB);
+    /**
+     * Generate migration plan by comparing current database state with target schema
+     */
+    generatePlan(schema: SchemaDefinition): Promise<MigrationPlan>;
+    /**
+     * Compare two attributes to see if they differ
+     */
+    private compareAttributes;
+    /**
+     * Compare two indexes to see if they differ
+     */
+    private compareIndexes;
+    /**
+     * Execute migration plan
+     *
+     * @param plan - Migration plan generated by generatePlan
+     * @param schema - Original schema definition (needed for collection properties)
+     * @param options - Execution options including dryRun mode
+     *
+     * @example
+     * ```typescript
+     * const schema: SchemaDefinition = {
+     *   databaseId: 'my-database',
+     *   collections: [{
+     *     name: 'memos',
+     *     documentSecurity: true,
+     *     attributes: [
+     *       { key: 'id', type: 'string', size: 36, required: true },
+     *       { key: 'title', type: 'string', size: 255, required: true }
+     *     ]
+     *   }]
+     * };
+     *
+     * const migration = new SchemaMigration(tablesDB);
+     * const plan = await migration.generatePlan(schema);
+     * await migration.execute(plan, schema, { dryRun: true }); // Preview changes
+     * await migration.execute(plan, schema); // Execute changes
+     * ```
+     */
+    execute(plan: MigrationPlan, schema: SchemaDefinition, options?: {
+        dryRun?: boolean;
+    }): Promise<void>;
+    /**
+     * Wait for a column to reach a specific state
+     *
+     * @param databaseId - Database ID
+     * @param collectionId - Collection ID
+     * @param attributeKey - Column key to wait for
+     * @param mode - Wait mode: 'available' (wait for column to be available) or 'deleted' (wait for column to be deleted)
+     * @param maxWaitTime - Maximum time to wait in milliseconds
+     * @param pollInterval - Polling interval in milliseconds
+     */
+    private waitForColumnState;
+    /**
+     * Wait for an attribute to become available
+     *
+     * @param databaseId - Database ID
+     * @param collectionId - Collection ID
+     * @param attributeKey - Attribute key to wait for
+     * @param maxWaitTime - Maximum time to wait in milliseconds (default: 10000 = 10 seconds)
+     * @param pollInterval - Polling interval in milliseconds (default: 50 = 50 milliseconds)
+     */
+    private waitForAttributeAvailable;
+    /**
+     * Wait for an attribute to be deleted
+     *
+     * @param databaseId - Database ID
+     * @param collectionId - Collection ID
+     * @param attributeKey - Attribute key to wait for
+     * @param maxWaitTime - Maximum time to wait in milliseconds (default: 30000 = 30 seconds)
+     * @param pollInterval - Polling interval in milliseconds (default: 500 = 500 milliseconds)
+     */
+    private waitForAttributeDeleted;
+    /**
+     * Wait for multiple attributes to become available
+     *
+     * @param databaseId - Database ID
+     * @param collectionId - Collection ID
+     * @param attributeKeys - Array of attribute keys to wait for
+     */
+    private waitForAttributesAvailable;
+    /**
+     * Wait for an index to be deleted
+     *
+     * @param databaseId - Database ID
+     * @param collectionId - Collection ID
+     * @param indexKey - Index key to wait for
+     * @param maxWaitTime - Maximum time to wait in milliseconds (default: 30000 = 30 seconds)
+     * @param pollInterval - Polling interval in milliseconds (default: 500 = 500 milliseconds)
+     */
+    private waitForIndexDeleted;
+    /**
+     * Execute a single migration operation
+     */
+    private executeOperation;
+    /**
+     * Create a column based on its type
+     */
+    private createAttribute;
+    /**
+     * Map index type string to IndexType enum
+     */
+    private mapIndexType;
+    /**
+     * Map relationship type string to RelationshipType enum
+     */
+    private mapRelationshipType;
+    /**
+     * Map relation mutate string to RelationMutate enum
+     */
+    private mapRelationMutate;
+}