<?php

declare(strict_types=1);

namespace PpPhp\Core\Database\Dialect;

interface DatabaseDialectInterface
{
    public function id(): string;

    public function label(): string;

    /** Frontend-safe engine capabilities and field-type metadata. */
    public function uiConfig(): array;

    /** @return array<int, array{name:string,type:string}> */
    public function listObjects(\PDO $pdo, array $config): array;

    /** @return array{columns:array,indexes:array,foreign_keys:array} */
    public function describeTable(\PDO $pdo, string $table, array $config): array;

    /**
     * Lightweight column-only introspection — just the column list, skipping the
     * index and foreign-key round-trips describeTable() performs. Used by callers
     * (schema explorer, autocomplete) that only need column name + type.
     *
     * @return array<int, array<string, mixed>>
     */
    public function listColumns(\PDO $pdo, string $table, array $config): array;

    public function createTable(\PDO $pdo, string $table, array $fields, array $config, array $foreignKeys = []): void;

    public function updateTable(
        \PDO $pdo,
        string $oldTable,
        string $newTable,
        array $fields,
        array $currentDetails,
        array $config
    ): void;

    public function dropObject(\PDO $pdo, string $name, string $type, array $config): void;

    public function createView(\PDO $pdo, string $name, string $selectSql, bool $replace, array $config): void;

    /** @return array{rows:array,columns:array} */
    public function preview(\PDO $pdo, string $selectSql, int $limit = 10): array;

    public function addForeignKey(\PDO $pdo, array $relation, array $config): void;

    public function dropForeignKey(\PDO $pdo, array $relation, array $config): void;

    public function countRows(\PDO $pdo, string $table, array $config): int;

    public function quoteIdentifier(string $identifier): string;

    /** Exposed for deterministic adapter tests and SQL previews. */
    public function compileCreateTable(string $table, array $fields, array $config = [], array $foreignKeys = []): string;
}
