Adding Connections
You can add connections in several ways in Visual Studio:
Adding Connections in Server Explorer
1
Right-click the Data Connections node in the Server Explorer and select Add Connection.
The Add Connection window appears.
2
If the PSQL data provider is displayed in the Data source field, skip to Step 4. Otherwise, click Change.
3
a.
In the Data source list box, select Pervasive PSQL Database.
b.
In the Data provider list, select ADO.NET Pervasive PSQL Provider.
c.
d.
Click OK to return to the Add Connection window.
4
a.
b.
c.
d.
5
Click the Advanced button to specify additional provider-specific property values.
To change a value in the Advanced Properties dialog box, select or type the new value into the field and press ENTER. The value is added to the connection string that appears in the field below the description of the property. If you accept the default values, the connection string field remains unchanged. When you have made the necessary changes, click OK to return to the Add Connection window.
Advanced
EnableIPv6: Provides backward compatibility for connecting to the PSQL Server using an IPv4 address.
If set to True, a client with IPv6 protocol installed can connect to the server using either an IPv4 address or an IPv6 address.
If set to False, the clients run in the backward compatibility mode. The client always connects to the server using an IPv4 address.
The default value for 4.0 is set to True.
For more information about IPv6 formats, see IPv6 in Getting Started with PSQL.
Encoding: Type the ANSI name or Windows code page to be used for translating string data stored in the database. By default, the Windows code page is used.
Initial Command Timeout: Specifies the default wait time (timeout in seconds) before the data provider terminates the attempt to execute the command and generates an error. This option provides the same functionality as the PsqlCommand object’s CommandTimeout property without the need to make changes to the application code. Subsequently, an application can use the CommandTimeout property to override the Initial Command Timeout connection string option.
The initial default value is 30 seconds.
NOTE: Set the Initial Command Timeout option to a value that is greater than the largest default deadlock detection and timeout value on the server. This ensures that the application receives a more meaningful reply in case of a timeout.
Initialization String: Type one statement that will be issued immediately after connecting to the database to manage session settings.
Example: To handle CHAR columns that are padded with NULLs, set the value to:
Initialization String=SET ANSI PADDING ON
NOTE: If the statement fails to execute for any reason, the connection to the server fails. The data provider throws an exception that contains the errors returned from the server.
Parameter Mode: Select the behavior of native parameter markers and binding. This allows applications to reuse provider-specific SQL code and simplifies migration to the PSQL data provider. Note that this option does not apply to the ADO.NET Entity Framework data provider.
If set to ANSI (the default), the ? character is processed as a parameter marker and bound as ordinal.
If set to BindByOrdinal, native parameter markers are used and are bound as ordinal.
If set to BindByName, native parameter markers are used and are bound by name.
PVTranslate: Select whether the client should negotiate a compatible encoding with the server.
If set to Auto (the default for the 4.2 provider), the data provider will set the Encoding connection property to the database code page. In addition, SQL query text will be sent to the engine using UTF-8 encoding instead of the data encoding. This preserves NCHAR string literals in the query text.
If set to Nothing (the default for the 4.0 provider), the setting for the Encoding connection property is used.
Timestamp: Select whether PSQL timestamps are stored and retrieved as strings.
If set to DateTime (the initial default), the data provider maps timestamps to DateTime. This setting may be appropriate when native precision is required, for example, when using the CommandBuilder with timestamp.
If set to String, the data provider maps PSQL timestamps as strings.
TimeType: Select whether PSQL times are retrieved as Timespan or DateTime in the ADO.NET data provider.
If set to As DateTime, the data provider maps the SQL type TIME to the .NET type System.DateTime.
If set to As TimeSpan, the data provider maps the SQL type TIME to the .NET type System.DateTimespan.
Connection Pooling
Connection Reset: Select whether a connection that is removed from the connection pool for reuse by an application will have its state reset to the initial configuration settings of the connection.
If set to False (the initial default), the data provider does not reset the state of the connection.
Connection Pool Behavior: Select the order in which a connection is removed from the connection pool for reuse, based on how frequently or how recently the connection has been used.
If set to MostRecentlyUsed, the data provider uses a Last In First Out (LIFO) approach to return the connection that was returned to the pool most recently.
If set to LeastRecentlyUsed, the data provider uses a First In First Out (FIFO) approach to return the connection with the lowest use count. This value ensures a balanced use of connections in the pool.
If set to MostFrequentlyUsed, the data provider returns the connection with the highest use count. This value enables applications to give preference to the most seasoned connection.
If set to LeastFrequentlyUsed, the data provider returns the connection with the lowest use count. This value ensures a balanced use of connections in the pool.
Connection Timeout: Type the number of seconds after which the attempted connection to the server will fail if not yet connected. If connection failover is enabled, this option applies to each connection attempt.
If set to 0, the data provider never times out on a connection attempt.
The initial default is 15 seconds.
Load Balance Timeout: Type the number of seconds to keep connections in a connection pool. The pool manager periodically checks all pools, and closes and removes any connection that exceeds this value. The Min Pool Size option can cause some connections to ignore the value specified for the Load Balance Timeout option.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), the connections have the maximum timeout.
See Removing Connections from a Pool for a discussion of connection lifetimes.
Max Pool Size: Type the maximum number of connections within a single pool. When the maximum number is reached, no additional connections can be added to the connection pool.
The value can be any integer from 1 to 65535.
The initial default is 100.
Max Pool Size Behavior: Select whether the data provider can exceed the number of connections specified by the Max Pool Size option when all connections in the connection pool are in use.
If set to SoftCap, when all connections are in use and another connection is requested, a new connection is created, even when the connection pool exceeds the number set by the MaxPoolSize option. If a connection is returned and the pool is full of idle connections, the pooling mechanism selects a connection to be discarded so the connection pool never exceeds the Max Pool Size.
If set to HardCap, when the maximum number of connections allowed in the pool are in use, any new connection requests wait for an available connection until the Connection Timeout is reached.
Min Pool Size: Type the minimum number of connections that are opened and placed in a connection pool when it is created. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), no additional connections are placed in the connection pool when it is created.
Pooling: Select True (the initial default) to enable connection pooling.
Failover
Alternate Servers: Type a list of alternate database servers to which the data provider will try to connect if the primary database server is unavailable. Specifying a value for this property enables connection failover for the data provider.
For example, the following Alternate Servers value defines two alternate servers for connection failover:
Alternate Servers="Host=AcctServer;Port=1584,
Host=123.456.78.90;Port=1584"
Connection Retry Count: Type the number of times the data provider tries to connect to the primary server, and, if specified, the alternate servers after the initial unsuccessful attempt.
The value can be any integer from 0 to 65535.
If set to 0 (the initial default), there is no limit to the number of attempts to reconnect.
Connection Retry Delay: Type the number of seconds the data provider waits after the initial unsuccessful connection attempt before retrying a connection to the primary server, and, if specified, the alternate servers.
The initial default is 3.
This property has no effect unless the Connection Retry Count property is set to an integer value greater than 0.
Load Balancing: Select True or False to determine whether the data provider uses client load balancing in its attempts to connect to primary and alternate database servers.
If set to False (the initial default), the data provider does not use client load balancing.
Performance
Enlist: Select True or False to determine whether the data provider automatically attempts to enlist the connection in creating the thread’s current transaction context.
NOTE: Because PSQL does not support distributed transactions, any attempt to enlist the connection in the thread’s current transaction context will fail.
If set to False (the initial default), the data provider does not automatically attempt to enlist the connection.
If set to True, the data provider returns an error on the connection if a current transaction context exists. If a current transaction context does not exist, the data provider raises a warning.
Max Statement Cache Size: Type the maximum number of statements generated by the application that can be held in the statement cache for this connection.
The value can be 0, or any integer greater than 1.
If set to 0, statement caching is disabled.
If set to an integer greater than 1, the value determines the number of statements that can be held in the statement cache.
The initial default is 10.
Statement Cache Mode: Select the statement caching mode for the lifetime of the connection. See Using Statement Caching for more information.
If set to Auto, statement caching is enabled. Statements marked as Implicit by the Command property StatementCacheBehavior are cached. These commands have a lower priority than that of explicitly marked commands, that is, if the statement pool reaches its maximum number of statements, the statements marked implicit are removed from the statement pool first to make room for statements marked Cache.
If set to ExplicitOnly (the initial default), only commands that are marked Cache by the StatementCacheBehavior property are cached. Note that this is the only valid value for the ADO.NET Entity Framework data provider.
Schema Information
Schema Collection Timeout: Type the number of seconds after which an attempted schema collection operation fails if it is not yet completed.
The initial default is 120.
Schema Options: Specifies additional database metadata that can be returned. By default, the data provider prevents the return of some performance-expensive database metadata to optimize performance. If your application needs this database metadata, specify the name or hexadecimal value of the metadata.
This option can affect performance.
If set to ShowColumnDefaults or 0x04, column defaults are returned.
If set to ShowParameterDefaults or 0x08, column defaults are returned.
If set to FixProcedureParamDirection or 0x10, procedure definitions are returned.
If set to ShowProcedureDefinitions or 0x20, procedure definitions are returned.
If set to ShowViewDefinitions or 0x40, view definitions are returned.
If set to ShowAll or 0xFFFFFFFF, all database metadata is returned.
For example, to return descriptions of procedure definitions, specify Schema Options=ShowProcedureDefinitions or Schema Options=0x20.
To show more than one piece of the omitted database metadata, specify either a comma-separated list of the names, or the sum of the hexadecimal values of the column collections that you want to restrict.
See Table 28 for the name and hexadecimal value of the database metadata that the data provider can add.
Use Current Schema: This connection string option is not supported. Setting it will cause the data provider to throw an exception.
Security
Encrypt: Select whether the data provider uses Encrypted Network Communications, also known as wire encryption.
If set to IfNeeded (the initial default), the data provider reflects the server's setting.
If set to Always, the data provider uses encryption, or, if the server does not allow wire encryption, returns an error.
If set to Never, the data provider does not use encryption and returns an error if wire encryption is required by the server.
Encryption: Select the minimum level of encryption allowed by the data provider. The meaning of these values depends on the encryption module used. With the default encryption module, the values Low, Medium, and High correspond to 40-, 56-, and 128-bit encryption, respectively.
The initial default is Medium.
Password: Type a case-insensitive password used to connect to your PSQL database. A password is required only if security is enabled on your database. If so, contact your system administrator to get your password.
Persist Security Info: Select whether to display secure information in clear text in the ConnectionString property.
If set to True, the value of the Password connection string option is displayed in clear text.
If set to False (the initial default), the data provider does not display secure information in clear text.
User ID: Type the default PSQL user name used to connect to your PSQL database.
Standard Connection
Database Name: Type a string that identifies the internal name of the database to which you want to connect.
If you enter a value for this field, the Server DSN field is not available.
Host: Type the name or the IP address of the PSQL server to which you want to connect. For example, you can specify a server name such as accountingserver. Or, you can specify an IPv4 address such as 199.262.22.34 or an IPv6 address such as 2001:DB8:0000:0000:8:800:200C:417A.
Port: Type the TCP port number of the listener running on the PSQL database.
The default port number is 1583.
Server DSN: The name of the data source on the server, such as DEMODATA.
If you enter a value for this field, the Database Name field is not available.
Tracing
Enable Trace: Type a value of 1 or higher to enable tracing. If set to 0 (the initial default), tracing is not enabled.
Trace File: Type the path and name of the trace file. If the specified trace file does not exist, the data provider creates it. The initial default is an empty string.
6
Click Test Connection. At any point during the configuration process, you can click Test Connection to attempt to connect to the data source using the connection properties specified in the Add Connection window.
Click OK.
NOTE: If you are configuring alternate servers for use with the connection failover feature, be aware that the Test Connection button tests only the primary server, not the alternate servers.
7
Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.
Adding Connections with the Data Source Configuration Wizard
You can add a new connection to your application using the Data Configuration Wizard.
1
In the Data Sources window in Visual Studio, select Add New Data Source. To open the Data Sources window, select View from the main menu and then select Other Windows > Data Sources.
The Data Source Configuration Wizard appears.
2
Select Database and then click Next. The Choose Your Data Connection window appears.
3
Click New Connection The Add Connection window is displayed. Continue from Step in Adding Connections in Server Explorer.