Version 7.0: Upgrade to anydataset-db 7.0

CHANGELOG-6.0.md

@@ -0,0 +1,188 @@
+# Changelog - Version 6.0
+
+## Overview
+
+Version 6.0 represents a major upgrade focused on modernizing the codebase, improving developer experience, and maintaining compatibility with the latest PHP versions and dependencies.
+
+## New Features
+
+### Built-in CLI Tool
+- **Standalone CLI without external dependencies**: Pure PHP implementation without requiring Symfony Console
+- **Environment variable support**: Configure migrations using `MIGRATION_CONNECTION`, `MIGRATION_PATH`, and `MIGRATION_TABLE`
+- **Comprehensive help system**: Multiple verbosity levels (`-v`, `-vv`, `-vvv`) for detailed output
+- **Available commands**:
+  - `version/status` - Show current database version
+  - `create/install` - Create migration tracking table
+  - `reset` - Reset database to base schema
+  - `up` - Migrate to a specific or latest version
+  - `down` - Migrate down to a specific version or version 0
+  - `update` - Automatically update to latest version
+- **Composer bin integration**: Automatically available as `vendor/bin/migrate`
+- **Comprehensive CLI tests**: Full test coverage for CLI functionality
+
+### Enhanced Documentation
+- Complete documentation restructure with separate guides:
+  - Getting Started guide
+  - Database Setup guide
+  - Migration Scripts guide
+  - CLI Usage guide
+  - API Reference guide
+- Docusaurus-ready documentation format
+- Improved accuracy and examples throughout
+
+### Database Handling Improvements
+- Better database name extraction for SQL Server (support for `dbname` and `Database` query parameters)
+- Improved database preparation methods across all database drivers
+- Enhanced SQL statement parsing for SQL Server
+- Type safety improvements with PHP 8.3+ attributes
+
+### Development Environment Enhancements
+- Gitpod configuration for cloud-based development
+- VS Code launch configurations
+- Enhanced GitHub Actions CI workflow with SQL Server support
+- Improved Docker Compose setup
+
+## Bug Fixes
+
+- Fixed Psalm static analysis issues
+- Improved SQL statement splitting for SQL Server to handle edge cases
+- Fixed database name extraction for SQL Server connections
+- Enhanced type checking and error handling throughout the codebase
+- Better handling of file operations with proper false checks
+
+## Breaking Changes
+
+| Component | Before (5.x) | After (6.x) | Description |
+|-----------|-------------|------------|-------------|
+| **PHP Version** | `>=8.1 <8.4` | `>=8.3 <8.6` | Minimum PHP version raised to 8.3, added support for PHP 8.4 and 8.5 |
+| **PHPUnit** | `^9.6` | `^10.5\|^11.5` | Upgraded to PHPUnit 10/11 for PHP 8.3+ compatibility |
+| **Psalm** | `^5.9` | `^6.13` | Upgraded to Psalm 6 for better PHP 8.3+ analysis |
+| **byjg/anydataset-db** | `^5.0` | `^6.0` | Updated dependency to match version |
+| **Import paths** | `use ByJG\AnyDataset\Db\DbDriverInterface` | `use ByJG\AnyDataset\Db\Interfaces\DbDriverInterface` | Interface namespace changed in anydataset-db 6.0 |
+| **Type declarations** | PHP version requirement was in `require-dev` | Now in `require` | PHP version is now a production requirement |
+
+## Upgrade Path from 5.x to 6.x
+
+### Step 1: Check PHP Version
+Ensure you're running PHP 8.3 or higher:
+```bash
+php -v
+```
+
+If you're on PHP 8.1 or 8.2, you need to upgrade PHP before proceeding.
+
+### Step 2: Update composer.json
+Update your `composer.json` to require the new version:
+```json
+{
+  "require": {
+    "byjg/migration": "^6.0"
+  }
+}
+```
+
+### Step 3: Update Dependencies
+Run composer update:
+```bash
+composer update byjg/migration
+```
+
+This will automatically update `byjg/anydataset-db` to version 6.0 as well.
+
+### Step 4: Update Import Statements (If Using Library Directly)
+If you're using the library programmatically and importing `DbDriverInterface`, update the import:
+
+**Before:**
+```php
+use ByJG\AnyDataset\Db\DbDriverInterface;
+```
+
+**After:**
+```php
+use ByJG\AnyDataset\Db\Interfaces\DbDriverInterface;
+```
+
+Note: This change is in the `byjg/anydataset-db` package, not in the migration package itself.
+
+### Step 5: Update Dev Dependencies (If Applicable)
+If you have PHPUnit or Psalm in your project, you may need to update them as well:
+```bash
+composer update --with-dependencies phpunit/phpunit vimeo/psalm
+```
+
+### Step 6: Test Your Migrations
+Run your test suite to ensure everything works:
+```bash
+vendor/bin/phpunit
+```
+
+Test your migrations in a development environment:
+```bash
+# Using the new CLI tool
+vendor/bin/migrate version -c <your-connection-string>
+vendor/bin/migrate update -c <your-connection-string> -p ./migrations
+```
+
+### Step 7: Optional - Migrate to Built-in CLI
+If you were using a custom CLI solution, you can now use the built-in CLI tool:
+
+**Old approach (custom script):**
+```php
+#!/usr/bin/env php
+<?php
+require 'vendor/autoload.php';
+
+$migration = new \ByJG\DbMigration\Migration($uri, $path);
+$migration->update();
+```
+
+**New approach (built-in CLI):**
+```bash
+vendor/bin/migrate update -c <connection-uri> -p ./migrations
+```
+
+Or use environment variables:
+```bash
+export MIGRATION_CONNECTION="mysql://user:pass@localhost/mydb"
+export MIGRATION_PATH="./migrations"
+vendor/bin/migrate update
+```
+
+### Known Issues & Compatibility Notes
+
+1. **SQL Server Connections**: If you're using SQL Server, ensure your connection string includes the database name in the query parameters (`?dbname=mydb` or `?Database=mydb`) in addition to or instead of the path component.
+
+2. **Database Interface Changes**: If you've implemented custom database adapters, you may need to update them to match the new interface signatures and add `#[\Override]` attributes for PHP 8.3+ compatibility.
+
+3. **Namespace Changes**: The primary breaking change comes from the `byjg/anydataset-db` v6.0 dependency, which moved interfaces to an `Interfaces` namespace. This is handled internally by the migration library, but may affect you if you're using these interfaces directly.
+
+## Performance & Quality Improvements
+
+- Enhanced static analysis with Psalm 6
+- Improved test infrastructure with PHPUnit 10/11
+- Better type safety with PHP 8.3+ features
+- More robust error handling
+- Enhanced CI/CD pipeline with SQL Server testing
+
+## Migration Statistics
+
+- 42 files changed
+- 2,218 insertions(+)
+- 597 deletions(-)
+- Major commits: 17
+
+## Contributors
+
+This release includes contributions and improvements from:
+- Joao Gilberto Magalhaes (@byjg)
+- Community contributors
+
+## Support
+
+For issues or questions about this release:
+- GitHub Issues: https://github.com/byjg/php-migration/issues
+- Documentation: See the `docs/` directory
+
+## License
+
+This project continues to be licensed under the MIT License.

