Connection strings|V1.0.0|OceanBase Connector/NET|OceanBase Connector/NET docs|Distributed Database

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

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

MySQL mode

When you connect to OceanBase Database in MySQL mode, you use the same connection string format and parameters as those for MySqlConnector, for example:

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

Note

For connections through ODP, the user field is usually a three-part value: Username@TenantName#ClusterName (this maps to Uid in MySQL mode). Some cloud deployments also support shorthand forms. Replace tenant_name and cluster_name with your actual tenant and cluster names.

Oracle mode

Basic format

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

Note

Data Source supports only host or host:port. It does not support appending /servicename. If you need a service name, specify it using another connection string parameter.

For connections through ODP, User Id is usually the three-part form: Username@TenantName#ClusterName. Some cloud deployments also support shorthand forms such as a one-part user name. Follow your environment. Replace username, tenant_name, and cluster_name with real values.

Main parameters

Parameter	Description
Data Source	The data source address. Only `host` or `host:port` is supported; the `host:port/servicename` form is not supported. host is the IP address or hostname of the OBServer or ODP node. port is 2881 for direct connections or 2883 for connections through ODP. If a service name is required, set it using another parameter. Do not append it to `Data Source`.
User Id	User identity. For ODP connections, this is usually the three-part form: `Username@TenantName#ClusterName`, consistent with the `User Id` value in the connection string. Some cloud deployments support shorthand forms.
Password	The password of the database.
Database	Mandatory. In Oracle mode, this parameter must be set to the schema name. Otherwise, Open will throw an ArgumentException.
UseLobLocatorV2	Specifies whether to enable the LOB Locator feature. The default value is true.

Note

This topic describes the connection parameters. For an overview of the interface capabilities, see Common Interfaces. The driver is based on MySqlConnector. The connection parameters are consistent with those of MySqlConnector. Some parameters have adjusted default values: ConnectionReset defaults to false, and SslMode defaults to None.

Full parameter list (by type)

Connection

Parameter (Common)	Type	Default Value	Description
Server / Host / Data Source	string	`""`	The server address. Multiple hosts are supported and separated by commas.
Port	uint	`3306`	The port number.
User ID / UserID / Username / Uid	string	`""`	User identity. In multi-tenant deployments, ODP connections usually use the three-part form: `Username@TenantName#ClusterName`. Some cloud deployments support shorthand forms.
Password / Pwd	string	`""`	The password.
Database / Initial Catalog	string	`""`	The initial database (schema), which is required for the Oracle mode.
Load Balance / LoadBalance	enum	`RoundRobin`	The load balancing strategy for multiple hosts.
Connection Protocol / Protocol	enum	`Socket`	The 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`	The connection timeout (seconds).
Interactive Session / Interactive	bool	`false`	Specifies whether to enable an interactive session.
Keep Alive / Keepalive	uint	`0`	The TCP keepalive idle time (seconds). `0` indicates the default system value.
Server Redirection Mode	enum	`Disabled`	Specifies whether to enable server redirection.
Server RSA Public Key File	string	`""`	The path of the server RSA public key.
Server SPN	string	`""`	The server SPN.

TLS

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

Pooling

Parameter (Common)	Type	Default Value	Description
Pooling	bool	`true`	Specifies whether to enable connection pooling.
Connection Lifetime / ConnectionLifeTime	uint	`0`	The maximum connection lifetime (seconds).
Connection Reset / ConnectionReset	bool	`false`	Specifies whether to reset the connection state when a connection is taken from the pool.
Connection Idle Timeout / ConnectionIdleTimeout	uint	`180`	The connection pool idle timeout (seconds).
Minimum Pool Size / Min Pool Size	uint	`0`	The minimum number of connections.
Maximum Pool Size / Max Pool Size	uint	`100`	The maximum number of connections.
DNS Check Interval / DnsCheckInterval	uint	`0`	The DNS change check interval (seconds).

OceanBase

Parameter (Common)	Type	Default Value	Description
Use LOB Locator V2 / UseLobLocatorV2	bool	`true`	Specifies whether to enable OceanBase LOB Locator V2.

Other

Parameter (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 retrieving an RSA public key from the server.
Allow User Variables	bool	`false`	Whether to allow the use of user variables in SQL.
Allow Zero DateTime	bool	`false`	Whether to allow zero date values.
Application Name	string	`""`	Application name (connection property).
Auto Enlist / AutoEnlist	bool	`true`	Whether to automatically register with `TransactionScope`.
Cancellation Timeout	int	`2`	Command cancellation timeout (seconds).
Convert Zero DateTime	bool	`false`	Whether to convert invalid dates to `DateTime.MinValue`.
DateTime Kind	enum	`Unspecified`	Deserialization of `DateTimeKind`.
Default Command Timeout / Command Timeout	uint	`30`	Default command timeout (seconds).
Force Synchronous	bool	`false`	Whether to force asynchronous APIs to execute synchronously.
GUID Format / GuidFormat	enum	`Default`	`Guid` mapping format.
Ignore Command Transaction	bool	`false`	Whether to ignore command transaction consistency checks.
Ignore Prepare	bool	`false`	Whether to ignore `Prepare` calls.
No Backslash Escapes	bool	`false`	Whether to disable backslash escaping.
Persist Security Info	bool	`false`	Whether to retain sensitive information after the connection is established.
Pipelining	bool	`true`	Whether to enable pipelining.
Treat Tiny As Boolean	bool	`true`	Whether to treat `TINYINT(1)` 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`	Whether to use XA with `TransactionScope`.
Character Set / CharSet	string	`utf8mb4`	Character set parameter, retained for compatibility.