Remove dups; add some docs; update Pool

src/Connection.php

@@ -2,31 +2,20 @@
 
 namespace Amp\Sql;
 
+use Amp\CancellationToken;
 use Amp\Promise;
 
 interface Connection extends Link {
-    public function connect(): Promise;
-
     /**
-     * @return bool False if the connection has been closed.
+     * @param ConnectionConfig       $config
+     * @param CancellationToken|null $token
+     *
+     * @return Promise<Connection>
      */
-    public function isAlive(): bool;
+    public static function connect(ConnectionConfig $config, CancellationToken $token = null): Promise;
 
     /**
      * @return int Timestamp of the last time this connection was used.
      */
     public function lastUsedAt(): int;
-
-    public function close();
-
-    public function query(string $query): Promise;
-
-    public function transaction(int $isolation = Transaction::COMMITTED): Promise;
-
-    public function prepare(string $query): Promise;
-
-    /**
-     * {@inheritdoc}
-     */
-    public function execute(string $sql, array $params = []): Promise;
 }

src/Executor.php

@@ -8,22 +8,22 @@ interface Executor {
     /**
      * @param string $sql SQL query to execute.
      *
-     * @return \Amp\Promise<\Amp\Sql\CommandResult|\Amp\Sql\ResultSet>
+     * @return Promise<CommandResult|ResultSet>
      *
-     * @throws \Amp\Sql\FailureException If the operation fails due to unexpected condition.
-     * @throws \Amp\Sql\ConnectionException If the connection to the database is lost.
-     * @throws \Amp\Sql\QueryError If the operation fails due to an error in the query (such as a syntax error).
+     * @throws FailureException If the operation fails due to unexpected condition.
+     * @throws ConnectionException If the connection to the database is lost.
+     * @throws QueryError If the operation fails due to an error in the query (such as a syntax error).
      */
     public function query(string $sql): Promise;
 
     /**
      * @param string $sql SQL query to prepare.
      *
-     * @return \Amp\Promise<\Amp\Mysql\Statement>
+     * @return Promise<Statement>
      *
-     * @throws \Amp\Sql\FailureException If the operation fails due to unexpected condition.
-     * @throws \Amp\Sql\ConnectionException If the connection to the database is lost.
-     * @throws \Amp\Sql\QueryError If the operation fails due to an error in the query (such as a syntax error).
+     * @throws FailureException If the operation fails due to unexpected condition.
+     * @throws ConnectionException If the connection to the database is lost.
+     * @throws QueryError If the operation fails due to an error in the query (such as a syntax error).
      */
     public function prepare(string $sql): Promise;
 
@@ -31,11 +31,11 @@ interface Executor {
      * @param string $sql SQL query to prepare and execute.
      * @param mixed[] $params Query parameters.
      *
-     * @return \Amp\Promise<\Amp\Sql\CommandResult|\Amp\Sql\ResultSet>
+     * @return Promise<CommandResult|ResultSet>
      *
-     * @throws \Amp\Sql\FailureException If the operation fails due to unexpected condition.
-     * @throws \Amp\Sql\ConnectionException If the connection to the database is lost.
-     * @throws \Amp\Sql\QueryError If the operation fails due to an error in the query (such as a syntax error).
+     * @throws FailureException If the operation fails due to unexpected condition.
+     * @throws ConnectionException If the connection to the database is lost.
+     * @throws QueryError If the operation fails due to an error in the query (such as a syntax error).
      */
     public function execute(string $sql, array $params = []): Promise;
 

src/Link.php

@@ -8,7 +8,9 @@ interface Link extends Executor {
     /**
      * Starts a transaction on a single connection.
      *
-     * @return \Amp\Promise
+     * @param int $isolation Transaction isolation level.
+     *
+     * @return Promise<Transaction>
      */
-    public function transaction(): Promise;
+    public function transaction(int $isolation = Transaction::ISOLATION_COMMITTED): Promise;
 }

src/Pool.php

@@ -4,37 +4,37 @@ namespace Amp\Sql;
 
 use Amp\Promise;
 
-interface Pool extends Link
-{
+interface Pool extends Link {
     const DEFAULT_MAX_CONNECTIONS = 100;
     const DEFAULT_IDLE_TIMEOUT = 60;
 
-    public function getIdleTimeout(): int;
-
     /**
-     * @param int $timeout The maximum number of seconds a connection may be idle before being closed and removed
-     *     from the pool.
-     *
-     * @throws \Error If the timeout is less than 1.
-     */
-    public function setIdleTimeout(int $timeout);
-
-    public function getMaxConnections(): int;
-
-    public function getConnectionCount(): int;
-
-    public function getIdleConnectionCount(): int;
-
-    /**
-     * Extracts an idle connection from the pool. The connection is completely removed from the pool and cannot be
-     * put back into the pool. Useful for operations where connection state must be changed.
-     *
-     * @return \Amp\Promise<\Amp\Sql\Connection>
+     * @return Promise<Link>
      */
     public function extractConnection(): Promise;
 
     /**
-     * {@inheritdoc}
+     * @return int Total number of active connections in the pool.
      */
-    public function transaction(int $isolation = Transaction::COMMITTED): Promise;
+    public function getConnectionCount(): int;
+
+    /**
+     * @return int Total number of idle connections in the pool.
+     */
+    public function getIdleConnectionCount(): int;
+
+    /**
+     * @return int Maximum number of connections this pool will create.
+     */
+    public function getMaxConnections(): int;
+
+    /**
+     * @return int Number of seconds a connection may remain idle before it is automatically closed.
+     */
+    public function getIdleTimeout(): int;
+
+    /**
+     * @param int $timeout Number of seconds a connection may remain idle before it is automatically closed.
+     */
+    public function setIdleTimeout(int $timeout);
 }

src/Statement.php

@@ -8,7 +8,7 @@ interface Statement {
     /**
      * @param mixed[] $params
      *
-     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     * @return \Amp\Promise<CommandResult|ResultSet>
      */
     public function execute(array $params = []): Promise;
 

src/Transaction.php

@@ -5,10 +5,10 @@ namespace Amp\Sql;
 use Amp\Promise;
 
 interface Transaction extends Executor, Operation {
-    const UNCOMMITTED  = 0;
-    const COMMITTED    = 1;
-    const REPEATABLE   = 2;
-    const SERIALIZABLE = 4;
+    const ISOLATION_UNCOMMITTED  = 0;
+    const ISOLATION_COMMITTED    = 1;
+    const ISOLATION_REPEATABLE   = 2;
+    const ISOLATION_SERIALIZABLE = 4;
 
     /**
      * @return int
@@ -47,7 +47,7 @@ interface Transaction extends Executor, Operation {
      *
      * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
      */
-    public function savepoint(string $identifier): Promise;
+    public function createSavepoint(string $identifier): Promise;
 
     /**
      * Rolls back to the savepoint with the given identifier.
@@ -69,5 +69,5 @@ interface Transaction extends Executor, Operation {
      *
      * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
      */
-    public function release(string $identifier): Promise;
+    public function releaseSavepoint(string $identifier): Promise;
 }