PostgreSQL ODBC Driver on Debian
================================

This package contains the PostgreSQL ODBC driver.  Applications wishing
to make use of it need to go through an ODBC driver manager.  On Debian,
this normally means that they have a dependency on the package
"libiodbc2" or "unixodbc".


ANSI vs. Unicode
----------------

This package actually contains two drivers, one ANSI variant (psqlodbca)
and one Unicode variant (psqlodbcw).  The Unicode variant works with
Unicode and ASCII clients, the ANSI variant should work with any client
encoding provided that the database encoding matches.  The specifics
depend on the application and the driver manager; experimentation may be
necessary in some cases.


Registering the Driver
----------------------

To register the PostgreSQL ODBC drivers in /etc/odbcinst.ini, run the
following command as root:

# odbcinst -i -d -f /usr/share/psqlodbc/odbcinst.ini.template

You can also edit /etc/odbcinst.ini by hand, but the above command is
generally the safest and most convenient way if you don't have special
requirements.


Creating Data Sources
---------------------

To be able to access a particular database via ODBC you need to register
it as an ODBC data source.  Data sources are registered globally in
/etc/odbc.ini or for each user in ~/.odbc.ini.  An example entry is
included in this package.  You can install it like this:

$ cat /usr/share/doc/odbc-postgresql/examples/odbc.ini.template >> ~/.odbc.ini

This entry will give you read-only access to the template1 database on
the PostgreSQL server on localhost under the data source name (DSN)
"PostgreSQL test".

You should edit ~/.odbc.ini or /etc/odbc.ini as required, to add extra
databases, change the read only status, and so on.  The program
ODBCConfig in the package unixodbc-bin can be used as a graphical
editing frontend.


Testing Connectivity
--------------------

To test the connectivity, you can use the program isql from the
package unixodbc:

$ isql 'PostgreSQL test' username

The first argument is the name of the data source, inserted above into
.odbc.ini.  If this command doesn't produce an error, you should be
able to enter SQL queries and see the results.  (Note that the example
data source is read-only and to template1, so you shouldn't issue
write commands.)

Alternatively, the program DataManager from the package unixodbc-bin can
be used to test the connectivity and browse the database.

At this point, you should be able to use the ODBC access features of any
application to connect to any of the listed data sources.  For example,
in the OpenOffice.org Base application's "Database Wizard", choose
"Connect to an existing database", "ODBC", press Next, choose "Browse",
then select your data source.


Accessing Schemas
-----------------

If you have schemas that are not in the default search path ($user,
public) you have to set the search path in the connection settings of
the odbc.ini file.  Here's an example, where the search path is set to
prod, public:

    [Production]
    Description         = Production control
    Driver              = PostgreSQL
    Trace               = No
    TraceFile           = /tmp/psqlodbc.log
    Database            = companydb
    Servername          = localhost
    UserName            = userme
    Password            =
    Port                =
    ReadOnly            = No
    RowVersioning       = Yes
    ShowSystemTables    = No
    ShowOidColumn       = No
    FakeOidIndex        = No
    ConnSettings        = SET search_path TO prod, public
