initial commit

.gitignore

@@ -0,0 +1,7 @@
+.php_cs.cache
+.idea
+build
+composer.lock
+phpunit.xml
+vendor
+*.pid

README.md

@@ -0,0 +1,21 @@
+# Amp SQL
+
+## About
+
+This package provides interfaces and common classes shared by [amp/mysql](https://github.com/amphp/mysql/) and [amp/postgres](https://github.com/amphp/postgres/).
+
+## Requirements
+
+- PHP 7.0+
+
+## Versioning
+
+`amphp/sql` follows the [semver](http://semver.org/) semantic versioning specification like all other `amphp` packages.
+
+## Security
+
+If you discover any security related issues, please email [`contact@amphp.org`](mailto:contact@amphp.org) instead of using the issue tracker.
+
+## License
+
+The MIT License (MIT). Please see [`LICENSE`](./LICENSE) for more information.

composer.json

@@ -0,0 +1,26 @@
+{
+    "name": "amphp/sql",
+    "description": "Asynchronous SQL client for Amp.",
+    "keywords": [
+        "database",
+        "db",
+        "sql",
+        "asynchronous",
+        "async"
+    ],
+    "homepage": "http://amphp.org",
+    "license": "MIT",
+    "require": {
+        "amphp/amp": "^2"
+    },
+    "autoload": {
+        "psr-4": {
+            "Amp\\Sql\\": "src"
+        }
+    },
+    "config": {
+        "platform": {
+            "php": "7.0.0"
+        }
+    }
+}

src/CommandResult.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Amp\Sql;
+
+interface CommandResult {
+    /**
+     * Returns the number of rows affected by the query.
+     *
+     * @return int
+     */
+    public function affectedRows(): int;
+}

src/Connection.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Connection extends Link {
+    /**
+     * @return bool False if the connection has been closed.
+     */
+    public function isAlive(): bool;
+
+    /**
+     * @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/ConnectionException.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class ConnectionException extends FailureException {
+}

src/Connector.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Connector {
+    /**
+     * @param string $connectionString
+     *
+     * @return Promise<Connection>
+     */
+    public function connect(string $connectionString): Promise;
+}

src/Executor.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Executor {
+    /**
+     * @param string $sql SQL query to execute.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult|\Amp\Sql\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).
+     */
+    public function query(string $sql): Promise;
+
+    /**
+     * @param string $sql SQL query to prepare.
+     *
+     * @return \Amp\Promise<\Amp\Mysql\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).
+     */
+    public function prepare(string $sql): Promise;
+
+    /**
+     * @param string $sql SQL query to prepare and execute.
+     * @param mixed[] $params Query parameters.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult|\Amp\Sql\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).
+     */
+    public function execute(string $sql, array $params = []): Promise;
+
+    /**
+     * Indicates if the connection to the database is still alive.
+     *
+     * @return bool
+     */
+    public function isAlive(): bool;
+
+    /**
+     * Closes the executor. No further queries may be performed.
+     */
+    public function close();
+}

src/FailureException.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class FailureException extends \Exception {
+}

src/Link.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Link extends Executor {
+    /**
+     * Starts a transaction on a single connection.
+     *
+     * @return \Amp\Promise
+     */
+    public function transaction(): Promise;
+}

src/Operation.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Amp\Sql;
+
+interface Operation {
+    /**
+     * @param callable $onDestruct Callback executed when the operation completes or the object is destroyed.
+     */
+    public function onDestruct(callable $onDestruct);
+}

src/Pool.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+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>
+     */
+    public function extractConnection(): Promise;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function transaction(int $isolation = Transaction::COMMITTED): Promise;
+}

src/PoolError.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class PoolError extends \Error {
+}

src/QueryError.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Amp\Sql;
+
+class QueryError extends \Error {
+    protected $query = "";
+
+    public function __construct(string $message, string $query = "", \Throwable $previous = null) {
+        if ($query != "") {
+            $this->query = $query;
+        }
+        parent::__construct($message, 0, $previous);
+    }
+
+    final public function getQuery(): string {
+        return $this->query;
+    }
+
+    public function __toString(): string {
+        if ($this->query == "") {
+            return parent::__toString();
+        }
+
+        $msg = $this->message;
+        $this->message .= "\nCurrent query was {$this->query}";
+        $str = parent::__toString();
+        $this->message = $msg;
+        return $str;
+    }
+}

src/ResultSet.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Iterator;
+use Amp\Promise;
+
+interface ResultSet extends Iterator {
+    const FETCH_ARRAY = 0;
+    const FETCH_ASSOC = 1;
+    const FETCH_OBJECT = 2;
+
+    /**
+     * {@inheritdoc}
+     *
+     * @param int $type Next row fetch type. Use the FETCH_* constants provided by this interface.
+     */
+    public function advance(int $type = self::FETCH_ASSOC): Promise;
+}

src/Statement.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Statement {
+    /**
+     * @param mixed[] $params
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     */
+    public function execute(array $params = []): Promise;
+
+    /**
+     * @return bool True if the statement can still be executed, false if the connection has died.
+     */
+    public function isAlive(): bool;
+
+    /**
+     * @return string The SQL string used to prepare the statement.
+     */
+    public function getQuery(): string;
+
+    /**
+     * @return int Timestamp of when the statement was last used.
+     */
+    public function lastUsedAt(): int;
+}

src/Transaction.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace Amp\Sql;
+
+use Amp\Promise;
+
+interface Transaction extends Operation {
+    const UNCOMMITTED  = 0;
+    const COMMITTED    = 1;
+    const REPEATABLE   = 2;
+    const SERIALIZABLE = 4;
+
+    /**
+     * {@inheritdoc}
+     *
+     * Closes and commits all changes in the transaction.
+     */
+    public function close();
+
+    /**
+     * @return int
+     */
+    public function getIsolationLevel(): int;
+
+    /**
+     * {@inheritdoc}
+     */
+    public function isAlive(): bool;
+
+    /**
+     * @return bool True if the transaction is active, false if it has been committed or rolled back.
+     */
+    public function isActive(): bool;
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function query(string $sql): Promise;
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function prepare(string $sql): Promise;
+
+    /**
+     * {@inheritdoc}
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function execute(string $sql, array $params = []): Promise;
+
+    /**
+     * Commits the transaction and makes it inactive.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function commit(): Promise;
+
+    /**
+     * Rolls back the transaction and makes it inactive.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function rollback(): Promise;
+
+    /**
+     * Creates a savepoint with the given identifier.
+     *
+     * @param string $identifier Savepoint identifier.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function savepoint(string $identifier): Promise;
+
+    /**
+     * Rolls back to the savepoint with the given identifier.
+     *
+     * @param string $identifier Savepoint identifier.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function rollbackTo(string $identifier): Promise;
+
+    /**
+     * Releases the savepoint with the given identifier.
+     *
+     * @param string $identifier Savepoint identifier.
+     *
+     * @return \Amp\Promise<\Amp\Sql\CommandResult>
+     *
+     * @throws \Amp\Sql\TransactionError If the transaction has been committed or rolled back.
+     */
+    public function release(string $identifier): Promise;
+}

src/TransactionError.php

@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class TransactionError extends \Error {
+}