db-migrate-x 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8946c58a0fbd70adc0f1c92b27dcfc001ede4438379d1c90731c061c34ad79d
-  data.tar.gz: 804e612a9163f3692b2265b881b806800dbe13eeb2cb3ce6c1c36e0dbab36d09
+  metadata.gz: 0e074cbb0b589d7362ae27ff450ada897cda5fe6f061fabe73f8c67cec13b16e
+  data.tar.gz: 75b1eb715150b5f8c7f26ccdb8b0c692c260876f4f7e110ed28546fe3bf2ba4f
 SHA512:
-  metadata.gz: c62649721fe87d70e29554f15f147bcba2a168b951d28834f340ba42363d7c6984d6b0b4fe0e16c5bbd879d0f3eb2ddeef63e9f91feee77611eadffe9702cc3c
-  data.tar.gz: ba5da48eaf8bf907a8e71f3264d71f8372426b67938ab28631185a02314f72d3b64cb57fd11063c27e7d59c10d9a25e925e4d261bfd6fd66f3d861ac32d94ca0
+  metadata.gz: b2c772821a3da23ce85e73175e8597ff6c91f087b4ddc9f11ad9369caa05853d6df705e6d6c816c66300def442a35e157a3af92543016d8179bbc95acd5c6cb5
+  data.tar.gz: f65162f9b2c246dcccaec045ea47f5e5bbe75b75cbc30983eb34a47c39d8b9cb7553e03708e0cfa63d0fa5862e71a502f87c5528505183a6e0bcd354ce8b8ac9

data/context/alter-table.md

@@ -0,0 +1,183 @@
+# Alter Table
+
+This guide explains how to modify existing database tables using `db-migrate`.
+
+## Basic Table Alterations
+
+Use `alter_table` to modify an existing table:
+
+```ruby
+DB::Migrate.migrate("update_users_table", client) do
+	alter_table :users do
+		add_column :age, "INTEGER"
+		add_column :active, "BOOLEAN DEFAULT TRUE"
+	end
+end
+```
+
+## Adding Columns
+
+### Basic Column Addition
+
+```ruby
+alter_table :users do
+	add_column :email, "TEXT"
+	add_column :phone, "TEXT"
+end
+```
+
+### Columns with Constraints
+
+```ruby
+alter_table :users do
+	add_column :email, "TEXT NOT NULL"
+	add_column :age, "INTEGER", default: 0
+	add_column :status, "TEXT", unique: true
+end
+```
+
+## Dropping Columns
+
+### Basic Column Removal
+
+```ruby
+alter_table :users do
+	drop_column :old_field
+	drop_column :deprecated_column
+end
+```
+
+### Safe Column Removal
+
+Use `if_exists` to avoid errors if the column doesn't exist:
+
+```ruby
+alter_table :users do
+	drop_column :maybe_missing_column, if_exists: true
+end
+```
+
+## Renaming Columns
+
+```ruby
+alter_table :users do
+	rename_column :full_name, :name
+	rename_column :email_address, :email
+end
+```
+
+## Changing Column Types
+
+Use `change_column` to modify a column's data type:
+
+```ruby
+alter_table :users do
+	change_column :age, "INTEGER"
+	change_column :balance, "DECIMAL(10,2)"
+end
+```
+
+### Database-Specific Behavior
+
+The gem automatically uses the appropriate syntax for your database:
+
+**PostgreSQL:**
+```sql
+ALTER TABLE users ALTER COLUMN age TYPE INTEGER USING age::INTEGER;
+```
+
+**MariaDB/MySQL:**
+```sql
+ALTER TABLE users MODIFY COLUMN age INTEGER;
+```
+
+## Multiple Operations
+
+Combine multiple alterations in a single migration:
+
+```ruby
+alter_table :users do
+	add_column :middle_name, "TEXT"
+	drop_column :old_field, if_exists: true
+	rename_column :full_name, :name
+	change_column :age, "INTEGER"
+end
+```
+
+## Advanced Examples
+
+### Data Type Conversions
+
+```ruby
+# Convert text to integer with explicit casting
+alter_table :products do
+	change_column :price_text, "DECIMAL(10,2)"
+end
+```
+
+For PostgreSQL, this automatically includes a `USING` clause for safe conversion.
+
+### Adding Columns with Complex Defaults
+
+```ruby
+alter_table :orders do
+	add_column :order_number, "TEXT NOT NULL", 
+				default: "'ORD-' || EXTRACT(epoch FROM NOW())::TEXT"
+end
+```
+
+### Conditional Schema Changes
+
+```ruby
+alter_table :users do
+		# Only add column if it doesn't exist
+	unless information_schema.column_exists?(:users, :created_at)
+		add_column :created_at, "TIMESTAMP DEFAULT NOW()"
+	end
+end
+```
+
+## Feature Detection
+
+The gem uses feature detection to ensure compatibility:
+
+- **Conditional Operations**: `IF EXISTS` clauses are only used when supported
+- **Column Modification**: Uses `MODIFY COLUMN` (MariaDB) vs `ALTER COLUMN TYPE` (PostgreSQL)
+- **Using Clauses**: PostgreSQL's `USING` clause for safe type conversions
+
+## Best Practices
+
+### Safe Alterations
+
+Always use conditional operations when uncertain:
+
+```ruby
+alter_table :users do
+	drop_column :deprecated_field, if_exists: true
+	add_column :new_field, "TEXT"
+end
+```
+
+### Incremental Changes
+
+Make small, focused changes rather than large alterations:
+
+```ruby
+# Good: Focused change
+alter_table :users do
+	add_column :email_verified, "BOOLEAN DEFAULT FALSE"
+end
+
+# Better than: Large, complex change
+alter_table :users do
+	add_column :email_verified, "BOOLEAN DEFAULT FALSE"
+	add_column :phone_verified, "BOOLEAN DEFAULT FALSE"
+	add_column :two_factor_enabled, "BOOLEAN DEFAULT FALSE"
+	drop_column :old_verification_method, if_exists: true
+	rename_column :verification_code, :email_verification_code
+end
+```
+
+### Performance Considerations
+
+For large tables, consider the performance impact of schema changes, especially when adding `NOT NULL` columns without defaults.

