db-migrate-x 0.2.0 → 0.3.0

data/context/drop-table.md

@@ -0,0 +1,180 @@
+# Drop Table
+
+This guide explains how to remove database tables using `db-migrate`.
+
+## Basic Table Removal
+
+Use `drop_table` to remove a table:
+
+```ruby
+DB::Migrate.migrate("remove_old_table", client) do
+	drop_table :old_users_table
+end
+```
+
+## Safe Table Removal
+
+Use `if_exists` to avoid errors if the table doesn't exist:
+
+```ruby
+DB::Migrate.migrate("safe_cleanup", client) do
+	drop_table :maybe_missing_table, if_exists: true
+end
+```
+
+## Feature Detection
+
+The gem automatically detects whether your database supports `IF EXISTS` clauses:
+
+**PostgreSQL & MariaDB:**
+```sql
+DROP TABLE IF EXISTS old_table;
+```
+
+**Databases without IF EXISTS support:**
+```sql
+DROP TABLE old_table;
+```
+
+## Multiple Table Removal
+
+Remove multiple tables in a single migration:
+
+```ruby
+DB::Migrate.migrate("cleanup_old_tables", client) do
+	drop_table :temp_users, if_exists: true
+	drop_table :old_analytics, if_exists: true
+	drop_table :deprecated_logs, if_exists: true
+end
+```
+
+## Advanced Examples
+
+### Conditional Removal
+
+Check if a table exists before dropping it:
+
+```ruby
+DB::Migrate.migrate("conditional_cleanup", client) do
+	if information_schema.table_exists?(:old_table)
+		drop_table :old_table
+	end
+end
+```
+
+### Table Replacement
+
+Replace an existing table with a new structure:
+
+```ruby
+DB::Migrate.migrate("replace_users_table", client) do
+		# Drop the old table
+	drop_table :users, if_exists: true
+	
+		# Create the new table
+	create_table :users do
+		primary_key
+		column :name, "TEXT NOT NULL"
+		column :email, "TEXT UNIQUE NOT NULL"
+		timestamps
+	end
+end
+```
+
+### Dependent Table Cleanup
+
+Remove tables in the correct order to handle dependencies:
+
+```ruby
+DB::Migrate.migrate("cleanup_related_tables", client) do
+		# Drop dependent tables first
+	drop_table :user_preferences, if_exists: true
+	drop_table :user_sessions, if_exists: true
+	
+		# Then drop the main table
+	drop_table :users, if_exists: true
+end
+```
+
+## Best Practices
+
+### Always Use if_exists for Cleanup
+
+When removing tables during cleanup operations, always use `if_exists`:
+
+```ruby
+# Good: Safe cleanup
+drop_table :temp_table, if_exists: true
+
+# Risky: May fail if table doesn't exist
+drop_table :temp_table
+```
+
+### Document Destructive Operations
+
+Add clear comments for destructive operations:
+
+```ruby
+DB::Migrate.migrate("remove_deprecated_analytics", client) do
+		# WARNING: This permanently removes all analytics data from before 2023
+		# Ensure backup is completed before running this migration
+	drop_table :old_analytics_2022, if_exists: true
+end
+```
+
+### Consider Data Migration
+
+Before dropping tables with important data, consider migrating it:
+
+```ruby
+DB::Migrate.migrate("migrate_user_data", client) do
+		# First, migrate important data
+	session.query("INSERT INTO users_new SELECT id, name, email FROM users_old")
+	
+		# Then drop the old table
+	drop_table :users_old, if_exists: true
+end
+```
+
+## Safety Considerations
+
+### Backup Important Data
+
+Always backup important data before dropping tables:
+
+```bash
+# PostgreSQL
+pg_dump -t old_important_table mydb > backup.sql
+
+# MariaDB/MySQL  
+mysqldump mydb old_important_table > backup.sql
+```
+
+### Test Migrations
+
+Test destructive migrations on a copy of your production data:
+
+```ruby
+# Test migration on development/staging first
+DB::Migrate.migrate("test_table_removal", client) do
+	drop_table :test_table, if_exists: true
+end
+```
+
+### Transaction Safety
+
+Table drops are included in the migration transaction and will be rolled back if any subsequent operation fails:
+
+```ruby
+DB::Migrate.migrate("safe_migration", client) do
+	drop_table :old_table, if_exists: true
+	
+	create_table :new_table do
+		primary_key
+		column :name, "TEXT NOT NULL"
+	end
+	
+		# If this fails, the table drop above is rolled back
+	create_index :new_table, :name
+end
+```

data/context/getting-started.md