CHANGELOG-7.0.md

@@ -0,0 +1,103 @@
+# Changelog - Version 7.0
+
+## Overview
+
+Version 7.0 upgrades the library to `byjg/anydataset-db` 7.0, which introduced a major API redesign: query execution moved from the database driver to the new `DatabaseExecutor` class. Starting with this release, the migration library version is aligned with the `byjg/anydataset-db` major version.
+
+## New Features
+
+### DatabaseExecutor Support
+- **New `getExecutor()` method**: Available on `Migration`, `DatabaseInterface`, and `AbstractDatabase`, returning a `ByJG\AnyDataset\Db\DatabaseExecutor` instance
+- **Single entry point for queries**: Use the executor to run queries against the connection managed by the migration library:
+
+```php
+$migration = new Migration($uri, $path);
+
+// Before (6.x)
+$migration->getDbDriver()->execute("insert into ...");
+$value = $migration->getDbDriver()->getScalar("select ...");
+
+// After (7.x)
+$migration->getExecutor()->execute("insert into ...");
+$value = $migration->getExecutor()->getScalar("select ...");
+```
+
+### Development Environment
+- SQL Server image pinned to `mcr.microsoft.com/mssql/server:2022-latest` with `MSSQL_SA_PASSWORD` environment variable
+- Removed obsolete `version` key from `docker-compose.yml`
+
+## Breaking Changes
+
+| Component | Before (6.x) | After (7.x) | Description |
+|-----------|-------------|------------|-------------|
+| **byjg/anydataset-db** | `^6.0` | `^7.0` | Query methods (`execute`, `getScalar`, `getIterator`) were removed from `DbDriverInterface` and moved to `DatabaseExecutor` |
+| **Query execution** | `$migration->getDbDriver()->execute($sql)` | `$migration->getExecutor()->execute($sql)` | The driver returned by `getDbDriver()` no longer executes queries; it still handles connection and transactions |
+| **DatabaseInterface** | — | `getExecutor(): DatabaseExecutor` | New required method. Custom database handlers must implement it (or extend `AbstractDatabase`, which provides it) |
+| **AbstractDatabase (protected)** | `getDbDriverWithoutDatabase(): DbDriverInterface` | `getExecutorWithoutDatabase(): DatabaseExecutor` | Renamed static helper used by `prepareEnvironment()` implementations |
+| **PgsqlDatabase (protected)** | `createDatabaseIfNotExists(DbDriverInterface $dbDriver, ...)` | `createDatabaseIfNotExists(DatabaseExecutor $executor, ...)` | Signature changed for subclasses overriding this method |
+| **PHPUnit** | `^10.5\|^11.5` | `^12.5` | Dev dependency upgrade |
+
+### Unchanged
+
+- PHP requirement remains `>=8.3 <8.6`
+- `getDbDriver()` is still available on `Migration` and `DatabaseInterface` for connection and transaction control (`beginTransaction`, `commitTransaction`, `rollbackTransaction`)
+- Migration scripts, folder structure, CLI usage, and connection strings are unaffected
+
+## Upgrade Path from 6.x to 7.x
+
+### Step 1: Update composer.json
+
+```json
+{
+  "require": {
+    "byjg/migration": "^7.0"
+  }
+}
+```
+
+```bash
+composer update byjg/migration
+```
+
+This will automatically update `byjg/anydataset-db` to version 7.0 as well.
+
+### Step 2: Replace Direct Driver Query Calls (If Applicable)
+
+If you call query methods on the driver returned by `getDbDriver()`, switch to the executor:
+
+```php
+// Before
+$migration->getDbDriver()->getIterator("select * from users");
+
+// After
+$migration->getExecutor()->getIterator("select * from users");
+```
+
+Transaction calls on the driver do not need to change.
+
+### Step 3: Update Custom Database Handlers (If Applicable)
+
+If you implemented `DatabaseInterface` directly, add the new method:
+
+```php
+public function getExecutor(): DatabaseExecutor;
+```
+
+If you extend `AbstractDatabase`, the method is inherited. Subclasses using the static helper must rename `getDbDriverWithoutDatabase()` calls to `getExecutorWithoutDatabase()` (note it now returns a `DatabaseExecutor`).
+
+### Step 4: Test Your Migrations
+
+```bash
+vendor/bin/phpunit
+vendor/bin/migrate version -c <your-connection-string>
+```
+
+## Support
+
+For issues or questions about this release:
+- GitHub Issues: https://github.com/byjg/php-migration/issues
+- Documentation: See the `docs/` directory
+
+## License
+
+This project continues to be licensed under the MIT License.