data/context/create-index.md

@@ -0,0 +1,217 @@
+# Create Index
+
+This guide explains how to create database indexes using `db-migrate`.
+
+## Basic Index Creation
+
+Use `create_index` to add indexes for better query performance:
+
+```ruby
+DB::Migrate.migrate("add_user_indexes", client) do
+	create_index :users, :email
+	create_index :users, :name
+end
+```
+
+## Composite Indexes
+
+Create indexes on multiple columns:
+
+```ruby
+DB::Migrate.migrate("add_composite_indexes", client) do
+	create_index :orders, [:user_id, :created_at]
+	create_index :user_preferences, [:user_id, :preference_key]
+end
+```
+
+## Index Options
+
+### Unique Indexes
+
+Enforce uniqueness at the database level:
+
+```ruby
+create_index :users, :email, unique: true
+create_index :user_preferences, [:user_id, :preference_key], unique: true
+```
+
+### Named Indexes
+
+Specify custom index names:
+
+```ruby
+create_index :users, :email, name: "idx_users_email_unique", unique: true
+create_index :orders, [:user_id, :status], name: "idx_orders_user_status"
+```
+
+### Conditional Indexes (PostgreSQL)
+
+Create partial indexes with conditions:
+
+```ruby
+# PostgreSQL-specific conditional index
+create_index :users, :email, 
+		name: "idx_active_users_email",
+		condition: "active = true"
+```
+
+## Index Types
+
+### Standard B-tree Indexes
+
+Default index type, good for equality and range queries:
+
+```ruby
+create_index :users, :created_at  # Range queries
+create_index :users, :status      # Equality queries
+```
+
+### Database-Specific Index Types
+
+```ruby
+# PostgreSQL GIN index for JSONB
+create_index :documents, :metadata, type: "GIN"
+
+# PostgreSQL GiST index for geometric data
+create_index :locations, :coordinates, type: "GiST"
+
+# Text search indexes
+create_index :articles, :content, type: "GIN", 
+		expression: "to_tsvector('english', content)"
+```
+
+## Advanced Examples
+
+### Functional Indexes
+
+Create indexes on expressions:
+
+```ruby
+# Index on lowercase email for case-insensitive searches
+create_index :users, nil,
+		name: "idx_users_email_lower",
+		expression: "LOWER(email)"
+
+# Index on extracted JSON field
+create_index :documents, nil,
+		name: "idx_documents_title", 
+		expression: "metadata->>'title'"
+```
+
+### Concurrent Index Creation (PostgreSQL)
+
+For large tables, create indexes without blocking writes:
+
+```ruby
+# Note: This requires special handling and may not be supported
+# in all migration contexts due to transaction requirements
+create_index :large_table, :important_column, 
+		algorithm: "CONCURRENTLY"
+```
+
+## Performance Considerations
+
+### Index Strategy
+
+Choose indexes based on your query patterns:
+
+```ruby
+# Good: Index frequently queried columns
+create_index :orders, :user_id      # For user's orders
+create_index :orders, :created_at   # For recent orders
+create_index :orders, :status       # For order filtering
+
+# Composite index for common query combinations
+create_index :orders, [:user_id, :status]  # For user's pending orders
+```
+
+### Avoid Over-Indexing
+
+Don't create unnecessary indexes:
+
+```ruby
+# Avoid: Too many single-column indexes
+create_index :users, :first_name
+create_index :users, :last_name  
+create_index :users, [:first_name, :last_name]  # This composite covers both
+
+# Better: Strategic composite index
+create_index :users, [:last_name, :first_name]  # Covers both queries
+```
+
+## Creating Indexes in Table Definitions
+
+You can also create indexes when defining tables:
+
+```ruby
+create_table :users do
+	primary_key
+	column :email, "TEXT NOT NULL", unique: true, index: true
+	column :name, "TEXT", index: true
+	timestamps
+	
+		# Composite indexes
+	index [:email, :created_at]
+	index [:name, :active], name: "idx_active_users_by_name"
+end
+```
+
+## Dropping Indexes
+
+Remove indexes when they're no longer needed:
+
+```ruby
+DB::Migrate.migrate("cleanup_unused_indexes", client) do
+	drop_index :idx_old_user_lookup, if_exists: true
+	drop_index :idx_deprecated_search, if_exists: true
+end
+```
+
+## Feature Detection
+
+The gem automatically handles database-specific index features:
+
+- **Conditional Indexes**: Only used when supported (PostgreSQL)
+- **Index Types**: Database-specific types like GIN, GiST
+- **IF EXISTS**: Safe index creation/removal when supported
+
+## Best Practices
+
+### Index Naming Convention
+
+Use consistent naming patterns:
+
+```ruby
+# Good: Descriptive names
+create_index :users, :email, name: "idx_users_email"
+create_index :orders, [:user_id, :status], name: "idx_orders_user_status"
+
+# Pattern: idx_{table}_{columns}_{suffix}
+create_index :users, :email, name: "idx_users_email_unique", unique: true
+```
+
+### Monitor Index Usage
+
+Regularly review index effectiveness:
+
+```sql
+-- PostgreSQL: Check index usage
+SELECT schemaname, tablename, indexname, idx_scan 
+FROM pg_stat_user_indexes 
+WHERE idx_scan = 0;
+
+-- MariaDB: Check index cardinality
+SHOW INDEX FROM users;
+```
+
+### Index Maintenance
+
+Consider index maintenance in high-traffic applications:
+
+```ruby
+# For very large tables, create indexes during low-traffic periods
+DB::Migrate.migrate("add_large_table_index", client) do
+		# Consider creating this during maintenance windows
+	create_index :large_transaction_table, :created_at
+end
+```

