From 1b83852d0abce97f05658719122930bc8bf7b1a9 Mon Sep 17 00:00:00 2001
From: prolic <saschaprolic@googlemail.com>
Date: Tue, 26 Jun 2018 19:14:24 +0800
Subject: [PATCH] initial commit

---
 .gitignore                  |   7 +++
 README.md                   |  21 +++++++
 composer.json               |  26 +++++++++
 src/CommandResult.php       |  12 ++++
 src/Connection.php          |  30 ++++++++++
 src/ConnectionException.php |   6 ++
 src/Connector.php           |  14 +++++
 src/Executor.php            |  53 ++++++++++++++++++
 src/FailureException.php    |   6 ++
 src/Link.php                |  14 +++++
 src/Operation.php           |  10 ++++
 src/Pool.php                |  40 ++++++++++++++
 src/PoolError.php           |   6 ++
 src/QueryError.php          |  30 ++++++++++
 src/ResultSet.php           |  19 +++++++
 src/Statement.php           |  29 ++++++++++
 src/Transaction.php         | 106 ++++++++++++++++++++++++++++++++++++
 src/TransactionError.php    |   6 ++
 18 files changed, 435 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 composer.json
 create mode 100644 src/CommandResult.php
 create mode 100644 src/Connection.php
 create mode 100644 src/ConnectionException.php
 create mode 100644 src/Connector.php
 create mode 100644 src/Executor.php
 create mode 100644 src/FailureException.php
 create mode 100644 src/Link.php
 create mode 100644 src/Operation.php
 create mode 100644 src/Pool.php
 create mode 100644 src/PoolError.php
 create mode 100644 src/QueryError.php
 create mode 100644 src/ResultSet.php
 create mode 100644 src/Statement.php
 create mode 100644 src/Transaction.php
 create mode 100644 src/TransactionError.php

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4c4c133
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,7 @@
+.php_cs.cache
+.idea
+build
+composer.lock
+phpunit.xml
+vendor
+*.pid
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c8742b1
--- /dev/null
+++ b/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.
diff --git a/composer.json b/composer.json
new file mode 100644
index 0000000..b398408
--- /dev/null
+++ b/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"
+        }
+    }
+}
diff --git a/src/CommandResult.php b/src/CommandResult.php
new file mode 100644
index 0000000..cdc86ed
--- /dev/null
+++ b/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;
+}
\ No newline at end of file
diff --git a/src/Connection.php b/src/Connection.php
new file mode 100644
index 0000000..fdcad26
--- /dev/null
+++ b/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;
+}
diff --git a/src/ConnectionException.php b/src/ConnectionException.php
new file mode 100644
index 0000000..3672312
--- /dev/null
+++ b/src/ConnectionException.php
@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class ConnectionException extends FailureException {
+}
diff --git a/src/Connector.php b/src/Connector.php
new file mode 100644
index 0000000..33354d7
--- /dev/null
+++ b/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;
+}
diff --git a/src/Executor.php b/src/Executor.php
new file mode 100644
index 0000000..50a2c31
--- /dev/null
+++ b/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();
+}
diff --git a/src/FailureException.php b/src/FailureException.php
new file mode 100644
index 0000000..31171ea
--- /dev/null
+++ b/src/FailureException.php
@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class FailureException extends \Exception {
+}
diff --git a/src/Link.php b/src/Link.php
new file mode 100644
index 0000000..90b3108
--- /dev/null
+++ b/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;
+}
diff --git a/src/Operation.php b/src/Operation.php
new file mode 100644
index 0000000..0f98a46
--- /dev/null
+++ b/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);
+}
diff --git a/src/Pool.php b/src/Pool.php
new file mode 100644
index 0000000..efec222
--- /dev/null
+++ b/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;
+}
diff --git a/src/PoolError.php b/src/PoolError.php
new file mode 100644
index 0000000..150e1ca
--- /dev/null
+++ b/src/PoolError.php
@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class PoolError extends \Error {
+}
diff --git a/src/QueryError.php b/src/QueryError.php
new file mode 100644
index 0000000..2d00f50
--- /dev/null
+++ b/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;
+    }
+}
diff --git a/src/ResultSet.php b/src/ResultSet.php
new file mode 100644
index 0000000..8f14ba7
--- /dev/null
+++ b/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;
+}
diff --git a/src/Statement.php b/src/Statement.php
new file mode 100644
index 0000000..071a905
--- /dev/null
+++ b/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;
+}
diff --git a/src/Transaction.php b/src/Transaction.php
new file mode 100644
index 0000000..5a800cb
--- /dev/null
+++ b/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;
+}
diff --git a/src/TransactionError.php b/src/TransactionError.php
new file mode 100644
index 0000000..05faa12
--- /dev/null
+++ b/src/TransactionError.php
@@ -0,0 +1,6 @@
+<?php
+
+namespace Amp\Sql;
+
+class TransactionError extends \Error {
+}