On Wed, 15 Jun 2011, marcelo Cortez wrote:

> hi all

i would like to know the status of the proyect  
"A client for PostgreSQL using the V3 protocol"
i donwnloaded from  squeaksource this proyect
but the few tests that contain the downloaded project 
don't help me  to understand the use of the framework
any help would be appreciated
best


We're using it in production, though we're a few versions ahead of the 
public repository. For general consumption I'd say it's usable, but the 
API may change and there may be bugs (so it's alpha). Some features are 
not implemented yet, some will never be. Also there's no user 
documentation yet, just some API docs and only a small, but critical part 
of the package has tests.

So here's some ad-hoc user's guide:

The package provides different ways to access the database. The simplest 
thing you can do is to create a PG3Connection object which represents a 
connection to the database. The easiest way to do this is to create a 
PG3ConnectionArguments object, initialize it and request a new connection 
from it. Here's an example:

 	connectionArguments := PG3ConnectionArguments new
 		hostname: '127.0.0.1';
 		port: 5432;
 		username: 'user1';
 		password: '123';
 		databaseName: 'foo'
 		yourself.
 	connection := connectionArguments newConnection.

then you can activate the connection:

 	connection startup.

and execute a query:

 	resultSets := connection execute: 'select 3 + 4, now()'. "an OrderedCollection of PG3ResultSets"
 	resultSet := resultSets first. "a PG3ResultSet"
 	rows := resultSet rows. "an OrderedCollection of PG3Rows"
 	firstRow := rows first. "a PG3Row"
 	firstRow at: 1. "7"
 	firstRow at: 2. "2011-06-16T23:21:36.358833+02:00"

finally close the connection:

 	connection terminate.

If you ask #rowsWithColumnNameDictionary instead of #rows from the result 
set, then the PG3Row objects will understand the names of the columns as 
messages. For example:

 	resultSets := connection execute: 'select 3 + 4 as result, now() as "currentDateAndTime"'.
 	resultSet := resultSets first.
 	rows := resultSet rowsWithColumnNameDictionary.
 	firstRow := rows first.
 	firstRow result. "7"
 	firstRow currentDateAndTime. "2011-06-16T23:21:36.358833+02:00"

Frequently creating connections is not cheap, so there's a connection 
pool, which besides storing connections also provides some cool stuff, 
like transactions. Here's how to create a new connection pool:

A connection pool is a singleton, so create a subclass of 
PG3ConnectionPool:

 	PG3ConnectionPool subclass: #PG3ExampleConnectionPool
 		instanceVariableNames: ''
 		classVariableNames: ''
 		poolDictionaries: ''
 		category: 'Postgres-Example'

implement #defaultConnectionArguments on the class side:

 	defaultConnectionArguments

 		^PG3ConnectionArguments new
 			hostname: '127.0.0.1';
 			port: 5432;
 			username: 'user1';
 			password: '123';
 			databaseName: 'foo';
 			yourself

then you can execute queries:

 	PG3ExampleConnectionPool default withConnectionDo: [ :connection |
 		connection execute: 'select 3 + 4'.
 		connection execute: 'select now()' ].

the latest version (which is not available yet) can also execute 
transactions:

 	PG3ExampleConnectionPool default executeTransation: [ :connection |
 		connection execute: 'insert into foo values(1, 2, 3)'.
 		connection savepoint: 'foo1'.
 		...
 		connection execute: 'insert into baz values('abc')'.
 		connection rollbackTo: 'foo1' ].

Passing the connection around in smalltalk is a bit tedious, so you can 
use the pool again, which will be able execute your query in the same 
transation:

 	PG3ExampleConnectionPool default executeTransation: [
 		PG3ExampleConnectionPool default executeQuery: 'insert into foo values(1, 2, 3)'.
 		... ].

Managing queries in smalltalk is not easy, so instead of string queries 
you can use functions to access postgres. I won't write about this now, 
because it'd be a bit too long and the API on squeaksource is obsolete now
(PG3FunctionClient). In the new API you can edit, save, debug, 
synchronize, etc. the (plpgsql) functions from the Browser in Squeak.


Levente

mdc

>
>