5. Customizing the pgExpress Driver

5.1. Driver Parameters

This is a list of the standard Driver Parameters supported by the pgExpress Driver (please check your Delphi help on Driver Parameters for more information on each of them).

Table 2.2. Driver Parameters

ParameterObs.
DriverName 
Database Used also to provide Special Params to the pgExpress Driver. This parameter can also be used as an URL for providing extra host and port info:
host:port/database
Please check the Installation section for more details.
User_Name
Password See also the Authentication section.
BlobSize This parameter is actually ignored, since PostgreSQL can report the exact Blob field size.
LocaleCode See also the Multibyte, UNICODE and Locales section.
RowsetSize Only works if the BlockRead param is True.
HostName Name can instead be specified as a member of the Database paramater.
RoleName Will set a PostgreSQL7.3+ schema (namespace) to log in. Please check here for more details. Multiple Schemas can be specified (just as in PostgreSQL) if separated by collons, such as:
RoleName = public,schema1,schema2
ServerCharset See also Multibyte, UNICODE and Locales.
Custom String This param allows to supply Special Params through a way other then the traditional, i.e. after the Database. D7+ only.
ServerPort

Allows setting the port to connect to. D7+ only.

Can instead be specified as a member of the Database paramater.

ConnectionTimeout The ConnectionTimeoutSpecial Param can be used on Delphi 6/7 too, or Kylix. D7+ only.
BlockingMode If False, asynchronous connections will be used to connect to the server.
Decimal Separator Same as ServerDecimalSeparator, but since BDS 2006, it is also supported as a regular dbExpress parameter. It will not work with applications built with older IDEs.
ConnectionString dbExpress applications (BDS 2006+), support a custom connection string, that will be passed directly to the PQconnectdb() function, and thus supporting anything that function supports. You can use that parameter instead of Database parameter, User_Name parameter, etc. Syntax will be the same as of the conninfo parameter of the PQconnectdb() function.
ErrorResourceFile Allows to set the language resource file for the driver. Please refer to Multilanguage Driver section for more details.

Notes:

The behavior for this parameter has changed on pgExpress v3.0. To get the same behavior as the v2.X series, check the Language.

Trim Char When True, trailing space chars CHAR fields will be trimmed. VCL/CLX default is False.

5.2. Special Params

The pgExpress Driver has a few special parameters that can be used to customize its behaviors; we refer to them as "Special Params". Default values are formatted like this.

IMPORTANT:

To set a special param, add it in your dbxconnections(.ini) file after the database parameter, such as:

          [PGEConnection]
          Database=localhost/template1,TextAsMemo=False,ByteaMode=asVarBytes
          ...
        

Table 2.3. Special Params

Key Values Meaning
TextAsMemo
True
False
If True, the PostgreSQL TEXT fields will be mapped as Blob (Memo); if False (default), it will be mapped as String. A VARCHAR field with no length specifier behaves exactly like a TEXT field.

Obs:

If mapped as string, a TEXT field will be padded at the maximum string length imposed by dbExpress (~32Kb).
NumericAsBcd
True
False
This special param has been deprecated and will be ignored as of pgExpress 4.0. Please refer to BorlandCompatible for a better solution.
MapUnknownAsString
True
False
If True, unknown/unsupported field types such as point will be mapped as strings.
ArrayAsString
True
False
If True, arrays will be mapped as strings. If False, they will be ignored (hidden).
ByteaMode
AsGraphic
AsBlob
AsVarBytes
This parameter controls to which type the bytea fields get mapped. Check Bytea fields as BLOBs for more details. For compatibility with pre-v3.50 behavior(TVarBytesField, set this to asVarBytes. New in version v3.50.
Int8Mode
AsInt8
AsBcd
AsString
AsInt4
Ignore
AsInt8
The field will be mapped as Int8 using a hack (default).
AsBcd
The field will be mapped as TFMTBcdField.

Note

This is the pgExpress Driver1.X default setting, but is deprecated now (except in this situation).
AsString
The field will be mapped as string
AsInt4
The field will be mapped as Int4. Values are calculated using the following formula:
Int4Value := Int8Value mod High(Int4))
Ignore
The Int8 field will be ignored (hidden).

Notes:

  • Usage of this special parameter is DEPRECATED due to the introduction of the new default parameter AsInt8, which eliminates the Int8 typecasting need, except in this situation.
  • Please check Native Int8 support for more details.
  • On protocol 3.0+ drivers, this parameter will be ignored, since they can map to int8 field natively.
