Template Version: @(#)onepager.txt 1.35 07/11/07 SMI
Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
libpqxx - Provide C++ API to PostgreSQL for Solaris and Opensolaris
1.2. Name of Document Author/Supplier:
Geir Green
1.3. Date of This Document:
02/27/08
1.3.1. Date this project was conceived:
01/03/08
1.4. Name of Major Document Customer(s)/Consumer(s):
1.4.1. The PAC or CPT you expect to review your project:
Database
1.4.2. The ARC(s) you expect to review your project:
LSARC
1.4.3. The Director/VP who is "Sponsoring" this project:
Heidi Bergh-Hoff <heidi.bergh-hoff at sun.com>
1.4.4. The name of your business unit:
Database Technology Group (DBTG)
1.5. Email Aliases:
1.5.1. Responsible Manager:
Erlend Dahl <erlend.dahl at sun.com>
1.5.2. Responsible Engineer:
Geir Green <geir.green at sun.com>
1.5.3. Marketing Manager:
Rebecca Hansen <rebecca.hansen at sun.com>
1.5.4. Interest List:
databases-discuss at sun.com
postgresql-techteam at sun.com
sun-postgres-pteam at sun.com
2. Project Summary
2.1. Project Description:
libpqxx is the official C++ client API for PostgreSQL.
This project aims to provide libpqxx as a part of the OpenSolaris
distribution(s).
2.2. Risks and Assumptions:
It is assumed that porting the libpqxx to Solaris may cause
modifications of the libpqxx code so that it will run properly
on the
Solaris platform. The modifications (if any) are expected to be
minor.
3. Business Summary
3.1. Problem Area:
A customer who is writing software in C++ that needs to access
databases managed by postgres (on just about any platform)
libpqxx is
the library to use.
3.2. Market/Requester:
Projects Using libpqxx (taken from the README file following the
source-code) - this list is far from complete. It is known
that there
are many other projects using libpqxx that are not included here.
Some of them may be proprietary, or even have no names.
As found on Google:
DocConversion http://docconversion.sourceforge.net/
Genea http://savannah.nongnu.org/projects/genea/
Gnucomo http://www.gnucomo.org/
MapServer http://mapserver.gis.umn.edu/
QHacc http://qhacc.sourceforge.net/
Vocal/Mascarpone http://www.vovida.org/
Confirmed by authors:
OKE
http://www.liacs.nl/home/bsamwel/oke/prerelease-0.10/
KOffice/Kexi http://www.kexi-project.org/
KPoGre http://kpogre.sourceforge.net/
Once MMORPG http://sourceforge.net/projects/once/
Scippy http://dicomlib.swri.ca/scippy.html
3.6. How will you know when you are done?:
Included in the source code is set of test-programs and a script to
execute them. So when 'make check' executes with no errors,
the job
is done so far.
4. Technical Description:
4.1. Details:
libpqxx(TM) is a C++ API to PostgreSQL(TM). It replaces the earlier
libpq++(TM) with a more Standard Template Library (STL)-conformant
interface and makes more extensive use of C++ language features
such
as exceptions, templates, and strings.
Since libpqxx builds on top of the C front-end libpq(TM), you
will need
a working libpq library on your system prior to getting started
with
libpqxx. This is similar to the situation with the older libpq++
interface.
The first thing you're likely to notice in programming with
libpqxx is
that unlike other libraries, it revolves entirely around
transactions. Transactions are a central concept in database
management systems, but they are widely under-appreciated among
application developers.
It may sometimes be possible to build limited applications reliably
without serious use of transactions. More usually, however,
applications are designed without transactions simply because the
developers aren't aware of the risks they are taking, and any data
loss is rare or small enough not to be noticed. That kind of design
was not considered acceptable for libpqxx.
With conventional database APIs, you issue commands and queries
to a
database session or connection, and optionally create the
occasional
transaction. In libpqxx you start a transaction inside the
connection
first, do your SQL work using that transaction, then commit the
transaction when it's complete. There are several types of
transactions with various "quality of service" properties; if you
don't really want to use transactions at all, one of the available
transaction types is called nontransaction. This transaction type
provides classic, non-transactional behavior.
Every command or query issues a result object, which is really
a smart
pointer so it can be copied around without incurring much cost in
terms of performance. No need to write special code to check
these for
success; error conditions are converted to regular C++ exceptions.
Result objects can be kept around for as long as they are needed,
completely separate from the connections and transactions that
originated them.
4.5. Interfaces:
This library works on top of the C-level API library, libpq.
You will
need libpq in order to use libpqxx.
The library libpqxx is installed in:
/usr/postgres/8.3/lib/libpqxx.so
and the header files in the directory:
/usr/postgres/8.3/include/pqxx/
Here is a list of all libpqxx modules:
* String conversion
* Utility functions
* String escaping
* Connection classes
* Error/warning output
* Transaction classes
* Exception classes
* Transactor framework
* Notifications and Triggers
See the libpqxx Documentation:
http://pqxx.org/devprojects/libpqxx/doc/2.6.9/html/Reference/
4.12. Dependencies:
/usr/postgres/8.3/lib/libpq.so
/usr/postgres/8.3/include/libpq-fe.h
5. Reference Documents:
http://pqxx.org/devprojects/libpqxx/doc/2.6.9/html/
6. Resources and Schedule:
6.1. Projected Availability:
Q4FY08
6.4. Product Approval Committee requested information:
6.4.1. Consolidation or Component Name:
SFWNV
6.5. ARC review type:
FastTrack
6.6. ARC Exposure:
open