data/context/create-table.md

@@ -0,0 +1,170 @@
+# Create Table
+
+This guide explains how to create database tables using `db-migrate`.
+
+## Basic Table Creation
+
+Use `create_table` to define a new table:
+
+```ruby
+DB::Migrate.migrate("create_users", client) do
+	create_table :users do
+		primary_key
+		column :name, "TEXT NOT NULL"
+		column :email, "TEXT UNIQUE"
+		timestamps
+	end
+end
+```
+
+## Conditional Table Creation
+
+Use `create_table?` to create a table only if it doesn't already exist:
+
+```ruby
+DB::Migrate.migrate("safe_create_users", client) do
+	create_table? :users do
+		primary_key
+		column :name, "TEXT NOT NULL"
+	end
+end
+```
+
+## Column Definitions
+
+### Basic Columns
+
+Define columns with their SQL type:
+
+```ruby
+create_table :products do
+	column :name, "TEXT NOT NULL"
+	column :price, "DECIMAL(10,2)"
+	column :description, "TEXT"
+	column :active, "BOOLEAN DEFAULT TRUE"
+end
+```
+
+### Primary Keys
+
+Add an auto-incrementing primary key:
+
+```ruby
+create_table :users do
+	primary_key # Creates 'id' column
+		# Other columns...
+end
+
+# Custom primary key name
+create_table :users do
+	primary_key :user_id
+		# Other columns...
+end
+```
+
+The primary key uses database-appropriate types:
+- PostgreSQL: `BIGSERIAL PRIMARY KEY`
+- MariaDB/MySQL: `BIGINT AUTO_INCREMENT PRIMARY KEY`
+
+### Timestamps
+
+Add created_at and updated_at columns:
+
+```ruby
+create_table :posts do
+	primary_key
+	column :title, "TEXT NOT NULL"
+	timestamps # Adds created_at and updated_at
+end
+```
+
+## Column Options
+
+### Constraints
+
+```ruby
+create_table :users do
+	primary_key
+	column :email, "TEXT NOT NULL", unique: true
+	column :age, "INTEGER", null: false
+	column :status, "TEXT", default: "'active'"
+end
+```
+
+### Indexes
+
+Create indexes on columns:
+
+```ruby
+create_table :users do
+	primary_key
+	column :email, "TEXT NOT NULL", unique: true, index: true
+	column :name, "TEXT", index: true
+end
+```
+
+## Advanced Examples
+
+### Composite Indexes
+
+```ruby
+create_table :user_preferences do
+	primary_key
+	column :user_id, "BIGINT NOT NULL"
+	column :preference_key, "TEXT NOT NULL"
+	column :preference_value, "TEXT"
+	
+		# Create composite index
+	index [:user_id, :preference_key], unique: true
+end
+```
+
+### Foreign Key References
+
+```ruby
+create_table :posts do
+	primary_key
+	column :user_id, "BIGINT NOT NULL"
+	column :title, "TEXT NOT NULL"
+	column :content, "TEXT"
+	timestamps
+	
+		# Note: Foreign key constraints are defined separately
+		# This just creates the reference column
+end
+```
+
+### Database-Specific Types
+
+```ruby
+create_table :analytics do
+	primary_key
+	column :event_data, "JSONB"  # PostgreSQL
+	column :tags, "JSON"         # MariaDB/MySQL
+	column :metadata, "TEXT"     # Universal fallback
+end
+```
+
+## Options
+
+### Drop Existing Table
+
+Replace an existing table:
+
+```ruby
+create_table :users, drop_if_exists: true do
+	primary_key
+	column :name, "TEXT NOT NULL"
+end
+```
+
+### Temporary Tables
+
+```ruby
+create_table :temp_data, temporary: true do
+	column :id, "BIGINT"
+	column :data, "TEXT"
+end
+```
+
+Note: Temporary table support depends on your database adapter implementation.