PostgreSQL Driver Reference

Understanding the SAS Federation Server Driver for PostgreSQL

The SAS Federation Server Driver for PostgreSQL(Driver for PostreSQL) enables SAS Federation Server to read and update legacy PostgreSQL tables. In addition, the driver creates PostgreSQL tables that can be accessed by both SAS Federation Server and the PostgreSQL data management system.
The Driver for PostgreSQL supports most of the FedSQL functionality. The driver also supports an application’s ability to submit native SQL statements.
The Driver for PostgreSQL is a remote driver, which means that it connects to a server process in order to access data. The process might be running on the same machine as SAS Federation Server, or it might be running on another machine in the network.

Connection Options for PostgreSQL

Overview

To access data that is hosted on SAS Federation Server, a client must submit a connection string, which defines how to connect to the data. The data service connection arguments for PostgreSQL include connection options and advanced options.

Connection Options

Connection options are used to establish a connection to a data source. Specify one or more connection options when defining a data service using the CREATE DATA SERVICE DDL statement.
The following connection options are supported for Postgres data sources.
Option
Description
CATALOG
CATALOG=catalog-identifier;
Specifies an arbitrary identifier for an SQL catalog, which groups schemas that are logically related. For example, catalog=ptgtest.
Note: SAS Federation Server automatically quotes SQL identifiers that do not meet the regular naming convention as defined in the SAS FedSQL Reference Guide.
CONOPTS
CONOPTS=(ODBC—compliant database connection string);
Specifies an ODBC-compliant database connection string using ODBC-style syntax. These options, combined with the ODBC_DSN option, must specify a complete connection string to the data source. If you include a DSN= or FILEDSN= specification within the CONOPTS= option, do not use the ODBC_DSN= connection option. However, you can specify the ODBC database-specific connection options by using CONOPTS=. Then you can specify an ODBC DSN that contains other connection information by using the ODBC_DSN= connection option.
Here is an example string using the CONOPTS option: DRIVER=ODBC;CONOPTS=(DRIVER={DataFlux 32-bit SQL Server Wire Protocol};SERVER=myserver;APP=Microsoft ODBC SDK;DATABASE=mydb)
This example uses the ODBC_DSN option with the CONOPTS option: DRIVER=ODBC;ODBC_DSN=mydsn;CONOPTS=(DATABASE=mydb)
DRIVER
DRIVER=postgres;
Specifies the data service for the PostgreSQL database to which you want to connect..
Note: DRIVER is a required option. You must specify a driver.
DATABASE
DATABASE=database-name;
Specifies the name of the PostgreSQL database. Enclose the database name in single quotation marks if it contains spaces or non-alphanumeric characters. You can also specify DATABASE= with the DB= alias.database=sample, DB=sample.
DSN
DSN=data-source-identifier;
Specifies the data source name to which you want to connect.
PASSWORD
PWD=password;
Specifies the password associated with the user ID. Enclose password in single quotation marks if it contains spaces or nonalphanumeric characters. You can also specify PASSWORD= with the PWD=, PASS=, and PW= aliases.
PORT
PORT=port_number
Specifies the port number that is used to connect to the specified PostgreSQL Server. If you do not specify a port, the default is 5432.
SERVER
SERVER=‘server-name’
Specifies the server name or IP address of the PostgreSQL server to which you want to connect. Enclose the server name in single quotation marks if the name contains spaces or non-alphanumeric characters: SERVER=’server name’.
USER
USER=user-name
Specifies the PostgreSQL user name (also called the user ID) that you use to connect to your database. If the user name contains spaces or non-alphanumeric characters, you must enclose it in quotation marks.

Advanced Options

The following advanced options are supported for PostgreSQL data sources.
Option
Description
ALLOW UNQUOTED NAMES
ALLOW_UNQUOTED_NAMES=NO|YES
Specifies whether to enclose table and column names in quotation marks. Tables and columns are quoted when this option is set at NO. If set to YES, the driver does not automatically add quotation marks to table and column names if they are not specified. This allows PostgreSQL tables and columns to be created in the default lower case. The default option is NO.
CLIENT ENCODING
CLIENT_ENCODING=cei
Used to specify encoding for the client.
CT_PRESERVE
CT_PRESERVE=STRICT | SAFE | FORCE | FORCE_COL_SIZE
Allows users to control how data types are mapped. Note that data type mapping is disabled when CT_PRESERVE is set to STRICT. If the requested type does not exist on the target database, an error is returned. The options are as follows:
  • STRICT The requested type must exist in the target database. No type promotion occurs. If the type does not exist, an error is returned.
  • SAFE Target data types are upscaled only if they do not result in a loss of precision or scale. When character encodings are changed, the new column size is recalculated to ensure all characters can be stored in the new encoding.
  • FORCE This is the default for all drivers. The best corresponding target data type is chosen, even if it could potentially result in a loss of precision or scale. When character encodings are changed, the new column size is recalculated to ensure all characters can be stored in the new encoding.
  • FORCE_COL_SIZE This option is the same as FORCE, except that the column size for the new encoding is the same as the original encoding. This option can be used to avoid column size creep. However, the resulting column might be too large or too small for the target data.
