feat(db): add db:mysql-optimize (beta), to replace db:size --cleanup

legacy/src/Command/Db/DbSizeCommand.php

@@ -46,7 +46,7 @@ protected function configure(): void
     {
         $this
             ->addOption('bytes', 'B', InputOption::VALUE_NONE, 'Show sizes in bytes.')
-            ->addOption('cleanup', 'C', InputOption::VALUE_NONE, 'Check if tables can be cleaned up and show me recommendations (InnoDb only).');
+            ->addOption('cleanup', 'C', InputOption::VALUE_NONE, 'Deprecated: use the db:mysql-optimize command instead.');
         $help = self::ESTIMATE_WARNING;
         if ($this->config->getBool('api.metrics')) {
             $this->stability = self::STABILITY_DEPRECATED;
@@ -70,6 +70,15 @@ protected function configure(): void
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
+        if (Option::bool($input, 'cleanup')) {
+            $this->stdErr->writeln('<options=bold;fg=yellow>Deprecated:</> The --cleanup option is deprecated and will be removed in a future version.');
+            $this->stdErr->writeln(\sprintf(
+                'To find tables with reclaimable space, and check whether they can be rebuilt safely, run: <comment>%s db:mysql-optimize</comment>',
+                $this->config->getStr('application.executable'),
+            ));
+            $this->stdErr->writeln('');
+        }
+
         $selection = $this->selector->getSelection($input, new SelectorConfig(allowLocalHost: $this->relationships->hasLocalEnvVar(), chooseEnvFilter: SelectorConfig::filterEnvsMaybeActive()));
         $host = $this->selector->getHostFromSelection($input, $selection);
 
@@ -136,7 +145,7 @@ private function getCleanupQueries(array $rows): array
                 }
                 [$schema, $table] = explode("\t", $row);
 
-                return sprintf('ALTER TABLE `%s`.`%s` ENGINE="InnoDB";', $schema, $table);
+                return sprintf('ALTER TABLE %s.%s ENGINE="InnoDB";', DbMysqlOptimizeCommand::quoteIdentifier($schema), DbMysqlOptimizeCommand::quoteIdentifier($table));
             }, $rows),
         );
     }