composer.json

@@ -5,11 +5,11 @@
   "prefer-stable": true,
   "require": {
     "ext-pdo": "*",
-    "byjg/anydataset-db": "^6.0",
+    "byjg/anydataset-db": "^7.0",
     "php": ">=8.3 <8.6"
   },
   "require-dev": {
-    "phpunit/phpunit": "^10.5|^11.5",
+    "phpunit/phpunit": "^12.5",
     "vimeo/psalm": "^6.13"
   },
   "autoload": {

docker-compose.yml

@@ -1,10 +1,9 @@
-version: '3.4'
 services:
   mssql:
-    image: mcr.microsoft.com/mssql/server
+    image: mcr.microsoft.com/mssql/server:2022-latest
     environment:
       - ACCEPT_EULA=Y
-      - SA_PASSWORD=Pa55word
+      - MSSQL_SA_PASSWORD=Pa55word
     ports:
       - "1433:1433"
     healthcheck:

docs/api-reference.md

@@ -81,6 +81,9 @@ public static function registerDatabase(string $class): void
 // Get database driver instance
 public function getDbDriver(): DbDriverInterface
 
+// Get database executor instance (run queries: execute, getScalar, getIterator)
+public function getExecutor(): DatabaseExecutor
+
 // Get database command instance
 public function getDbCommand(): DatabaseInterface
 ```
@@ -120,6 +123,7 @@ interface DatabaseInterface
     public function getCurrentVersion(): int;
     public function executeSql(string $sql): void;
     public function getDbDriver(): DbDriverInterface;
+    public function getExecutor(): DatabaseExecutor;
     // ... other methods
 }
 ```