Connection string|V1.3.1|OceanBase Connector/NET|docs|OceanBase Documentations

OceanBase Connector/NET supports connecting to OceanBase Database in Oracle-compatible mode and MySQL-compatible mode. The connection methods are as follows:

MySQL-compatible mode: The connection method is the same as that of MySqlConnector, using the standard MySQL connection string format and parameters.
Oracle-compatible mode: Uses Oracle-compatible APIs, with a connection string format similar to Oracle ODP.NET.

MySQL-compatible mode

When connecting to OceanBase Database in MySQL-compatible mode, use the same connection string format and parameters as MySqlConnector, for example:

Server=host;Port=port;Database=database_name;Uid=username@tenant_name#cluster_name;Pwd=password;

Note

When connecting through ODP, the user identifier is typically in a three-part format: username@tenant_name#cluster_name (corresponding to Uid in MySQL-compatible mode). Some cloud scenarios also support abbreviated formats like one-part; please refer to the actual environment. Replace tenant_name and cluster_name with the actual tenant name and cluster name.

Oracle-compatible mode

Basic format

Data Source=host:port;User Id=username@tenant_name#cluster_name;Password=password;Database=schema_name;

Note

Data Source currently only supports host or host:port; appending /servicename after it is not supported. If needed, specify the service name separately through other parameters in the connection string.

The port for direct connection to an OBServer node is usually 2881, and through ODP, it is usually 2883. Please refer to the actual environment.

The User Id in the connection string is typically in a three-part format when connecting through ODP: username@tenant_name#cluster_name (can be written as Username@TenantName#ClusterName in English). Some cloud scenarios also support abbreviated formats like one-part; please refer to the actual environment. Replace username, tenant_name, and cluster_name in the example with actual values.

Main parameters

Parameter	Description
Data Source	Data source address. Only `host` or `host:port` is supported. `host:port/servicename` is not supported.
User Id	User identifier. When connecting through ODP, it is typically in the three-part format: `username@tenant name#cluster name`, which matches the `User Id` in the connection string. Some cloud-based scenarios support abbreviated formats such as the one-part format.
Password	The database password.
Database	Required. In Oracle-compatible mode, it must be set to the schema name; otherwise, Open will throw a ArgumentException.
UseLobLocatorV2	Controls whether to enable the LOB locator feature. The default value is true.

Note

This page is the main document for connection parameters. For an overview of interface capabilities, refer to Overview of common interfaces. The driver is developed based on MySqlConnector, and the connection parameters are consistent with those of MySqlConnector. Default values for some parameters have been adjusted: ConnectionReset defaults to false; SslMode defaults to None.

Complete parameter list (by type)

Connection

Parameter name (commonly used)	Type	Default Value	Description
Server / Host / Data Source	string	`""`	Server address. Multiple host addresses can be specified, separated by commas.
Port	uint	`3306`	Port number.
User ID / UserID / Username / Uid	string	`""`	User identifier. In a multi-tenant scenario, it typically follows the three-part format `username@tenant_name#cluster_name` when passing through ODP. Some cloud-based scenarios support abbreviated formats such as the one-part format.
Password / Pwd	string	`""`	Password.
Database / Initial Catalog	string	`""`	Initial database (schema), required in Oracle-compatible mode.
Load Balance / LoadBalance	enum	`RoundRobin`	Multi-host load balancing strategy.
Connection Protocol / Protocol	enum	`Socket`	Connection protocol.
Pipe Name / PipeName	string	`"MYSQL"`	The name of the named pipe, which is valid only for the NamedPipe protocol.
Connection Timeout / Connect Timeout	uint	`15`	Connection timeout (seconds).
Interactive Session / Interactive	bool	`false`	Whether to enable interactive sessions.
Keep Alive / Keepalive	uint	`0`	TCP Keepalive Idle Time (seconds),`0`Indicates the system default.
Server Redirection Mode	enum	`Disabled`	Whether to enable server-side redirection.
Server RSA Public Key File	string	`""`	The path of the server-side RSA public key.
Server SPN	string	`""`	Server SPN.

TLS

Parameter name (commonly used)	Type	Default Value	Description
SSL Mode / SslMode	enum	`None`	SSL mode.
Certificate File	string	`""`	Client certificate file (`.pfx`).
Certificate Password	string	`""`	Certificate password.
Certificate Store Location	enum	`None`	The storage location of the certificate.
Certificate Thumbprint	string	`""`	Certificate fingerprint.
SSL Cert / SslCert	string	`""`	Path of the client's PEM certificate.
SSL Key / SslKey	string	`""`	Path to the client's PEM private key.
SSL CA / SslCa	string	`""`	Path of the CA certificate.
TLS Version / TlsVersion	string	`""`	The allowed TLS version.
TLS Cipher Suites	string	`""`	The allowed cipher suites.

