24.2.6. C API 프리페어드 명령문 함수 개요

프리페어드 명령문을 실행할 때 사용 가능한 함수는 다음과 같다.

mysql_stmt_init()를 호출해서 명령문 핸들을 생성한 후에, mysql_stmt_prepare를 실행해서 그것을 준비하고, mysql_stmt_bind_param()을 실행해서 파라미터 데이터를 입력한 후에, 마지막으로 mysql_stmt_execute()를 통해서 명령문을 실행한다. mysql_stmt_bind_param()를 통해서 제공 받은 버퍼에서 파라미터 값을 변경하면 mysql_stmt_execute()를 반복적으로 실행할 수가 있다.

명령문이 SELECT이거나 또는 결과 셋을 생성하는 다른 형태의 명령문이라면, mysql_stmt_prepare()도 mysql_stmt_result_metadata()를 통해서 MYSQL_RES 결과 셋 형식으로 결과 셋 메타데이터 정보를 리턴한다.

mysql_stmt_bind_result()를 사용해서 결과 버퍼를 제공하면 mysql_stmt_fetch()가 자동으로 이 버퍼에 데이터를 리턴하도록 만들 수가 있다.

명령문 실행을 완료하면, 이것과 연관된 모든 자원을 풀어 놓기 위해서는 mysql_stmt_close()를 사용해서 명령문 핸들을 닫도록 한다.

mysql_stmt_result_metadata()를 호출해서 SELECT 명령문의 결과 셋 메타데이터를 얻었다면, mysql_free_result()를 사용해서 메타데이터로 함께 풀어 놓도록 한다.

Execution Steps

명령문을 준비하고 실행하기 위해서는 다음과 같은 단계로 어플리케이션을 실행하도록 한다:

1.     mysql_stmt_init()를 사용해서 프리페어드 명령문 핸들을 생성한다. 서버에서 명령문을 준비하기 위해서는, mysql_stmt_prepare()를 호출한 후에 그것을 SQL 명령문을 가지고 있는 스트링에 전달한다.

2.     명령문이 결과 셋을 생성한다면, 결과 셋 메타데이터를 가져오기 위한 mysql_stmt_result_metadata()를 호출한다. 이 메타데이터는 결과 셋 형식 자체가 된다. 메타데이터 결과 셋은 결과에 얼마나 많은 컬럼이 있는지를 나타내며 각 컬럼에 대한 정보를 가지고 있다.

3.     mysql_stmt_bind_param()을 사용해서 파라미터 값을 설정한다. 반드시 모든 파라미터를 설정해야 한다. 그렇지 않으면, 에러 또는 기대하지 않은 결과가 리턴된다.

4.     mysql_stmt_execute()를 호출해서 명령문을 실행한다.

5.     명령문이 결과 셋을 생성한다면, 데이터 버퍼를 바인딩해서 mysql_stmt_bind_result() 호출로 추출한 열값으로 사용한다.

6.     더 이상 열이 존재하지 않을 때까지 mysql_stmt_fetch()를 반복적으로 호출해서 데이터를 열 단위로 버퍼에 넣는다.

7.     필요할 경우에는 파라미터 값을 변경하면서 3번 단계부터 6번 단계까지를 반복 실행한다.

mysql_stmt_prepare()이 호출되면, MySQL 클라이언트/서버 프로토콜은 다음과 같은 동작을 실행한다:

• 서버는 명령문을 분석한 후에 명령문 ID를 할당해서 OK 상태를 클라이언트에 다시 전송한다. 또한, 결과 셋 지향 명령문에 대해서는 파라미터의 전체 수, 컬럼 카운트, 그리고 메타데이터도 함께 전송한다. 이 호출이 실행되는 동안 서버는 명령문의 모든 신텍스와 의미 (semantics)를 검사한다.
• 클라이언트는 다른 용도의 연산용으로 이 명령문 ID를 사용하기 때문에, 서버는 이것을 사용해서 명령문 풀에 들어 있는 명령문들을 구분한다.

mysql_stmt_execute()가 호출되면, MySQL 클라이언트/서버 프로토콜은 다음과 같은 동작을 실행한다:

• 클라이언트는 명령문 핸들을 사용하며 파라미터 데이터를 서버에 전송한다.
• 서버는 클라이언트가 제공한 ID를 사용해서 명령문을 구분하고, 파라미터 마커를 새롭게 제공된 데이터로 대체한 후에, 명령문을 실행한다. 명령문이 결과 셋을 생성하면, 서버는 데이터를 클라이언트에 다시 전송한다. 그렇지 않으면, 서버는 OK 상태와 변경, 삭제, 또는 삽입된 전체 열의 숫자를 클라이언트에 전송한다.

mysql_stmt_fetch()가 호출되면, MySQL 클라이언트/서버 프로토콜은 다음과 같은 동작을 실행한다:

• 클라이언트는 패킷에서 데이터를 열 단위로 읽은 후에 읽은 열을 필요한 변환 절차를 거쳐서 어플리케이션 데이터 버퍼에 저장한다. 어플리케이션 버퍼 타입이 서버가 리턴하는 필드 타입과 같다면, 변환은 일어나지 않는다.

에러가 발생한다면, mysql_stmt_errno(), mysql_stmt_error(), 그리고 mysql_stmt_sqlstate()를 사용해서 명령문 에러 코드, 에러 메시지, 그리고 SQLSTATE 값을 가져온다.

프리페어드 명령문 로깅

mysql_stmt_prepare() 그리고 mysql_stmt_execute() C API 함수와 함께 실행된 프리페어드 명령문의 경우, 서버는 Prepare 및 Execute 라인을 일반 쿼리 로그에 기록해서 명령문이 준비되고 실행될 때 호출할 수 있도록 만든다.

다음과 같이 명령문을 준비하고 실행한다고 가정하자:

1.     명령문 스트링 "SELECT ?"를 준비하기 위해서 mysql_stmt_prepare()를 호출한다.

2.     3을 프리페어드 명령문에 들어 있는 파라미터에 바인딩하기 위해서 mysql_stmt_bind_param()를 호출한다.

3.     프리페어드 명령문을 실행하기 위해서 mysql_stmt_execute()를 호출한다.

위의 호출에 대한 결과로, 서버는 다음과 같은 라인을 일반 쿼리 로그에 기록한다:

Prepare  [1] SELECT ?

Execute  [1] SELECT 3

로그에 있는 각 Prepare및 Execute 라인에는 [N] 명령문 아이덴티파이어가 추가되어서 로깅된 프리페어드 명령문을 추적할 수 있도록 한다. N은 양수 정수 값이다. 클라이언트용으로 여러 개의 프리페어드 명령문이 동시에 활성화 되어 있다면, N은 1보다 큰 수가 된다. 각각의 Execute 라인은 ? 파라미터용 데이터 값이 대체된 이후의 프리페이드 명령문을 나타낸다.