QuoteObjects
True
False
If True, quote objects names. To this setting to take effect, the connection must be reopened (if already opened of course). An example of unquoted and quoted query:

Example 2.1. Quoted and unquoted queries

select typname from pg_type; -- unquoted version
select "typname" from "pg_type"; -- quoted version

Please note that quoted objects names are case sensitive for PostgreSQL. The query above written like this would fail:

db =# select "typname" from "Pg_type";
ERROR: Relation "Pg_type" does not exist
                
TypesCachingMode
Default
Once
Connection
Cursor
This setting will control how often the types from PostgreSQL will be loaded and mapped into VCL/CLX types. Of course the less times they are loaded, the faster the application will be. The default setting should be OK for most applications (unless you do types manipulation).
Default
Currently, the same as "Once"
Driver
Types will be mapped only once and cached for later use.
Connection
Types will be remapped for each connection open.
Cursor
Types will be remapped for each new Dataset retrieved from the server.

Obs:

The PostgreSQL database has a flexible types support; that means we must retrieve the types information before we know what each type name means. This information is retrieved from the pg_type catalog and then mapped into actual dbExpress/VCL types by the pgExpress driver. Please refer to your PostgreSQL documentation for more details.
GetExtendedFieldsInformation
True
False
If True, will retrieve extra information about the fields in a table (for single table queries). That will allow the pgExpress Driver to determine if a field can be null (ISQLCursor.IsNullable()) or are automatically generated by a sequence the server (ISQLCursor.IsAutoIncrement()). Few applications should need this setting and they can be manually added to the TFields list representing each physical field. Since this will add a new query overhead for each cursor (TDataset) retrieved, slowing down the operation, it's adviced not to use it unless you need the information (for instance, on situations where you don't know the structure of the table that is going to be open).
ServerDecimalSeparator(char)

The pgExpress Driver should automatically detect your locale settings and use the appropriate decimal separator. However, if you want to force some specific value, this options is available. Set it to the char you want to be the decimal separator (usually either "." or ",").

However, since the "," is the options separator, you'll need to escape that char, like this:

ServerDecimalSeparator = \,

Another exemple:

ServerDecimalSeparator = .

See also ServerDecimalSeparator.

BlockRead
True
False

If True, the pgExpress Driver will use Fetch Cursors to retrieve the records from the server. The standard RowsetSize param (check your Kylix/ Delphi documentation) will determine the number of rows retrieved on each operation.

It is required to use this parameter to read the records in blocks since the pgExpress Driver will have to use a totally different method to retrieve the records from the server. Please refer to the section for more details.

UseQualifiedNames
True
False

If True, the pgExpress Driver will return qualified names on metadata retrieving, such as public.MyTable, pg_catalog.abstime, etc.

This option will only work PostgreSQL 7.3 which supports schemas.

RestrictedNameSpace
True
False
Controls which metadata is retrieved. If True, only objects in the current namespace search path will be retrieved. If False, all objects will be retrieved, regardless of which namespace they are in.
RequireSSL
True
False
If True, will only make a connection to the server in SSL mode. This option will only work with a SSL enabled libpq (currently only under Linux).
ShowOID
True
False

If True, the pgExpress Driver will return the OID field in the list of fields for a table (ISQLConnection.getColumns()).

See also this FAQ entry on OIDs usage with pgExpress.

ConnectionTimeoutX Allows to specify connection timeouts (X in seconds). It needs libpq v7.3 or above (included with pgExpress Driver). This parameter is an integer value.
AutoRecover
True
False
If True, the pgExpress Driver will automatically try to detect if the connection has been broken and recover it automatically and continue processing. If it is sucessful, the whole operation is fully transparent to the user. If not, an appropriate error message will be displayed.

Note

This feature is avaiable only on the registered version of the driver.
RetainCursor
True
False

Controls the Retaining Cursors behavior.

If True, the pgExpress Driver will retain the cursor for the previous SELECT statement and return it if a previous dataset record is acessed again, instead of running the whole query again (dbExpress behavior). No matter how many times the same query is run again, always the same result set is returned (from the internal cache).

Note

This setting will be ignored if Fetch Cursors are being used.
BlobWriting
True
False
If True, the pgExpress Driver will allow Blob (Large Objects) writes. Blob writing is a delicate issue; just activate this setting if you read Section 6.7.1, “Large Objects (BLOBs)”. Registered users only.
LogDeclareFetch
True
False