@@ -148,6 +157,8 @@ private function getCleanupQueries(array $rows): array
      */
     private function checkInnoDbTablesInNeedOfOptimizing(HostInterface $host, array $database, InputInterface $input): void
     {
+        $this->stdErr->writeln('');
+
         $tablesNeedingCleanup = $host->runCommand($this->getMysqlCommand($database), true, true, $this->mysqlTablesInNeedOfOptimizing());
         $queries = [];
         if (is_string($tablesNeedingCleanup)) {

legacy/src/Model/Mysql/DiskHeadroom.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Platformsh\Cli\Model\Mysql;
+
+use Platformsh\Cli\Command\Db\DbMysqlOptimizeCommand;
+use Platformsh\Cli\Service\Observability;
+
+/**
+ * The disk and /tmp usage of a database service, from the metrics API.
+ */
+readonly class DiskHeadroom
+{
+    public function __construct(
+        public float $diskUsed,
+        public float $diskLimit,
+        public ?float $tmpUsed = null,
+        public ?float $tmpLimit = null,
+    ) {}
+
+    /**
+     * Reads the usage from a service's metrics data point.
+     *
+     * @param array<mixed> $point
+     */
+    public static function fromMetrics(array $point): ?self
+    {
+        $value = function (string $mountpoint, string $metric, string $agg) use ($point): ?float {
+            $v = Observability::nested($point, 'mountpoints', $mountpoint, $metric, $agg);
+            return is_numeric($v) ? (float) $v : null;
+        };
+        $diskUsed = $value('/mnt', 'disk_used', 'avg');
+        $diskLimit = $value('/mnt', 'disk_limit', 'max');
+        if ($diskUsed === null || !$diskLimit) {
+            return null;
+        }
+        $tmpUsed = $value('/tmp', 'disk_used', 'avg');
+        $tmpLimit = $value('/tmp', 'disk_limit', 'max');
+        if ($tmpUsed === null || !$tmpLimit) {
+            $tmpUsed = $tmpLimit = null;
+        }
+
+        return new self($diskUsed, $diskLimit, $tmpUsed, $tmpLimit);
+    }
+
+    public function diskFree(): float
+    {
+        return max(0, $this->diskLimit - $this->diskUsed);
+    }
+
+    public function hasTmp(): bool
+    {
+        return $this->tmpLimit !== null;
+    }
+
+    public function tmpFree(): ?float
+    {
+        return $this->tmpLimit !== null ? max(0, $this->tmpLimit - (float) $this->tmpUsed) : null;
+    }
+
+    /**
+     * Returns whether the disk has room for a rebuild, keeping a reserve free.
+     */
+    public function diskFits(int $needed): bool
+    {
+        return self::fits($this->diskUsed, $this->diskLimit, $needed);
+    }
+
+    /**
+     * Returns whether /tmp has room for a rebuild, or null if its usage is unknown.
+     */
+    public function tmpFits(int $needed): ?bool
+    {
+        if ($this->tmpLimit === null) {
+            return null;
+        }
+
+        return self::fits((float) $this->tmpUsed, $this->tmpLimit, $needed);
+    }
+
+    private static function fits(float $used, float $limit, int $needed): bool
+    {
+        return $used + $needed <= $limit * (100 - DbMysqlOptimizeCommand::RESERVE_PERCENT) / 100;
+    }
+}

legacy/src/Model/Mysql/MysqlServerInfo.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Platformsh\Cli\Model\Mysql;
+
+/**
+ * Settings of a MySQL or MariaDB server, read from its global variables and status.
+ */
+readonly class MysqlServerInfo
+{
+    public string $version;
+    public bool $isMariaDB;
+    /** Whether innodb_file_per_table is ON, or null if it is unknown. */
+    public ?bool $filePerTable;
+    public bool $wsrepOn;
+    public int $clusterSize;
+    /** Whether information_schema_stats_expiry exists (MySQL 8+). */
+    public bool $hasStatsExpiry;
+    private ?string $tmpdir;
+
+    /**
+     * @param array<string, string> $vars Variables and status values, by lowercase name.
+     */
+    public function __construct(array $vars)
+    {
+        $this->version = $vars['version'] ?? '';
+        $this->isMariaDB = stripos($this->version . ' ' . ($vars['version_comment'] ?? ''), 'mariadb') !== false;
+        $this->filePerTable = isset($vars['innodb_file_per_table']) ? self::bool($vars['innodb_file_per_table']) : null;
+        $this->wsrepOn = isset($vars['wsrep_on']) && self::bool($vars['wsrep_on']);
+        $this->clusterSize = (int) ($vars['wsrep_cluster_size'] ?? 0);
+        $this->hasStatsExpiry = isset($vars['information_schema_stats_expiry']);
+        $tmpdir = ($vars['innodb_tmpdir'] ?? '') !== '' ? $vars['innodb_tmpdir'] : ($vars['tmpdir'] ?? '');
+        $this->tmpdir = $tmpdir !== '' ? $tmpdir : null;
+    }
+
+    /**
+     * Returns whether the server is a node of a Galera cluster with more than one node.
+     */
+    public function isGaleraCluster(): bool
+    {
+        return $this->wsrepOn && $this->clusterSize > 1;
+    }
+
+    /**
+     * Returns the directory for temporary files of online DDL (innodb_tmpdir, or tmpdir).
+     */
+    public function tmpdir(): ?string
+    {
+        return $this->tmpdir;
+    }
+
+    private static function bool(string $value): bool
+    {
+        return \in_array(strtoupper($value), ['ON', '1', 'TRUE', 'YES'], true);
+    }
+}

legacy/src/Model/Mysql/TableCandidate.php

@@ -0,0 +1,165 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Platformsh\Cli\Model\Mysql;
+
+use Platformsh\Cli\Command\Db\DbMysqlOptimizeCommand;
+
+/**
+ * An InnoDB table with reclaimable space, from information_schema.
+ */
+readonly class TableCandidate
+{
+    /** The ratio of a rebuilt table's data size to the bytes in its rows (for headers and free space in pages). */
+    public const PAGE_OVERHEAD = 1.5;
+
+    /** The disk space needed for a rebuild, beyond the estimated size, as a percentage and in bytes (for the file's free extents). */
+    public const DISK_MARGIN_PERCENT = 10;
+    public const DISK_MARGIN_BYTES = 8 * 1024 * 1024;
+
+    public function __construct(
+        public string $schema,
+        public string $name,
+        public int $dataLength,
+        public int $indexLength,
+        public int $dataFree,
+        /** The estimated number of rows (TABLE_ROWS). */
+        public int $rows = 0,
+        /** The number of FULLTEXT or SPATIAL indexes, which prevent an online rebuild. */
+        public int $offlineIndexes = 0,
+        /** The number of other tables reporting the same free space (a sign of a shared tablespace). */
+        public int $sameFree = 0,
+        /** The average bytes per row, from a sample of rows, or null if unknown. */
+        public ?float $avgRowBytes = null,
+        /** Whether the sample is the first rows only, rather than spread across the table. */
+        public bool $sampledFirstRows = false,
+    ) {}
+
+    /**
+     * @param string[] $row
+     */
+    public static function fromRow(array $row): self
+    {
+        return new self($row[0], $row[1], (int) $row[2], (int) $row[3], (int) $row[4], (int) $row[5], (int) $row[6], (int) $row[7]);
+    }
+
+    /**
+     * Returns a copy with the result of a sample of rows.
+     */
+    public function withSample(float $avgRowBytes, bool $firstRows): self
+    {
+        return new self($this->schema, $this->name, $this->dataLength, $this->indexLength, $this->dataFree, $this->rows, $this->offlineIndexes, $this->sameFree, $avgRowBytes, $firstRows);
+    }
+
+    /**
+     * The size of the table's data, indexes and free extents (about the size of its file).
+     *
+     * In a shared tablespace, the free extents are the tablespace's, so they are not counted.
+     */
+    public function size(MysqlServerInfo $server): int
+    {
+        if ($this->inSharedTablespace($server)) {
+            return $this->dataLength + $this->indexLength;
+        }
+
+        return $this->dataLength + $this->indexLength + $this->dataFree;
+    }
+
+    /**
+     * The estimated size of the table's data and indexes after a rebuild, or null if unknown.
+     *
+     * Secondary indexes are assumed to shrink in the same ratio as the data.
+     */
+    public function rebuiltSize(): ?int
+    {
+        if ($this->avgRowBytes === null) {
+            return null;
+        }
+        $data = (int) ceil($this->avgRowBytes * $this->rows * self::PAGE_OVERHEAD);
+        $index = $this->dataLength > 0 ? (int) round($this->indexLength * min(1, $data / $this->dataLength)) : $this->indexLength;
+
+        return $data + $index;
+    }
+
+    /**
+     * The estimated disk space that a rebuild would return.
+     *
+     * Free extents (DATA_FREE) are always reclaimable. Free space inside
+     * pages is only counted if rows were sampled.
+     */
+    public function reclaimable(): int
+    {
+        $rebuilt = $this->rebuiltSize();
+        if ($rebuilt === null) {
+            return $this->dataFree;
+        }
+
+        return max($this->dataFree, $this->dataLength + $this->indexLength + $this->dataFree - $rebuilt);
+    }
+
+    /**
+     * The disk space needed for the rebuilt copy of the table.
+     */
+    public function diskNeeded(): int
+    {
+        $rebuilt = $this->rebuiltSize();
+        if ($rebuilt === null) {
+            return $this->dataLength + $this->indexLength;
+        }
+
+        return $rebuilt + intdiv($rebuilt * self::DISK_MARGIN_PERCENT, 100) + self::DISK_MARGIN_BYTES;
+    }
+
+    /**
+     * The temporary space that may be needed, to sort the secondary indexes.
+     *
+     * Concurrent writes during the rebuild are also logged to a temporary
+     * file (up to innodb_online_alter_log_max_size), which is not counted.
+     */
+    public function tmpNeeded(): int
+    {
+        return $this->indexLength;
+    }
+
+    public function displayName(): string
+    {
+        return $this->schema . '.' . $this->name;
+    }
+
+    public function quotedName(): string
+    {
+        return DbMysqlOptimizeCommand::quoteIdentifier($this->schema) . '.' . DbMysqlOptimizeCommand::quoteIdentifier($this->name);
+    }
+
+    /**
+     * Returns the query that rebuilds the table online, or fails.
+     */
+    public function rebuildQuery(): string
+    {
+        return 'ALTER TABLE ' . $this->quotedName() . ' FORCE, ALGORITHM=INPLACE, LOCK=NONE;';
+    }
+
+    /**
+     * Whether the table is probably in a shared tablespace, which a rebuild does not shrink.
+     */
+    public function inSharedTablespace(MysqlServerInfo $server): bool
+    {
+        return $this->sameFree > 0 || $server->filePerTable === false;
+    }
+
+    /**
+     * Returns why the table would not be rebuilt, or null.
+     */
+    public function skipReason(MysqlServerInfo $server): ?string
+    {
+        if ($this->inSharedTablespace($server)) {
+            return 'probably in a shared tablespace: a rebuild would not reclaim space';
+        }
+        if ($this->offlineIndexes > 0) {
+            return 'has a FULLTEXT or SPATIAL index: it cannot be rebuilt without blocking writes';
+        }
+
+        return null;
+    }
+}

legacy/src/Service/Observability.php

@@ -7,6 +7,7 @@
 use GuzzleHttp\Exception\BadResponseException;
 use GuzzleHttp\Exception\RequestException;
 use GuzzleHttp\Psr7\Request;
+use Platformsh\Cli\Model\Metrics\Query;
 use Platformsh\Client\Exception\ApiResponseException;
 use Platformsh\Client\Model\Environment;
 
@@ -65,6 +66,36 @@ public static function nested(mixed $data, string ...$keys): mixed
         return $data;
     }
 
+    /**
+     * Returns the latest metrics reported by a service, from the resources overview.
+     *
+     * @param string[] $types The metric types (e.g. "disk").
+     * @param string[] $aggs  The aggregations (e.g. "avg").
+     *
+     * @return array<mixed>|null The service's latest data point, or null if metrics are not available.
+     */
+    public function latestServiceMetrics(Environment $environment, string $service, array $types, array $aggs, int $range = 600): ?array
+    {
+        if (!$link = self::getLink($this->getEntrypoint($environment), 'resources_overview')) {
+            return null;
+        }
+        $now = time();
+        $query = (new Query($now - $range, $now, null))
+            ->setServices([$service])
+            ->setTypes($types)
+            ->setAggs($aggs);
+        $data = $this->get($link . $query->asString());
+        $points = self::nested($data, 'data');
+        foreach (array_reverse(is_array($points) ? $points : []) as $point) {
+            $metrics = self::nested($point, 'services', $service);
+            if (is_array($metrics)) {
+                return $metrics;
+            }
+        }
+
+        return null;
+    }
+
     /**
      * Sends a GET request and decodes the JSON response.
      *