> For the complete documentation index, see [llms.txt](https://docs.tibero.com/tibero-manuals/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tibero.com/tibero-manuals/7.2.6.manuals/tdp-net-guide/basic-usage-of-tdp.net.md).

# TDP.NET 기본 사용

TDP.NET을 사용하여 애플리케이션 프로그램을 개발하는 과정을 순서대로 설명하고 연결속성, 데이터 타입, PSM 호출 방법 등을 설명합니다.

## 개발 과정

다음은 TDP.NET을 사용하여 애플리케이션을 개발하는 과정입니다.<br>

**1. 네임스페이스 추가**

기본이 되는 Tibero.DataAccess.Client 네임스페이스를 추가합니다.

```
using Tibero.DataAccess.Client;
```

\
**2. 데이터베이스 연결**

데이터베이스에 연결하려면 접속 정보를 connection string으로 직접 명시합니다. TiberoConnection 객체를 생성한 뒤 Open() 메소드를 호출하여 데이터베이스에 접속합니다.

```
string connStr = "Data Source=((INSTANCE="
                  + "(HOST=localhost)(PORT=8629)(DB_NAME=dbsvr)));"
                  + "User Id=tibero;Password=tmax;"; 
TiberoConnection conn = new TiberoConnection(connStr); 
conn.Open();
```

또는 TiberoConnectionStringBuilder를 사용하여 Connection string을 생성할 수 있습니다.

```
TiberoConnectionStringBuilder builder = new TiberoConnectionStringBuilder(); 
builder.DataSource = "((INSTANCE=(HOST=localhost)(PORT=8629)(DB_NAME=dbsvr)))"; 
builder.UserID = "tibero";
builder.Password = "tmax";

TiberoConnection conn = new TiberoConnection(builder.ToString()); 
conn.Open();
```

Connection string의 Data Source에 Data Source Name을 명시하면, $TB\_HOME/client/config/tbdsn.tbr 파일에 명시된 DSN의 HOST, PORT, DB\_NAME을 파싱하여 접속 정보로 사용합니다.

```
string connStr = "Data Source=tibero;User Id=tibero;Password=tmax;"; 
TiberoConnection conn = new TiberoConnection(connStr);
conn.Open();
```

\
**3. TiberoCommand 객체 생성과 SQL 문 수행**

데이터베이스에 연결되면, TiberoCommand 객체를 생성한 뒤 ExecuteXXX() 메소드를 통해 SQL 커맨드를 데이터베이스에 보냅니다.

```
conn.Open();
TiberoCommand cmd = new TiberoCommand("create table t (c1 varchar2(10), c2 number)",conn);
cmd.ExecuteNonQuery();
```

\
**4. 질의문 수행과 TiberoDataReader 객체 받기**

커맨드 객체를 생성하여 질의문을 수행하고 TiberoDataReader 객체를 받습니다.

```
TiberoCommand cmd = new TiberoCommand("select * from t"); 
cmd.Connection = conn;
cmd.CommandType = CommandType.Text; 
TiberoDataReader reader = cmd.ExecuteReader();
```

\
**5. TiberoDataReader 객체 처리**

TiberoDataReader 객체는 Read() 메소드를 이용하여 결과 집합의 각 로우에 순차적으로 접근할 수 있습니다. 더 이상 읽을 로우가 없으면 Read() 메소드는 false를 반환합니다. TiberoDataReader의 GetXXX() 메소드를 호출하거나 컬럼 배열에 접근하여 컬럼 값을 얻어올 수 있습니다.

```
while (reader.Read())
{
   string c1 = reader.GetString(0); 
   int c2 = reader["c2"];
}
```

\
**6. TiberoDataAdapter를 통한 질의문 수행**

TiberoDataAdapter를 통해서도 데이터베이스에 커맨드를 요청하고, Fill 메소드를 통해 DataSet 객체에 결과 집합을 담을 수 있습니다. 데이터베이스 연결이 닫혀 있는 상태라도 Fill 메소드 내부에서 암시적으로 데이터베이스에 연결합니다. 데이터를 조회해 온 후 연결을 해제하여 닫힌 상태로 되돌립니다.

```
TiberoCommand cmd = new TiberoCommand("select * from t", conn); 
DataSet ds = new DataSet();
TiberoDataAdapter da = new TiberoDataAdapter(cmd);

da.Fill(ds);
foreach (DataRow r in ds.Tables[0].Rows)
{
    Console.WriteLine(r[0] + "," + r[1]);
}
```

\
**7. 데이터베이스 연결 해제**

TiberoConnection 객체의 Close() 메소드를 호출하면 데이터베이스와의 연결이 해제됩니다.

```
conn.Close();
```

{% hint style="info" %}
**참고**\
Close() 메소드를 호출하지 않으면 불필요한 커넥션이 남아서 성능 저하를 유발시킬 수 있으므로,\
항상 Close() 메소드를 사용하여 연결을 해제해야 합니다.
{% endhint %}

\
**8. 객체 소멸**

명시적으로 Dispose() 메소드를 호출하면 TiberoDataReader, TiberoCommand, TiberoConnection 등의 객체가 사용한 리소스가 정리되며 소멸됩니다.

```
cmd.Dispose();
reader.Dispose(); 
conn.Dispose();
```

## Connection Properties

다음은 데이터베이스에 연결할 때 Connection String으로 설정할 수 있는 속성입니다.

<table><thead><tr><th width="192">속성명</th><th width="93">타입</th><th>설명</th></tr></thead><tbody><tr><td>DB_NAME</td><td>String</td><td>서버에 존재하는 특정 데이터베이스의 이름</td></tr><tr><td>Data Source</td><td>String</td><td>데이터 소스의 이름</td></tr><tr><td>INSTANCE</td><td>String</td><td>접속할 인스턴스 정보</td></tr><tr><td>Password</td><td>String</td><td>서버 접속을 위한 패스워드</td></tr><tr><td>User Id</td><td>String</td><td>서버 접속을 위한 사용자 이름</td></tr><tr><td>PORT</td><td>String</td><td>서버 리스너의 포트 번호</td></tr><tr><td>HOST</td><td>String</td><td>접속할 인스턴스의 호스트 및 IP 주소 정보</td></tr><tr><td>Enlist</td><td>String</td><td><p>트랜잭션 범위 내에서 Connection을 열 때 암시적으로 System.Transactions의 트랜잭션에 참여할지 여부를 지정</p><p>(기본값: True)</p></td></tr><tr><td>Pooling</td><td>String</td><td>Connection Pooling 기능을 사용할지 여부를 지정<br>(기본값: True)</td></tr><tr><td>Min Pool Size</td><td>String</td><td>Connection Pool 내에 존재해야 하는 커넥션의 최소 개수<br>(기본값: 1)</td></tr><tr><td>Max Pool Size</td><td>String</td><td>Connection Pool 내에 존재할 수 있는 커넥션의 최대 개수<br>(기본값: 100)</td></tr><tr><td>Decr Pool Size</td><td>String</td><td>Connection Pool 내 커넥션의 단위 감소량<br>(기본값: 1)</td></tr><tr><td>Incr Pool Size</td><td>String</td><td>Connection Pool 내 커넥션의 단위 증가량<br>(기본값: 5)</td></tr><tr><td>Validate Connection</td><td>String</td><td><ul><li>Connection Pool에서 커넥션을 가져올 때마다 데이터베이스 연결 유효성 검사를 할지 여부를 지정</li><li>True로 지정하면 연결 유효성 검사에 따른 오버헤드가 발생할 수 있음<br>(기본값: False)</li></ul></td></tr><tr><td>Connection Timeout</td><td>String</td><td>Connection Pool에서 커넥션을 가져올 때 Max Pool Size만큼의 커넥션이 모두 Busy 상태이면, 커넥션을 획득하기 위해 기다리는 최대 시간을 지정<br>(단위: 초, 기본값: 15초)</td></tr><tr><td>Promotable Transaction</td><td>String</td><td><p>분산 트랜잭션으로의 승격 가능 여부를 지정</p><ul><li>Promotable (기본값)</li><li>Local</li></ul></td></tr><tr><td>Persist Security Info</td><td>String</td><td>열린 Connection의 Connection String에 패스워드가 노출되지 않도록 지정<br>(기본값: False)</td></tr><tr><td>Load Balance <mark style="color:cyan;background-color:cyan;">Core</mark></td><td>String</td><td>접속 대상 INSTANCE가 여러 개일 때 접속할 INSTANCE를 무작위로 선택할지 여부를 지정 (기본값: False)</td></tr><tr><td>Session Failover <mark style="color:cyan;background-color:cyan;">Core</mark></td><td>String</td><td>세션 사용 중 통신 오류가 발생하면 자동으로 재접속할지 여부를 지정. '고가용성 접속' 절 참고 (기본값: False)</td></tr></tbody></table>

### 커넥션 풀 설정 <mark style="color:cyan;background-color:cyan;">Core</mark>

다음 환경 변수로 커넥션 풀 동작을 조정할 수 있습니다. Core 드라이버에서만 동작합니다.

<table><thead><tr><th width="300.111083984375">환경 변수</th><th width="453.444580078125">설명</th></tr></thead><tbody><tr><td>TDPNET_RELEASE_POOL_DISABLE_COMMIT</td><td>커넥션을 풀에 반납할 때 드라이버는 트랜잭션이 진행 중이 아닌 커넥션에 COMMIT을 보냅니다. TRUE로 설정하면 이 COMMIT을 생략합니다. (기본값: 미설정, COMMIT 수행)</td></tr><tr><td>TDPNET_IDLE_CHECKING_TIME</td><td>유휴 커넥션을 정리하는 주기를 초 단위로 지정합니다. (기본값: 180)</td></tr></tbody></table>

### 고가용성 접속 <mark style="color:cyan;background-color:cyan;">Core</mark>

Core 드라이버는 접속 대상을 여러 개 지정하여 접속 실패 시 다른 INSTANCE로 재시도하거나, 사용 중인 세션의 통신 오류를 감지하여 자동으로 재접속할 수 있습니다.

**다중 INSTANCE 지정**

Data Source에 INSTANCE를 두 개 이상 나열합니다. 접속에 실패하면 다음 INSTANCE로 재시도합니다.

```
Data Source=((INSTANCE=(HOST=host1)(PORT=8629)(DB_NAME=tibero))
             (INSTANCE=(HOST=host2)(PORT=8629)(DB_NAME=tibero)));
User Id=tibero;Password=tmax;
```

**Load Balance**

Load Balance=true를 지정하면 나열한 INSTANCE 중 하나를 무작위로 선택하여 접속합니다. 지정하지 않으면 첫 번째 INSTANCE부터 시도합니다.

**Session Failover**

Session Failover=true를 지정하면 SQL 수행 중 서버와의 통신 오류가 발생했을 때 드라이버가 연결을 닫고 다시 접속합니다. INSTANCE가 하나여도 사용할 수 있습니다. 동작은 다음과 같습니다.

• 재접속에 성공하면 수행 중이던 명령은 ODP-90700 에러를 throw하며, 재접속된 연결은 그대로 사용할 수 있으므로 애플리케이션이 명령을 다시 수행해야 합니다.\
• 재접속에 실패하면 통신 오류 예외가 발생하고 연결 상태는 Closed가 됩니다.\
• 재접속 시 이전 세션의 트랜잭션과 세션 상태는 복구되지 않습니다.

```
string connStr = "Data Source=((INSTANCE=(HOST=host1)(PORT=8629)(DB_NAME=tibero))"
               + "(INSTANCE=(HOST=host2)(PORT=8629)(DB_NAME=tibero)));"
               + "User Id=tibero;Password=tmax;"
               + "Load Balance=true;Session Failover=true;";
TiberoConnection conn = new TiberoConnection(connStr);
conn.Open();
```

## 데이터 타입

다음은 TDP.NET에서 제공하는 타입의 Value 속성과 .NET 프레임워크 데이터 타입의 대응 관계입니다. Tibero.DataAccess.Types 네임스페이스를 추가하면 TDP.NET 타입을 사용할 수 있습니다.

| Tibero DB 데이터 타입               | TDP.NET 타입         | .NET 프레임워크 데이터 타입 |
| ------------------------------ | ------------------ | ----------------- |
| BFILE                          | TiberoBFile        | System.Byte\[]    |
| BINARY\_DOUBLE                 | TiberoDecimal      | System.Decimal    |
| BINARY\_FLOAT                  | TiberoDecimal      | System.Decimal    |
| BINARY\_INTEGER                | TiberoDecimal      | System.Decimal    |
| BLOB                           | TiberoBlob         | System.Byte\[]    |
| BOOLEAN                        | TiberoBoolean      | System.Boolean    |
| CHAR                           | TiberoString       | System.String     |
| CLOB                           | TiberoClob         | System.String     |
| DATE                           | TiberoDate         | System.DateTime   |
| INTERVAL DAY TO SECOND         | TiberoIntervalDS   | System.TimeSpan   |
| INTERVAL YEAR TO MONTH         | TiberoIntervalYM   | System.Int64      |
| LONG                           | TiberoString       | System.Byte\[]    |
| LONG RAW                       | TiberoBinary       | System.Byte\[]    |
| NCHAR                          | TiberoString       | System.String     |
| NCLOB                          | TiberoClob         | System.String     |
| NUMBER                         | TiberoDecimal      | System.Decimal    |
| NVARCHAR2                      | TiberoString       | System.String     |
| REF                            | TiberoRef          | System.String     |
| REF CURSOR                     | TiberoRefCursor    | -                 |
| ROWID                          | TiberoString       | System.String     |
| TIMESTAMP                      | TiberoTimeStamp    | System.DateTime   |
| TIMESTAMP WITH LOCAL TIME ZONE | TiberoTimeStampLTZ | System.DateTime   |
| TIMESTAMP WITH TIME ZONE       | TiberoTimeStampTZ  | System.DateTime   |
| VARCHAR2                       | TiberoString       | System.String     |
| XMLTYPE                        | TiberoXmlType      | System.String     |

## 기본 예제

다음은 파라미터를 바인딩하여 DML을 수행하는 예제입니다.

**1. BindByName 설정 후 파라미터 바인딩**

TiberoCommand 객체의 BindByName 값을 True로 설정하면 지정한 파라미터 이름에 따라 바인딩합니다.

```
TiberoCommand cmd = new TiberoCommand("create table test " +
                                      "(c1 varchar2(20), c2 varchar2(20))", 
                                      conn);
cmd.ExecuteNonQuery();
cmd = new TiberoCommand("insert into test values (:col1, :col2)", conn); 
cmd.BindByName = true;

TiberoParameter param = new TiberoParameter(); 
param.ParameterName = "col2"; 
param.TiberoDbType = TiberoDbType.Varchar2; 
param.Direction = ParameterDirection.Input; 
param.Size = 20;
param.CollectionType = TiberoCollectionType.None; 
param.Value = "second column"; 
cmd.Parameters.Add(param);
cmd.Parameters.Add("col1", TiberoDbType.Varchar2).Value = "first column"; 
int affectedRowCnt = cmd.ExecuteNonQuery();
```

\
**2. 일반적인 파라미터 바인딩**

TiberoCommand 객체에 BindByName 설정을 별도로 하지 않으면 기본값은 False입니다. 따라서 파라미터 이름은 의미가 없으며, 추가하는 순서대로 바인딩된다는 점에 유의해야 합니다.

```
TiberoCommand cmd = new TiberoCommand("create table test2 " +
                                      "(c1 date, c2 number, c3 number)", conn);
cmd.ExecuteNonQuery();
cmd = new TiberoCommand("insert into test2 values (:col1, :col2, :colNull)", conn);

DateTime dt = new DateTime(2020, 3, 23, 17, 50, 30); 
cmd.Parameters.Add("col1", TiberoDbType.Date, dt, ParameterDirection.Input);
cmd.Parameters.Add("col2", TiberoDbType.Decimal, 123.45m, ParameterDirection.Input);
cmd.Parameters.Add("col3", null);
int affectedRowCnt = cmd.ExecuteNonQuery();
```

## PSM 호출

다음은 REF CURSOR를 아웃 파라미터로 바인딩하여 Stored Procedure를 수행하고 테이블 데이터를 조회하는 예제입니다.

```
TiberoCommand cmd = new TiberoCommand("create table test3 " +
                                      "(c1 varchar(50), c2 number)", conn);
cmd.ExecuteNonQuery();
cmd = new TiberoCommand("insert into test3 values ('hello', 10)", conn); 
cmd.ExecuteNonQuery();
cmd = new TiberoCommand("create or replace procedure " +
                        "out_cursor(p1 out sys_refcursor)" + 
                        "as " +
                        "begin " +
                        "open p1 for 'select * from test3'; " + 
                        "end; ", conn);
cmd.ExecuteNonQuery();
cmd = new TiberoCommand(); 
cmd.Connection = conn; 
cmd.CommandText = "out_cursor";
cmd.CommandType = CommandType.StoredProcedure; 
cmd.Parameters.Add("csr", TiberoDbType.RefCursor, ParameterDirection.Output);

TiberoDataAdapter oAdapter = new TiberoDataAdapter(cmd); 
DataSet ds = new DataSet();
oAdapter.Fill(ds);
foreach (DataRow r in ds.Tables[0].Rows)
{
   Console.WriteLine(r[0] + ", " + r[1]);
}
```
