PEP 248 – Python 데이터베이스 API 명세 v1.0

Author:

Greg Stein <gstein at lyra.org>, Marc-André Lemburg <mal at lemburg.com>

Discussions-To:

Db-SIG list

Status:

Final

Type:

Informational

Created:

08-May-1996

Post-History:

Superseded-By:

249

---

Table of Contents

• 소개
• 모듈 인터페이스
• Connection 객체
• Cursor 객체
• DBI 헬퍼 객체
• 감사의 말
• Copyright

번역·라이선스 안내

이 비공식 한국어 번역은 원문 Copyright 절의 Public Domain 조건에 따라 제공합니다. 원저자와 공식 원문은 그대로 표시합니다. 수정되지 않은 기준 원문 · 공식 최신판

소개

이 API는 데이터베이스에 접근하는 데 사용되는 Python 모듈 간의 유사성을 촉진하기 위해 정의되었습니다. 이를 통해 더 쉽게 이해할 수 있는 모듈, 여러 데이터베이스 간에 일반적으로 더 이식 가능한 코드, 그리고 Python으로부터의 더 폭넓은 데이터베이스 연결성으로 이어지는 일관성을 달성하고자 합니다.

이 인터페이스 명세는 다음 몇 가지 항목으로 구성됩니다:

• 모듈 인터페이스
• Connection 객체
• Cursor 객체
• DBI 헬퍼 객체