Pooling

Parameter name (commonly used)	Type	Default Value	Description
Pooling	bool	`true`	Whether to enable the connection pool.
Connection Lifetime / ConnectionLifeTime	uint	`0`	Maximum Connection Lifetime (seconds).
Connection Reset / ConnectionReset	bool	`false`	Whether to reset the connection status when a connection is retrieved from the pool.
Connection Idle Timeout / ConnectionIdleTimeout	uint	`180`	Idle connection pool timeout (seconds).
Minimum Pool Size / Min Pool Size	uint	`0`	Minimum number of connections.
Maximum Pool Size / Max Pool Size	uint	`100`	Maximum number of connections.
DNS Check Interval / DnsCheckInterval	uint	`0`	The interval for DNS change checks, in seconds.

OceanBase

Parameter name (commonly used)	Type	Default Value	Description
Use LOB Locator V2 / UseLobLocatorV2	bool	`true`	Whether to enable OceanBase LOB Locator V2.
Use Array Binding / UseArrayBinding	bool	`false`	Whether to enable the ArrayBinding feature. Required in`OracleCommand.ArrayBindCount`Effective when greater than 0.
Auto Commit / AutoCommit	bool	`true`	Initial connection default values and the connection pool reset baseline. You can set these by using the`OracleConnection.AutoCommit`Modifies the value of the current session.
Auto Close Prepared Statements / AutoClosePreparedStatements	bool	`true`	Whether to automatically close prepared statements. When enabled, it prevents resource exhaustion caused by the accumulation of cursors under the PS protocol.

Note

ArrayBinding requires the current session to have autocommit=0. You can set the connection string AutoCommit to false, or set it at runtime with OracleConnection.AutoCommit = false. Simply calling BeginTransaction() does not replace this prerequisite. For details, see AutoCommit and Transactions and ArrayBinding.

Other

Parameter name (commonly used)	Type	Default Value	Description
Allow Load Local Infile	bool	`false`	Whether to Allow`LOAD DATA LOCAL`.
Allow Public Key Retrieval	bool	`false`	Whether to allow pulling the RSA public key from the server.
Allow User Variables	bool	`false`	Whether to allow user variables in SQL statements.
Allow Zero DateTime	bool	`false`	Whether to allow zero-value dates.
Application Name	string	`""`	Application name (connection attribute).
Auto Enlist / AutoEnlist	bool	`true`	Whether to automatically register with the`TransactionScope`.
Cancellation Timeout	int	`2`	Command cancellation timeout period (in seconds).
Convert Zero DateTime	bool	`false`	Whether to convert invalid dates to`DateTime.MinValue`.
DateTime Kind	enum	`Unspecified`	Deserialization`DateTimeKind`.
Default Command Timeout / Command Timeout	uint	`30`	Default command timeout (in seconds).
Force Synchronous	bool	`false`	Whether to force synchronous execution of asynchronous APIs.
GUID Format / GuidFormat	enum	`Default`	`Guid`The mapping format.
Ignore Command Transaction	bool	`false`	Whether to ignore the command transaction consistency check.
Ignore Prepare	bool	`false`	Whether to ignore`Prepare`Call.
No Backslash Escapes	bool	`false`	Whether to disable backslash escape.
Persist Security Info	bool	`false`	Whether to retain sensitive information after the connection is closed.
Pipelining	bool	`true`	Whether to enable pipelining.
Treat Tiny As Boolean	bool	`true`	`TINYINT(1)`Whether to treat as a boolean.
Use Affected Rows	bool	`false`	Whether to return the number of affected rows.
Use Compression / Compress	bool	`false`	Whether to compress network transmissions.
Use XA Transactions	bool	`true`	`TransactionScope`Specifies whether to use XA.
Character Set / CharSet / CharacterSet	string	Not set (UTF-8 in Oracle-compatible mode)	The character set for Oracle-compatible mode sessions. Starting from V1.3.0, it can be set to`gbk`, used for GBK encoding and decoding of types such as VARCHAR2, CHAR, and CLOB;`NCHAR` / `NVARCHAR2`This parameter is not used.

Note

When using GBK with FreeSql, SqlSugar, or EF Core 6/7/8, please use V1.3.1 and its corresponding ORM Provider version.