<?php
declare(strict_types=1);
namespace JKingWeb\NewsSync\Db;

interface Driver {
    const TS_TIME = -1;
    const TS_DATE = 0;
    const TS_BOTH = 1;

    const TS_FORMAT = [
        self::TS_TIME => 'h:i:sP',
        self::TS_DATE => 'Y-m-d',
        self::TS_BOTH => 'Y-m-d h:i:sP',
    ];
    
    function __construct(\JKingWeb\NewsSync\RuntimeData $data, bool $install = false);
    // returns a human-friendly name for the driver (for display in installer, for example)
    static function driverName(): string;
    // returns the version of the scheme of the opened database; if uninitialized should return 0
    function schemaVersion(): int;
    // begin a real or synthetic transactions, with real or synthetic nesting
    function begin(): bool;
    // commit either the latest or all pending nested transactions; use of this method should assume a partial commit is a no-op
    function commit(bool $all = false): bool;
    // rollback either the latest or all pending nested transactions; use of this method should assume a partial rollback will not work
    function rollback(bool $all = false): bool;
    // attempt to advise other processes that they should not attempt to access the database; used during live upgrades
    function lock(): bool;
    function unlock(): bool;
    function isLocked(): bool;
    // attempt to perform an in-place upgrade of the database schema; this may be a no-op which always throws an exception
    function update(int $to): bool;
    // execute one or more unsanitized SQL queries and return an indication of success
    function exec(string $query): bool;
    // perform a single unsanitized query and return a result set
    function query(string $query): Result;
    // ready a prepared statement for later execution
    function prepare(string $query, string ...$paramType): Statement;
}