<commit_before>vertx-postgresql
================

Asynchronous PostgreSQL driver with support for transactions. 

This driver is used as a library directly in your Verticle and supports running transactions against the database.
This allows for full control over the life-cycle of transactions and how query results are processed.

The design goals of this driver are:

* Designed for PostgreSQL
* Memory-friendly: little to no copying of result sets in memory, fly-weight pattern in the driver itself
* Support for PostgreSQL advanced type systems (forthcoming)
* Control over number of connections to DB per verticle (defaults to 5 per verticle)

NOTE: As of now the driver is in its infancy. Simple queries work, but only a few data types are supported.
See integration tests for examples.

In initial tests, a single verticle processed 100,000 event bus messages, ran a query for each one using 5 connections in roughly 26 seconds on a Mid 2011 iMac. See EventBusTest.
 
**In this early stage this is a proof of concept, not more.**

**I'd love to hear feedback in the vert.x google group**


How to use
----------

For now, clone the repository and run ./gradlew

Either use the resulting mod or copy the JAR file to your libraries as there is currently no main verticle defined.

You can also try to run
```bash
vertx install monoid-us~vertx-postgresql~0.2
```

Features
----------

* Run single or multiple commands and queries within the context of a transaction (see Transaction.execute)
* Run one or more SELECT statements and receive rows using a simple call-back interface (see ResultListener)
* Run multiple transaction inside a single verticle
* Configurable number of connections per verticle
* Supports simple password login (see limitations/todo)
* Support for JSON data-type. Using Row.asObject(...) returns a JsonObject or JsonArray. Also JsonResult embeds columns containing JSON into resulting JsonObject.

Limitations/Todo
-----------------

* No support yet for MD5, Kerberos, GSS, SSPI authentication (see Transaction.on(AuthenticationRequest))
* No support for prepared statements
* Lousy error handling
* Even lousier support for data-types and conversion. Only PostgreSQL types defined in class _Types_ with a converter are useable. 
	For now that is Bigint, Integer, Reltime, Smallint, Varchar, Character Varying and JSON. The goal is to support all built-in types and have support for custom types as well for validation and conversion


Example code
-------------

Java 8 example:

```Java
  pg = new Postgres(vertx, "test", "test".toCharArray(), "test");	
  pg.withTransaction(trx -> trx.query("SELECT count(*) FROM pg_tables", 
    (row,trx2) -> System.out.println("Count:" + row.asInt(0)),
    (count,trx3) -> trx3.release()));
```

Java 7 (complete example):

```java
	Postgres pg;
	public void start() {
	 // in your verticle's start method create an instance of the PostgreSQL driver.
	 // transactions run by this instance below will connect to DB test on localhost using credentials test/test
	 pg = new Postgres(vertx, "test", "test".toCharArray(), "test");
	  
	    // Once a transaction is available, handle(Transaction) will be called. 
	    // Use the trx object to execute commands and run queries
	    // You can use a regular handler or chain calls using the Promise classes in the callback package.
		  p.withTransaction(new Handler<Transaction>() {
			@Override
			public void handle(Transaction trx) {
				trx.execute("BEGIN; " +
					"CREATE TABLE account ( owner character varying (40), amount integer );" +
					"INSERT INTO account (owner, amount) VALUES ('JB', 100), ('LG', 100);").
				done(new TrxCallback() {
					@Override public void handle(Transaction trx) {
						checkAmount(trx);
					}
				});
			}
		});
	}
	
	// Run a query against the DB. In this case only one result is expected.
	// SingleResult makes it reasy to retrieve the result in a single call back
	// Do check out ResultListener, which gives you full control over 
	// how query results are being returned to your verticle!
	private void checkAmount(Transaction trx) {
		trx.query("SELECT amount FROM account WHERE owner = " + owner, new SingleResult<Integer>() {
			@Override public void result(Integer currentAmount, Transaction trx) {
				if (currentAmount < amount) {
					updateAccounts(trx);
				} else {
					System.out.println("Not enough money!");
					trx.execute("ROLLBACK", new Handler<Transaction>() {
						@Override public void handle(Transaction trx) {
							trx.release();
							testComplete();
						}						
					});
				}
			}
		});
	}

	private void updateAccounts(Transaction trx) {
		trx.execute("UPDATE account SET amount = amount - " + amount +  " WHERE owner = " + owner + ";" +
								"UPDATE account SET amount = amount + " + amount + " WHERE owner = " + target + ";").
		done(new TrxCallback() {
			@Override public void handle(Transaction trx) {
			// Note the usage of COMMIT 
				trx.execute("COMMIT; DROP TABLE account", new Handler<Transaction>() {
					@Override public void handle(Transaction trx) {
						trx.release(); // release so other callbacks can use it
						testComplete();
					}
				});
			}
		});
	}
```		
 

Changes
-------------
* 0.3 - added support for MD5 login<commit_msg>v0.4 updated readme<commit_after>vertx-postgresql
================

Asynchronous PostgreSQL driver with support for transactions. 