If True, the pgExpress Driver will log (into TSQLMonitor) the DECLARE/FETCH commands executed internally as it requests rows from the server. The reason for this special param is that those commands could fill the logs with information not necessary to everybody; you can filter them setting it to False.

An example of unfiltered output (LogDeclareFetch=False):

Starting transaction for DECLARE/FETCH
Starting transaction
>> BEGIN;
>> DECLARE pgeCursor CURSOR for select * from pg_type;
>> FETCH 50 FROM pgeCursor
>> FETCH 50 FROM pgeCursor
>> FETCH 50 FROM pgeCursor
>> FETCH 50 FROM pgeCursor
>> FETCH 50 FROM pgeCursor
Closing cursor pgeCursor
>> CLOSE pgeCursor
Ending DECLARE/FETCH transaction
Rolling back transaction
>> ROLLBACK;

The same operation, but filtered (LogDeclareFetch=True):

>> BEGIN;
Rolling back transaction
>> ROLLBACK;

For more info on DECLARE/FETCH cursors, check Section 6.2, “Fetch Cursors”.

Registered users only since depends on Section 6.2, “Fetch Cursors”
Language (none) If empty, the pgExpress Driver will assume the language to be used is English. Otherwise, it is one of the entries of the Supported languages table table.
Borland Compatible False If True, the pgExpress Driver will try to be more compatible with the behavior of Codegear dbExpress drivers, mapping NUMERIC values like Codegear does.
UnicodeAsWideChar False If True, the pgExpress Driver will map string (CHAR, VARCHAR, TEXT) fields as TWideString, when using UNICODE client charset.

Note

This parameter is only meaningful for dbExpress protocol 3.0 and later applications, whose can map to TWideString.

DBX4Compatible (auto) If True, the pgExpress Driver will get into dbExpress 4 compatibility mode. Among other things, NUMERIC/DECIMAL fields will be mapped as TBcdField instead of TFMTBcdField. Please read ??? for further information.

Note

This parameter is only meaningful for dbExpress protocol 3.0 and later applications, running under dbExpress 4.


On older pgExpress Driver versions, these parameters used go into the dbxdrivers(.ini) file. But since version 1.5, they go after the Database parameter in the dbxconnections(.ini) parameter, separated by commas. On Delphi 7 or later, they can also go on the Custom String parameter.

Example 2.2. Special Parameters usage

[OfficeServer]
Database = sales,TextAsMemo = False, Int8Mode = AsString

[PGEConnection]
Database = sales, ArrayAsString = False, QuoteObjects = True, GetExtendedFieldsInformation = False

On Delphi 7, using the new Custom String section (works the same way as above, but this section was made for using with special params):

Example 2.3. Special parameters usage with the Custom String param

[PGEConnection]
Database = sales
Custom String = ArrayAsString = False, QuoteObjects = True, GetExtendedFieldsInformation = False

If you don't want to use any special parameters (as most users will), specify the Database parameter alone, normally:

[OfficeServer]
Database = sales

Of course these parameters could also go in the TSQLConnections. Params property as any other dbxconnections(.ini) parameter:

SQLConnection1.Params.Add('Database = sales,TextAsMemo = False,Int8Mode = AsString');

Or on Delphi 7, using the new Custom String section:

SQLConnection1.Params.Add('Custom String = ArrayAsString = False, QuoteObjects = True, GetExtendedFieldsInformation = False ');

Unhappily, due to the way dbExpress was designed on Delphi 6 and Kylix 1/2/3 , there can't be real custom parameters from VCL/CLX to the driver, so misusing the Database parameter was a hack that we had to do to allow custom params. Even on Delphi 7 only a single Custom parameter (Custom String) can be specified.

5.3. Custom Info

"Custom Info" are methods that can be used to retrieve information from the driver that otherwise could not be retrieved. They will only work with Delphi 7 or newer which implements the eConnCustomInfo interface.

For easy implementation of these interfaces, please use the corresponding functions from the pgeDriverUtils.pas unit.

Table 2.4. Custom Info Interfaces

InformationMeaningFunction
GetPGVersion Returns the PostgreSQL server version as a float. GetPGVersion
TTY Allows setting or retrieving file or TTY for optional debug output from the backend server. Set before connecting. GetTTY
BackendPID Will retrieve the PID of the process of the connection in the backend server.GetBackendPID
Online Will return True if a connection to the server exists. This implements the eCommOnline interface. GetOnline