ConnectionInterface.php

<?php

declare(strict_types=1);

namespace Hypervel\Database;

use Closure;
use Generator;
use Hypervel\Contracts\Database\Query\Expression;
use Hypervel\Database\Eloquent\Builder as EloquentBuilder;
use Hypervel\Database\Eloquent\Relations\Relation;
use Hypervel\Database\Query\Builder;
use Hypervel\Database\Query\Grammars\Grammar as QueryGrammar;
use Hypervel\Database\Query\Processors\Processor;
use Hypervel\Database\Schema\Builder as SchemaBuilder;
use Throwable;
use UnitEnum;

interface ConnectionInterface
{
    /**
     * Begin a fluent query against a database table.
     *
     * @param Closure|Builder|EloquentBuilder<*>|Relation<*, *, *>|Expression|UnitEnum|string $table
     */
    public function table(Closure|Builder|EloquentBuilder|Relation|Expression|UnitEnum|string $table, ?string $as = null): Builder;

    /**
     * Get a new raw query expression.
     */
    public function raw(mixed $value): Expression;

    /**
     * Escape a value for safe SQL embedding.
     */
    public function escape(mixed $value, bool $binary = false): string;

    /**
     * Run a select statement and return a single result.
     */
    public function selectOne(string $query, array $bindings = [], bool $useReadPdo = true): mixed;

    /**
     * Run a select statement and return the first column of the first row.
     *
     * @throws MultipleColumnsSelectedException
     */
    public function scalar(string $query, array $bindings = [], bool $useReadPdo = true): mixed;

    /**
     * Run a select statement against the database.
     */
    public function select(string $query, array $bindings = [], bool $useReadPdo = true, array $fetchUsing = []): array;

    /**
     * Run a select statement against the database and return a generator.
     *
     * @return Generator<int, mixed>
     */
    public function cursor(string $query, array $bindings = [], bool $useReadPdo = true, array $fetchUsing = []): Generator;

    /**
     * Run an insert statement against the database.
     */
    public function insert(string $query, array $bindings = []): bool;

    /**
     * Get the last insert ID.
     */
    public function getLastInsertId(?string $sequence = null): int|string;

    /**
     * Run an update statement against the database.
     */
    public function update(string $query, array $bindings = []): int;

    /**
     * Run a delete statement against the database.
     */
    public function delete(string $query, array $bindings = []): int;

    /**
     * Execute an SQL statement and return the boolean result.
     */
    public function statement(string $query, array $bindings = []): bool;

    /**
     * Run an SQL statement and get the number of rows affected.
     */
    public function affectingStatement(string $query, array $bindings = []): int;

    /**
     * Run a raw, unprepared query against the connection.
     */
    public function unprepared(string $query): bool;

    /**
     * Prepare the query bindings for execution.
     */
    public function prepareBindings(array $bindings): array;

    /**
     * Execute a Closure within a transaction.
     *
     * @template TReturn
     *
     * @param Closure(static): TReturn $callback
     * @return TReturn
     *
     * @throws Throwable
     */
    public function transaction(Closure $callback, int $attempts = 1): mixed;

    /**
     * Start a new database transaction.
     */
    public function beginTransaction(): void;

    /**
     * Commit the active database transaction.
     */
    public function commit(): void;

    /**
     * Rollback the active database transaction.
     */
    public function rollBack(?int $toLevel = null): void;

    /**
     * Get the number of active transactions.
     *
     * @phpstan-impure
     */
    public function transactionLevel(): int;

    /**
     * Determine whether the connection has an active physical transaction.
     */
    public function inTransaction(): bool;

    /**
     * Execute the given callback in "dry run" mode.
     */
    public function pretend(Closure $callback): array;

    /**
     * Get the name of the connected database.
     */
    public function getDatabaseName(): string;

    /**
     * Get the connection name.
     */
    public function getName(): ?string;

    /**
     * Get the database driver name (e.g. "mysql", "pgsql", "sqlite").
     */
    public function getDriverName(): string;

    /**
     * Get a human-readable name for the database driver.
     */
    public function getDriverTitle(): string;

    /**
     * Get the number of open connections to the database.
     */
    public function threadCount(): ?int;

    /**
     * Run a callback without the table prefix on the connection.
     *
     * @template TReturn
     *
     * @param Closure($this): TReturn $callback
     * @return TReturn
     */
    public function withoutTablePrefix(Closure $callback): mixed;

    /**
     * Get a schema builder instance for the connection.
     */
    public function getSchemaBuilder(): SchemaBuilder;

    /**
     * Get the query grammar used by the connection.
     */
    public function getQueryGrammar(): QueryGrammar;

    /**
     * Get the query post processor used by the connection.
     */
    public function getPostProcessor(): Processor;

    /**
     * Get the table prefix for the connection.
     */
    public function getTablePrefix(): string;

    /**
     * Get the database server version.
     */
    public function getServerVersion(): string;

    /**
     * Get an option from the configuration options.
     */
    public function getConfig(?string $option = null): mixed;

    /**
     * Run a select statement against the database using the write connection.
     */
    public function selectFromWriteConnection(string $query, array $bindings = []): array;

    /**
     * Indicate if any records have been modified.
     */
    public function recordsHaveBeenModified(bool $value = true): void;

    /**
     * Disconnect from the underlying driver resources.
     */
    public function disconnect(): void;
}