이 명세에 대한 의견과 질문은 Python의 표 형식 데이터베이스에 관한 SIG(http://www.python.org/sigs/db-sig)로 보내주시기 바랍니다.

이 명세 문서는 1996년 4월 9일에 마지막으로 갱신되었습니다. 이 명세는 버전 1.0으로 알려지게 됩니다.

모듈 인터페이스

데이터베이스 인터페이스 모듈은 일반적으로 db로 끝나는 이름으로 명명되어야 합니다. 기존의 예로는 oracledb, informixdb, pg95db가 있습니다. 이 모듈들은 몇 가지 이름을 내보내야 합니다:

modulename(connection_string)

데이터베이스에 대한 연결을 생성하는 생성자입니다. Connection 객체를 반환합니다.

error

데이터베이스 모듈에서 발생하는 오류에 대해 발생되는 예외입니다.

Connection 객체

Connection 객체는 다음 메서드에 응답해야 합니다.

close()

(__del__이 호출될 때가 아니라) 지금 즉시 연결을 닫습니다. 이 시점 이후로 연결은 사용할 수 없게 되며, 이 연결로 어떤 작업이든 시도하면 예외가 발생합니다.

commit()

보류 중인 트랜잭션을 데이터베이스에 커밋합니다.

rollback()

보류 중인 트랜잭션이 시작되기 이전 상태로 데이터베이스를 되돌립니다.

cursor()

새로운 Cursor 객체를 반환합니다. 데이터베이스가 커서 개념을 지원하지 않으면 예외가 발생할 수 있습니다.

callproc([params])

(참고: 이 메서드는 아직 명확하게 정의되지 않았습니다.) 주어진 (선택적) 매개변수로 저장된 데이터베이스 프로시저를 호출합니다. 저장 프로시저의 결과를 반환합니다.

(모든 Cursor 객체의 속성과 메서드)

커서가 없는 데이터베이스와 커서의 복잡성이 필요하지 않은 간단한 애플리케이션의 경우, Connection 객체가 Cursor 객체의 각 속성과 메서드에 응답해야 합니다. 커서가 있는 데이터베이스는 암시적인 내부 커서를 사용하여 이를 구현할 수 있습니다.

Cursor 객체

이 객체들은 페치 작업의 컨텍스트를 관리하는 데 사용되는 데이터베이스 커서를 나타냅니다.

Cursor 객체는 다음 메서드와 속성에 응답해야 합니다:

arraysize

이 읽기/쓰기 속성은 fetchmany()로 한 번에 페치할 행의 수를 지정합니다. 이 값은 여러 행을 한 번에 삽입할 때(execute()의 params 값으로 튜플/리스트의 튜플/리스트를 전달할 때)도 사용됩니다. 이 속성의 기본값은 단일 행입니다.

arraysize는 선택적이며, 더 높은 성능의 데이터베이스 상호작용을 위해 제공될 뿐이라는 점에 유의하십시오. 구현체는 fetchmany() 메서드와 관련하여 이를 준수해야 하지만, 한 번에 한 행씩 데이터베이스와 상호작용해도 무방합니다.

description

이 읽기 전용 속성은 7-튜플의 튜플입니다. 각 7-튜플은 각 결과 열을 설명하는 정보를 담고 있습니다: (name, type_code, display_size, internal_size, precision, scale, null_ok). 이 속성은 행을 반환하지 않는 연산에 대해서는, 또는 커서에 대해 아직 execute() 메서드를 통한 연산이 호출되지 않은 경우에는 None이 됩니다.

‘type_code’는 아래 섹션에 명시된 ‘dbi’ 값 중 하나입니다.

참고: 이 부분은 다소 유동적입니다. 일반적으로 7-튜플의 처음 두 항목은 항상 존재하지만, 나머지는 데이터베이스에 따라 다를 수 있습니다.

close()

(__del__이 호출될 때까지 기다리지 않고) 지금 커서를 닫습니다. 이 시점 이후로 커서는 사용할 수 없게 되며, 커서로 어떤 연산이라도 시도하면 예외가 발생합니다.

execute(operation [,params])

데이터베이스 연산(쿼리 또는 명령)을 실행(준비)합니다. 매개변수는 (튜플/리스트 등의) 시퀀스 형태로 제공될 수 있으며, 연산 내의 변수에 바인딩됩니다. 변수는 매개변수 튜플 내의 인덱스를 기반으로 하는(이름 기반이 아니라 위치 기반의) 데이터베이스별 표기법으로 지정됩니다.

매개변수는 단일 연산으로 여러 행을 삽입하기 위해 시퀀스의 시퀀스(예: 튜플의 리스트) 형태로 지정할 수도 있습니다.

연산에 대한 참조는 커서에 유지됩니다. 동일한 연산 객체가 다시 전달되면, 커서는 그 동작을 최적화할 수 있습니다. 이는 동일한 연산이 사용되지만 (여러 번) 서로 다른 매개변수가 바인딩되는 알고리즘에서 가장 효과적입니다.

연산을 재사용할 때 최대의 효율을 얻으려면, setinputsizes() 메서드를 사용하여 매개변수 타입과 크기를 미리 지정하는 것이 가장 좋습니다. 매개변수가 미리 정의된 정보와 일치하지 않아도 무방합니다; 구현체는 이를 보완해야 하며, 그 과정에서 효율성이 저하될 수 있습니다.

SQL 용어를 사용하면, execute() 메서드에서 나올 수 있는 결과 값은 다음과 같습니다:

• 문이 DDL(예: CREATE TABLE)인 경우, 1이 반환됩니다.
• 문이 DML(예: UPDATE 또는 INSERT)인 경우, 영향을 받은 행의 수가 반환됩니다(0 또는 양의 정수).
• 문이 DQL(예: SELECT)인 경우, None이 반환되며, 이는 ‘fetch’ 메서드 중 하나를 사용하기 전까지는 문이 실제로 완료되지 않았음을 나타냅니다.

fetchone()

쿼리 결과의 다음 행을 가져와, 단일 튜플로 반환합니다.

fetchmany([size])

쿼리 결과의 다음 행 집합을 가져와 튜플의 리스트로 반환합니다. 더 이상 가져올 행이 없으면 빈 리스트가 반환됩니다. 가져올 행의 수는 매개변수로 지정합니다. 이 값이 None이면 커서의 arraysize가 가져올 행 수를 결정합니다.

size 매개변수와 관련해서는 성능상 고려할 사항이 있다는 점에 유의하십시오. 최적의 성능을 위해서는 대체로 arraysize 속성을 사용하는 것이 가장 좋습니다. size 매개변수를 사용하는 경우, fetchmany() 호출마다 동일한 값을 유지하는 것이 가장 좋습니다.

fetchall()

쿼리 결과의 모든 행을 가져와 튜플의 리스트로 반환합니다. 커서의 arraysize 속성이 이 작업의 성능에 영향을 줄 수 있다는 점에 유의하십시오.

setinputsizes(sizes)

(참고: 이 메서드는 아직 명확히 정의되지 않았습니다.) 이 메서드는 작업의 매개변수에 대한 메모리 영역을 미리 정의하기 위해 execute() 호출 전에 사용할 수 있습니다. sizes는 튜플로 지정하며, 각 입력 매개변수마다 하나의 항목을 가집니다. 각 항목은 사용될 입력에 대응하는 Type 객체이거나, 문자열 매개변수의 최대 길이를 지정하는 정수여야 합니다. 항목이 None이면 해당 열에 대해 미리 정의된 메모리 영역이 예약되지 않습니다(이는 큰 입력에 대해 미리 정의된 영역을 피하는 데 유용합니다).

이 메서드는 execute() 메서드가 호출되기 전에 사용됩니다.

이 메서드는 선택 사항이며 더 높은 성능의 데이터베이스 상호작용을 위해서만 제공된다는 점에 유의하십시오. 구현체는 아무 것도 하지 않아도 되며, 사용자는 이를 사용하지 않아도 됩니다.

setoutputsize(size [,col])

(참고: 이 메서드는 아직 잘 정의되어 있지 않습니다.)

큰 컬럼(예: LONG)을 페치할 때 사용할 컬럼 버퍼 크기를 설정합니다. 컬럼은 결과 튜플에 대한 인덱스로 지정됩니다. 컬럼으로 None을 사용하면 커서 내 모든 큰 컬럼에 대한 기본 크기가 설정됩니다.

이 메서드는 execute() 메서드가 호출되기 전에 사용됩니다.

이 메서드는 선택 사항이며 더 높은 성능의 데이터베이스 상호작용을 위해서만 제공된다는 점에 유의하십시오. 구현체는 아무 것도 하지 않아도 되며, 사용자는 이를 사용하지 않아도 됩니다.

DBI 헬퍼 객체

많은 데이터베이스는 연산의 입력 매개변수에 바인딩하기 위해 입력이 특정 형식으로 되어 있어야 합니다. 예를 들어, 입력이 DATE 컬럼을 대상으로 한다면, 특정 문자열 형식으로 데이터베이스에 바인딩되어야 합니다. “Row ID” 컬럼이나 큰 바이너리 항목(예: blob 또는 RAW 컬럼)에도 유사한 문제가 존재합니다. execute() 메서드의 매개변수는 타입이 지정되어 있지 않기 때문에, 이는 Python에서 문제를 일으킵니다. 데이터베이스 모듈은 Python 문자열 객체를 만났을 때, 이를 단순 CHAR 컬럼으로 바인딩해야 할지, 원시 바이너리 항목으로 바인딩해야 할지, 아니면 DATE로 바인딩해야 할지 알 수 없습니다.

이 문제를 해결하기 위해 ‘dbi’ 모듈이 만들어졌습니다. 이 모듈은 데이터베이스 작업을 위한 몇 가지 기본 데이터베이스 인터페이스 타입을 정의합니다. ‘dbiDate’와 ‘dbiRaw’, 두 개의 클래스가 있습니다. 이들은 값을 감싸는 단순한 컨테이너 클래스입니다. 데이터베이스 모듈에 전달되면, 해당 모듈은 입력 매개변수가 DATE나 RAW로 의도되었음을 감지할 수 있습니다. 대칭성을 위해, 데이터베이스 모듈은 DATE와 RAW 열을 이 클래스들의 인스턴스로 반환합니다.

Cursor 객체의 ‘description’ 속성은 쿼리의 각 결과 열에 대한 정보를 반환합니다. ‘type_code’는 이 모듈이 내보내는 다섯 가지 타입, 즉 STRING, RAW, NUMBER, DATE, ROWID 중 하나로 정의됩니다.

이 모듈은 다음 이름들을 내보냅니다.

dbiDate(value)

이 함수는 날짜 값을 담는 ‘dbiDate’ 인스턴스를 생성합니다. 값은 “에포크” 이후 경과한 초 수를 나타내는 정수로 지정해야 합니다(예: time.time()).

dbiRaw(value)

이 함수는 원시(바이너리) 값을 담는 ‘dbiRaw’ 인스턴스를 생성합니다. 값은 파이썬 문자열로 지정해야 합니다.

STRING

이 객체는 데이터베이스에서 문자열 기반(예: CHAR) 열을 설명하는 데 사용됩니다.

RAW

이 객체는 데이터베이스에서 (대용량) 이진 열(예: LONG RAW, blob)을 설명하는 데 사용됩니다.

NUMBER

이 객체는 데이터베이스에서 숫자 열을 설명하는 데 사용됩니다.

DATE

이 객체는 데이터베이스에서 날짜 열을 설명하는 데 사용됩니다.

ROWID

이 객체는 데이터베이스의 “Row ID” 열을 설명하는 데 사용됩니다.

감사의 말

2001년에 Python Database API Specification 1.0을 원본 HTML 형식에서 PEP 형식으로 변환해 준 Andrew Kuchling에게 깊이 감사드립니다.

Greg Stein은 Python Database API Specification 1.0의 원저자입니다. Marc-André는 이후 편집자로서 이 API의 유지 관리를 계속했습니다.

Copyright

This document has been placed in the Public Domain.