This driver is used as a library directly in your Verticle and supports running transactions against the database.
This allows for full control over the life-cycle of transactions and how query results are processed.

The design goals of this driver are:

* Designed for PostgreSQL
* Memory-friendly: little to no copying of result sets in memory, fly-weight pattern in the driver itself
* Support for PostgreSQL advanced type systems (forthcoming)
* Control over number of connections to DB per verticle (defaults to 5 per verticle)

NOTE: As of now the driver is in its infancy. Simple queries work, but only a few data types are supported.
See integration tests for examples.

In initial tests, a single verticle processed 100,000 event bus messages, ran a query for each one using 5 connections in roughly 26 seconds on a Mid 2011 iMac. See EventBusTest.
 
**In this early stage this is a proof of concept, not more.**

**I'd love to hear feedback in the vert.x google group**


How to use
----------

For now, clone the repository and run ./gradlew

Either use the resulting mod or copy the JAR file to your libraries as there is currently no main verticle defined.

You can also try to run
```bash
vertx install monoid-us~vertx-postgresql~0.4
```

Features
----------

* Run single or multiple commands and queries within the context of a transaction (see Transaction.execute)
* Run one or more SELECT statements and receive rows using a simple call-back interface (see ResultListener)
* Run multiple transaction inside a single verticle
* Configurable number of connections per verticle
* Supports simple password login (see limitations/todo)
* Support for JSON data-type. Using Row.asObject(...) returns a JsonObject or JsonArray. Also JsonResult embeds columns containing JSON into resulting JsonObject.

Limitations/Todo
-----------------

* No support yet for Kerberos, GSS, SSPI authentication (see Transaction.on(AuthenticationRequest))
* No support for prepared statements
* Lousy error handling
* Even lousier support for data-types and conversion. Only PostgreSQL types defined in class _Types_ with a converter are useable. 
	For now that is Bigint, Integer, Reltime, Smallint, Varchar, Character Varying and JSON. The goal is to support all built-in types and have support for custom types as well for validation and conversion


Example code
-------------

Java 8 example:

```Java
  pg = new Postgres(vertx, "test", "test".toCharArray(), "test");	
  pg.withTransaction(trx -> trx.query("SELECT count(*) FROM pg_tables", 
    (row,trx2) -> System.out.println("Count:" + row.asInt(0)),
    (count,trx3) -> trx3.release()));
```

Java 7 (complete example):

```java
	Postgres pg;
	public void start() {
	 // in your verticle's start method create an instance of the PostgreSQL driver.
	 // transactions run by this instance below will connect to DB test on localhost using credentials test/test
	 pg = new Postgres(vertx, "test", "test".toCharArray(), "test");
	  
	    // Once a transaction is available, handle(Transaction) will be called. 
	    // Use the trx object to execute commands and run queries
	    // You can use a regular handler or chain calls using the Promise classes in the callback package.
		  p.withTransaction(new Handler<Transaction>() {
			@Override
			public void handle(Transaction trx) {
				trx.execute("BEGIN; " +
					"CREATE TABLE account ( owner character varying (40), amount integer );" +
					"INSERT INTO account (owner, amount) VALUES ('JB', 100), ('LG', 100);").
				done(new TrxCallback() {
					@Override public void handle(Transaction trx) {
						checkAmount(trx);
					}
				});
			}
		});
	}
	
	// Run a query against the DB. In this case only one result is expected.
	// SingleResult makes it reasy to retrieve the result in a single call back
	// Do check out ResultListener, which gives you full control over 
	// how query results are being returned to your verticle!
	private void checkAmount(Transaction trx) {
		trx.query("SELECT amount FROM account WHERE owner = " + owner, new SingleResult<Integer>() {
			@Override public void result(Integer currentAmount, Transaction trx) {
				if (currentAmount < amount) {
					updateAccounts(trx);
				} else {
					System.out.println("Not enough money!");
					trx.execute("ROLLBACK", new Handler<Transaction>() {
						@Override public void handle(Transaction trx) {
							trx.release();
							testComplete();
						}						
					});
				}
			}
		});
	}

	private void updateAccounts(Transaction trx) {
		trx.execute("UPDATE account SET amount = amount - " + amount +  " WHERE owner = " + owner + ";" +
								"UPDATE account SET amount = amount + " + amount + " WHERE owner = " + target + ";").
		done(new TrxCallback() {
			@Override public void handle(Transaction trx) {
			// Note the usage of COMMIT 
				trx.execute("COMMIT; DROP TABLE account", new Handler<Transaction>() {
					@Override public void handle(Transaction trx) {
						trx.release(); // release so other callbacks can use it
						testComplete();
					}
				});
			}
		});
	}
```		
 

Changes
-------------
* 0.4 - fixed problem with over-sized postgres messages and corrected message parsing
* 0.3 - added support for MD5 login
{'fraction_non_alphanumeric': 0.09885859824544854, 'fraction_numerical': 0.006697481369682105, 'mean_word_length': 3.5095703955763504, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6212695', 'n_tokens_mistral': 3191, 'n_tokens_neox': 2776, 'n_words': 1281}