From 3d91dd687bf3a077c776ef2fd7e264b3f85b0420 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 14 Nov 2026 13:54:21 -0300 Subject: [PATCH 1/4] fix: Remove only the containers and networks a run created, including those a failed creation leaves behind. --- phpstan.neon.dist | 1 + src/Internal/Commands/DockerCreate.php | 3 + src/Internal/Commands/DockerList.php | 18 +- src/Internal/Commands/DockerNetworkCreate.php | 12 +- src/Internal/Commands/DockerNetworkPrune.php | 12 +- src/Internal/Commands/DockerReaper.php | 39 +- src/Internal/Containers/ContainerLauncher.php | 11 +- src/Internal/Containers/ContainerReaper.php | 11 +- src/Internal/Containers/ContainerSharing.php | 7 +- src/Internal/Containers/HostEnvironment.php | 5 + src/Internal/Containers/OwnedContainers.php | 32 ++ src/Internal/Containers/Run.php | 37 ++ src/Internal/Containers/Started.php | 2 +- tests/Integration/DockerContainerTest.php | 37 ++ tests/Unit/ClientMock.php | 5 + tests/Unit/FlywayContainerGatedTest.php | 4 + tests/Unit/FlywayDockerContainerTest.php | 29 +- tests/Unit/GenericDockerContainerTest.php | 373 ++++++++++-------- tests/Unit/MySQLDockerContainerTest.php | 7 +- 19 files changed, 424 insertions(+), 221 deletions(-) create mode 100644 src/Internal/Containers/OwnedContainers.php create mode 100644 src/Internal/Containers/Run.php diff --git a/phpstan.neon.dist b/phpstan.neon.dist index 75e082f..a29edee 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -42,6 +42,7 @@ parameters: paths: - src/Internal/Containers/ContainerLauncher.php - src/Internal/Containers/ContainerWaits.php + - src/Internal/Containers/OwnedContainers.php - src/Internal/Containers/Address/Ports.php - src/Internal/Containers/Definitions/ContainerDefinition.php # docker inspect json_decode and sprintf feed mixed values across the system boundary. diff --git a/src/Internal/Commands/DockerCreate.php b/src/Internal/Commands/DockerCreate.php index 95aed02..236b993 100644 --- a/src/Internal/Commands/DockerCreate.php +++ b/src/Internal/Commands/DockerCreate.php @@ -6,6 +6,7 @@ use TinyBlocks\DockerContainer\DockerCommandWithTimeout; use TinyBlocks\DockerContainer\Internal\Containers\Definitions\ContainerDefinition; +use TinyBlocks\DockerContainer\Internal\Containers\Run; use TinyBlocks\Time\Duration; final readonly class DockerCreate implements DockerCommandWithTimeout @@ -41,6 +42,8 @@ public function toArguments(): array $name, '--label', self::MANAGED_LABEL, + '--label', + Run::current()->label(), ...$this->definition->toArguments(), $this->definition->image->name, ...$this->commands diff --git a/src/Internal/Commands/DockerList.php b/src/Internal/Commands/DockerList.php index 32eca97..ff4bd90 100644 --- a/src/Internal/Commands/DockerList.php +++ b/src/Internal/Commands/DockerList.php @@ -6,22 +6,32 @@ use TinyBlocks\DockerContainer\DockerCommand; use TinyBlocks\DockerContainer\Internal\Containers\Name; +use TinyBlocks\DockerContainer\Internal\Containers\Run; final readonly class DockerList implements DockerCommand { - private function __construct(private Name $name) + private function __construct(private Run $run, private Name $name) { } - public static function from(Name $name): DockerList + public static function from(Run $run, Name $name): DockerList { - return new DockerList(name: $name); + return new DockerList(run: $run, name: $name); } public function toArguments(): array { $template = 'name=^%s$'; - return ['docker', 'ps', '--all', '--quiet', '--filter', sprintf($template, $this->name->value)]; + return [ + 'docker', + 'ps', + '--all', + '--quiet', + '--filter', + sprintf($template, $this->name->value), + '--filter', + $this->run->filter() + ]; } } diff --git a/src/Internal/Commands/DockerNetworkCreate.php b/src/Internal/Commands/DockerNetworkCreate.php index 7cd0d38..51efa91 100644 --- a/src/Internal/Commands/DockerNetworkCreate.php +++ b/src/Internal/Commands/DockerNetworkCreate.php @@ -6,6 +6,7 @@ use TinyBlocks\DockerContainer\DockerCommand; use TinyBlocks\DockerContainer\Internal\Containers\Definitions\Network; +use TinyBlocks\DockerContainer\Internal\Containers\Run; final readonly class DockerNetworkCreate implements DockerCommand { @@ -20,6 +21,15 @@ public static function from(Network $network): DockerNetworkCreate public function toArguments(): array { - return ['docker', 'network', 'create', '--label', DockerCreate::MANAGED_LABEL, $this->network->name]; + return [ + 'docker', + 'network', + 'create', + '--label', + DockerCreate::MANAGED_LABEL, + '--label', + Run::current()->label(), + $this->network->name + ]; } } diff --git a/src/Internal/Commands/DockerNetworkPrune.php b/src/Internal/Commands/DockerNetworkPrune.php index dec12c1..22526fa 100644 --- a/src/Internal/Commands/DockerNetworkPrune.php +++ b/src/Internal/Commands/DockerNetworkPrune.php @@ -5,23 +5,21 @@ namespace TinyBlocks\DockerContainer\Internal\Commands; use TinyBlocks\DockerContainer\DockerCommand; +use TinyBlocks\DockerContainer\Internal\Containers\Run; final readonly class DockerNetworkPrune implements DockerCommand { - private function __construct() + private function __construct(private Run $run) { } - public static function create(): DockerNetworkPrune + public static function from(Run $run): DockerNetworkPrune { - return new DockerNetworkPrune(); + return new DockerNetworkPrune(run: $run); } public function toArguments(): array { - $template = 'label=%s'; - $filter = sprintf($template, DockerCreate::MANAGED_LABEL); - - return ['docker', 'network', 'prune', '--force', '--filter', $filter]; + return ['docker', 'network', 'prune', '--force', '--filter', $this->run->filter()]; } } diff --git a/src/Internal/Commands/DockerReaper.php b/src/Internal/Commands/DockerReaper.php index 6145da9..8f76715 100644 --- a/src/Internal/Commands/DockerReaper.php +++ b/src/Internal/Commands/DockerReaper.php @@ -5,31 +5,18 @@ namespace TinyBlocks\DockerContainer\Internal\Commands; use TinyBlocks\DockerContainer\DockerCommandWithTimeout; -use TinyBlocks\DockerContainer\Internal\Containers\Name; +use TinyBlocks\DockerContainer\Internal\Containers\Run; use TinyBlocks\Time\Duration; final readonly class DockerReaper implements DockerCommandWithTimeout { - private function __construct( - private Duration $timeout, - private Name $reaperName, - private Name $containerName, - private string $testRunnerHostname - ) { + private function __construct(private Run $run, private Duration $timeout, private string $testRunnerHostname) + { } - public static function from( - Duration $timeout, - Name $reaperName, - Name $containerName, - string $testRunnerHostname - ): DockerReaper { - return new DockerReaper( - timeout: $timeout, - reaperName: $reaperName, - containerName: $containerName, - testRunnerHostname: $testRunnerHostname - ); + public static function from(Run $run, Duration $timeout, string $testRunnerHostname): DockerReaper + { + return new DockerReaper(run: $run, timeout: $timeout, testRunnerHostname: $testRunnerHostname); } public function timeout(): Duration @@ -41,15 +28,11 @@ public function toArguments(): array { $template = implode(' ', [ 'while docker inspect %s >/dev/null 2>&1; do sleep 2; done;', - 'docker rm -fv %s 2>/dev/null;', - 'docker network prune -f --filter label=%s 2>/dev/null' + 'docker ps --all --quiet --filter %s | xargs -r docker rm --force --volumes >/dev/null 2>&1;', + 'docker network prune --force --filter %s >/dev/null 2>&1' ]); - $script = sprintf( - $template, - $this->testRunnerHostname, - $this->containerName->value, - DockerCreate::MANAGED_LABEL - ); + $script = sprintf($template, $this->testRunnerHostname, $this->run->filter(), $this->run->filter()); + $nameTemplate = 'tiny-blocks-reaper-%s'; return [ 'docker', @@ -57,7 +40,7 @@ public function toArguments(): array '--rm', '-d', '--name', - $this->reaperName->value, + sprintf($nameTemplate, $this->run->identifier), '--label', DockerCreate::MANAGED_LABEL, '-v', diff --git a/src/Internal/Containers/ContainerLauncher.php b/src/Internal/Containers/ContainerLauncher.php index 41342cf..fb73cce 100644 --- a/src/Internal/Containers/ContainerLauncher.php +++ b/src/Internal/Containers/ContainerLauncher.php @@ -40,6 +40,8 @@ public function start(array $commands, ContainerDefinition $definition): Contain public function create(array $commands, ContainerDefinition $definition): ContainerId { + new ContainerReaper(client: $this->client)->watch(definition: $definition); + $provisioner = new NetworkProvisioner(client: $this->client); $definition->networks->each( actions: static fn(Network $network) => $provisioner->provision(network: $network) @@ -47,7 +49,14 @@ public function create(array $commands, ContainerDefinition $definition): Contai $executor = new StrictExecutor(client: $this->client); $dockerCreate = DockerCreate::from(commands: $commands, definition: $definition); - $id = ContainerId::from(value: $executor->executeWithTimeout(command: $dockerCreate)->getOutput()); + + try { + $id = ContainerId::from(value: $executor->executeWithTimeout(command: $dockerCreate)->getOutput()); + } catch (DockerCommandExecutionFailed $failure) { + new OwnedContainers(client: $this->client)->remove(name: $definition->name); + + throw $failure; + } try { $definition->copyInstructions->each( diff --git a/src/Internal/Containers/ContainerReaper.php b/src/Internal/Containers/ContainerReaper.php index baff3fb..82872d7 100644 --- a/src/Internal/Containers/ContainerReaper.php +++ b/src/Internal/Containers/ContainerReaper.php @@ -5,7 +5,6 @@ namespace TinyBlocks\DockerContainer\Internal\Containers; use TinyBlocks\DockerContainer\DockerClient; -use TinyBlocks\DockerContainer\Internal\Commands\DockerList; use TinyBlocks\DockerContainer\Internal\Commands\DockerReaper; use TinyBlocks\DockerContainer\Internal\Containers\Definitions\ContainerDefinition; @@ -21,18 +20,10 @@ public function watch(ContainerDefinition $definition): void return; } - $template = 'tiny-blocks-reaper-%s'; - $reaperName = Name::from(value: sprintf($template, $definition->name->value)); - - if (trim($this->client->execute(command: DockerList::from(name: $reaperName))->getOutput()) !== '') { - return; - } - $this->client->executeWithTimeout( command: DockerReaper::from( + run: Run::current(), timeout: $definition->pullTimeout, - reaperName: $reaperName, - containerName: $definition->name, testRunnerHostname: HostEnvironment::containerHostname() ) ); diff --git a/src/Internal/Containers/ContainerSharing.php b/src/Internal/Containers/ContainerSharing.php index 0a005be..81cdfac 100644 --- a/src/Internal/Containers/ContainerSharing.php +++ b/src/Internal/Containers/ContainerSharing.php @@ -21,12 +21,9 @@ public function share(array $commands): Shared $name = $this->definition->name; $lookup = new ContainerLookup(client: $this->client); $existing = $lookup->byName(name: $name); - $shared = is_null($existing) + + return is_null($existing) ? new SharedStart(name: $name, lookup: $lookup, startup: $this->startup)->startOrJoin(commands: $commands) : Shared::reused(containerStarted: $existing); - - new ContainerReaper(client: $this->client)->watch(definition: $this->definition); - - return $shared; } } diff --git a/src/Internal/Containers/HostEnvironment.php b/src/Internal/Containers/HostEnvironment.php index 014a388..add72f8 100644 --- a/src/Internal/Containers/HostEnvironment.php +++ b/src/Internal/Containers/HostEnvironment.php @@ -10,6 +10,11 @@ private function __construct() { } + public static function processId(): int + { + return (int)getmypid(); + } + public static function isInsideDocker(): bool { return file_exists('/.dockerenv'); diff --git a/src/Internal/Containers/OwnedContainers.php b/src/Internal/Containers/OwnedContainers.php new file mode 100644 index 0000000..bb3a503 --- /dev/null +++ b/src/Internal/Containers/OwnedContainers.php @@ -0,0 +1,32 @@ +client->execute(command: DockerList::from(run: Run::current(), name: $name)); + + if (!$listing->isSuccessful()) { + return; + } + + Collection::createFrom(elements: explode(PHP_EOL, trim($listing->getOutput()))) + ->filter() + ->each(actions: fn(string $id) => $this->client->execute( + command: DockerRemove::from(id: ContainerId::from(value: $id)) + )); + } +} diff --git a/src/Internal/Containers/Run.php b/src/Internal/Containers/Run.php new file mode 100644 index 0000000..5feaf7c --- /dev/null +++ b/src/Internal/Containers/Run.php @@ -0,0 +1,37 @@ +identifier); + } + + public function filter(): string + { + $template = 'label=%s'; + + return sprintf($template, $this->label()); + } +} diff --git a/src/Internal/Containers/Started.php b/src/Internal/Containers/Started.php index a7cefc4..4e14595 100644 --- a/src/Internal/Containers/Started.php +++ b/src/Internal/Containers/Started.php @@ -54,7 +54,7 @@ public function getId(): string public function remove(): void { $this->client->execute(command: DockerRemove::from(id: $this->id)); - $this->client->execute(command: DockerNetworkPrune::create()); + $this->client->execute(command: DockerNetworkPrune::from(run: Run::current())); } public function getName(): string diff --git a/tests/Integration/DockerContainerTest.php b/tests/Integration/DockerContainerTest.php index b9e7b1e..533b258 100644 --- a/tests/Integration/DockerContainerTest.php +++ b/tests/Integration/DockerContainerTest.php @@ -5,6 +5,7 @@ namespace Test\Integration; use PHPUnit\Framework\TestCase; +use Symfony\Component\Process\Process; use TinyBlocks\DockerContainer\Exceptions\ContainerExitUnsuccessful; use TinyBlocks\DockerContainer\FlywayDockerContainer; use TinyBlocks\DockerContainer\GenericDockerContainer; @@ -17,6 +18,7 @@ final class DockerContainerTest extends TestCase { private const string ROOT = 'xpto'; private const string DATABASE = 'test_adm'; + private const string FOREIGN_NETWORK = 'foreign-run-%s'; private static MySQLDockerContainer $mySQL; @@ -41,6 +43,11 @@ public static function setUpBeforeClass(): void self::$mySQLStarted = self::$mySQL->runIfNotExists(); } + protected function tearDown(): void + { + new Process(command: ['docker', 'network', 'rm', sprintf(self::FOREIGN_NETWORK, gethostname())])->run(); + } + public function testMySQLWhenStartedThenAcceptsConnectionsToItsDatabase(): void { /** @Given the MySQL container shared by this test run */ @@ -69,6 +76,35 @@ public function testRunToCompletionWhenCommandSucceedsThenReturnsItsOutput(): vo self::assertSame('completed', trim($execution->getOutput())); } + public function testRemoveWhenAnUnusedNetworkBelongsToAnotherRunThenItIsKept(): void + { + /** @Given an unused network the library created for another run */ + new Process(command: [ + 'docker', + 'network', + 'create', + '--label', + 'tiny-blocks.docker-container=true', + '--label', + 'tiny-blocks.docker-container.run=another-run', + sprintf(self::FOREIGN_NETWORK, gethostname()) + ])->mustRun(); + + /** @And a container of this run started on a network of its own */ + $started = GenericDockerContainer::from(image: 'alpine:3.22') + ->withNetwork(name: sprintf('own-run-%s', gethostname())) + ->run(commands: ['sleep', '60']); + + /** @When the container is removed */ + $started->remove(); + + /** @Then the network of the other run should still exist */ + self::assertSame( + 0, + new Process(command: ['docker', 'network', 'inspect', sprintf(self::FOREIGN_NETWORK, gethostname())])->run() + ); + } + public function testRunIfNotExistsWhenCalledTwiceThenTheSameContainerIsReused(): void { /** @Given a container name unique to this test run */ @@ -176,4 +212,5 @@ public function testRunToCompletionWhenCommandFailsThenContainerExitUnsuccessful commands: ['sh', '-c', 'echo "migration failed" >&2; exit 3'] ); } + } diff --git a/tests/Unit/ClientMock.php b/tests/Unit/ClientMock.php index e653b80..7b7a73f 100644 --- a/tests/Unit/ClientMock.php +++ b/tests/Unit/ClientMock.php @@ -135,6 +135,11 @@ public function withDockerExecuteException(Throwable $exception): void $this->responses['docker exec'][] = $exception; } + public function withFailedDockerListResponse(string $output): void + { + $this->responses['docker ps'][] = [$output, false]; + } + public function withDockerAttachedStartResponse(string $output, bool $isSuccessful = true): void { $this->responses['docker start --attach'][] = [$output, $isSuccessful]; diff --git a/tests/Unit/FlywayContainerGatedTest.php b/tests/Unit/FlywayContainerGatedTest.php index b5e2f70..700e93e 100644 --- a/tests/Unit/FlywayContainerGatedTest.php +++ b/tests/Unit/FlywayContainerGatedTest.php @@ -15,12 +15,15 @@ final class FlywayContainerGatedTest extends TestCase protected function setUp(): void { + HostMock::outsideDocker(); + $this->client = new ClientMock(); } protected function tearDown(): void { putenv('RUN_MIGRATIONS'); + HostMock::reset(); } public function testMigrateWhenVariableIsNotSetThenNothingRuns(): void @@ -220,4 +223,5 @@ public function testMigrateWhenVariableIsEnabledAfterTheDefinitionThenRunsFlyway /** @Then the variable should be read when the command is called, so Flyway should have run */ self::assertStringEndsWith('flyway/flyway:12-alpine migrate', $this->client->getExecutedCommandLines()[0]); } + } diff --git a/tests/Unit/FlywayDockerContainerTest.php b/tests/Unit/FlywayDockerContainerTest.php index fc73e2d..0131e32 100644 --- a/tests/Unit/FlywayDockerContainerTest.php +++ b/tests/Unit/FlywayDockerContainerTest.php @@ -20,12 +20,14 @@ final class FlywayDockerContainerTest extends TestCase protected function setUp(): void { ClockMock::freeze(); + HostMock::outsideDocker(); $this->client = new ClientMock(); } protected function tearDown(): void { + HostMock::reset(); ClockMock::release(); } @@ -59,8 +61,9 @@ public function testWithNetworkThenFlywayJoinsTheNetwork(): void /** @Then the network should be created and joined */ $commandLines = implode(PHP_EOL, $this->client->getExecutedCommandLines()); self::assertStringContainsString('--network=test-network', $commandLines); + $template = 'docker network create --label tiny-blocks.docker-container=true --label %s=%s-%d test-network'; self::assertStringContainsString( - 'docker network create --label tiny-blocks.docker-container=true test-network', + sprintf($template, 'tiny-blocks.docker-container.run', gethostname(), getmypid()), $commandLines ); } @@ -609,6 +612,29 @@ public function testMigrateWhenFlywayOutlastsTimeoutThenFlywayContainerIsRemoved } } + public function testMigrateWhenInsideDockerThenReaperStartsBeforeFlywayIsCreated(): void + { + /** @Given the code runs inside Docker */ + HostMock::insideDocker(); + + /** @And a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When migrate is called */ + $flyway->migrate(); + + /** @Then the reaper of this run should start before Flyway is created, so a killed run leaves nothing behind */ + $template = 'docker run --rm -d --name tiny-blocks-reaper-%s-%d '; + self::assertStringStartsWith( + sprintf($template, gethostname(), getmypid()), + $this->client->getExecutedCommandLines()[0] + ); + self::assertStringStartsWith('docker create', $this->client->getExecutedCommandLines()[1]); + } + public function testMigrateWhenPullTimeoutIsGivenThenContainerCreationIsBoundedByIt(): void { /** @Given a Flyway container whose image may take up to ten minutes to pull */ @@ -664,4 +690,5 @@ public function testMigrateWhenFlywayFailsThenContainerExitUnsuccessfulCarriesFl /** @When migrate is called */ $flyway->migrate(); } + } diff --git a/tests/Unit/GenericDockerContainerTest.php b/tests/Unit/GenericDockerContainerTest.php index 1f58212..4855c59 100644 --- a/tests/Unit/GenericDockerContainerTest.php +++ b/tests/Unit/GenericDockerContainerTest.php @@ -25,6 +25,7 @@ final class GenericDockerContainerTest extends TestCase protected function setUp(): void { ClockMock::freeze(); + HostMock::outsideDocker(); $this->client = new ClientMock(); } @@ -149,6 +150,29 @@ public function testRunWhenNoPortIsExposedThenFirstPortsAreNull(): void self::assertEmpty($started->getAddress()->getPorts()->hostPorts()); } + public function testRunThenCreateCommandCarriesTheLabelOfThisRun(): void + { + /** @Given a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'labeled'); + + /** @And the Docker daemon creates the container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @And the inspect response carries the container details */ + $this->client->withDockerInspectResponse(inspectResult: InspectResponseFixture::build(hostname: 'labeled')); + + /** @When the container is started */ + $container->run(); + + /** @Then the container should carry the managed label and the label of this run */ + $template = '--label tiny-blocks.docker-container=true --label tiny-blocks.docker-container.run=%s-%d '; + self::assertStringContainsString( + sprintf($template, gethostname(), getmypid()), + $this->client->getExecutedCommandLines()[0] + ); + } + public function testRunWhenCommandsAreGivenThenContainerIsStarted(): void { /** @Given a container */ @@ -357,15 +381,15 @@ public function testRunWhenNetworkIsSetThenNetworkIsCreatedAndJoined(): void /** @When the container is started */ $container->run(); - /** @Then the first command should be the network creation */ - $networkCommand = $this->client->getExecutedCommandLines()[0]; - self::assertStringContainsString( - 'docker network create --label tiny-blocks.docker-container=true my-network', - $networkCommand + /** @Then the first command should be the network creation, labeled with the managed label and this run */ + $template = 'docker network create --label %s --label tiny-blocks.docker-container.run=%s-%d my-network'; + self::assertSame( + sprintf($template, 'tiny-blocks.docker-container=true', gethostname(), getmypid()), + $this->client->getExecutedCommandLines()[0] ); /** @And the docker run command should contain the network argument */ - $runCommand = $this->client->getExecutedCommandLines()[2]; + $runCommand = $this->client->getExecutedCommandLines()[1]; self::assertStringContainsString('--network=my-network', $runCommand); } @@ -475,8 +499,8 @@ public function testRunWhenInsideDockerThenHostIsConnectedToTheNetwork(): void /** @When the container is started */ $container->run(); - /** @Then a docker network connect command should connect the host to the network */ - $connectCommand = $client->getExecutedCommandLines()[1]; + /** @Then a docker network connect command should connect the host to the network, after the reaper starts */ + $connectCommand = $client->getExecutedCommandLines()[2]; self::assertStringStartsWith('docker network connect my-network', $connectCommand); } @@ -1107,6 +1131,30 @@ public function testRunIfNotExistsWhenContainerIsMissingThenANewOneIsStarted(): self::assertSame('test', $started->getEnvironmentVariables()->getValueBy(key: 'APP_ENV')); } + public function testRunIfNotExistsWhenContainerIsReusedThenNoReaperIsStarted(): void + { + /** @Given the code runs inside Docker */ + HostMock::insideDocker(); + + /** @And a container that another run already started */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'reused-elsewhere'); + + /** @And the lookup returns the container details */ + $this->client->withDockerLookupResponse( + inspectResult: InspectResponseFixture::build(hostname: 'reused-elsewhere') + ); + + /** @When the container is asked for */ + $container->runIfNotExists(); + + /** @Then only the lookup should run, since this run created nothing to reap */ + self::assertSame( + ['docker inspect --type container reused-elsewhere'], + $this->client->getExecutedCommandLines() + ); + } + public function testRunWhenAutoRemoveIsNotDisabledThenCreateCommandCarriesRm(): void { /** @Given a container with default configuration */ @@ -1398,35 +1446,6 @@ public function testRunIfNotExistsWhenContainerExistsThenItsDetailsAreReturned() self::assertSame('true', $started->getEnvironmentVariables()->getValueBy(key: 'EXISTING')); } - public function testRunIfNotExistsWhenReaperIsMissingThenStartsReaperContainer(): void - { - /** @Given the code runs inside Docker */ - HostMock::insideDocker(); - - /** @And a Docker client */ - $client = new ClientMock(); - - /** @And a container that already exists */ - $container = GenericDockerContainer::from(image: 'alpine:latest', client: $client) - ->withName(name: 'reaper-start'); - - /** @And the Docker inspect returns the container details */ - $client->withDockerLookupResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaper-start')); - - /** @And no reaper container is currently listed */ - $client->withDockerListResponse(output: ''); - - /** @When runIfNotExists is called */ - $container->runIfNotExists(); - - /** @Then a reaper container should have been started with the docker run command */ - $commandLines = implode(PHP_EOL, $client->getExecutedCommandLines()); - self::assertStringContainsString('docker run --rm -d --name tiny-blocks-reaper-reaper-start', $commandLines); - - /** @And the reaper script should watch the test-runner hostname before pruning */ - self::assertStringContainsString('while docker inspect', $commandLines); - } - public function testRunIfNotExistsThenLookupCommandTargetsTheExactContainerName(): void { /** @Given a container that already exists */ @@ -1554,6 +1573,29 @@ public function testRunWhenEnvironmentVariableIsAddedThenCreateCommandCarriesIt( self::assertStringContainsString('--env APP_ENV=production', $runCommand); } + public function testRunWhenInsideDockerThenReaperStartIsBoundedByThePullTimeout(): void + { + /** @Given the code runs inside Docker */ + HostMock::insideDocker(); + + /** @And a container with a pull timeout of ten minutes */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'reaper-pull') + ->withPullTimeout(timeout: Duration::fromSeconds(seconds: 600)); + + /** @And the Docker daemon creates the container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @And the inspect response carries the container details */ + $this->client->withDockerInspectResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaper-pull')); + + /** @When the container is started */ + $container->run(); + + /** @Then starting the reaper and creating the container should both be bounded by the pull timeout */ + self::assertSame([600, 600], $this->client->getRequestedTimeouts()); + } + public function testRunWhenNetworkDetailsAreEmptyThenAddressFallsBackToDefaults(): void { /** @Given a container with empty network info */ @@ -1631,46 +1673,6 @@ public function testRunWhenSeveralEnvironmentVariablesAreAddedThenAllAreExposed( self::assertSame('mydb', $started->getEnvironmentVariables()->getValueBy(key: 'DB_NAME')); } - public function testRunIfNotExistsWhenReaperAlreadyExistsThenSkipsReaperCreation(): void - { - /** @Given the code runs inside Docker */ - HostMock::insideDocker(); - - /** @And a Docker client */ - $client = new ClientMock(); - - /** @And a container that already exists */ - $container = GenericDockerContainer::from(image: 'alpine:latest', client: $client) - ->withName(name: 'reaper-skip'); - - /** @And the Docker inspect returns the container details */ - $client->withDockerLookupResponse( - inspectResult: InspectResponseFixture::build(hostname: 'reaper-skip') - ); - - /** @And the reaper container already exists */ - $client->withDockerListResponse(output: 'existing-reaper-id'); - - /** @When runIfNotExists is called */ - $started = $container->runIfNotExists(); - - /** @Then the container should be returned */ - self::assertSame('reaper-skip', $started->getName()); - - /** @And the reused container should have probed for the reaper list to exist */ - $commandLines = $client->getExecutedCommandLines(); - $reaperListed = false; - - foreach ($commandLines as $commandLine) { - $reaperListed = $reaperListed || str_contains($commandLine, 'tiny-blocks-reaper-reaper-skip'); - self::assertStringNotContainsString( - 'docker run --rm -d --name tiny-blocks-reaper', - $commandLine - ); - } - self::assertTrue($reaperListed); - } - public function testRunWhenWaitAfterStartedFailsThenTheStartedContainerIsRemoved(): void { /** @Given a wait strategy that fails once the container has started */ @@ -1842,6 +1844,35 @@ public function testRunWhenFilesAreCopiedThenTheyAreCopiedBeforeTheContainerStar ); } + public function testRunWhenInsideDockerThenReaperStartsBeforeTheContainerIsCreated(): void + { + /** @Given the code runs inside Docker */ + HostMock::insideDocker(); + + /** @And a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'reaped'); + + /** @And the Docker daemon creates the container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @And the inspect response carries the container details */ + $this->client->withDockerInspectResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaped')); + + /** @When the container is started */ + $container->run(); + + /** @Then the reaper of this run should start first, named after the run */ + $template = 'docker run --rm -d --name tiny-blocks-reaper-%s-%d --label tiny-blocks.docker-container=true'; + self::assertStringStartsWith( + sprintf($template, gethostname(), getmypid()), + $this->client->getExecutedCommandLines()[0] + ); + + /** @And the container should be created right after it */ + self::assertStringStartsWith('docker create', $this->client->getExecutedCommandLines()[1]); + } + public function testRunWhenTwoWaitsAfterStartedAreAddedThenBothReceiveTheContainer(): void { /** @Given a first wait strategy applied after the container starts */ @@ -1905,6 +1936,35 @@ public function testGetHostForConnectionWhenOutsideDockerThenReturnsLoopbackAddr self::assertSame('127.0.0.1', $host); } + public function testRunWhenCreateFailsThenContainersOfThisRunWithThatNameAreRemoved(): void + { + /** @Given a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'half-created'); + + /** @And the Docker daemon gives up on the creation after registering the container */ + $this->client->withDockerCreateResponse(output: 'context deadline exceeded', isSuccessful: false); + + /** @And two containers of this run carry that name */ + $this->client->withDockerListResponse(output: "aaaaaaaaaaaa\nbbbbbbbbbbbb\n"); + + try { + /** @When the container is started */ + $container->run(); + } catch (DockerCommandExecutionFailed) { + /** @Then the containers of this run with that name should be listed and removed */ + $template = 'docker ps --all --quiet --filter name=^half-created$ --filter label=%s=%s-%d'; + self::assertSame( + [ + sprintf($template, 'tiny-blocks.docker-container.run', gethostname(), getmypid()), + 'docker rm --force --volumes aaaaaaaaaaaa', + 'docker rm --force --volumes bbbbbbbbbbbb' + ], + array_slice($this->client->getExecutedCommandLines(), 1) + ); + } + } + public function testRunWhenNetworkVanishesBeforeStartThenTheContainerIsStartedAgain(): void { /** @Given a container that joins a network */ @@ -2007,31 +2067,6 @@ public function testRunIfNotExistsWhenExistingContainerIsStoppedThenItIsReusedAs self::assertSame(0.0, ClockMock::elapsedInSeconds()); } - public function testRunIfNotExistsWhenInsideDockerThenReaperIsLookedUpByItsExactName(): void - { - /** @Given the code runs inside Docker */ - HostMock::insideDocker(); - - /** @And a Docker client */ - $client = new ClientMock(); - - /** @And a container that already exists */ - $container = GenericDockerContainer::from(image: 'alpine:latest', client: $client) - ->withName(name: 'reaper-list'); - - /** @And the lookup returns the container details */ - $client->withDockerLookupResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaper-list')); - - /** @When the container is asked for */ - $container->runIfNotExists(); - - /** @Then the reaper should be listed by its exact name */ - self::assertContains( - 'docker ps --all --quiet --filter name=^tiny-blocks-reaper-reaper-list$', - $client->getExecutedCommandLines() - ); - } - public function testRunContainerWhenContainerIdIsExactlyMinimumLengthThenIdIsAccepted(): void { /** @Given a container */ @@ -2051,34 +2086,6 @@ public function testRunContainerWhenContainerIdIsExactlyMinimumLengthThenIdIsAcc self::assertSame('123456789012', $started->getId()); } - public function testRunIfNotExistsWhenReaperListIsWhitespaceThenStartsReaperContainer(): void - { - /** @Given the code runs inside Docker */ - HostMock::insideDocker(); - - /** @And a Docker client */ - $client = new ClientMock(); - - /** @And a container that already exists */ - $container = GenericDockerContainer::from(image: 'alpine:latest', client: $client) - ->withName(name: 'reaper-blank'); - - /** @And the Docker inspect returns the container details */ - $client->withDockerLookupResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaper-blank')); - - /** @And the reaper list response contains only whitespace */ - $client->withDockerListResponse(output: " \n\t "); - - /** @When runIfNotExists is called */ - $container->runIfNotExists(); - - /** @Then a reaper container should have been started because the whitespace list is treated as empty */ - self::assertStringContainsString( - 'docker run --rm -d --name tiny-blocks-reaper-reaper-blank', - implode(PHP_EOL, $client->getExecutedCommandLines()) - ); - } - public function testRunWhenNetworkVanishesBeforeStartThenTheNetworkIsProvisionedAgain(): void { /** @Given a container that joins a network */ @@ -2351,13 +2358,9 @@ public function testRemoveWhenContainerIsRunningThenContainerIsRemovedAndNetwork $removeCommand ); - /** @And a docker network prune command should have been executed with the managed label */ - $pruneCommand = $commandLines[4]; - - self::assertStringContainsString( - 'docker network prune --force --filter label=tiny-blocks.docker-container=true', - $pruneCommand - ); + /** @And only the unused networks this run created should have been pruned */ + $template = 'docker network prune --force --filter label=tiny-blocks.docker-container.run=%s-%d'; + self::assertSame(sprintf($template, gethostname(), getmypid()), $commandLines[4]); } public function testRunIfNotExistsWhenAnotherProcessCreatesTheContainerFirstThenItIsReused(): void @@ -2545,6 +2548,59 @@ public function testRunIfNotExistsWhenInspectionCarriesNoStateThenTheContainerIs self::assertSame(0.0, ClockMock::elapsedInSeconds()); } + public function testRunWhenCreateFailsAndContainersCannotBeListedThenCreationFailureIsRaised(): void + { + /** @Given a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'unlisted'); + + /** @And the Docker daemon fails to create it */ + $this->client->withDockerCreateResponse(output: 'no space left on device', isSuccessful: false); + + /** @And the containers of this run cannot be listed */ + $this->client->withFailedDockerListResponse(output: 'denied'); + + /** @Then the failure reported by Docker for the creation should be thrown */ + $this->expectException(DockerCommandExecutionFailed::class); + $this->expectExceptionMessageMatches('/Reason: no space left on device/'); + + /** @When the container is started */ + $container->run(); + } + + public function testRunWhenReaperStartsThenItRemovesOnlyWhatThisRunCreatedOnceTheRunnerExits(): void + { + /** @Given the code runs inside Docker */ + HostMock::insideDocker(); + + /** @And a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'reaper-script'); + + /** @And the Docker daemon creates the container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @And the inspect response carries the container details */ + $this->client->withDockerInspectResponse( + inspectResult: InspectResponseFixture::build(hostname: 'reaper-script') + ); + + /** @When the container is started */ + $container->run(); + + /** @Then the reaper should wait for the runner, then remove the containers and networks of this run only */ + $template = implode(' ', [ + 'while docker inspect %1$s >/dev/null 2>&1; do sleep 2; done;', + 'docker ps --all --quiet --filter label=tiny-blocks.docker-container.run=%1$s-%2$d', + '| xargs -r docker rm --force --volumes >/dev/null 2>&1;', + 'docker network prune --force --filter label=tiny-blocks.docker-container.run=%1$s-%2$d >/dev/null 2>&1' + ]); + self::assertSame( + sprintf($template, gethostname(), getmypid()), + array_last($this->client->getExecutedArguments()[0]) + ); + } + public function testRunIfNotExistsWhenExistingContainerIsNeverStartedThenContainerWaitTimeout(): void { /** @Given a container another process created and never started */ @@ -2605,29 +2661,6 @@ public function testRunToCompletionWhenNetworkVanishesBeforeStartThenBothContain ); } - public function testRunIfNotExistsWhenReaperIsStartedThenItsImagePullIsBoundedByThePullTimeout(): void - { - /** @Given the code runs inside Docker */ - HostMock::insideDocker(); - - /** @And a Docker client */ - $client = new ClientMock(); - - /** @And a container that already exists, with a pull timeout of ten minutes */ - $container = GenericDockerContainer::from(image: 'alpine:latest', client: $client) - ->withName(name: 'reaper-pull') - ->withPullTimeout(timeout: Duration::fromSeconds(seconds: 600)); - - /** @And the lookup returns the container details */ - $client->withDockerLookupResponse(inspectResult: InspectResponseFixture::build(hostname: 'reaper-pull')); - - /** @When the container is asked for */ - $container->runIfNotExists(); - - /** @Then starting the reaper should be bounded by the pull timeout */ - self::assertSame([600], $client->getRequestedTimeouts()); - } - public function testRunToCompletionWhenNeverStartedOnBothAttemptsThenContainerExitUnsuccessful(): void { /** @Given a one-shot container that joins a network */ @@ -2762,6 +2795,26 @@ public function testRunToCompletionWhenWaitBeforeRunIsRegisteredThenWaitsBeforeC self::assertStringStartsWith('docker create', $this->client->getExecutedCommandLines()[0]); } + public function testRunWhenCreateFailsAndNoContainerOfThisRunHasThatNameThenCreationFailureIsRaised(): void + { + /** @Given a container */ + $container = GenericDockerContainer::from(image: 'alpine:latest', client: $this->client) + ->withName(name: 'never-created'); + + /** @And the Docker daemon fails to create it */ + $this->client->withDockerCreateResponse(output: 'no space left on device', isSuccessful: false); + + /** @And no container of this run carries that name */ + $this->client->withDockerListResponse(output: " \n"); + + /** @Then the failure reported by Docker should be thrown */ + $this->expectException(DockerCommandExecutionFailed::class); + $this->expectExceptionMessageMatches('/Reason: no space left on device/'); + + /** @When the container is started */ + $container->run(); + } + public function testRunIfNotExistsWhenCreationFailsAndNoContainerExistsThenDockerCommandExecutionFailed(): void { /** @Given a container that does not exist */ diff --git a/tests/Unit/MySQLDockerContainerTest.php b/tests/Unit/MySQLDockerContainerTest.php index f8ccbf9..8b276df 100644 --- a/tests/Unit/MySQLDockerContainerTest.php +++ b/tests/Unit/MySQLDockerContainerTest.php @@ -21,6 +21,7 @@ final class MySQLDockerContainerTest extends TestCase protected function setUp(): void { ClockMock::freeze(); + HostMock::outsideDocker(); $this->client = new ClientMock(); } @@ -492,7 +493,7 @@ public function testRunWhenMySQLBecomesReadyThenReturnsMySQLContainerStarted(): /** @And the docker run command should reflect delegated configuration */ $commandLines = $this->client->getExecutedCommandLines(); - $runCommand = $commandLines[2]; + $runCommand = $commandLines[1]; self::assertStringNotContainsString('--rm', $runCommand); self::assertStringContainsString('--volume /var/lib/mysql:/var/lib/mysql', $runCommand); @@ -504,7 +505,7 @@ public function testRunWhenMySQLBecomesReadyThenReturnsMySQLContainerStarted(): self::assertStringContainsString('MYSQL_ROOT_PASSWORD=root', $runCommand); /** @And the readiness probe should execute env-prefixed mysqladmin ping via docker exec */ - $readinessCommand = $commandLines[5]; + $readinessCommand = $commandLines[4]; self::assertStringContainsString( 'docker exec test-db env MYSQL_PWD=root mysqladmin ping -h 127.0.0.1', @@ -512,7 +513,7 @@ public function testRunWhenMySQLBecomesReadyThenReturnsMySQLContainerStarted(): ); /** @And the database setup should include CREATE DATABASE, GRANT, and FLUSH */ - $setupCommand = $commandLines[6]; + $setupCommand = $commandLines[5]; self::assertStringContainsString('CREATE DATABASE IF NOT EXISTS `test_adm`', $setupCommand); self::assertStringContainsString('GRANT ALL PRIVILEGES', $setupCommand); From f7668e93397234b768d193aad98635c574bd10ce Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 14 Nov 2026 13:54:30 -0300 Subject: [PATCH 2/4] feat: Add cleanAndMigrateSchemas to clean and migrate several schemas in one Flyway container. --- phpstan.neon.dist | 1 + src/Exceptions/SchemaListEmpty.php | 18 ++ src/FlywayContainerGated.php | 21 +++ src/FlywayDockerContainer.php | 83 +++++++-- .../Definitions/ContainerDefinition.php | 12 +- .../Containers/Definitions/Entrypoint.php | 22 +++ .../Drivers/Flyway/FlywaySchemas.php | 44 +++++ .../Drivers/Flyway/FlywaySettings.php | 8 +- tests/Integration/DockerContainerTest.php | 39 ++++ tests/Unit/FlywayContainerGatedTest.php | 37 ++++ tests/Unit/FlywayDockerContainerTest.php | 167 ++++++++++++++++++ 11 files changed, 429 insertions(+), 23 deletions(-) create mode 100644 src/Exceptions/SchemaListEmpty.php create mode 100644 src/Internal/Containers/Definitions/Entrypoint.php create mode 100644 src/Internal/Containers/Drivers/Flyway/FlywaySchemas.php diff --git a/phpstan.neon.dist b/phpstan.neon.dist index a29edee..b91f354 100644 --- a/phpstan.neon.dist +++ b/phpstan.neon.dist @@ -26,6 +26,7 @@ parameters: - src/Internal/Containers/Definitions/ContainerDefinition.php - src/Internal/Containers/Definitions/CopyInstruction.php - src/Internal/Containers/Drivers/MySQL/JdbcUrl.php + - src/Internal/Containers/Drivers/Flyway/FlywaySchemas.php - src/Internal/Containers/Drivers/Flyway/FlywaySettings.php - src/Internal/Containers/Drivers/Flyway/FlywaySource.php - src/Internal/Containers/Drivers/MySQL/MySQLCommands.php diff --git a/src/Exceptions/SchemaListEmpty.php b/src/Exceptions/SchemaListEmpty.php new file mode 100644 index 0000000..cf1cc06 --- /dev/null +++ b/src/Exceptions/SchemaListEmpty.php @@ -0,0 +1,18 @@ +flag->isEnabled() ? $this->flyway->cleanAndMigrate() : null; } + + /** + * Runs the Flyway clean command followed by migrate once for each schema, in a single Flyway container, when the + * variable is enabled, and blocks until Flyway exits. + * + *