DEFAULT_ATTR
DEFAULT_ATTR=(attr=value;...)
Used to specify connection handle or statement handle attributes supported for initial connect-time configuration, where attr=value corresponds to any of the following options:
  • CURSORS=n- Connection handle option. This option controls the driver’s use of client side result set cursors. The possible values are 0, 1 or 2.
    0 Causes the driver to use client-side static cursor emulation if a scrollable cursor is requested but the database server cannot provide one.
    1 Causes the driver to always use client-side static cursor emulation if a scrollable cursor is requested. The database server’s native cursor is not used.
    2 (Default) Causes the driver to never use client-side static cursor emulation if a scrollable cursor is requested. The database server’s native cursor is used if available. Otherwise, the cursor will be forward-only.
    Example: DEFAULT_ATTR=(CURSORS=2)
  • USE_EVP=n - Statement handle option. This option optimizes the driver for large result sets. The possible values are 0 (OFF) or 1 (ON), which is the default. Example: DEFAULT_ATTR=(USE_EVP=0)
  • XCODE_WARN=n - Statement handle option. Used to warn on character transcoding errors that occur during row input or output operations. Possible values are 0 (returns an error), 1 (returns a warning), or 2 (ignore transaction errors). 0 is the default. Example: DEFAULT_ATTR=(XCODE_WARN=1)
DRIVER TRACE
DRIVER_TRACE=’API | SQL | ALL’;
Requests tracing information, which logs transaction records to an external file that can be used for debugging purposes. The SAS Federation Server driver writes a record of each command that is sent to the database to the trace log based on the specified tracing level, which determines the type of tracing information. The tracing levels are:
  • ALL Activates all trace levels.
  • API Specifies that API method calls be sent to the trace log. This option is most useful if you are having a problem and need to send a trace log to Technical Support for troubleshooting.
  • DRIVER Specifies that driver-specific information be sent to the trace log.
  • SQL Specifies that SQL statements that are sent to the database management system (DBMS) be sent to the trace log. Tracing information is DBMS specific, but most SAS Federation Server drivers log SQL statements such as SELECT and COMMIT.
Default: Tracing is not activated.
Note: If you activate tracing, you must also specify the location of the trace log with DRIVER_TRACEFILE=. Note that DRIVER_TRACEFILE= is resolved against the TRACEFILEPATH set in ALTER SERVER. TRACEFILEPATH is relative to the server's content root location.
(Optional) You can control trace log formatting with DRIVER_TRACEOPTIONS=.
Interaction: You can specify one trace level, or you can concatenate more than one by including the | (OR) symbol. For example: driver_trace='api|sql' generates tracing information for API calls and SQL statements.
DRIVER TRACE FILE
DRIVER_TRACEFILE=’filename’;
Used to specify the name of the text file for the trace log. Include the filename and extension in single or double quotation marks. For example: driver_tracefile='\mytrace.log'
Default: The default TRACEFILE location applies to a relative filename, and it is placed relative to TRACEFILEPATH.
Requirement: DRIVER_TRACEFILE is required when activating tracing using DRIVER_TRACE.
Interaction: (Optional) You can control trace log formatting with DRIVER_TRACEOPTIONS=.
DRIVER TRACE OPTIONS
DRIVER_TRACEOPTIONS=APPEND | THREADSTAMP | TIMESTAMP;
Specifies options in order to control formatting and other properties for the trace log:
  • APPEND Adds trace information to the end of an existing trace log. The contents of the file are not overwritten.
  • THREADSTAMP Prepends each line of the trace log with a thread identification.
  • TIMESTAMP Prepends each line of the trace log with a time stamp.
Default: The trace log is overwritten with no thread identification or time stamp.
MAX_BINARY_LEN
MAX_BINARY_LEN=value;
Specifies a value, in bytes, that limits the length of long binary fields (LONG VARBINARY). Unlike other databases, PostgreSQL does not have a size limit for long binary fields. The default is 1048576.
MAX_CHAR_LEN
MAX_CHAR_LEN=value;
Specifies a value that limits the length of character fields (CHAR and VARCHAR). The default is 2000.
MAX_TEXT_LEN
MAX_TEXT_LEN=value;
Specifies a value that limits the length of long character fields (LONG VARCHAR). The default is 409500.
SCHEMA
SCHEMA=value;
Specifies the default schema for the connection. If not specified, the schema, or list of schemas, is determined based on the value of the schema search path defined on the database server.
STRIP_BLANKS
STRIP_BLANKS=YES|NO;
Specifies whether to strip blanks from character fields.
Copyright © SAS Institute Inc. All rights reserved.