P

E n te r p r ise R e a dy Da ta b a s e fo r yo ur M a c

GETTING STARTED WITH PGSQLKIT

MODIFICATIONS: Dru Satori Dru satori Nov 25, 2008 Jan 7, 2009 Rough Draft Added Structure and started detail content (About PGSQLKit Draft)

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m

Table of Contents

About PGSQLKit
A Little History Building on the Shoulders of Giants - libpq Fundamental Design of PGSQLKit Dog Food

3 3 3 3 3 4 4 5 5 5 6

Setting the Environment

Installing the Framework

The First Project

Adding the Framework Making the Connection Testing the Project

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m

About PGSQLKit
A Little History PGSQLKit is a solution to an itch. It is not necessarily a required tool, being as it is really a wrapper around a lower level library that is a part of the PostgreSQL distribution. It exposed the C interfaces found in the PostgreSQL provided libpq in a more Cocoa-like fashion. PGSQLKit is the second iteration of this concept for the PostgreSQL for Mac project. The rst was pgCocoaDB. The pgCocoaDB framework began out of the need to access PostgreSQL data that resided on a remote server, and predates the the PostgreSQL for Mac project by about 6 months. If you look at the code, and you can because it is the foundation for the Query Tool as late as January 2009, you will see alot of things that are not very Cocoa-like. The reason, is that the primary developer was new to Cocoa, and came from a Windows background. That code was written prior to really learning how to program with Cocoa. So it was that as the PostgreSQL for Mac project came to be, pgCocoaDB needed to be replaced with something that made more sense. Something that could appeal to both the Cocoa community and the Windows refugees. Building on the Shoulders of Giants - libpq In the case of PGSQLKit, it made no sense to reinvent the wheel when a very good foundation was already present. PostgreSQL has used libpq as the primary point of entry for accessing the server and its data for a long time. With that in mind, PGSQLKit is an Objective-C wrapper around libpq, that makes an effort to take a traditional C interface and wrap it cleanly into an Object Oriented interface. These new Objects represent logical parts of the communications channels between the server and the client, without burdening them with the heavy lifting done in the libpq foundation. Fundamental Design of PGSQLKit Built on a paradigm that is familiar to most Windows and Java developers, the PGSQLKit embraces the concept of a Connection as the hub of all transactions between the client and server. The Connection object is responsible for marshaling requests, commands and results to and from the server, while those other objects are all owned by the connection. A single connection can be used for multiple queries, but does not support having multiple queries open at once. Conceptually connection work ow would follow the pattern of open the connection, request a query, read the results, make changes, submit a command to update, close the connection. The middle steps could be repeated often, without closing the connection. Dog Food One of the more interesting bits about the PGSQLKit is that it is the heart and soul of the graphical tools that are being written as part of the PostgreSQL for Mac project. Because of that, they are under constant scrutiny by both internal and external developers. In the development industry, this is referred to as eating your own dog food. We are doing this, and believe that the only way to build the best product is to have to use it on a daily basis.

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m

Setting the Environment

Installing the Framework Before anything else can be done, the PGSQLKit.framework needs to be installed. For developers, this needs to be into either ~/Library/Frameworks or /Library/Frameworks. For the purposes of this document, we will use the /Library/Frameworks location, as it makes it easier to test using both privileged and non-privileged users. If you install the PostgreSQL for Mac Unied installer, the framework is installed by the installer and nothing more needs to be done.

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m

The First Project

Adding the Framework The rst step in creating a connection with the PGSQLKit is to add the framework to the project. For this rst project, you want to create a Cocoa Application (not Document Based) and name is Version Information. Once you have the project created, you should have a simple project, if you navigate to the Frameworks group, you should see just one framework, the base Cocoa.framework as seen in gure 1. On the linked frameworks group, control-click or right click and select add existing frameworks. Now navigate to where you installed your PGSQLKit.framework in /Library/Frameworks and select it. With that complete, you should now have the framework ready to be linked into the application when it builds. This also lets Xcode know to look for headers in the included framework. It does not, by default notify Xcode to bundle the framework, so the resulting program will not run if the framework is not present in /Library/Frameworks. We will address that in a later example. Making the Connection With the framework added, now you get to dive into the code. The rst thing we need is a Controller for our example. As per normal Cocoa application, goto classes and create a new subclass of NSObject as the Controller. and name it PGVIController. Once created, it is time to add the import the .h so that you have access to the PGSQLKit classes. While there, go ahead and add a text eld to display the version information into. #import <Cocoa/Cocoa.h> #import <PGSQLKit/PGSQLKit.h> @interface PGVIController : NSObject { IBOutlet NSTextField *serverVersion; } Save that and go ahead and wire up the serverVersion outlet to a NSTextField in Interface Builder. With this complete, you dont really need to muck with Interface Builder any more, the rest is code. As you can see in the screenshot, this is a very simple user interface. We will expand this interface over the next couple of examples though. Also of note, is that is not a connection pointer as part of the controller class. This example will make use of the connection for a very short period of time, and as such does not need to keep a connection around consuming resources on the server and client both.

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m

Now you are ready to do the meat of the work. Goto the PGVIController.m le and create an -awakeFromNib method. -(void)awakeFromNib {

PGSQLConnection *connection = [[PGSQLConnection alloc] init]; [connection [connection [connection [connection [connection setUserName:@"postgres"]; setPassword:@""]; setServer:@"localhost"]; setPort:@"5432"]; setDatabaseName:@"postgres"];

if ([connection connect]) { NSString *cmd; cmd = [NSString stringWithString:@"select version() as version"]; PGSQLRecordset *rs = [connection open:cmd]; if (![rs isEOF]) { [serverVersion setStringValue: [[rs fieldByName:@"version"] asString] ]; } [rs close]; [connection close]; NSLog(@"Connection Error: %@", [connection lastError]);

} else { } }

With that entered, you can now run the project, and see your results, assuming of course that you have a local instance of PostgreSQL running with Trust enabled (the default installation). You may need to adjust some of the parameters in the code to make a different connection. Looking at the bits in parts, there are four parts to look at., the connection and setup are part one. That denes the connection. Part two is the connect command which returns NO if the connection fails. Part three is the open command which opens and reads the database for the query. Finally, part four closes the results and the connection. At this point, you have an application that will create a connection to the server and read the database version from the server using a SQL command all in under 30 lines of code. Testing the Project When you run the project, you should get a quick window with the results, if you dont get something like the following, look at the debug log, you should see an error that you can use to track things down.

w w w. p o s t g r e s q l f o r m a c . c o m w w w. d r u w a r e . c o m