From c5f7c8e1734fc55eeb1cf3844f2141301f25f576 Mon Sep 17 00:00:00 2001
From: Michael Wallner <mike@php.net>
Date: Thu, 17 Jul 2014 21:19:23 +0200
Subject: [PATCH] first connection docs

---
 pq.md                        | 12 +++++
 pq/Connection.md             | 91 ++++++++++++++++++++++++++++++++++++
 pq/Connection/__construct.md | 29 ++++++++++++
 3 files changed, 132 insertions(+)
 create mode 100644 pq.md
 create mode 100644 pq/Connection.md
 create mode 100644 pq/Connection/__construct.md

diff --git a/pq.md b/pq.md
new file mode 100644
index 0000000..45d9faa
--- /dev/null
+++ b/pq.md
@@ -0,0 +1,12 @@
+# pecl/pq
+
+## About:
+
+This is a modern binding to the mature [libpq, the official PostgreSQL C-client library](http://www.postgresql.org/docs/current/static/libpq.html).
+
+### Highlights:
+
+* Nearly 100% support for [asynchronous usage](pq/AsyncOperations).
+* Extended type [support by pg_type](pq/UsingTypes).
+* Fetching simple [multi-dimensional array maps](pq/FetchingResults#markdown-header-fetching-simple-maps).
+* Working [Gateway implementation](https://bitbucket.org/m6w6/pq-gateway).
diff --git a/pq/Connection.md b/pq/Connection.md
new file mode 100644
index 0000000..924e104
--- /dev/null
+++ b/pq/Connection.md
@@ -0,0 +1,91 @@
+# class pq\Connection
+
+A class representing a connection to the PostgreSQL server.
+
+See the [General Usage](pq/Connection/: General Usage) page for an introduction on how to use this class.
+
+## Constants:
+### Connection Flags:
+* PERSISTENT  
+(Re-)open a persistent connection.
+* ASYNC  
+If the connection is not already open, perform the connection attempt [asynchronously](pq/Connection/: Asynchronous Usage).
+
+### Connection Status:
+* OK  
+Everything well; if a connection has been newly and synchronously created, the connection will always have this status right after creation.
+* BAD  
+Broken connection; consider pq\Connection::reset() or recreation.
+* STARTED  
+Waiting for connection to be made.
+* MADE  
+Connection OK; waiting to send.
+* AWAITING_RESPONSE  
+Waiting for a response from the server.
+* AUTH_OK  
+Received authentication; waiting for backend start-up to finish.
+* SSL_STARTUP  
+Negotiating SSL encryption.
+* SETENV  
+Negotiating environment-driven parameter settings.
+
+### Transaction Status:
+* TRANS_IDLE  
+  No active transaction.
+* TRANS_ACTIVE  
+  A transaction command is in progress.
+* TRANS_INTRANS  
+  Idling in a valid transcation block.
+* TRANS_INERROR  
+  Idling in a failed transaction block.
+* TRANS_UNKNOWN  
+  Bad connection.
+
+### Polling Status:
+* POLLING_FAILED  
+  The connection procedure has failed.
+* POLLING_READING  
+  Select for read-readiness.
+* POLLING_WRITING  
+  Select for write-readiness.
+* POLLING_OK  
+  The connection has been successfully made.
+
+### Event Listener Types:
+* EVENT_NOTICE  
+  Register the event handler for notices.
+* EVENT_RESULT  
+  Register the event handler for any created results.
+* EVENT_RESET  
+  Register the event handler for connection resets.
+
+
+## Properties:
+* public (readonly) $status  
+  A [connection status constant](pq/Connection#Connection.Status:) value.
+* public (readonly) $transactionStatus  
+  A [transaction status constant](pq/Connection#Transaction.Status:) value.
+* public (readonly) $socket  
+  The server socket resource.
+* public (readonly) $busy  
+  Whether the connection is busy with [asynchronous operations](pq/Connection/: Asynchronous Usage).
+* public (readonly) $errorMessage  
+  Any error message on failure.
+* public $encoding = NULL  
+  Connection character set.
+* public $unbuffered = FALSE  
+  Whether to fetch results in unbuffered mode, i.e. each row generates a distinct pq\Result.
+
+### Connection Information:
+* public (readonly) $db  
+The database name of the connection.
+* public (readonly) $user  
+The user name of the connection.
+* public (readonly) $pass  
+The password of the connection.
+* public (readonly) $host  
+The server host name of the connection.
+* public (readonly) $port  
+The port of the connection.
+* public (readonly) $options  
+The command-line options passed in the connection request.
diff --git a/pq/Connection/__construct.md b/pq/Connection/__construct.md
new file mode 100644
index 0000000..10d78d8
--- /dev/null
+++ b/pq/Connection/__construct.md
@@ -0,0 +1,29 @@
+# void pq\Connection::__construct([string $dsn = ""[, int $flags = 0]])
+
+Create a new PostgreSQL connection.
+See also [General Usage](pq/Connection/: General Usage).
+
+## Params:
+* string $dsn = ""  
+  A ***connection string*** as described [in the PostgreSQL documentation](http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING).
+* int $flags = 0  
+  See [connection flag constants](pq/Connection#Connection.Flags:).
+
+## Throws:
+
+* pq\Exception\InvalidArgumentException
+* pq\Exception\BadMethodCallException
+* pq\Exception\RuntimeException
+
+## Example:
+
+Creating a connection:
+
+	<?php
+
+	$connection = new pq\Connection("dbname=test user=test password=test",
+		pq\Connection::ASYNC | pq\Connection::PERSISTENT);
+
+	?>
+
+
-- 
2.30.2