Connection string|V1.3.0|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, and the connection string format is 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 User Id in the connection string is generally 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. The host is the IP address or hostname of an OBServer or ODP, and the port is typically 2881 (for direct connection) or 2883 (via ODP). If a service name is required, specify it separately using other connection parameters; do not include it in `Data Source`.
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 one-part identifiers.
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 (common)	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 multi-tenant scenarios, it typically follows the three-part format `username@tenant_name#cluster_name` after passing through ODP. Some cloud-based scenarios support simplified 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 RSA public key.
Server SPN	string	`""`	Server SPN.

TLS

Parameter name (common)	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 location where the certificate is stored.
Certificate Thumbprint	string	`""`	Certificate fingerprint.
SSL Cert / SslCert	string	`""`	Path to the client's PEM certificate.
SSL Key / SslKey	string	`""`	The path of the client's private key in PEM format.
SSL CA / SslCa	string	`""`	The path of the CA certificate.
TLS Version / TlsVersion	string	`""`	The allowed TLS version.
TLS Cipher Suites	string	`""`	List of allowed cipher suites.

Pooling

Parameter name (common)	Type	Default Value	Description
Pooling	bool	`true`	Whether to enable the connection pool.
Connection Lifetime / ConnectionLifeTime	uint	`0`	Maximum Connection Liveness Time (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`	Interval for DNS change check (seconds).

OceanBase

Parameter name (common)	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. You must specify the value in the`OracleCommand.ArrayBindCount`Effective when greater than 0. When using it, you need to set`AutoCommit=false`.
Auto Commit / AutoCommit	bool	`true`	Whether to automatically commit transactions. In ArrayBinding scenarios, this parameter must be set to`false`.
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.

Other

Parameter name (common)	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`	Specifies whether user variables can be used 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 (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 transmission.
Use XA Transactions	bool	`true`	`TransactionScope`Specifies whether to use XA.
Character Set / CharSet / CharacterSet	string	Not set (UTF-8)	The character set for Oracle-compatible mode sessions. V1.3.0 supports setting it to`gbk`, and encodes and decodes types such as VARCHAR2/CHAR in GBK. If not specified, UTF-8 is used.`NCHAR` / `NVARCHAR2`This parameter is ignored. GBK support applies only to Oracle-compatible mode.

Note

When using GBK with FreeSql, SqlSugar, or EF Core 8, the corresponding OceanBase ORM Provider must be upgraded to the latest version (V1.1.0 or later).