@@ -0,0 +1,94 @@
+# Getting Started
+
+This guide explains how to get started with `db-migrate` for managing database schema changes in Ruby applications.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add db-migrate
+```
+
+You'll also need a database adapter. For PostgreSQL:
+
+```bash
+$ bundle add db-postgres
+```
+
+For MariaDB/MySQL:
+
+```bash
+$ bundle add db-mariadb
+```
+
+## Core Concepts
+
+`db-migrate` provides a simple and flexible way to manage database schema changes:
+
+- {DB::Migrate::Migration} which represents a single database migration with schema changes.
+- Database-agnostic migration operations that work across PostgreSQL, MariaDB, and other supported databases.
+- Feature detection that automatically uses the best SQL syntax for your database.
+
+## Usage
+
+Create and run a migration:
+
+```ruby
+require "db/migrate"
+require "db/postgres" # or 'db/mariadb'
+
+# Connect to your database
+client = DB::Client.new(DB::Postgres::Adapter.new(
+		host: "localhost",
+		database: "myapp_development"
+))
+
+# Define and run a migration
+DB::Migrate.migrate("create_users_table", client) do
+	create_table :users do
+		primary_key
+		column :name, "TEXT NOT NULL"
+		column :email, "TEXT UNIQUE"
+		timestamps
+	end
+end
+```
+
+### Running Multiple Operations
+
+Migrations can include multiple operations:
+
+```ruby
+DB::Migrate.migrate("update_users_schema", client) do
+		# Add new columns
+	alter_table :users do
+		add_column :age, "INTEGER"
+		add_column :active, "BOOLEAN DEFAULT TRUE"
+	end
+	
+		# Create indexes
+	create_index :users, :email
+	create_index :users, [:name, :active]
+end
+```
+
+### Conditional Operations
+
+Use conditional operations when you're not sure if tables or columns exist:
+
+```ruby
+DB::Migrate.migrate("safe_schema_update", client) do
+		# Only create table if it doesn't exist
+	create_table? :profiles do
+		primary_key
+		column :user_id, "BIGINT NOT NULL"
+		column :bio, "TEXT"
+	end
+	
+		# Only drop table if it exists
+	drop_table :old_table, if_exists: true
+end
+```
+
+The `db-migrate` gem automatically detects your database's capabilities and only uses conditional operations (like `IF EXISTS`) when supported.

data/context/index.yaml

@@ -0,0 +1,29 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: Database migrations.
+metadata:
+  documentation_uri: https://socketry.github.io/db-migrate/
+  funding_uri: https://github.com/sponsors/ioquatix/
+  source_code_uri: https://github.com/socketry/db-migrate.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to get started with `db-migrate` for managing
+    database schema changes in Ruby applications.
+- path: migrations.md
+  title: Migrations
+  description: This guide explains how to create and structure database migrations
+    using `db-migrate`.
+- path: create-table.md
+  title: Create Table
+  description: This guide explains how to create database tables using `db-migrate`.
+- path: alter-table.md
+  title: Alter Table
+  description: This guide explains how to modify existing database tables using `db-migrate`.
+- path: drop-table.md
+  title: Drop Table
+  description: This guide explains how to remove database tables using `db-migrate`.
+- path: create-index.md
+  title: Create Index
+  description: This guide explains how to create database indexes using `db-migrate`.

data/context/migrations.md

@@ -0,0 +1,98 @@
+# Migrations
+
+This guide explains how to create and structure database migrations using `db-migrate`.
+
+## Overview
+
+Migrations in `db-migrate` are Ruby blocks that define schema changes. Each migration runs inside a database transaction, ensuring consistency and allowing rollback on errors.
+
+## Basic Migration Structure
+
+```ruby
+DB::Migrate.migrate("migration_name", client) do
+		# Schema operations go here
+end
+```
+
+## Migration Naming
+
+Use descriptive names that indicate what the migration does:
+
+```ruby
+# Good examples
+DB::Migrate.migrate("create_users_table", client) do
+		# ...
+end
+
+DB::Migrate.migrate("add_email_index_to_users", client) do
+		# ...
+end
+
+DB::Migrate.migrate("remove_deprecated_columns", client) do
+		# ...
+end
+```
+
+## Transaction Safety
+
+All migration operations run inside a database transaction. If any operation fails, the entire migration is rolled back:
+
+```ruby
+DB::Migrate.migrate("complex_migration", client) do
+	create_table :users do
+		primary_key
+		column :name, "TEXT NOT NULL"
+	end
+	
+		# If this fails, the table creation above is rolled back
+	create_index :users, :name
+end
+```
+
+## Database Compatibility
+
+`db-migrate` automatically detects your database's capabilities and generates appropriate SQL:
+
+### PostgreSQL
+- Uses `BIGSERIAL` for auto-increment columns
+- Supports `IF EXISTS` clauses
+- Uses `ALTER COLUMN ... TYPE ... USING ...` for column type changes
+
+### MariaDB/MySQL  
+- Uses `BIGINT AUTO_INCREMENT` for auto-increment columns
+- Supports `IF EXISTS` clauses
+- Uses `MODIFY COLUMN` for column type changes
+
+## Available Operations
+
+### Table Operations
+- `create_table(name)` - Create a new table
+- `create_table?(name)` - Create table only if it doesn't exist
+- `drop_table(name, if_exists: true)` - Drop a table
+- `rename_table(old_name, new_name)` - Rename a table
+
+### Column Operations
+- `add_column(name, type)` - Add a new column
+- `drop_column(name, if_exists: true)` - Remove a column
+- `rename_column(old_name, new_name)` - Rename a column
+- `change_column(name, new_type)` - Change column type
+
+### Index Operations
+- `create_index(table, columns)` - Create an index
+- `drop_index(name, if_exists: true)` - Drop an index
+
+## Information Schema Access
+
+Query database metadata within migrations:
+
+```ruby
+DB::Migrate.migrate("conditional_migration", client) do
+		# Check if table exists before creating
+	unless information_schema.table_exists?(:users)
+		create_table :users do
+			primary_key
+			column :name, "TEXT NOT NULL"
+		end
+	end
+end
+```

data/lib/db/migrate/alter_table.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2021-2024, by Samuel Williams.
+
+module DB
+	module Migrate
+		class AlterTable
+			def initialize(name)
+				@name = name
+				@operations = []
+			end
+			
+			attr_reader :name, :operations
+			
+			# Add a new column to the table
+			def add_column(name, type, **options)
+				@operations << [:add_column, name, type, options]
+			end
+			
+			# Drop a column from the table
+			def drop_column(name, if_exists: false)
+				@operations << [:drop_column, name, {if_exists: if_exists}]
+			end
+			
+			# Rename a column
+			def rename_column(old_name, new_name)
+				@operations << [:rename_column, old_name, new_name, {}]
+			end
+			
+			# Change column type or options
+			def change_column(name, type, **options)
+				@operations << [:change_column, name, type, options]
+			end
+			
+			def call(session)
+				@operations.each do |operation, *args|
+					case operation
+					when :add_column
+						add_column_statement(session, *args)
+					when :drop_column
+						drop_column_statement(session, *args)
+					when :rename_column
+						rename_column_statement(session, *args)
+					when :change_column
+						change_column_statement(session, *args)
+					end
+				end
+			end
+			
+			private
+			
+			def add_column_statement(session, column_name, type, options)
+				statement = session.clause("ALTER TABLE")
+				statement.identifier(@name)
+				statement.clause("ADD COLUMN")
+				statement.identifier(column_name)
+				statement.clause(type)
+				
+				if options.key?(:null) && !options[:null]
+					statement.clause("NOT NULL")
+				end
+				
+				if options.key?(:default)
+					statement.clause("DEFAULT")
+					statement.literal(options[:default])
+				end
+				
+				if options[:unique]
+					statement.clause("UNIQUE")
+				end
+				
+				Console.logger.info(self, statement)
+				statement.call
+			end
+			
+			def drop_column_statement(session, column_name, options)
+				statement = session.clause("ALTER TABLE")
+				statement.identifier(@name)
+				statement.clause("DROP COLUMN")
+				
+				# Use feature detection for IF EXISTS support
+				features = session.connection.features
+				if options[:if_exists] && features.conditional_operations?
+					statement.clause("IF EXISTS")
+				end
+				
+				statement.identifier(column_name)
+				
+				Console.logger.info(self, statement)
+				statement.call
+			end
+			
+			def rename_column_statement(session, old_name, new_name, options)
+				statement = session.clause("ALTER TABLE")
+				statement.identifier(@name)
+				statement.clause("RENAME COLUMN")
+				statement.identifier(old_name)
+				statement.clause("TO")
+				statement.identifier(new_name)
+				
+				Console.logger.info(self, statement)
+				statement.call
+			end
+			
+			def change_column_statement(session, column_name, type, options)
+				# Use feature detection for database-specific syntax
+				features = session.connection.features
+				
+				if features.modify_column?
+					# MySQL/MariaDB syntax: MODIFY COLUMN
+					statement = session.clause("ALTER TABLE")
+					statement.identifier(@name)
+					statement.clause("MODIFY COLUMN")
+					statement.identifier(column_name)
+					statement.clause(type)
+					
+					Console.logger.info(self, statement)
+					statement.call
+				elsif features.alter_column_type?
+					# PostgreSQL syntax: ALTER COLUMN ... TYPE ... USING ...
+					statement = session.clause("ALTER TABLE")
+					statement.identifier(@name)
+					statement.clause("ALTER COLUMN")
+					statement.identifier(column_name)
+					statement.clause("TYPE")
+					statement.clause(type)
+					
+					if features.using_clause?
+						# Add USING clause for safe conversion
+						statement.clause("USING")
+						statement.identifier(column_name)
+						statement.clause("::")
+						statement.clause(type)
+					end
+					
+					Console.logger.info(self, statement)
+					statement.call
+				else
+					# Generic syntax for unsupported databases (default to PostgreSQL-style)
+					statement = session.clause("ALTER TABLE")
+					statement.identifier(@name)
+					statement.clause("ALTER COLUMN")
+					statement.identifier(column_name)
+					statement.clause("TYPE")
+					statement.clause(type)
+					
+					Console.logger.info(self, statement)
+					statement.call
+				end
+			end
+		end
+	end
+end

data/lib/db/migrate/create_table.rb

@@ -77,7 +77,7 @@ module DB
 					else
 						statement.clause(",")
 					end
-						
+					
 					if type == :key_column
 						statement.clause(session.connection.key_column(name, **options))
 					else

data/lib/db/migrate/drop_index.rb

@@ -18,7 +18,9 @@ module DB
 			def call(session)
 				statement = session.clause("DROP INDEX")
 				
-				if @if_exists
+				# Use feature detection for IF EXISTS support
+				features = session.connection.features
+				if @if_exists && features.conditional_operations?
 					statement.clause("IF EXISTS")
 				end
 				

data/lib/db/migrate/drop_table.rb

@@ -20,7 +20,9 @@ module DB
 			def call(session)
 				statement = session.clause("DROP TABLE")
 				
-				if @if_exists
+				# Use feature detection for IF EXISTS support
+				features = session.connection.features
+				if @if_exists && features.conditional_operations?
 					statement.clause("IF EXISTS")
 				end
 				

data/lib/db/migrate/information_schema.rb

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2021-2024, by Samuel Williams.
 
+require "db"
+
 module DB
 	module Migrate
 		class InformationSchema

data/lib/db/migrate/migration.rb

@@ -4,10 +4,12 @@
 # Copyright, 2021-2024, by Samuel Williams.
 
 require "async"
+require "console"
 
 require_relative "create_table"
 require_relative "rename_table"
 require_relative "create_index"
+require_relative "alter_table"
 
 module DB
 	module Migrate
@@ -17,6 +19,8 @@ module DB
 				@session = session
 			end
 			
+			attr_reader :name, :session
+			
 			def call(&block)
 				create_table?(:migration) do
 					primary_key
@@ -24,7 +28,19 @@ module DB
 					timestamps
 				end
 				
+				# Check if migration has already been executed
+				if migration_exists?
+					Console.logger.info(self, "Migration '#{@name}' already executed, skipping...")
+					return
+				end
+				
+				# Execute the migration
+				Console.logger.info(self, "Running migration '#{@name}'...")
 				self.instance_eval(&block)
+				
+				# Record successful migration
+				record_migration
+				Console.logger.info(self, "Migration '#{@name}' completed successfully.")
 			end
 			
 			def information_schema
@@ -59,6 +75,45 @@ module DB
 				drop_table = DropTable.new(name, if_exists: if_exists)
 				drop_table.call(@session)
 			end
+			
+			def alter_table(name, &block)
+				alter_table = AlterTable.new(name)
+				alter_table.instance_eval(&block)
+				alter_table.call(@session)
+			end
+			
+			private
+			
+			# Check if this migration has already been executed
+			def migration_exists?
+				statement = @session.clause("SELECT COUNT(*) FROM")
+				statement.identifier(:migration)
+				statement.clause("WHERE")
+				statement.identifier(:name)
+				statement.clause("=")
+				statement.literal(@name)
+				
+				result = statement.call
+				count = result.to_a.first.first
+				count > 0
+			end
+			
+			# Record that this migration has been executed
+			def record_migration
+				statement = @session.clause("INSERT INTO")
+				statement.identifier(:migration)
+				statement.clause("(")
+				statement.identifier(:name)
+				statement.clause(",")
+				statement.identifier(:created_at)
+				statement.clause(",")
+				statement.identifier(:updated_at)
+				statement.clause(") VALUES (")
+				statement.literal(@name)
+				statement.clause(", NOW(), NOW())")
+				
+				statement.call
+			end
 		end
 		
 		def self.migrate(name, client, &block)

data/lib/db/migrate/version.rb

@@ -5,6 +5,6 @@
 
 module DB
 	module Migrate
-		VERSION = "0.2.0"
+		VERSION = "0.3.0"
 	end
 end