See {@see FlywayDockerContainer::cleanAndMigrateSchemas()} for how the schemas are migrated and how long the + * run may take.

+ * + * @param array $schemas The schemas to clean and migrate, in order. + * @return ExecutionCompleted|null The successful outcome, or null when the variable is not enabled and nothing + * ran. + * @throws SchemaListEmpty If the variable is enabled and no schema is given. + * @throws DockerCommandExecutionFailed If a Docker command fails. + * @throws ContainerWaitTimeout If the MySQL source is not ready or Flyway does not exit within the timeout. + * @throws ContainerExitUnsuccessful If Flyway exits with a non-zero status, carrying the Flyway error output. + */ + public function cleanAndMigrateSchemas(array $schemas): ?ExecutionCompleted + { + return $this->flag->isEnabled() ? $this->flyway->cleanAndMigrateSchemas(schemas: $schemas) : null; + } } diff --git a/src/FlywayDockerContainer.php b/src/FlywayDockerContainer.php index 2e519bb..678a132 100644 --- a/src/FlywayDockerContainer.php +++ b/src/FlywayDockerContainer.php @@ -8,8 +8,12 @@ use TinyBlocks\DockerContainer\Exceptions\ContainerWaitTimeout; use TinyBlocks\DockerContainer\Exceptions\DockerCommandExecutionFailed; use TinyBlocks\DockerContainer\Exceptions\ImageNameEmpty; +use TinyBlocks\DockerContainer\Exceptions\SchemaListEmpty; use TinyBlocks\DockerContainer\Internal\Client\CommandLineDockerClient; +use TinyBlocks\DockerContainer\Internal\Containers\Definitions\ContainerDefinition; +use TinyBlocks\DockerContainer\Internal\Containers\Drivers\Flyway\FlywaySchemas; use TinyBlocks\DockerContainer\Internal\Containers\Drivers\Flyway\FlywaySettings; +use TinyBlocks\DockerContainer\Internal\Containers\OneShotContainer; use TinyBlocks\Time\Duration; /** @@ -25,9 +29,10 @@ private const int DEFAULT_TIMEOUT_IN_SECONDS = 120; private function __construct( + private DockerClient $client, private Duration $timeout, private FlywaySettings $settings, - private GenericDockerContainer $container + private ContainerDefinition $definition ) { } @@ -45,9 +50,10 @@ public static function from( DockerClient $client = new CommandLineDockerClient() ): FlywayDockerContainer { return new FlywayDockerContainer( + client: $client, timeout: Duration::fromSeconds(seconds: self::DEFAULT_TIMEOUT_IN_SECONDS), settings: FlywaySettings::create(), - container: GenericDockerContainer::from(image: $image, client: $client) + definition: ContainerDefinition::create(image: $image) ); } @@ -61,9 +67,11 @@ public static function from( */ public function repair(): ExecutionCompleted { - return $this->settings - ->applyTo(container: $this->container) - ->runToCompletion(timeout: $this->timeout, commands: ['repair']); + return new OneShotContainer(client: $this->client)->run( + timeout: $this->timeout, + commands: ['repair'], + definition: $this->settings->applyTo(definition: $this->definition) + ); } /** @@ -76,9 +84,11 @@ public function repair(): ExecutionCompleted */ public function migrate(): ExecutionCompleted { - return $this->settings - ->applyTo(container: $this->container) - ->runToCompletion(timeout: $this->timeout, commands: ['migrate']); + return new OneShotContainer(client: $this->client)->run( + timeout: $this->timeout, + commands: ['migrate'], + definition: $this->settings->applyTo(definition: $this->definition) + ); } /** @@ -91,9 +101,11 @@ public function migrate(): ExecutionCompleted */ public function validate(): ExecutionCompleted { - return $this->settings - ->applyTo(container: $this->container) - ->runToCompletion(timeout: $this->timeout, commands: ['validate']); + return new OneShotContainer(client: $this->client)->run( + timeout: $this->timeout, + commands: ['validate'], + definition: $this->settings->applyTo(definition: $this->definition) + ); } /** @@ -144,7 +156,7 @@ public function withSource(MySQLDockerContainer $container): FlywayDockerContain */ public function withNetwork(string $name): FlywayDockerContainer { - return clone($this, ['container' => $this->container->withNetwork(name: $name)]); + return clone($this, ['definition' => $this->definition->withNetwork(name: $name)]); } /** @@ -177,7 +189,7 @@ public function withMigrations(string $pathOnHost): FlywayDockerContainer key: 'FLYWAY_LOCATIONS', value: sprintf($template, self::MIGRATIONS_ON_CONTAINER) ), - 'container' => $this->container->copyToContainer( + 'definition' => $this->definition->withCopyInstruction( pathOnHost: $pathOnHost, pathOnContainer: self::MIGRATIONS_ON_CONTAINER ) @@ -197,10 +209,13 @@ public function withMigrations(string $pathOnHost): FlywayDockerContainer */ public function cleanAndMigrate(): ExecutionCompleted { - return $this->settings - ->applyTo(container: $this->container) - ->withEnvironmentVariable(key: 'FLYWAY_CLEAN_DISABLED', value: 'false') - ->runToCompletion(timeout: $this->timeout, commands: ['clean', 'migrate']); + return new OneShotContainer(client: $this->client)->run( + timeout: $this->timeout, + commands: ['clean', 'migrate'], + definition: $this->settings + ->applyTo(definition: $this->definition) + ->withEnvironmentVariable(key: 'FLYWAY_CLEAN_DISABLED', value: 'false') + ); } /** @@ -245,7 +260,7 @@ public function withCredentials(string $password, string $username): FlywayDocke */ public function withPullTimeout(Duration $timeout): FlywayDockerContainer { - return clone($this, ['container' => $this->container->withPullTimeout(timeout: $timeout)]); + return clone($this, ['definition' => $this->definition->withPullTimeout(timeout: $timeout)]); } /** @@ -259,6 +274,38 @@ public function withConnectRetries(int $retries): FlywayDockerContainer return $this->withEnvironmentVariable(key: 'FLYWAY_CONNECT_RETRIES', value: (string)$retries); } + /** + * Runs the Flyway clean command followed by migrate once for each schema, in a single Flyway container, and blocks + * until Flyway exits. + * + *

Each schema ends exactly as withSchema($schema)->cleanAndMigrate() leaves it: cleaned, migrated, + * and with its own history table. The schemas are migrated in order, the migrations are copied and the MySQL + * source is checked once for all of them, and the first schema Flyway fails on stops the run. The timeout of + * each schema is the one set by withTimeout(), so the run waits up to that timeout times the number of + * schemas.

+ * + * @param array $schemas The schemas to clean and migrate, in order. + * @return ExecutionCompleted The successful outcome, carrying the Flyway output of every schema. + * @throws SchemaListEmpty If no schema is given. + * @throws DockerCommandExecutionFailed If a Docker command fails. + * @throws ContainerWaitTimeout If the MySQL source is not ready or Flyway does not exit within the timeout. + * @throws ContainerExitUnsuccessful If Flyway exits with a non-zero status, carrying the Flyway error output. + */ + public function cleanAndMigrateSchemas(array $schemas): ExecutionCompleted + { + $flywaySchemas = FlywaySchemas::from(schemas: $schemas); + + return new OneShotContainer(client: $this->client)->run( + timeout: $flywaySchemas->timeoutFor(timeout: $this->timeout), + commands: $flywaySchemas->toCommands(), + definition: $flywaySchemas->applyTo( + definition: $this->settings + ->applyTo(definition: $this->definition) + ->withEnvironmentVariable(key: 'FLYWAY_CLEAN_DISABLED', value: 'false') + ) + ); + } + /** * Returns a copy of the FlywayDockerContainer with an environment variable added. * diff --git a/src/Internal/Containers/Definitions/ContainerDefinition.php b/src/Internal/Containers/Definitions/ContainerDefinition.php index 79a3f87..947a5f8 100644 --- a/src/Internal/Containers/Definitions/ContainerDefinition.php +++ b/src/Internal/Containers/Definitions/ContainerDefinition.php @@ -20,6 +20,7 @@ private function __construct( public Name $name, public Image $image, public Collection $networks, + public Collection $entrypoint, public Duration $pullTimeout, public Collection $tmpfsMounts, public Collection $portMappings, @@ -36,6 +37,7 @@ public static function create(string $image): ContainerDefinition name: Name::generated(), image: Image::from(image: $image), networks: Collection::createFromEmpty(), + entrypoint: Collection::createFromEmpty(), pullTimeout: Duration::fromSeconds(seconds: self::DEFAULT_PULL_TIMEOUT_IN_SECONDS), tmpfsMounts: Collection::createFromEmpty(), portMappings: Collection::createFromEmpty(), @@ -52,7 +54,8 @@ public function withName(string $name): ContainerDefinition public function toArguments(): array { - return $this->portMappings + return $this->entrypoint + ->merge(other: $this->portMappings) ->merge(other: $this->networks) ->merge(other: $this->volumeMappings) ->merge(other: $this->tmpfsMounts) @@ -73,6 +76,13 @@ public function startAttempts(): int return $this->networks->isEmpty() ? self::SINGLE_START_ATTEMPT : self::START_ATTEMPTS_ON_A_NETWORK; } + public function withEntrypoint(string $executable): ContainerDefinition + { + return clone($this, [ + 'entrypoint' => Collection::createFrom(elements: [Entrypoint::from(executable: $executable)]) + ]); + } + public function withTmpfsMount(string $pathOnContainer): ContainerDefinition { return clone($this, [ diff --git a/src/Internal/Containers/Definitions/Entrypoint.php b/src/Internal/Containers/Definitions/Entrypoint.php new file mode 100644 index 0000000..bfa7f4f --- /dev/null +++ b/src/Internal/Containers/Definitions/Entrypoint.php @@ -0,0 +1,22 @@ +executable]; + } +} diff --git a/src/Internal/Containers/Drivers/Flyway/FlywaySchemas.php b/src/Internal/Containers/Drivers/Flyway/FlywaySchemas.php new file mode 100644 index 0000000..a05b944 --- /dev/null +++ b/src/Internal/Containers/Drivers/Flyway/FlywaySchemas.php @@ -0,0 +1,44 @@ +withEntrypoint(executable: self::SHELL); + } + + public function timeoutFor(Duration $timeout): Duration + { + return Duration::fromSeconds(seconds: ($timeout->toSeconds() * count($this->schemas))); + } + + public function toCommands(): array + { + return ['-c', self::CLEAN_AND_MIGRATE_EACH, self::SHELL, ...$this->schemas]; + } +} diff --git a/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php b/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php index 523c0c1..64d461e 100644 --- a/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php +++ b/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php @@ -4,7 +4,7 @@ namespace TinyBlocks\DockerContainer\Internal\Containers\Drivers\Flyway; -use TinyBlocks\DockerContainer\GenericDockerContainer; +use TinyBlocks\DockerContainer\Internal\Containers\Definitions\ContainerDefinition; use TinyBlocks\DockerContainer\MySQLDockerContainer; final readonly class FlywaySettings @@ -23,15 +23,15 @@ public function with(string $key, string $value): FlywaySettings return clone($this, ['settings' => [...$this->settings, $key => $value]]); } - public function applyTo(GenericDockerContainer $container): GenericDockerContainer + public function applyTo(ContainerDefinition $definition): ContainerDefinition { $settings = [...$this->source->toSettings(), ...$this->settings]; return array_reduce( array_keys($settings), - static fn(GenericDockerContainer $container, string $key): GenericDockerContainer => $container + static fn(ContainerDefinition $definition, string $key): ContainerDefinition => $definition ->withEnvironmentVariable(key: $key, value: $settings[$key]), - $container + $definition ); } diff --git a/tests/Integration/DockerContainerTest.php b/tests/Integration/DockerContainerTest.php index 533b258..cebf726 100644 --- a/tests/Integration/DockerContainerTest.php +++ b/tests/Integration/DockerContainerTest.php @@ -213,4 +213,43 @@ public function testRunToCompletionWhenCommandFailsThenContainerExitUnsuccessful ); } + public function testCleanAndMigrateSchemasWhenSchemasAreGivenThenEachEndsAsCleanAndMigrateLeavesIt(): void + { + /** @Given a migration directory */ + $template = '%s/Database/Migrations'; + + /** @And a Flyway container bound to the MySQL container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine') + ->withSource(container: self::$mySQL) + ->withNetwork(name: 'tiny-blocks') + ->withMigrations(pathOnHost: sprintf($template, __DIR__)); + + /** @And a reference schema cleaned and migrated on its own */ + $flyway->withSchema(schema: 'reference_schema')->cleanAndMigrate(); + + /** @When two schemas are cleaned and migrated in a single Flyway run */ + $flyway->cleanAndMigrateSchemas(schemas: ['first_schema', 'second_schema']); + + /** @Then each schema should hold the rows and the migration history of the reference schema */ + $template = implode(' ', [ + 'SELECT version, description, type, checksum, success FROM `%1$s`.schema_history ORDER BY installed_rank;', + 'SELECT id FROM `%1$s`.xpto ORDER BY id' + ]); + $contents = array_map( + static fn(string $schema): string => self::$mySQLStarted->executeAfterStarted(commands: [ + 'env', + 'MYSQL_PWD=xpto', + 'mysql', + '-N', + '-B', + '-uroot', + '-h127.0.0.1', + '-e', + sprintf($template, $schema) + ])->getOutput(), + ['reference_schema', 'first_schema', 'second_schema'] + ); + self::assertStringContainsString("0001\tInsert xpto table\tSQL", $contents[0]); + self::assertSame([$contents[0], $contents[0]], [$contents[1], $contents[2]]); + } } diff --git a/tests/Unit/FlywayContainerGatedTest.php b/tests/Unit/FlywayContainerGatedTest.php index 700e93e..a5be74a 100644 --- a/tests/Unit/FlywayContainerGatedTest.php +++ b/tests/Unit/FlywayContainerGatedTest.php @@ -159,6 +159,22 @@ public function testMigrateWhenVariableIsOneWithLeadingZeroThenNothingRuns(): vo self::assertSame([null, []], [$execution, $this->client->getExecutedArguments()]); } + public function testCleanAndMigrateSchemasWhenVariableIsNotSetThenNothingRuns(): void + { + /** @Given the variable that enables the migrations is not set */ + putenv('RUN_MIGRATIONS'); + + /** @And a Flyway container that runs only while the variable is enabled */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client) + ->onlyWhenEnabled(variable: 'RUN_MIGRATIONS'); + + /** @When cleanAndMigrateSchemas is called */ + $execution = $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1']); + + /** @Then nothing should have run, and no Docker command should have been issued */ + self::assertSame([null, []], [$execution, $this->client->getExecutedArguments()]); + } + public function testCleanAndMigrateWhenVariableIsDisabledThenNeitherMySQLNorFlywayRuns(): void { /** @Given the variable that enables the migrations is set to 0 */ @@ -224,4 +240,25 @@ public function testMigrateWhenVariableIsEnabledAfterTheDefinitionThenRunsFlyway self::assertStringEndsWith('flyway/flyway:12-alpine migrate', $this->client->getExecutedCommandLines()[0]); } + public function testCleanAndMigrateSchemasWhenVariableIsEnabledThenRunsEverySchemaInOneFlywayContainer(): void + { + /** @Given the variable that enables the migrations is set to 1 */ + putenv('RUN_MIGRATIONS=1'); + + /** @And a Flyway container that runs only while the variable is enabled */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client) + ->onlyWhenEnabled(variable: 'RUN_MIGRATIONS'); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called */ + $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1']); + + /** @Then one Flyway container should run clean and migrate for both schemas */ + self::assertStringEndsWith( + 'flyway clean migrate; done sh app_0 app_1', + $this->client->getExecutedCommandLines()[0] + ); + } } diff --git a/tests/Unit/FlywayDockerContainerTest.php b/tests/Unit/FlywayDockerContainerTest.php index 0131e32..9aab7f8 100644 --- a/tests/Unit/FlywayDockerContainerTest.php +++ b/tests/Unit/FlywayDockerContainerTest.php @@ -9,6 +9,7 @@ use TinyBlocks\DockerContainer\Exceptions\ContainerExitUnsuccessful; use TinyBlocks\DockerContainer\Exceptions\ContainerWaitTimeout; use TinyBlocks\DockerContainer\Exceptions\DockerCommandExecutionFailed; +use TinyBlocks\DockerContainer\Exceptions\SchemaListEmpty; use TinyBlocks\DockerContainer\FlywayDockerContainer; use TinyBlocks\DockerContainer\MySQLDockerContainer; use TinyBlocks\Time\Duration; @@ -569,6 +570,19 @@ public function testMigrateWhenFlywayOutlastsTimeoutThenContainerWaitTimeout(): $flyway->migrate(); } + public function testCleanAndMigrateSchemasWhenNoSchemaIsGivenThenSchemaListEmpty(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @Then an exception telling that the schema list is empty should be thrown */ + $this->expectException(SchemaListEmpty::class); + $this->expectExceptionMessage('Schema list cannot be empty.'); + + /** @When cleanAndMigrateSchemas is called without schemas */ + $flyway->cleanAndMigrateSchemas(schemas: []); + } + public function testCleanAndMigrateThenEnablesCleanAndRunsCleanFollowedByMigrate(): void { /** @Given a Flyway container */ @@ -635,6 +649,86 @@ public function testMigrateWhenInsideDockerThenReaperStartsBeforeFlywayIsCreated self::assertStringStartsWith('docker create', $this->client->getExecutedCommandLines()[1]); } + public function testCleanAndMigrateSchemasThenRunsOneFlywayContainerForEverySchema(): void + { + /** @Given a MySQL container definition */ + $mySQL = DefinedMySQLContainer::definedWith( + client: $this->client, + database: 'app_database', + hostname: 'schemas-db' + ); + + /** @And a Flyway container with the MySQL source and a migrations directory */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client) + ->withSource(container: $mySQL) + ->withMigrations(pathOnHost: '/host/migrations'); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called with three schemas */ + $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1', 'app_2']); + + /** @Then MySQL should be checked once, and Flyway created, copied, run and removed once for all schemas */ + $commandLines = $this->client->getExecutedCommandLines(); + self::assertSame( + [ + 'mysqladmin ping' => 1, + 'docker create' => 2, + 'docker cp' => 1, + 'docker start --attach' => 1, + 'docker rm' => 1 + ], + [ + 'mysqladmin ping' => count(array_filter( + $commandLines, + static fn(string $line): bool => str_contains($line, 'mysqladmin ping') + )), + 'docker create' => count(array_filter( + $commandLines, + static fn(string $line): bool => str_starts_with($line, 'docker create') + )), + 'docker cp' => count(array_filter( + $commandLines, + static fn(string $line): bool => str_starts_with($line, 'docker cp') + )), + 'docker start --attach' => count(array_filter( + $commandLines, + static fn(string $line): bool => str_starts_with($line, 'docker start --attach') + )), + 'docker rm' => count(array_filter( + $commandLines, + static fn(string $line): bool => str_starts_with($line, 'docker rm') + )) + ] + ); + } + + public function testCleanAndMigrateSchemasThenEachSchemaIsCleanedAndMigratedInOrder(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called with three schemas */ + $flyway->cleanAndMigrateSchemas(schemas: ['app', 'app_0', 'app_1']); + + /** @Then the shell of the Flyway image should run clean and migrate once per schema, in order */ + self::assertSame( + [ + '-c', + 'set -e; for schema in "$@"; do FLYWAY_SCHEMAS="$schema" flyway clean migrate; done', + 'sh', + 'app', + 'app_0', + 'app_1' + ], + array_slice($this->client->getExecutedArguments()[0], -6) + ); + } + public function testMigrateWhenPullTimeoutIsGivenThenContainerCreationIsBoundedByIt(): void { /** @Given a Flyway container whose image may take up to ten minutes to pull */ @@ -667,6 +761,23 @@ public function testMigrateWhenFlywayCannotBeCreatedThenDockerCommandExecutionFa $flyway->migrate(); } + public function testCleanAndMigrateSchemasThenEnablesCleanAndReplacesTheFlywayEntrypoint(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called */ + $flyway->cleanAndMigrateSchemas(schemas: ['app']); + + /** @Then the container should start the shell instead of Flyway, with clean enabled */ + $commandLine = $this->client->getExecutedCommandLines()[0]; + self::assertStringContainsString('--entrypoint sh ', $commandLine); + self::assertStringContainsString('--env FLYWAY_CLEAN_DISABLED=false ', $commandLine); + } + public function testMigrateWhenFlywayFailsThenContainerExitUnsuccessfulCarriesFlywayError(): void { /** @Given a Flyway container */ @@ -691,4 +802,60 @@ public function testMigrateWhenFlywayFailsThenContainerExitUnsuccessfulCarriesFl $flyway->migrate(); } + public function testCleanAndMigrateSchemasWhenTimeoutIsGivenThenWaitsUpToThatTimeoutPerSchema(): void + { + /** @Given a Flyway container that waits up to fifty seconds for each run */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client) + ->withTimeout(timeout: Duration::fromSeconds(seconds: 50)); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called with three schemas */ + $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1', 'app_2']); + + /** @Then the run should wait up to fifty seconds for each of the three schemas */ + self::assertSame([300, 150], $this->client->getRequestedTimeouts()); + } + + public function testCleanAndMigrateSchemasWhenFlywayFailsForASchemaThenFlywayContainerIsRemoved(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @And Flyway exits with a non-zero status on the second schema */ + $this->client->withDockerAttachedStartResponse( + output: "ERROR: Migration V0001 failed in app_1\n", + isSuccessful: false + ); + + try { + /** @When cleanAndMigrateSchemas is called */ + $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1', 'app_2']); + } catch (ContainerExitUnsuccessful) { + /** @Then the Flyway container should have been removed */ + self::assertSame( + 'docker rm --force --volumes 6acae5967be0', + array_last($this->client->getExecutedCommandLines()) + ); + } + } + + public function testCleanAndMigrateSchemasWhenTimeoutIsNotGivenThenWaitsUpToTwoMinutesPerSchema(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When cleanAndMigrateSchemas is called with two schemas */ + $flyway->cleanAndMigrateSchemas(schemas: ['app_0', 'app_1']); + + /** @Then the creation should be bounded by the pull timeout, and the run by two minutes per schema */ + self::assertSame([300, 240], $this->client->getRequestedTimeouts()); + } } From f9782e91b7cf55d75de7b51dbd9ba8f93c2b2cde Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 14 Nov 2026 13:54:31 -0300 Subject: [PATCH 3/4] feat: Start Flyway with a JVM tuned for short runs. --- .../Drivers/Flyway/FlywaySettings.php | 4 +- tests/Unit/FlywayDockerContainerTest.php | 38 +++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php b/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php index 64d461e..1fde72d 100644 --- a/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php +++ b/src/Internal/Containers/Drivers/Flyway/FlywaySettings.php @@ -9,6 +9,8 @@ final readonly class FlywaySettings { + private const array DEFAULT_SETTINGS = ['JAVA_ARGS' => '-XX:TieredStopAtLevel=1 -XX:+UseSerialGC']; + private function __construct(private FlywaySource $source, private array $settings = []) { } @@ -25,7 +27,7 @@ public function with(string $key, string $value): FlywaySettings public function applyTo(ContainerDefinition $definition): ContainerDefinition { - $settings = [...$this->source->toSettings(), ...$this->settings]; + $settings = [...self::DEFAULT_SETTINGS, ...$this->source->toSettings(), ...$this->settings]; return array_reduce( array_keys($settings), diff --git a/tests/Unit/FlywayDockerContainerTest.php b/tests/Unit/FlywayDockerContainerTest.php index 9aab7f8..ee417b2 100644 --- a/tests/Unit/FlywayDockerContainerTest.php +++ b/tests/Unit/FlywayDockerContainerTest.php @@ -252,6 +252,24 @@ public function testWithMigrationsThenCopiesThemBeforeFlywayStarts(): void ); } + public function testMigrateThenFlywayStartsWithAJvmTunedForShortRuns(): void + { + /** @Given a Flyway container */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When migrate is called */ + $flyway->migrate(); + + /** @Then Flyway should start with the C1 compiler only and the serial collector */ + self::assertContains( + 'JAVA_ARGS=-XX:TieredStopAtLevel=1 -XX:+UseSerialGC', + $this->client->getExecutedArguments()[0] + ); + } + public function testMigrateWhenFlywaySucceedsThenReturnsFlywayOutput(): void { /** @Given a Flyway container */ @@ -818,6 +836,26 @@ public function testCleanAndMigrateSchemasWhenTimeoutIsGivenThenWaitsUpToThatTim self::assertSame([300, 150], $this->client->getRequestedTimeouts()); } + public function testWithEnvironmentVariableWhenJavaArgumentsAreGivenThenTheyReplaceTheTunedJvm(): void + { + /** @Given a Flyway container with its own JVM arguments */ + $flyway = FlywayDockerContainer::from(image: 'flyway/flyway:12-alpine', client: $this->client) + ->withEnvironmentVariable(key: 'JAVA_ARGS', value: '-Xmx256m'); + + /** @And the Docker daemon creates the Flyway container */ + $this->client->withDockerCreateResponse(output: InspectResponseFixture::containerId()); + + /** @When migrate is called */ + $flyway->migrate(); + + /** @Then the JVM arguments given should be the only ones Flyway receives */ + $javaArguments = array_values(array_filter( + $this->client->getExecutedArguments()[0], + static fn(string $argument): bool => str_starts_with($argument, 'JAVA_ARGS=') + )); + self::assertSame(['JAVA_ARGS=-Xmx256m'], $javaArguments); + } + public function testCleanAndMigrateSchemasWhenFlywayFailsForASchemaThenFlywayContainerIsRemoved(): void { /** @Given a Flyway container */ From 3a2bdb13d53d5feb8ea36ad5fc6c6eeaa1217b21 Mon Sep 17 00:00:00 2001 From: Gustavo Freze Date: Sat, 14 Nov 2026 13:54:38 -0300 Subject: [PATCH 4/4] docs: Document the multi-schema migration, the tuned Flyway JVM and the run-scoped cleanup. --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 5fb23d8..e50f293 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ - [Configuring migrations](#configuring-migrations) - [Configuring Flyway options](#configuring-flyway-options) - [Running Flyway commands](#running-flyway-commands) + - [Migrating several schemas](#migrating-several-schemas) - [Running only when enabled](#running-only-when-enabled) + [Handling failures](#handling-failures) + [Using a custom Docker client](#using-a-custom-docker-client) @@ -103,14 +104,18 @@ To wait after the container starts, register a wait strategy on the definition ( [Wait strategies](#wait-strategies)). A container that fails to receive its files, to start, or to satisfy a wait strategy is removed before the failure is -raised, since nothing else holds it. +raised, since nothing else holds it. A creation that fails after Docker registered the container, for example when the +image pull outlasts the pull timeout, removes that container too. ### Running if not exists Starts a container only if a container with the same name does not exist yet, and reuses it otherwise. The returned `SharedContainer` is shared by every PHP process that asks for the same name (as in mutation testing), so it offers -neither `stopOnShutdown()` nor `remove()`: no single process owns it. When the code runs inside Docker, a reaper -container removes the shared container once the test runner container exits. The wait strategies registered with +neither `stopOnShutdown()` nor `remove()`: no single process owns it. When the code runs inside Docker, the first +container a process creates also starts a reaper container for that process. Once the test runner container exits, +the reaper removes every container the process created, in any state, and the networks it created that nothing uses +anymore. It finds them by the label of the process (see [Stopping on shutdown](#stopping-on-shutdown)), so the +containers and networks of other processes are never touched. The wait strategies registered with `withWaitAfterStarted()` apply only when a new container starts. Processes that ask for the same name at the same time are safe: Docker lets only one of them create the container, @@ -162,8 +167,8 @@ $alreadyRunning = $started->wasReused(); ### Setting network Sets the Docker network the container should join. The network is created automatically when the container runs, if -it does not already exist. Networks created by the library are labeled with `tiny-blocks.docker-container=true` for -safe cleanup. When a cleanup running in parallel removes the network before the container starts, the network is +it does not already exist. Networks created by the library are labeled with `tiny-blocks.docker-container=true` and +with the label of the process that created them, for safe cleanup. When a cleanup running in parallel removes the network before the container starts, the network is created again and the container is started once more. ```php @@ -268,10 +273,12 @@ following cleanup is performed automatically: - The container is killed and removed (`docker rm --force --volumes`). - Anonymous volumes created by the container (e.g., MySQL's `/var/lib/mysql`) are removed. -- Unused networks created by the library are pruned. +- Unused networks created by this process are pruned. -Only resources labeled with `tiny-blocks.docker-container=true` are affected. Containers, volumes, and networks -from other environments are never touched. +Every container and network the library creates carries the label `tiny-blocks.docker-container=true` and the label of +the process that created it, `tiny-blocks.docker-container.run=-`. Only resources carrying the +label of this process are affected. Containers, volumes, and networks of other processes and other environments are +never touched. ```php $started = $container->run(); @@ -560,6 +567,13 @@ $flyway = $flyway->withMigrations(pathOnHost: '/path/to/migrations'); | `withMigrationNamingValidation` | | Rejects migrations whose file names break the naming convention. | | `withEnvironmentVariable` | `$key`, `$value` | Sets any other Flyway setting through its `FLYWAY_*` variable. | +Flyway starts with a JVM tuned for short runs, `JAVA_ARGS=-XX:TieredStopAtLevel=1 -XX:+UseSerialGC`, which roughly +halves the processor time each run spends before Flyway reaches the database. Setting `JAVA_ARGS` replaces it: + +```php +$flyway = $flyway->withEnvironmentVariable(key: 'JAVA_ARGS', value: '-Xmx512m'); +``` + #### Running Flyway commands | Method | Flyway command | Description | @@ -587,6 +601,19 @@ use TinyBlocks\Time\Duration; $flyway->withTimeout(timeout: Duration::fromSeconds(seconds: 300))->cleanAndMigrate(); ``` +#### Migrating several schemas + +`cleanAndMigrateSchemas()` cleans and migrates a list of schemas in a single Flyway container. Each schema ends exactly +as `withSchema($schema)->cleanAndMigrate()` leaves it, cleaned, migrated, and with its own history table, while the +container is created, the migrations are copied, and the MySQL source is checked once for all of them instead of once +per schema. The schemas are migrated in order, and the first one Flyway fails on stops the run with +`ContainerExitUnsuccessful`. The run waits up to the timeout of `withTimeout()` for each schema, so 120 seconds per +schema by default. An empty list raises `SchemaListEmpty`. + +```php +$flyway->cleanAndMigrateSchemas(schemas: ['test_adm', 'test_adm_0', 'test_adm_1']); +``` + #### Running only when enabled `onlyWhenEnabled()` returns a `FlywayContainerGated`, whose commands run only while an environment @@ -603,7 +630,7 @@ $execution = $flyway ->cleanAndMigrate(); # ExecutionCompleted when RUN_MIGRATIONS=1, null otherwise ``` -The gated container offers the same four commands, with the same exceptions. A command returns an +The gated container offers the same five commands, with the same exceptions. A command returns an `ExecutionCompleted` only when Flyway did run, and `null` tells the caller that nothing ran. ### Handling failures @@ -616,6 +643,7 @@ The exceptions consumers may catch live in `TinyBlocks\DockerContainer\Exception | `ContainerWaitTimeout` | A readiness condition does not hold, or a one-shot container does not exit, in time. | | `ContainerExitUnsuccessful` | A one-shot container, such as Flyway, exits with a non-zero status. | | `ImageNameEmpty` | A container is created from an empty image name. | +| `SchemaListEmpty` | `cleanAndMigrateSchemas()` is called with an empty list of schemas. | `ContainerExitUnsuccessful` carries what the container wrote to its standard error, so a failed migration reports the Flyway error itself: @@ -739,6 +767,23 @@ FlywayDockerContainer::from(image: 'flyway/flyway:13.9.0-alpine') ->cleanAndMigrate(); ``` +When each process of the run works on a schema of its own, as mutation threads do, migrate the main schema and the +schema of every thread in one Flyway run instead of one run per schema: + +```php +onlyWhenEnabled(variable: 'RUN_MIGRATIONS')->cleanAndMigrateSchemas(schemas: $schemas); +``` + ## FAQ ### 01. Why is the shared container name scoped to the test runner?