`sqlite3` — SQLite 데이터베이스를 위한 DB-API 2.0 인터페이스¶

소스 코드: Lib/sqlite3/

SQLite는 별도의 서버 프로세스가 필요 없고 SQL 질의 언어의 비표준 변형을 사용하여 데이터베이스에 액세스할 수 있는 경량 디스크 기반 데이터베이스를 제공하는 C 라이브러리입니다. 일부 응용 프로그램은 내부 데이터 저장을 위해 SQLite를 사용할 수 있습니다. SQLite를 사용하여 응용 프로그램을 프로토타입 한 다음 PostgreSQL 이나 Oracle과 같은 더 큰 데이터베이스로 코드를 이식할 수도 있습니다.

sqlite3 모듈은 Gerhard Häring이 작성했습니다. 이 모듈은 PEP 249 에서 설명하는 DB-API 2.0 사양을 준수하는 SQL 인터페이스를 제공하며, 외부 라이브러리인 SQLite 가 필요합니다.

This is an optional module. If it is missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see 선택적 모듈의 요구 사항.

이 문서는 네 개의 주요 섹션으로 구성됩니다:

sqlite3-tutorial`에서는 :mod:!sqlite3` 모듈 사용법을 설명합니다.
참조 는 이 모듈이 정의하는 클래스와 함수를 기술합니다.
사용법 가이드 에서는 특정 작업을 처리하는 방법을 자세히 설명합니다.
설명 은 트랜잭션 제어에 대한 심층적인 배경 정보를 제공합니다.

https://www.sqlite.org: SQLite 웹 페이지; 설명서는 지원되는 SQL 언어에 대한 문법과 사용 가능한 데이터형을 설명합니다.
https://www.w3schools.com/sql/: SQL 문법 학습을 위한 자습서, 레퍼런스 및 예제
PEP 249 - 데이터베이스 API 명세 2.0: Marc-André Lemburg가 작성한 PEP.

튜토리얼¶

이 튜토리얼에서는 기본적인 sqlite3 기능을 사용하여 Monty Python 영화 데이터베이스를 생성합니다. 이 과정은 cursors 및 transactions 를 포함한 데이터베이스 개념에 대한 기초적인 이해가 필요합니다.

먼저, sqlite3 가 작동할 수 있도록 새 데이터베이스를 생성하고 연결을 열어야 합니다. 현재 작업 디렉토리에 있는 tutorial.db 에 대한 연결을 생성하려면 sqlite3.connect() 를 호출하십시오. 파일이 존재하지 않는 경우 자동으로 생성됩니다.

import sqlite3
con = sqlite3.connect("tutorial.db")

반환된 Connection 객체 con 은 디스크에 저장된 데이터베이스로의 연결을 나타냅니다.

SQL 문을 실행하고 SQL 쿼리 결과를 가져오려면 데이터베이스 커서가 필요합니다. con.cursor() 를 호출하여 Cursor 를 생성하십시오.

cur = con.cursor()

데이터베이스 연결과 커서를 확보했으므로, 제목, 출시 연도, 리뷰 점수 컬럼을 포함하는 movie 데이터베이스 테이블을 생성할 수 있습니다. 편리함을 위해 테이블 선언 시 컬럼 이름만 사용할 수 있으며, SQLite의 유연한 타이핑(flexible typing) 기능 덕분에 데이터 타입을 명시하는 것은 선택 사항입니다. cur.execute(...) <Cursor.execute>`를 호출하여 ``CREATE TABLE`() 문을 실행하십시오.

cur.execute("CREATE TABLE movie(title, year, score)")

SQLite에 내장된 sqlite_master 테이블을 쿼리하여 새 테이블이 생성되었는지 확인할 수 있습니다. 이 테이블에는 이제 movie 테이블 정의 항목이 포함되어 있어야 합니다(자세한 내용은 The Schema Table 참조). cur.execute(...) 를 호출하여 해당 쿼리를 실행하고, 결과를 res 에 할당한 다음, res.fetchone() 를 호출하여 결과 행을 가져옵니다.

>>> res = cur.execute("SELECT name FROM sqlite_master")
>>> res.fetchone()
('movie',)

쿼리 결과로 테이블 이름을 포함하는 tuple 이 반환되므로 테이블이 생성되었음을 확인할 수 있습니다. 존재하지 않는 테이블인 spam 을 위해 sqlite_master 를 쿼리하면, res.fetchone() 은 None 을 반환합니다.

>>> res = cur.execute("SELECT name FROM sqlite_master WHERE name='spam'")
>>> res.fetchone() is None
True

이제 다시 한번 cur.execute(...) <Cursor.execute>`를 호출하여, SQL 리터럴로 제공되는 두 행의 데이터를 ``INSERT`() 문으로 추가합니다.

cur.execute("""
    INSERT INTO movie VALUES
        ('Monty Python and the Holy Grail', 1975, 8.2),
        ('And Now for Something Completely Different', 1971, 7.5)
""")

INSERT 문은 묵시적으로 트랜잭션을 시작하며, 데이터베이스에 변경 사항이 저장되기 전에 커밋해야 합니다(자세한 내용은 트랜잭션 제어 참조). 연결 객체에서 con.commit() 를 호출하여 트랜잭션을 커밋하십시오.

con.commit()

SELECT 쿼리를 실행하여 데이터가 올바르게 삽입되었는지 확인할 수 있습니다. 익숙해진 cur.execute(...) 를 사용하여 결과를 res 에 할당하고, res.fetchall() 를 호출하여 모든 결과 행을 반환받습니다.

>>> res = cur.execute("SELECT score FROM movie")
>>> res.fetchall()
[(8.2,), (7.5,)]

결과는 각 행에 하나씩 포함되며, 각 행의 score 값을 포함하는 두 개의 tuple s로 구성된 list 입니다.

이제 cur.executemany(...) 를 호출하여 세 개의 행을 더 삽입합니다.

data = [
    ("Monty Python Live at the Hollywood Bowl", 1982, 7.9),
    ("Monty Python's The Meaning of Life", 1983, 7.5),
    ("Monty Python's Life of Brian", 1979, 8.0),
]
cur.executemany("INSERT INTO movie VALUES(?, ?, ?)", data)
con.commit()  # INSERT 실행 후 트랜잭션을 커밋하는 것을 잊지 마십시오.

? 자리 표시자가 쿼리에 data 를 바인딩하는 데 사용됨에 유의하십시오. SQL injection attacks 을 방지하려면 Python 값을 SQL 문에 바인딩할 때 항상 string formatting 대신 자리 표시자를 사용하십시오(자세한 내용은 SQL 쿼리에서 값을 바인딩하기 위한 자리 표시자 사용 방법 참조).

이번에는 쿼리 결과를 반복(iterate)하면서 SELECT 쿼리를 실행하여 새 행들이 삽입되었는지 확인할 수 있습니다.

>>> for row in cur.execute("SELECT year, title FROM movie ORDER BY year"):
...     print(row)
(1971, 'And Now for Something Completely Different')
(1975, 'Monty Python and the Holy Grail')
(1979, "Monty Python's Life of Brian")
(1982, 'Monty Python Live at the Hollywood Bowl')
(1983, "Monty Python's The Meaning of Life")

각 행은 쿼리에서 선택된 열과 일치하는 (year, title) 의 두 항목으로 구성된 tuple 입니다.

마지막으로 기존 연결을 닫고(con.close()), 새 연결을 열고, 새 커서를 생성한 다음 데이터베이스를 쿼리하여 데이터베이스가 디스크에 기록되었는지 확인하십시오.

>>> con.close()
>>> new_con = sqlite3.connect("tutorial.db")
>>> new_cur = new_con.cursor()
>>> res = new_cur.execute("SELECT title, year FROM movie ORDER BY score DESC")
>>> title, year = res.fetchone()
>>> print(f'The highest scoring Monty Python movie is {title!r}, released in {year}')
The highest scoring Monty Python movie is 'Monty Python and the Holy Grail', released in 1975
>>> new_con.close()

이제 sqlite3 모듈을 사용하여 SQLite 데이터베이스를 생성하고, 다양한 방법으로 데이터를 삽입하고 값을 검색했습니다.

더 읽어볼 내용: 사용법 가이드
트랜잭션 제어에 대한 심층적인 배경 정보: 설명

참조¶

모듈 함수¶

sqlite3.connect(database, *, timeout=5.0, detect_types=0, isolation_level='DEFERRED', check_same_thread=True, factory=sqlite3.Connection, cached_statements=128, uri=False, autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL)¶

SQLite 데이터베이스에 연결을 엽니다.

매개변수:

database (path-like object) – 열릴 데이터베이스 파일의 경로입니다. ":memory:" 를 전달하여 메모리에만 존재하는 SQLite 데이터베이스 <https://sqlite.org/inmemorydb.html> 를 생성하고 연결을 열 수 있습니다.
timeout (float) – 테이블이 잠겨 있을 때 연결이 OperationalError 를 발생시키기 전까지 대기할 시간(초)입니다. 다른 연결이 테이블 수정을 위해 트랜잭션을 열면 해당 트랜잭션이 커밋될 때까지 그 테이블은 잠깁니다. 기본값은 5초입니다.
detect_types (int) – register_converter() 로 등록된 변환기를 사용하여, SQLite에서 네이티브로 지원되지 않는 데이터 형식을 Python 형식으로 변환하는지 여부와 방법을 제어합니다. 이를 활성화하려면 PARSE_DECLTYPES 와 PARSE_COLNAMES 의 임의 조합(|, 비트 논리합 사용)을 설정하십시오. 두 플래그가 모두 설정된 경우 열 이름이 선언된 형보다 우선합니다. 기본값(0)은 형식 감지 기능이 꺼진 상태입니다.
isolation_level (str | None) – 레거시 트랜잭션 처리 동작을 제어합니다. 자세한 내용은 Connection.isolation_level 및 isolation_level 속성을 통한 트랜잭션 제어 을 참조하십시오. "DEFERRED" (기본값), "EXCLUSIVE" 또는 "IMMEDIATE" 로 설정하거나, 묵시적인 트랜잭션 생성을 비활성화하려면 None 으로 설정할 수 있습니다. Connection.autocommit 이 LEGACY_TRANSACTION_CONTROL (기본값)로 설정되지 않은 경우 아무런 영향도 없습니다.
check_same_thread (bool) – True (기본값)인 경우, 생성한 스레드 이외의 다른 스레드에서 데이터베이스 연결을 사용하면 ProgrammingError 가 발생합니다. False 인 경우, 여러 스레드에서 연결에 접근할 수 있으나, 데이터 손상을 방지하기 위해 사용자가 쓰기 작업을 직렬화해야 할 수도 있습니다. 자세한 내용은 threadsafety 를 참조하십시오.
factory (Connection) – 기본 Connection 클래스가 아닌 경우에 연결을 생성하기 위한 Connection 의 사용자 정의 하위 클래스입니다.
cached_statements (int) – 파싱 오버헤드를 방지하기 위해 sqlite3 가 이 연결을 위해 내부적으로 캐싱할 명령문의 수입니다. 기본값은 128개입니다.
uri (bool) – True 로 설정하면, database 를 파일 경로와 선택적 쿼리 문자열을 포함한 URI 로 해석합니다. 스킴 부분은 반드시 "file:" 여야 하며, 경로는 상대 또는 절대 경로일 수 있습니다. 쿼리 문자열을 통해 SQLite에 매개 변수를 전달할 수 있어 다양한 SQLite URI 작업 방법 를 활용할 수 있습니다.
autocommit (bool) – PEP 249 트랜잭션 처리 동작을 제어합니다. 자세한 내용은 Connection.autocommit 및 autocommit 속성을 통한 트랜잭션 제어 를 참조하십시오. autocommit 은 현재 LEGACY_TRANSACTION_CONTROL 이 기본값입니다. 이 기본값은 향후 파이썬 릴리스에서 False 로 변경될 예정입니다.

반환 형식:

Connection

인자 database로 감사 이벤트(auditing event) sqlite3.connect를 발생시킵니다.

인자 connection_handle 을 사용하여 감사 이벤트 sqlite3.connect/handle 를 발생시킵니다.

버전 3.4에서 변경: uri 매개 변수가 추가되었습니다.

버전 3.7에서 변경: database는 이제 문자열뿐만 아니라 경로류 객체 일 수도 있습니다.

버전 3.10에서 변경: sqlite3.connect/handle 감사 이벤트를 추가했습니다.

버전 3.12에서 변경: autocommit 매개 변수를 추가했습니다.

버전 3.15에서 변경: database 를 제외한 모든 매개 변수가 이제 키워드 전용(keyword-only)입니다.

sqlite3.complete_statement(statement)¶

문자열 statement 가 하나 이상의 완전한 SQL 문을 포함하고 있는 것처럼 보이면 True 를 반환합니다. 닫히지 않은 문자열 리터럴이 없고 문장이 세미콜론으로 끝나는지 확인하는 것 외에 어떠한 종류의 구문 검증이나 파싱도 수행하지 않습니다.

예:

>>> sqlite3.complete_statement("SELECT foo FROM bar;")
True
>>> sqlite3.complete_statement("SELECT foo")
False

이 함수는 명령줄 입력 시 입력된 텍스트가 완전한 SQL 문을 형성하는지, 또는 execute() 를 호출하기 전에 추가 입력이 필요한지 판단할 때 유용할 수 있습니다.

실제 사용 사례는 Lib/sqlite3/__main__.py`의 :func:!runsource`를 참조하십시오.

sqlite3.enable_callback_tracebacks(flag, /)¶: 콜백 트레이스백 활성/비활성 여부를 설정합니다. 기본적으로 사용자 정의 함수, 집계(aggregates), 변환기, 권한 부여 콜백 등에서 발생하는 트레이스백은 제공되지 않습니다. 이를 디버깅하려면 flag 를 True 로 설정하고 이 함수를 호출하십시오. 그 후부터는 콜백의 트레이스백이 sys.stderr 에 출력됩니다. 기능을 다시 끄려면 False 를 사용하십시오.

참고

사용자 정의 함수 콜백의 오류는 발생시킬 수 없는 예외(unraisable exceptions)로 기록됩니다. 실패한 콜백을 조사하려면 unraisable hook handler 를 사용하십시오.

sqlite3.register_adapter(type, adapter, /)¶: Python 타입 type 을 SQLite 타입으로 변환하는 어댑터(adapter) callable 을 등록합니다. 어댑터는 type 형의 Python 객체를 단일 인자로 받아 실행되며, 반드시 SQLite가 네이티브로 이해하는 형 중 하나를 반환해야 합니다.

sqlite3.register_converter(typename, converter, /)¶

SQLite 객체(형 typename)를 특정 형의 Python 객체로 변환하는 변환기(converter) callable 을 등록합니다. 변환기는 typename 형인 모든 SQLite 값에 대해 호출되며, bytes 객체를 전달받고 원하는 Python 형의 객체를 반환해야 합니다. 형 감지 작동 방식에 대해서는 connect() 함수의 detect_types 매개 변수를 참조하십시오.

참고: typename 과 쿼리에 포함된 형의 이름은 대소 문자를 구분하지 않고 비교됩니다.

모듈 상수¶

sqlite3.LEGACY_TRANSACTION_CONTROL¶: 구식(Python 3.12 이전) 트랜잭션 제어 방식을 선택하려면 autocommit 을 이 상수로 설정하십시오. 자세한 내용은 isolation_level 속성을 통한 트랜잭션 제어 을 참조하십시오.

sqlite3.PARSE_DECLTYPES¶

각 열에 대해 선언된 형을 사용하여 변환기 함수를 찾으려면 connect`의 *detect_types* 매개 변수에 이 플래그 값을 전달하십시오. 형은 데이터베이스 테이블이 생성될 때 선언됩니다. :mod:()!sqlite3`는 선언된 형의 첫 번째 단어를 변환기 딕셔너리의 키로 사용하여 변환기 함수를 찾습니다. 예를 들면:

CREATE TABLE test(
   i integer primary key,  ! will look up a converter named "integer"
   p point,                ! will look up a converter named "point"
   n number(10)            ! will look up a converter named "number"
 )

이 플래그는 | (비트 논리합) 연산자를 사용하여 PARSE_COLNAMES 와 결합할 수 있습니다.

참고

생성된 필드(예: MAX(p))는 str`로 반환됩니다. 이러한 쿼리에서 형을 강제하려면 :const:!PARSE_COLNAMES`를 사용하십시오.

sqlite3.PARSE_COLNAMES¶

쿼리 열 이름에서 파싱된 형의 이름을 변환기 딕셔너리의 키로 사용하여 변환기 함수를 찾으려면 connect`의 *detect_types* 매개 변수에 이 플래그 값을 전달하십시오. 쿼리 열 이름은 큰따옴표(`()”)로 감싸야 하며, 형 이름은 대괄호(``[])로 감싸야 합니다.

SELECT MAX(p) as "p [point]" FROM test;  ! will look up converter "point"

이 플래그는 | (비트 논리합) 연산자를 사용하여 PARSE_DECLTYPES 와 결합할 수 있습니다.

sqlite3.SQLITE_OK¶

sqlite3.SQLITE_DENY¶

sqlite3.SQLITE_IGNORE¶

Connection.set_authorizer() 에 전달되는 authorizer_callback callable 이 다음 상황을 나타내기 위해 반환해야 하는 플래그입니다:

액세스가 허용됨(SQLITE_OK),
SQL 문을 오류와 함께 중단해야 함(SQLITE_DENY)
해당 열을 NULL 값으로 처리해야 함(SQLITE_IGNORE)

sqlite3.apilevel¶: 지원되는 DB-API 수준을 나타내는 문자열 상수입니다. DB-API에서 필요하며, "2.0" 으로 고정되어 있습니다.

sqlite3.paramstyle¶: sqlite3 모듈이 기대하는 매개 변수 마커 형식의 종류를 나타내는 문자열 상수입니다. DB-API에서 필요하며, "qmark" 로 고정되어 있습니다.

참고

named DB-API 매개 변수 스타일도 지원됩니다.

sqlite3.sqlite_version¶: 실행 중인 SQLite 라이브러리의 버전 번호를 string 으로 표시합니다.

sqlite3.sqlite_version_info¶: 실행 중인 SQLite 라이브러리의 버전 번호를 integer 의 tuple 로 표시합니다.

sqlite3.SQLITE_KEYWORDS¶

모든 SQLite 키워드를 포함하는 tuple 입니다.

이 상수는 Python이 SQLite 3.24.0 이상 버전으로 컴파일된 경우에만 사용할 수 있습니다.

Added in version 3.15.

sqlite3.threadsafety¶

DB-API 2.0에서 요구하는 정수 상수로, sqlite3 모듈이 지원하는 스레드 안전성 수준을 나타냅니다. 이 속성은 기본 라이브러리인 SQLite가 컴파일될 때 설정된 기본 threading mode 에 따라 결정됩니다. SQLite 스레딩 모드는 다음과 같습니다:

Single-thread: 이 모드에서는 모든 뮤텍스가 비활성화되며, 한 번에 하나 이상의 스레드에서 SQLite를 사용하는 것이 안전하지 않습니다.
Multi-thread: 이 모드에서는 단일 데이터베이스 연결이 두 개 이상의 스레드에서 동시에 사용되지 않는 한, 여러 스레드에서 SQLite를 안전하게 사용할 수 있습니다.
Serialized: 직렬화 모드에서는 제한 없이 여러 스레드에서 SQLite를 안전하게 사용할 수 있습니다.

SQLite 스레딩 모드와 DB-API 2.0 스레드 안전성 수준 사이의 매핑은 다음과 같습니다:

SQLite 스레딩 모드	threadsafety	SQLITE_THREADSAFE	DB-API 2.0 의미
single-thread	0	0	스레드가 모듈을 공유할 수 없음
multi-thread	1	2	스레드가 모듈은 공유할 수 있으나 연결은 공유할 수 없음
serialized	3	1	스레드가 모듈, 연결 및 커서를 모두 공유할 수 있음

버전 3.11에서 변경: 하드코딩된 1 대신 threadsafety 를 동적으로 설정하십시오.

sqlite3.SQLITE_DBCONFIG_DEFENSIVE¶

sqlite3.SQLITE_DBCONFIG_DQS_DDL¶

sqlite3.SQLITE_DBCONFIG_DQS_DML¶

sqlite3.SQLITE_DBCONFIG_ENABLE_FKEY¶

sqlite3.SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER¶

sqlite3.SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION¶

sqlite3.SQLITE_DBCONFIG_ENABLE_QPSG¶

sqlite3.SQLITE_DBCONFIG_ENABLE_TRIGGER¶

sqlite3.SQLITE_DBCONFIG_ENABLE_VIEW¶

sqlite3.SQLITE_DBCONFIG_LEGACY_ALTER_TABLE¶

sqlite3.SQLITE_DBCONFIG_LEGACY_FILE_FORMAT¶

sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE¶

sqlite3.SQLITE_DBCONFIG_RESET_DATABASE¶

sqlite3.SQLITE_DBCONFIG_TRIGGER_EQP¶

sqlite3.SQLITE_DBCONFIG_TRUSTED_SCHEMA¶

sqlite3.SQLITE_DBCONFIG_WRITABLE_SCHEMA¶

이 상수들은 Connection.setconfig() 및 getconfig() 메서드에서 사용됩니다.

이 상수들의 가용성은 Python을 컴파일할 때 사용된 SQLite 버전에 따라 다릅니다.

Added in version 3.12.

https://www.sqlite.org/c3ref/c_dbconfig_defensive.html: SQLite 문서: 데이터베이스 연결 구성 옵션

버전 3.12부터 사용 지원 중단(deprecated), 버전 3.14에서 제거됨: version 및 version_info 상수.

Connection 객체¶

class sqlite3.Connection¶

열려 있는 각 SQLite 데이터베이스는 sqlite3.connect() 를 사용하여 생성된 Connection 객체로 표현됩니다. 이 객체의 주요 목적은 Cursor 객체를 생성하고 트랜잭션 제어 하는 것입니다.

연결 바로 가기 메서드 사용 방법
연결 컨텍스트 관리자 사용 방법

버전 3.13에서 변경: Connection 객체가 삭제되기 전에 close() 가 호출되지 않으면 ResourceWarning 이 발생합니다.

SQLite 데이터베이스 연결은 다음과 같은 어트리뷰트와 메서드를 가집니다:

cursor(factory=Cursor)¶: Cursor 객체를 생성하여 반환합니다. 커서 메서드는 단일 선택적 매개 변수 factory 를 받습니다. 이 값이 제공될 경우, 반드시 Cursor 또는 그 하위 클래스의 인스턴스를 반환하는 callable 이어야 합니다.

blobopen(table, column, rowid, /, *, readonly=False, name='main')¶

기존 BLOB 에 대한 Blob 핸들을 엽니다.

매개변수:

table (str) – 블롭이 위치한 테이블의 이름입니다.
column (str) – 블롭이 위치한 컬럼의 이름입니다.
rowid (int) – 블롭이 위치한 행 ID입니다.
readonly (bool) – 쓰기 권한 없이 블롭을 열어야 하는 경우 True 로 설정합니다. 기본값은 False 입니다.
name (str) – 블롭이 위치한 데이터베이스의 이름입니다. 기본값은 "main" 입니다.

예외 발생:

OperationalError – WITHOUT ROWID 테이블에서 블롭을 열려고 할 때 발생합니다.

반환 형식:

Blob

참고

Blob 클래스를 사용하여 블롭 크기를 변경할 수 없습니다. 고정된 크기의 블롭을 생성하려면 SQL 함수인 zeroblob 을 사용하십시오.

Added in version 3.11.

commit()¶: 대기 중인 모든 트랜잭션을 데이터베이스에 커밋합니다. autocommit 이 True 이거나 열려 있는 트랜잭션이 없는 경우 이 메서드는 아무 작업도 하지 않습니다. autocommit 이 False 이고 이 메서드에 의해 대기 중인 트랜잭션이 커밋된 경우, 새로운 트랜잭션이 암시적으로 생성됩니다.

rollback()¶: 대기 중인 모든 트랜잭션을 시작 시점으로 롤백합니다. autocommit 이 True 이거나 열려 있는 트랜잭션이 없는 경우 이 메서드는 아무 작업도 하지 않습니다. autocommit 이 False 이고 이 메서드에 의해 대기 중인 트랜잭션이 롤백된 경우, 새로운 트랜잭션이 암시적으로 생성됩니다.

close()¶: 데이터베이스 연결을 닫습니다. autocommit 이 False 인 경우, 대기 중인 모든 트랜잭션은 암시적으로 롤백됩니다. autocommit 이 True 이거나 LEGACY_TRANSACTION_CONTROL 인 경우에는 암시적 트랜잭션 제어가 실행되지 않습니다. 변경 사항을 잃지 않도록 닫기 전에 commit() 을 수행하십시오.

execute(sql, parameters=(), /)¶: 새로운 Cursor 객체를 생성하고 주어진 sql 과 parameters 를 사용하여 해당 객체에 execute() 를 호출합니다. 새 커서 객체를 반환합니다.

executemany(sql, parameters, /)¶: 새로운 Cursor 객체를 생성하고 주어진 sql 과 parameters 를 사용하여 해당 객체에 executemany() 를 호출합니다. 새 커서 객체를 반환합니다.

executescript(sql_script, /)¶: 새로운 Cursor 객체를 생성하고 주어진 sql_script 를 사용하여 해당 객체에 executescript() 를 호출합니다. 새 커서 객체를 반환합니다.

create_function(name, narg, func, /, *, deterministic=False)¶

사용자 정의 SQL 함수를 생성하거나 제거합니다.

매개변수:

name (str) – SQL 함수의 이름입니다.
narg (int) – SQL 함수가 수용할 수 있는 인자의 수입니다. -1 인 경우 인자의 수를 제한하지 않습니다.
func (callback | None) – SQL 함수가 호출될 때 실행되는 callable 입니다. 해당 콜러블은 반드시 SQLite에서 기본적으로 지원하는 형식 을 반환해야 합니다. 기존 SQL 함수를 제거하려면 None 으로 설정하십시오.
deterministic (bool) – True 인 경우 생성된 SQL 함수가 결정론적(deterministic) 으로 표시되어 SQLite가 추가적인 최적화를 수행할 수 있습니다.

버전 3.8에서 변경: deterministic 매개 변수가 추가되었습니다.

버전 3.15에서 변경: 첫 세 개의 매개 변수는 이제 위치 전용입니다.

예:

>>> import hashlib
>>> def md5sum(t):
...     return hashlib.md5(t).hexdigest()
>>> con = sqlite3.connect(":memory:")
>>> con.create_function("md5", 1, md5sum)
>>> for row in con.execute("SELECT md5(?)", (b"foo",)):
...     print(row)
('acbd18db4cc2f85cedef654fccc4a4d8',)
>>> con.close()

create_aggregate(name, n_arg, aggregate_class, /)¶

사용자 정의 SQL 집계 함수를 생성하거나 제거합니다.

매개변수:

name (str) – SQL 집계 함수의 이름입니다.
n_arg (int) – SQL 집계 함수가 수용할 수 있는 인자의 수입니다. -1 인 경우 인자의 수를 제한하지 않습니다.
aggregate_class (class | None) – 클래스는 다음 메서드들을 구현해야 합니다. * step(): 집계에 행을 추가합니다. * finalize(): 집계의 최종 결과를 SQLite에서 기본적으로 지원하는 형식 으로 반환합니다. step() 메서드가 받아야 하는 인자의 수는 n_arg 로 제어됩니다. 기존 SQL 집계 함수를 제거하려면 None 으로 설정하십시오.

버전 3.15에서 변경: 세 매개 변수 모두 이제 위치 전용입니다.

예:

class MySum:
    def __init__(self):
        self.count = 0

    def step(self, value):
        self.count += value

    def finalize(self):
        return self.count

con = sqlite3.connect(":memory:")
con.create_aggregate("mysum", 1, MySum)
cur = con.execute("CREATE TABLE test(i)")
cur.execute("INSERT INTO test(i) VALUES(1)")
cur.execute("INSERT INTO test(i) VALUES(2)")
cur.execute("SELECT mysum(i) FROM test")
print(cur.fetchone()[0])

con.close()

create_window_function(name, num_params, aggregate_class, /)¶

사용자 정의 집계 윈도우 함수를 생성하거나 제거합니다.

매개변수:

name (str) – 생성하거나 제거할 SQL 집계 윈도우 함수의 이름입니다.
num_params (int) – SQL 집계 윈도우 함수가 수용할 수 있는 인자의 수입니다. -1 인 경우 인자의 수를 제한하지 않습니다.
aggregate_class (class | None) – 클래스는 다음 메서드들을 구현해야 합니다. * step(): 현재 윈도에 행을 추가합니다. * value(): 집계의 현재 값을 반환합니다. * inverse(): 현재 윈도에서 행을 제거합니다. * finalize(): 집계의 최종 결과를 SQLite에서 기본적으로 지원하는 형식 으로 반환합니다. step() 및 value() 메서드가 받아야 하는 인자의 수는 num_params 에 의해 제어됩니다. 기존 SQL 집계 윈도 함수를 제거하려면 None 으로 설정하십시오.

예외 발생:

NotSupportedError – 집계 윈도 함수를 지원하지 않는 3.25.0 이전 버전의 SQLite와 함께 사용할 경우에 대한 안내입니다.

Added in version 3.11.

예:

## https://www.sqlite.org/windowfunctions.html#udfwinfunc에서 발췌한 예제
class WindowSumInt:
    def __init__(self):
        self.count = 0

    def step(self, value):
        """현재 윈도에 행을 추가합니다."""
        self.count += value

    def value(self):
        """집계의 현재 값을 반환합니다."""
        return self.count

    def inverse(self, value):
        """현재 윈도에서 행을 제거합니다."""
        self.count -= value

    def finalize(self):
        """집계의 최종 값을 반환합니다.

        정리 작업은 여기에 배치해야 합니다.
        """
        return self.count


con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE test(x, y)")
values = [
    ("a", 4),
    ("b", 5),
    ("c", 3),
    ("d", 8),
    ("e", 1),
]
cur.executemany("INSERT INTO test VALUES(?, ?)", values)
con.create_window_function("sumint", 1, WindowSumInt)
cur.execute("""
    SELECT x, sumint(y) OVER (
        ORDER BY x ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING
    ) AS sum_y
    FROM test ORDER BY x
""")
print(cur.fetchall())
con.close()

create_collation(name, callable, /)¶

callable 이라는 정렬 함수를 사용하여 name 이라는 이름의 콜레이션을 생성합니다. callable 은 두 개의 string 인자를 받으며, integer 를 반환해야 합니다.

첫 번째가 두 번째보다 높게 정렬되는 경우 1
첫 번째가 두 번째보다 낮게 정렬되는 경우 -1
두 값이 동일하게 정렬되는 경우 0

다음 예제는 역순 정렬 콜레이션을 보여줍니다:

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.execute("CREATE TABLE test(x)")
cur.executemany("INSERT INTO test(x) VALUES(?)", [("a",), ("b",)])
cur.execute("SELECT x FROM test ORDER BY x COLLATE reverse")
for row in cur:
    print(row)
con.close()

callable 을 None 으로 설정하여 콜레이션 함수를 제거합니다.

버전 3.11에서 변경: 콜레이션 이름에는 모든 유니코드 문자를 포함할 수 있습니다. 이전에는 ASCII 문자만 허용되었습니다.

interrupt()¶: 연결에서 실행 중일 수 있는 모든 쿼리를 중단하려면 다른 스레드에서 이 메서드를 호출하십시오. 중단된 쿼리는 OperationalError 를 발생시킵니다.

set_authorizer(authorizer_callback, /)¶

데이터베이스의 테이블 컬럼에 액세스할 때마다 호출될 callable authorizer_callback 을 등록합니다. 콜백은 하부 SQLite 라이브러리에서 해당 컬럼에 대한 액세스를 어떻게 처리해야 하는지 신호하기 위해 SQLITE_OK, SQLITE_DENY, 또는 SQLITE_IGNORE 중 하나를 반환해야 합니다.

콜백의 첫 번째 인자는 승인될 작업의 종류를 나타냅니다. 두 번째와 세 번째 인자는 첫 번째 인수에 따라 인자 또는 None 이 됩니다. 4번째 인자는 해당되는 경우 데이터베이스 이름(“main”, “temp” 등)입니다. 5번째 인자는 액세스 시도에 책임이 있는 가장 안쪽의 트리거나 뷰의 이름이며, 이 액세스 시도가 입력 SQL 코드에서 직접 수행된 경우 None 입니다.

첫 번째 인자의 가능한 값과 첫 번째 인수에 따른 두 번째 및 세 번째 인자의 의미에 대해서는 SQLite 문서를 참조하십시오. 필요한 모든 상수는 sqlite3 모듈에서 사용할 수 있습니다.

authorizer_callback 으로 None 을 전달하면 승인자가 비활성화됩니다.

버전 3.11에서 변경: None 을 사용하여 승인자를 비활성화하는 기능을 추가했습니다.

버전 3.15에서 변경: 유일한 매개변수가 이제 위치 전용(positional-only)입니다.

set_progress_handler(progress_handler, /, n)¶

SQLite 가상 머신의 모든 n 개 명령마다 호출될 callable progress_handler 를 등록합니다. 이는 GUI 업데이트와 같이 긴 실행 시간이 소요되는 작업 중에 SQLite로부터 호출을 받고자 할 때 유용합니다.

이전에 설치된 프로그레스 핸들러를 지우려면 progress_handler 에 None 을 넣어 메서드를 호출하십시오.

핸들러 함수에서 0이 아닌 값을 반환하면 현재 실행 중인 쿼리가 종료되고 DatabaseError 예외가 발생합니다.

버전 3.15에서 변경: 첫 번째 매개변수가 이제 위치 전용입니다.

set_trace_callback(trace_callback, /)¶

SQLite 백엔드에 의해 실제로 실행되는 각 SQL 문마다 호출될 callable trace_callback 을 등록합니다.

콜백에 전달되는 유일한 인수는 실행 중인 문( str)입니다. 콜백의 반환 값은 무시됩니다. 백엔드가 Cursor.execute() 메서드에 전달된 문만을 실행하는 것은 아닙니다. 다른 출처에는 sqlite3 모듈의 트랜잭션 관리 및 현재 데이터베이스에 정의된 트리거 실행이 포함됩니다.

trace_callback 으로 None 을 전달하면 트레이스 콜백이 비활성화됩니다.

참고

Exceptions raised in the trace callback are not propagated. As a development and debugging aid, use enable_callback_tracebacks() to enable printing tracebacks from exceptions raised in the trace callback.

Added in version 3.3.

버전 3.15에서 변경: 첫 번째 매개변수가 이제 위치 전용입니다.

enable_load_extension(enabled, /)¶

enabled 가 True 이면 SQLite 엔진이 공유 라이브러리에서 SQLite 확장을 로드할 수 있게 하고, 그렇지 않으면 SQLite 확장 로드를 허용하지 않습니다. SQLite 확장은 새로운 함수, 집계(aggregate) 또는 완전히 새로운 가상 테이블 구현을 정의할 수 있습니다. 잘 알려진 확장 중 하나는 SQLite와 함께 배포되는 전체 텍스트 검색(fulltext-search) 확장입니다.

참고

일부 플랫폼(특히 macOS)의 SQLite 라이브러리가 이 기능 없이 컴파일되었기 때문에, sqlite3 모듈은 기본적으로 로드 가능한 확장을 지원하도록 빌드되지 않습니다. 로드 가능한 확장 지원을 얻으려면 configure 에 --enable-loadable-sqlite-extensions 옵션을 전달해야 합니다.

connection, enabled 인자를 사용하여 auditing event sqlite3.enable_load_extension 을 발생시킵니다.

Added in version 3.2.

버전 3.10에서 변경: sqlite3.enable_load_extension 감사 이벤트를 추가했습니다.

con.enable_load_extension(True)

# Load the fulltext search extension
con.execute("select load_extension('./fts3.so')")

# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")

# disable extension loading again
con.enable_load_extension(False)

# example from SQLite wiki
con.execute("CREATE VIRTUAL TABLE recipe USING fts3(name, ingredients)")
con.executescript("""
    INSERT INTO recipe (name, ingredients) VALUES('broccoli stew', 'broccoli peppers cheese tomatoes');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin stew', 'pumpkin onions garlic celery');
    INSERT INTO recipe (name, ingredients) VALUES('broccoli pie', 'broccoli cheese onions flour');
    INSERT INTO recipe (name, ingredients) VALUES('pumpkin pie', 'pumpkin sugar flour butter');
    """)
for row in con.execute("SELECT rowid, name, ingredients FROM recipe WHERE name MATCH 'pie'"):
    print(row)

load_extension(path, /, *, entrypoint=None)¶

공유 라이브러리에서 SQLite 확장을 로드합니다. 이 메서드를 호출하기 전에 enable_load_extension() 을 사용하여 확장 로드를 활성화하십시오.

매개변수:

path (str) – SQLite 확장의 경로입니다.
entrypoint (str | None) – 진입점(entry point) 이름입니다. None (기본값)인 경우, SQLite가 자체적인 진입점 이름을 결정합니다. 자세한 내용은 SQLite 문서의 Loading an Extension 을 참조하십시오.

connection, path 인자를 사용하여 auditing event sqlite3.load_extension 를 발생시킵니다.

Added in version 3.2.

버전 3.10에서 변경: sqlite3.load_extension 감사 이벤트를 추가했습니다.

버전 3.12에서 변경: entrypoint 매개 변수를 추가했습니다.

iterdump(*, filter=None)¶

데이터베이스를 SQL 소스 코드로 덤프하는 iterator 를 반환합니다. 나중에 복구하기 위해 메모리 내 데이터베이스를 저장할 때 유용합니다. sqlite3 셸의 .dump 명령과 유사합니다.

매개변수:: filter (str | None) – 덤프할 데이터베이스 객체에 대한 선택적 LIKE 패턴입니다(예: prefix_%). None (기본값)인 경우 모든 데이터베이스 객체가 포함됩니다.

예:

# Convert file example.db to SQL dump file dump.sql
con = sqlite3.connect('example.db')
with open('dump.sql', 'w') as f:
    for line in con.iterdump():
        f.write('%s\n' % line)
con.close()

비 UTF-8 텍스트 인코딩 처리 방법

버전 3.13에서 변경: filter 매개 변수를 추가했습니다.

backup(target, *, pages=-1, progress=None, name='main', sleep=0.250)¶

SQLite 데이터베이스의 백업을 생성합니다.

다른 클라이언트가 접근 중이거나 동일한 연결에서 동시에 접근 중인 경우에도 작동합니다.

매개변수:

target (Connection) – 백업을 저장할 데이터베이스 연결입니다.
pages (int) – 한 번에 복사할 페이지 수입니다. 0 이하인 경우 전체 데이터베이스가 한 단계로 복사됩니다. 기본값은 -1 입니다.
progress (callback | None) – callable 인 경우, 매 백업 반복마다 세 개의 정수 인자(마지막 반복의 status, 아직 복사해야 할 남은 페이지 수인 remaining, 전체 페이지 수인 total)와 함께 호출됩니다. 기본값은 None 입니다.
name (str) – 백업할 데이터베이스 이름입니다. 메인 데이터베이스의 경우 "main"``(기본값), 임시 데이터베이스의 경우 ``"temp", 또는 ATTACH DATABASE SQL 문을 사용하여 연결된 사용자 정의 데이터베이스의 이름을 입력합니다.
sleep (float) – 남은 페이지를 백업하기 위한 연속적인 시도 사이에 대기할 시간(초)입니다.

예제 1, 기존 데이터베이스를 다른 곳으로 복사:

def progress(status, remaining, total):
    print(f'Copied {total-remaining} of {total} pages...')

src = sqlite3.connect('example.db')
dst = sqlite3.connect('backup.db')
with dst:
    src.backup(dst, pages=1, progress=progress)
dst.close()
src.close()

예제 2, 기존 데이터베이스를 일시적인 복사본으로 복사:

src = sqlite3.connect('example.db')
dst = sqlite3.connect(':memory:')
src.backup(dst)
dst.close()
src.close()

Added in version 3.7.

비 UTF-8 텍스트 인코딩 처리 방법

getlimit(category, /)¶

연결 실행 제한을 가져옵니다.

매개변수:: category (int) – 쿼리할 SQLite limit category 입니다.
반환 형식:: int
예외 발생:: ProgrammingError – category 가 하부 SQLite 라이브러리에 의해 인식되지 않는 경우.

예: Connection con 에 대한 SQL 문의 최대 길이를 조회(기본값은 1,000,000,000):

>>> con.getlimit(sqlite3.SQLITE_LIMIT_SQL_LENGTH)
1000000000

Added in version 3.11.

setlimit(category, limit, /)¶

연결 실행 제한을 설정합니다. 한계값을 하드 상한선보다 높게 올리려는 시도는 조용히 해당 상한선으로 잘립니다. 제한이 변경되었는지 여부와 상관없이 이전의 제한 값이 반환됩니다.

매개변수:

category (int) – 설정할 SQLite limit category 입니다.
limit (int) – 새로운 한계 값입니다. 음수인 경우 현재 한계는 변경되지 않습니다.

반환 형식:

int

예외 발생:

ProgrammingError – category 가 하부 SQLite 라이브러리에 의해 인식되지 않는 경우.

예: Connection con 에 대해 연결된 데이터베이스 수를 1로 제한(기본 제한은 10):

>>> con.setlimit(sqlite3.SQLITE_LIMIT_ATTACHED, 1)
10
>>> con.getlimit(sqlite3.SQLITE_LIMIT_ATTACHED)
1

Added in version 3.11.

getconfig(op, /)¶

불리언형 연결 구성 옵션을 조회합니다.

매개변수:: op (int) – 하나의 SQLITE_DBCONFIG code 입니다.
반환 형식:: bool

Added in version 3.12.

setconfig(op, enable=True, /)¶

불리언형 연결 구성 옵션을 설정합니다.

매개변수:

op (int) – 하나의 SQLITE_DBCONFIG code 입니다.
enable (bool) – 구성 옵션을 활성화해야 하는 경우 True (기본값), 비활성화해야 하는 경우 False 입니다.

Added in version 3.12.

serialize(*, name='main')¶

데이터베이스를 bytes 객체로 직렬화합니다. 일반적인 디스크 파일의 경우, 직렬화는 단순히 디스크 파일의 복사본입니다. 메모리 내 데이터베이스나 “temp” 데이터베이스의 경우, 직렬화는 해당 데이터베이스를 디스크에 백업할 때 작성될 것과 동일한 바이트 시퀀스입니다.

매개변수:: name (str) – 직렬화할 데이터베이스 이름입니다. 기본값은 "main" 입니다.
반환 형식:: bytes

참고

이 메서드는 하부 SQLite 라이브러리에 serialize API가 있는 경우에만 사용 가능합니다.

Added in version 3.11.

deserialize(data, /, *, name='main')¶

serialized 된 데이터베이스를 Connection 으로 역직렬화합니다. 이 메서드는 데이터베이스 연결을 name 에서 해제하고, data 에 포함된 직렬화 내용을 기반으로 name 을 메모리 내 데이터베이스로 다시 엽니다.

매개변수:

data (bytes) – 직렬화된 데이터베이스입니다.
name (str) – 역직렬화할 대상 데이터베이스 이름입니다. 기본값은 "main" 입니다.

예외 발생:

OperationalError – 데이터베이스 연결이 현재 읽기 트랜잭션이나 백업 작업에 참여 중인 경우.
DatabaseError – data 가 유효한 SQLite 데이터베이스를 포함하지 않는 경우.
OverflowError – len(data) 이 2**63 - 1 보다 큰 경우.

참고

이 메서드는 하부 SQLite 라이브러리에 deserialize API가 있는 경우에만 사용 가능합니다.

Added in version 3.11.

autocommit¶

이 어트리뷰트는 PEP 249 을 준수하는 트랜잭션 동작을 제어합니다. autocommit 은 세 가지 허용된 값을 가집니다.

False: PEP 249 를 준수하는 트랜잭션 동작을 선택하며, 이는 sqlite3 가 항상 트랜잭션을 열려 있는 상태로 유지함을 의미합니다. 트랜잭션을 닫으려면 commit() 및 rollback() 을 사용하십시오.

이것은 autocommit 의 권장값입니다.
True: SQLite의 autocommit mode 를 사용합니다. 이 모드에서는 commit() 및 rollback() 이 아무런 효과가 없습니다.
LEGACY_TRANSACTION_CONTROL: Python 3.12 이전(비-PEP 249 준수) 트랜잭션 제어입니다. 자세한 내용은 isolation_level 을 참조하십시오.

이것은 현재 autocommit 의 기본값입니다.

autocommit 을 False 로 변경하면 새로운 트랜잭션이 열리고, True 로 변경하면 대기 중인 모든 트랜잭션이 커밋됩니다.

자세한 내용은 autocommit 속성을 통한 트랜잭션 제어 을 참조하십시오.

참고

autocommit 이 LEGACY_TRANSACTION_CONTROL 인 경우를 제외하고, isolation_level 어트리뷰트는 아무런 영향을 미치지 않습니다.

Added in version 3.12.

in_transaction¶

This read-only attribute corresponds to the low-level SQLite autocommit mode.

트랜잭션이 활성화된 경우(커밋되지 않은 변경 사항이 있는 경우) True, 그렇지 않으면 False 입니다.

Added in version 3.2.

isolation_level¶

sqlite3 의 legacy transaction handling mode 를 제어합니다. None 으로 설정하면 트랜잭션이 자동으로 열리지 않습니다. "DEFERRED", "IMMEDIATE" 또는 "EXCLUSIVE" 중 하나로 설정하면 해당 값에 대응하는 하부 SQLite transaction behaviour 에 따라 implicit transaction management 가 수행됩니다.

connect() 의 isolation_level 매개변수에 의해 덮어써지지 않는 경우 기본값은 "" 이며, 이는 "DEFERRED" 의 별칭입니다.

참고

트랜잭션 처리를 제어할 때는 isolation_level 대신 autocommit 을 사용하는 것이 권장됩니다. isolation_level 은 autocommit 이 LEGACY_TRANSACTION_CONTROL (기본값)로 설정된 경우에만 효과가 있습니다.

row_factory¶

이 연결에서 생성된 Cursor 객체들의 초기 row_factory 입니다. 이 어트리뷰트에 값을 할당해도 기존 커서의 row_factory 에는 영향을 미치지 않으며, 새로 생성되는 커서에만 적용됩니다. 기본값은 None 이며, 이 경우 각 행은 tuple 로 반환됩니다.

자세한 내용은 행 팩토리 생성 및 사용 방법 를 참조하십시오.

버전 3.16.0a0 (unreleased)에서 변경: row_factory 어트리뷰트를 삭제하는 것은 더 이상 허용되지 않습니다.

text_factory¶

bytes 매개 변수를 받아 텍스트 표현을 반환하는 callable 입니다. 이 콜러블은 데이터 타입이 TEXT 인 SQLite 값에 대해 호출됩니다. 기본적으로 이 어트리뷰트는 str 로 설정됩니다.

자세한 내용은 비 UTF-8 텍스트 인코딩 처리 방법 을 참조하십시오.

버전 3.16.0a0 (unreleased)에서 변경: text_factory 어트리뷰트를 삭제하는 것은 더 이상 허용되지 않습니다.

total_changes¶: 데이터베이스 연결이 열린 이후 수정, 삽입 또는 삭제된 전체 행의 수를 반환합니다.

커서 객체¶

Cursor 객체는 SQL 문을 실행하고 가져오기(fetch) 작업의 컨텍스트를 관리하는 데 사용되는 database cursor 를 나타냅니다. 커서는 Connection.cursor() 를 사용하거나, connection shortcut methods 중 하나를 사용하여 생성됩니다.

커서 객체는 이터레이터 입니다. 즉, execute() 로 SELECT 쿼리를 실행하면 커서를 반복(iterate)하여 결과 행을 가져올 수 있습니다.
for row in cur.execute("SELECT t FROM data"):
    print(row)

class sqlite3.Cursor¶

Cursor 인스턴스에는 다음과 같은 어트리뷰트와 메서드가 있습니다.

execute(sql, parameters=(), /)¶

단일 SQL 문을 실행합니다. 선택적으로 placeholders 를 사용하여 파이썬 값을 바인딩할 수 있습니다.

매개변수:

sql (str) – 단일 SQL 문입니다.
parameters (dict | sequence) – sql 의 자리 표시자에 바인딩할 파이썬 값입니다. 이름 있는 자리 표시자를 사용하는 경우 dict 를, 이름 없는 자리 표시자를 사용하는 경우 sequence 를 사용합니다. 자세한 내용은 SQL 쿼리에서 값을 바인딩하기 위한 자리 표시자 사용 방법 를 참조하십시오.

예외 발생:

ProgrammingError – sql 이 하나 이상의 SQL 문을 포함하는 경우입니다. 또는 named placeholders 를 사용하면서 parameters 가 dict 대신 시퀀스인 경우입니다.

autocommit 이 LEGACY_TRANSACTION_CONTROL 이고, isolation_level 이 None 이 아니며, sql 이 INSERT, UPDATE, DELETE 또는 REPLACE 문이고 현재 열려 있는 트랜잭션이 없는 경우, sql 을 실행하기 전에 트랜잭션이 묵시적으로 생성됩니다.

버전 3.14에서 변경: named placeholders 를 사용하면서 parameters 가 dict 대신 시퀀스인 경우 ProgrammingError 가 발생합니다.

여러 개의 SQL 문을 실행하려면 executescript() 를 사용하십시오.

executemany(sql, parameters, /)¶

parameters 의 모든 항목에 대해, parameterized 방식인 DML SQL 문 sql 을 반복해서 실행합니다.

execute() 와 동일한 묵시적 트랜잭션 처리를 사용합니다.

매개변수:

sql (str) – 단일 SQL DML 문입니다.
parameters (iterable) – sql 의 자리 표시자와 바인딩할 매개 변수들의 iterable 입니다. 자세한 내용은 SQL 쿼리에서 값을 바인딩하기 위한 자리 표시자 사용 방법 를 참조하십시오.

예외 발생:

ProgrammingError – sql 이 하나 이상의 SQL 문을 포함하거나 DML 문이 아닌 경우에 해당합니다. 또는 named placeholders 를 사용하면서 parameters 의 항목들이 dict 대신 시퀀스인 경우입니다.

예:

rows = [
    ("row1",),
    ("row2",),
]
# cur은 sqlite3.Cursor 객체입니다.
cur.executemany("INSERT INTO data VALUES(?)", rows)

참고

RETURNING clauses 를 포함한 DML 문을 포함하여 모든 결과 행이 버려집니다.

버전 3.14에서 변경: named placeholders 를 사용하면서 parameters 의 항목들이 dict 대신 시퀀스인 경우 ProgrammingError 가 발생합니다.

executescript(sql_script, /)¶

sql_script 내의 SQL 문들을 실행합니다. autocommit 이 LEGACY_TRANSACTION_CONTROL 이고 처리 중인 트랜잭션이 있는 경우, 먼저 묵시적인 COMMIT 문이 실행됩니다. 그 외의 묵시적 트랜잭션 제어는 수행되지 않으므로 모든 트랜잭션 제어는 sql_script 에 포함되어야 합니다.

sql_script 은(는) string 이어야 합니다.

예:

# cur은 sqlite3.Cursor 객체입니다.
cur.executescript("""
    BEGIN;
    CREATE TABLE person(firstname, lastname, age);
    CREATE TABLE book(title, author, published);
    CREATE TABLE publisher(name, address);
    COMMIT;
""")

fetchone()¶: row_factory 가 None 이면 다음 행의 쿼리 결과 집합을 tuple 로 반환합니다. 그렇지 않으면 결과를 로우 팩토리에 전달하여 그 결과를 반환합니다. 더 이상 데이터가 없으면 None 을 반환합니다.

fetchmany(size=cursor.arraysize)¶

쿼리 결과의 다음 행 세트를 list 로 반환합니다. 더 이상 결과가 없으면 빈 리스트를 반환합니다.

호출당 가져올 행의 수는 size 매개 변수에 의해 결정됩니다. size 가 제공되지 않으면 arraysize 가 가져올 행의 수를 결정합니다. 사용 가능한 행이 size 보다 적은 경우, 사용할 수 있는 만큼의 행을 반환합니다.

size 매개 변수와 관련된 성능 고려 사항이 있습니다. 최적의 성능을 위해서, 일반적으로 arraysize 어트리뷰트를 사용하는 것이 가장 좋습니다. size 매개 변수가 사용되면, fetchmany() 호출마다 같은 값을 유지하는 것이 가장 좋습니다.

버전 3.15에서 변경: 음수인 size 값은 ValueError 를 발생시켜 거부됩니다.

fetchall()¶: 쿼리 결과의 모든(남은) 행을 list 로 반환합니다. 행이 없으면 빈 리스트를 반환합니다. 참고로 arraysize 어트리뷰트가 이 작업의 성능에 영향을 줄 수 있습니다.

close()¶

(__del__이 호출 될 때가 아니라) 지금 커서를 닫습니다.

이 시점부터는 커서를 사용할 수 없습니다; 커서로 어떤 연산이건 시도하면 ProgrammingError 예외가 발생합니다.

setinputsizes(sizes, /)¶: DB-API에서 요구하는 항목입니다. sqlite3 에서는 아무런 동작도 수행하지 않습니다.

setoutputsize(size, column=None, /)¶: DB-API에서 요구하는 항목입니다. sqlite3 에서는 아무런 동작도 수행하지 않습니다.

arraysize¶: fetchmany()에 의해 반환되는 행의 수를 제어하는 읽기/쓰기 어트리뷰트. 기본값은 1입니다. 이는 호출 당 하나의 행을 가져오는 것을 뜻합니다.

버전 3.15에서 변경: 음수 값은 ValueError 를 발생시켜 거부됩니다.

connection¶

커서가 속한 SQLite 데이터베이스 Connection 을 제공하는 읽기 전용 어트리뷰트입니다. con.cursor() 를 호출하여 생성된 Cursor 객체는 con 을 가리키는 connection 어트리뷰트를 갖게 됩니다.

>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
>>> con.close()

description¶

마지막 쿼리의 열 이름을 제공하는 읽기 전용 어트리뷰트입니다. Python DB API와 호환성을 유지하기 위해 각 열에 대해 마지막 6개 항목이 None 인 7-튜플을 반환합니다.

일치하는 행이 없는 SELECT 문에도 설정됩니다.

lastrowid¶: 마지막으로 삽입된 행의 ID를 제공하는 읽기 전용 어트리뷰트입니다. execute() 메서드를 사용하여 성공적인 INSERT 또는 REPLACE 문이 실행된 후에만 업데이트됩니다. 다른 구문의 경우, executemany() 나 executescript() 이후에 혹은 삽입에 실패한 경우에도 lastrowid 값은 변경되지 않습니다. lastrowid 의 초기값은 None 입니다.

참고

WITHOUT ROWID 테이블에 삽입된 데이터는 기록되지 않습니다.

버전 3.6에서 변경: REPLACE 문에 대한 지원이 추가되었습니다.

rowcount¶: INSERT, UPDATE, DELETE, 그리고 REPLACE 문에 대해 수정된 행의 수를 제공하는 읽기 전용 어트리뷰트입니다. CTE 쿼리를 포함한 다른 구문은 -1 을 반환합니다. 이 값은 execute() 및 executemany() 메서드에 의해 문장이 완전히 실행된 후에만 업데이트됩니다. 즉, rowcount 이 업데이트되려면 결과 행을 순차적으로 모두 가져와야 합니다.

row_factory¶

이 Cursor 에서 가져온 행이 표현되는 방식을 제어합니다. None 인 경우 행은 tuple 로 표현됩니다. 포함된 sqlite3.Row; 또는 Cursor 객체와 행 값의 tuple 을 두 개의 인자로 받아 SQLite 행을 나타내는 사용자 정의 객체를 반환하는 callable 로 설정할 수 있습니다.

Cursor 가 생성될 당시의 Connection.row_factory 설정값을 기본으로 합니다. 이 어트리뷰트에 값을 할당해도 부모 연결의 Connection.row_factory 에는 영향을 미치지 않습니다.

자세한 내용은 행 팩토리 생성 및 사용 방법 를 참조하십시오.

버전 3.16.0a0 (unreleased)에서 변경: row_factory 어트리뷰트를 삭제하는 것은 더 이상 허용되지 않습니다.

행 객체¶

class sqlite3.Row¶

Row 인스턴스는 Connection 객체를 위한 고도로 최적화된 row_factory 역할을 합니다. 이 모델은 반복(iteration), 동일성 테스트, len(), 그리고 열 이름 및 인덱스를 통한 mapping 액세스를 지원합니다.

두 개의 Row 객체가 동일한 열 이름과 값을 가지면 서로 같다고 판단됩니다.

자세한 내용은 행 팩토리 생성 및 사용 방법 를 참조하십시오.

keys()¶: 열 이름을 string 의 list 로 반환합니다. 쿼리 직후에는 Cursor.description 에 있는 각 튜플의 첫 번째 요소가 됩니다.

버전 3.5에서 변경: 슬라이싱 지원이 추가되었습니다.

블롭 객체¶

class sqlite3.Blob¶

Added in version 3.11.

Blob 인스턴스는 SQLite BLOB 에서 데이터를 읽고 쓸 수 있는 파일류 객체 입니다. 블롭의 크기(바이트 수)를 확인하려면 len(blob) 을 호출하십시오. 블롭 데이터에 직접 접근하려면 인덱스와 슬라이스 를 사용하십시오.

blob 핸들이 사용 후에 닫히도록 Blob 을 컨텍스트 관리자 로 사용하십시오.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE test(blob_col blob)")
con.execute("INSERT INTO test(blob_col) VALUES(zeroblob(13))")

# 두 번의 쓰기 작업을 사용하여 블롭에 씁니다:
with con.blobopen("test", "blob_col", 1) as blob:
    blob.write(b"hello, ")
    blob.write(b"world.")
    # 블롭의 첫 번째와 마지막 바이트를 수정합니다
    blob[0] = ord("H")
    blob[-1] = ord("!")

# 블롭 내용 읽기
with con.blobopen("test", "blob_col", 1) as blob:
    greeting = blob.read()

print(greeting)  # 출력: "b'Hello, world!'"
con.close()

close()¶

블롭을 닫습니다.

이 시점부터 블롭을 사용할 수 없습니다. 블롭으로 추가적인 작업을 시도하면 Error (또는 하위 클래스) 예외가 발생합니다.

read(length=-1, /)¶: 현재 오프셋 위치에서 blob으로부터 length 바이트의 데이터를 읽습니다. blob의 끝에 도달하면 EOF 까지의 데이터가 반환됩니다. length 가 지정되지 않거나 음수인 경우, read() 는 blob의 끝까지 읽습니다.

write(data, /)¶: 현재 오프셋 위치의 blob에 data 를 씁니다. 이 함수는 blob의 길이를 변경할 수 없습니다. blob의 끝을 넘어서 쓰는 경우 ValueError 가 발생합니다.

tell()¶: blob의 현재 접근 위치를 반환합니다.

seek(offset, origin=os.SEEK_SET, /)¶: blob의 현재 접근 위치를 offset 으로 설정합니다. origin 인수는 기본값으로 os.SEEK_SET (절대적인 blob 위치 지정)을 사용합니다. origin 에 대한 다른 값은 os.SEEK_CUR (현재 위치 기준 이동) 및 :40:c19d21 os.SEEK_END (blob 끝 기준 이동)이 있습니다.

PrepareProtocol 객체¶

class sqlite3.PrepareProtocol¶: PrepareProtocol 타입의 유일한 목적은 자신을 네이티브 SQLite 타입 으로 직접 어댑트할 수 있는 객체들을 위한 PEP 246 스타일의 어댑션 프로토콜 역할을 수행하는 것입니다.

예외¶

예외 계층은 DB-API 2.0(PEP 249)에 의해 정의됩니다.

exception sqlite3.Warning¶: 이 예외는 현재 sqlite3 모듈에 의해 발생하지 않으나, 사용자 정의 함수가 삽입 중에 데이터를 잘라내는 경우와 같이 sqlite3 를 사용하는 애플리케이션에서 발생할 수 있습니다. Warning 은 Exception 의 하위 클래스입니다.

exception sqlite3.Error¶

이 모듈에 있는 다른 예외들의 기본 클래스입니다. 하나의 except 문으로 모든 오류를 잡으려면 이를 사용하십시오. Error 는 Exception 의 하위 클래스입니다.

예외가 SQLite 라이브러리 내부에서 발생한 경우, 예외에 다음 두 속성이 추가됩니다:

sqlite_errorcode¶: SQLite API 의 숫자 에러 코드입니다.

Added in version 3.11.

sqlite_errorname¶: SQLite API 의 숫자 에러 코드에 대한 심볼릭 이름입니다.

Added in version 3.11.

exception sqlite3.InterfaceError¶: 저수준 SQLite C API를 잘못 사용했을 때 발생하는 예외입니다. 즉, 이 예외가 발생하면 sqlite3 모듈의 버그일 가능성이 높습니다. InterfaceError 는 Error 의 하위 클래스입니다.

exception sqlite3.DatabaseError¶: 데이터베이스와 관련된 오류에 대해 발생하는 예외입니다. 이는 여러 유형의 데이터베이스 오류에 대한 기본 예외 역할을 합니다. 이 예외는 전용 하위 클래스를 통해서만 묵시적으로 발생합니다. DatabaseError 는 Error 의 하위 클래스입니다.

exception sqlite3.DataError¶: 범위를 벗어난 숫자 값이나 너무 긴 문자열과 같이 처리된 데이터의 문제로 인해 발생하는 예량입니다. DataError 는 DatabaseError 의 하위 클래스입니다.

exception sqlite3.OperationalError¶: 데이터베이스 작업과 관련되어 있으며 프로그래머의 제어 하에 있지 않은 오류에 대해 발생하는 예외입니다. 예를 들어, 데이터베이스 경로를 찾을 수 없거나 트랜잭션을 처리할 수 없는 경우 등이 해당됩니다. OperationalError 는 DatabaseError 의 하위 클래스입니다.

exception sqlite3.IntegrityError¶: 데이터베이스의 관계형 무결성이 영향을 받을 때 발생하는 예외. 예를 들어, 외부 키(foreign key) 검사가 실패할 때. DatabaseError의 서브 클래스입니다.

exception sqlite3.InternalError¶: SQLite가 내부 오류를 감지했을 때 발생하는 예외입니다. 이 예외가 발생하면 런타임 SQLite 라이브러리에 문제가 있음을 나타낼 수 있습니다. InternalError 는 DatabaseError 의 하위 클래스입니다.

exception sqlite3.ProgrammingError¶: sqlite3 API 프로그래밍 오류가 발생했을 때 발생하는 예외이며, 예를 들어 쿼리에 바인딩되는 바인딩 수가 잘못되었거나 연결된 Connection 객체가 닫혔을 때 운영하려고 시도하는 경우입니다. ProgrammingError 는 DatabaseError 의 서브클래스입니다.

exception sqlite3.NotSupportedError¶: 기본 SQLite 라이브러리가 메서드나 데이터베이스 API를 지원하지 않을 때 발생하는 예량입니다. 예를 들어, 기본 SQLite 라이브러리가 결정론적 함수를 지원하지 않는데 create_function() 에서 deterministic 을 True 로 설정하는 경우입니다. NotSupportedError 는 DatabaseError 의 하위 클래스입니다.

SQLite 와 파이썬 형¶

SQLite는 기본적으로 다음 형을 지원합니다: NULL, INTEGER, REAL, TEXT, BLOB.

따라서 다음과 같은 파이썬 형을 아무 문제 없이 SQLite로 보낼 수 있습니다:

파이썬 형	SQLite 형
`None`	`NULL`
`int`	`INTEGER`
`float`	`REAL`
`str`	`TEXT`
`bytes`	`BLOB`

이것은 SQLite 형이 기본적으로 파이썬 형으로 변환되는 방법입니다:

SQLite 형	파이썬 형
`NULL`	`None`
`INTEGER`	`int`
`REAL`	`float`
`TEXT`	`text_factory`에 따라 다릅니다, 기본적으로 `str`.
`BLOB`	`bytes`

sqlite3 모듈의 타입 시스템은 두 가지 방식으로 확장할 수 있습니다. 객체 어댑터 를 통해 SQLite 데이터베이스에 추가적인 파이썬 타입을 저장하거나, 변환기 를 통해 sqlite3 모듈이 SQLite 유형을 파이썬 유형으로 변환하게 할 수 있습니다.

기본 어댑터 및 변환기 (더 이상 권장되지 않음)¶

참고

기본 어댑터와 변환기는 파이썬 3.12부터 더 이상 권장되지 않습니다. 대신 어댑터 및 변환기 레시피 를 사용하고 필요에 맞게 조정하십시오.

더 이상 권장되지 않는 기본 어댑터 및 변환기는 다음과 같습니다:

datetime.date 객체를 ISO 8601 형식의 문자열 으로 변환하는 어댑터입니다.
datetime.datetime 객체를 ISO 8601 형식의 문자열로 변환하는 어댑터입니다.
declared “date” 타입을 datetime.date 객체로 변환하는 커버터입니다.
선언된 “timestamp” 유형을 datetime.datetime 객체로 변환하는 어댑터입니다. 소수점 부분은 6자리(마이크로초 정밀도)로 절사됩니다.

참고

기본 “timestamp” 변환기는 데이터베이스의 UTC 오프셋을 무시하고 항상 일반(naive) datetime.datetime 객체를 반환합니다. 타임스탬프에서 UTC 오프셋을 유지하려면 변환 기능을 비활성화 상태로 두거나, register_converter() 를 사용하여 오프셋을 인식하는 변환기를 등록하십시오.

버전 3.12부터 폐지됨.

명령 줄 인터페이스¶

sqlite3 모듈은 인터프리터의 -m 스위치를 사용하여 스크립트로 호출할 수 있으며, 이를 통해 간단한 SQLite 셸을 제공합니다. 인자 구조는 다음과 같습니다:

python -m sqlite3 [-h] [-v] [filename] [sql]

셸을 종료하려면 .quit 을 입력하거나 CTRL-D를 누르십시오.

-h, --help¶: CLI 도움말을 출력합니다.

-v, --version¶: 기본이 되는 SQLite 라이브러리 버전을 출력합니다.

Added in version 3.12.

사용법 가이드¶

SQL 쿼리에서 값을 바인딩하기 위한 자리 표시자 사용 방법¶

일반적으로 SQL 연산에서는 Python 변수의 값을 사용해야 합니다. 하지만, 파이썬의 문자열 연산을 사용하여 쿼리를 조합하면 SQL injection attacks 에 취약해지므로 주의해야 합니다. 예를 들어, 공격자는 따옴표를 닫고 OR TRUE 를 주입하여 모든 행을 선택할 수 있습니다:

>>> # 절대로 이렇게 하지 마세요 -- 보안에 취약함!
>>> symbol = input()
' OR TRUE; --
>>> sql = "SELECT * FROM stocks WHERE symbol = '%s'" % symbol
>>> print(sql)
SELECT * FROM stocks WHERE symbol = '' OR TRUE; --
>>> cur.execute(sql)

대신 DB-API의 매개 변수 치환을 사용하십시오. 쿼리 문자열에 변수를 삽입하려면 문자열에 자리 표시자를 사용하고, 커서의 execute() 메서드의 두 번째 인자로 값들의 tuple 을 전달하여 실제 값을 치환하십시오.

SQL 문은 두 가지 종류의 자리 표시자 중 하나를 사용할 수 있습니다: 물음표(qmark 스타일) 또는 이름 있는 자리 표시자(named 스타일). qmark 스타일의 경우, parameters 는 자리 표시자의 개수와 일치하는 길이를 가진 sequence 여야 하며, 그렇지 않으면 ProgrammingError 가 발생합니다. named 스타일의 경우, parameters 는 모든 이름이 있는 매개 변수에 대한 키를 포함해야 하는 dict 의 인스턴스(또는 하위 클래스)여야 하며 추가 항목은 무시됩니다. 두 방식에 대한 예시는 다음과 같습니다:

con = sqlite3.connect(":memory:")
cur = con.execute("CREATE TABLE lang(name, first_appeared)")

# executemany()와 함께 사용되는 named 스타일:
data = (
    {"name": "C", "year": 1972},
    {"name": "Fortran", "year": 1957},
    {"name": "Python", "year": 1991},
    {"name": "Go", "year": 2009},
)
cur.executemany("INSERT INTO lang VALUES(:name, :year)", data)

# SELECT 쿼리에서 사용되는 qmark 스타일:
params = (1972,)
cur.execute("SELECT * FROM lang WHERE first_appeared = ?", params)
print(cur.fetchall())
con.close()

참고

PEP 249 숫자 자리 표시자는 지원되지 않습니다. 사용 시 이름이 있는 자리 표시자로 해석됩니다.

사용자 정의 파이썬 타입을 SQLite 값으로 어댑트하는 방법¶

SQLite는 기본적으로 제한된 데이터 타입만 지원합니다. SQLite 데이터베이스에 사용자 정의 파이썬 타입을 저장하려면, 이를 네이티브하게 이해되는 파이썬 유형 중 하나로 어댑트 하십시오.

파이썬 객체를 SQLite 타입으로 어댑트하는 두 가지 방법이 있습니다: 객체가 스스로 어댑트하게 하거나, 어댑터 콜러블 을 사용하는 것입니다. 후자가 전자의 경우보다 우선합니다. 사용자 정의 타입을 내보내는 라이브러리의 경우 해당 유형이 스스로 어댑트할 수 있도록 활성화하는 것이 적절할 수 있으며, 애플리케이션 개발자라면 커스텀 어댑터 함수를 등록하여 직접 제어하는 것이 더 나을 수 있습니다.

어댑터가 가능한 객체 작성 방법¶

데카르트 좌표계에서 한 쌍의 좌표인 x 와 y 를 나타내는 Point 클래스가 있다고 가정해 봅시다. 이 좌표쌍은 세미콜론으로 구분된 텍스트 문자열로 데이터베이스에 저장됩니다. 이는 변환된 값을 반환하는 __conform__(self, protocol) 메서드를 추가하여 구현할 수 있습니다. protocol 에 전달되는 객체는 PrepareProtocol 타입입니다.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __conform__(self, protocol):
        if protocol is sqlite3.PrepareProtocol:
            return f"{self.x};{self.y}"

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(4.0, -3.2),))
print(cur.fetchone()[0])
con.close()

어댑터 콜러블 등록 방법¶

다른 가능성은 파이썬 객체를 SQLite 호환 타입으로 변환하는 함수를 만드는 것입니다. 이 함수는 register_adapter() 를 사용하여 등록할 수 있습니다.

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

def adapt_point(point):
    return f"{point.x};{point.y}"

sqlite3.register_adapter(Point, adapt_point)

con = sqlite3.connect(":memory:")
cur = con.cursor()

cur.execute("SELECT ?", (Point(1.0, 2.5),))
print(cur.fetchone()[0])
con.close()

SQLite 값을 사용자 정의 파이썬 타입으로 변환하는 방법¶

어댑터를 작성하면 사용자 정의 파이썬 타입에서 SQLite 값으로 변환할 수 있습니다. SQLite 값에서 사용자 정의 파이썬 타입으로 변환하려면 변환기 를 사용합니다.

Point 클래스로 돌아가 보겠습니다. 우리는 x와 y 좌표를 세미콜론으로 구분된 문자열로 SQLite에 저장했습니다.

먼저, 문자열을 파라미터로 받아 이를 바탕으로 Point 객체를 생성하는 변환기 함수를 정의합니다.

참고

변환기 함수는 기반이 되는 SQLite 데이터 타입에 관계없이 항상 bytes 객체를 전달받습니다.

def convert_point(s):
    x, y = map(float, s.split(b";"))
    return Point(x, y)

이제 특정 SQLite 값을 언제 변환해야 하는지 sqlite3 에 알려야 합니다. 이는 데이터베이스에 연결할 때 connect() 의 detect_types 파라미터를 사용하여 수행됩니다. 세 가지 옵션이 있습니다.

암시적(Implicit): detect_types 를 PARSE_DECLTYPES 로 설정
명시적(Explicit): detect_types 를 PARSE_COLNAMES 로 설정
둘 다: detect_types 를 sqlite3.PARSE_DECLTYPES | sqlite3.PARSE_COLNAMES 로 설정하십시오. 선언된 타입보다 열 이름이 우선합니다.

다음 예제는 암시적 및 명시적 접근 방식을 설명합니다:

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):
        return f"Point({self.x}, {self.y})"

def adapt_point(point):
    return f"{point.x};{point.y}"

def convert_point(s):
    x, y = list(map(float, s.split(b";")))
    return Point(x, y)

# Register the adapter and converter
sqlite3.register_adapter(Point, adapt_point)
sqlite3.register_converter("point", convert_point)

# 1) Parse using declared types
p = Point(4.0, -3.2)
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_DECLTYPES)
cur = con.execute("CREATE TABLE test(p point)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute("SELECT p FROM test")
print("with declared types:", cur.fetchone()[0])
cur.close()
con.close()

# 2) Parse using column names
con = sqlite3.connect(":memory:", detect_types=sqlite3.PARSE_COLNAMES)
cur = con.execute("CREATE TABLE test(p)")

cur.execute("INSERT INTO test(p) VALUES(?)", (p,))
cur.execute('SELECT p AS "p [point]" FROM test')
print("with column names:", cur.fetchone()[0])
cur.close()
con.close()

어댑터 및 변환기 레시피¶

이 섹션에서는 일반적인 어댑터와 변환기에 대한 레시피를 보여줍니다.

import datetime as dt
import sqlite3

def adapt_date_iso(val):
    """Adapt datetime.date to ISO 8601 date."""
    return val.isoformat()

def adapt_datetime_iso(val):
    """Adapt datetime.datetime to timezone-naive ISO 8601 date."""
    return val.replace(tzinfo=None).isoformat()

def adapt_datetime_epoch(val):
    """Adapt datetime.datetime to Unix timestamp."""
    return int(val.timestamp())

sqlite3.register_adapter(dt.date, adapt_date_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_iso)
sqlite3.register_adapter(dt.datetime, adapt_datetime_epoch)

def convert_date(val):
    """Convert ISO 8601 date to datetime.date object."""
    return dt.date.fromisoformat(val.decode())

def convert_datetime(val):
    """Convert ISO 8601 datetime to datetime.datetime object."""
    return dt.datetime.fromisoformat(val.decode())

def convert_timestamp(val):
    """Convert Unix epoch timestamp to datetime.datetime object."""
    return dt.datetime.fromtimestamp(int(val))

sqlite3.register_converter("date", convert_date)
sqlite3.register_converter("datetime", convert_datetime)
sqlite3.register_converter("timestamp", convert_timestamp)

연결 바로 가기 메서드 사용 방법¶

Using the execute(), executemany(), and executescript() methods of the Connection class, your code can be written more concisely because you don’t have to create the (often superfluous) Cursor objects explicitly. Instead, the Cursor objects are created implicitly and these shortcut methods return the cursor objects. This way, you can execute a SELECT statement and iterate over it directly using only a single call on the Connection object.

# 테이블을 생성하고 데이터를 채웁니다.
con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(name, first_appeared)")
data = [
    ("C++", 1985),
    ("Objective-C", 1984),
]
con.executemany("INSERT INTO lang(name, first_appeared) VALUES(?, ?)", data)

# 테이블 내용 출력
for row in con.execute("SELECT name, first_appeared FROM lang"):
    print(row)

print("I just deleted", con.execute("DELETE FROM lang").rowcount, "rows")

# close()는 바로 가기 메서드가 아니며 자동으로 호출되지 않습니다;
# 연결 객체는 수동으로 닫아야 합니다
con.close()

연결 컨텍스트 관리자 사용 방법¶

A Connection object can be used as a context manager that automatically commits or rolls back open transactions when leaving the body of the context manager. If the body of the with statement finishes without exceptions, the transaction is committed. If this commit fails, or if the body of the with statement raises an uncaught exception, the transaction is rolled back. If autocommit is False, a new transaction is implicitly opened after committing or rolling back.

with 문의 본문을 벗어날 때 열려 있는 트랜잭션이 없거나, autocommit 이 True 인 경우 컨텍스트 관리자는 아무 작업도 수행하지 않습니다.

참고

이 컨텍스트 관리자는 트랜잭션을 묵시적으로 열지도 않고 연결을 닫지도 않습니다. 연결을 닫는 컨텍스트 관리자가 필요한 경우, contextlib.closing() 사용을 고려하십시오.

con = sqlite3.connect(":memory:")
con.execute("CREATE TABLE lang(id INTEGER PRIMARY KEY, name VARCHAR UNIQUE)")

# 성공 시 con.commit()이 자동으로 호출됩니다
with con:
    con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))

# with 블록이 예외와 함께 종료되면 con.rollback()이 호출되며,
# 예외는 여전히 발생하므로 반드시 처리되어야 합니다
try:
    with con:
        con.execute("INSERT INTO lang(name) VALUES(?)", ("Python",))
except sqlite3.IntegrityError:
    print("couldn't add Python twice")

# 컨텍스트 관리자로 사용된 연결 객체는 트랜잭션만 커밋하거나 롤백하므로,
# 연결 객체는 수동으로 닫아야 합니다
con.close()

SQLite URI 작업 방법¶

유용한 몇 가지 URI 기법은 다음과 같습니다.

데이터베이스를 읽기 전용 모드로 열기:

>>> con = sqlite3.connect("file:tutorial.db?mode=ro", uri=True)
>>> con.execute("CREATE TABLE readonly(data)")
Traceback (most recent call last):
OperationalError: attempt to write a readonly database
>>> con.close()

이미 존재하지 않는 경우 새 데이터베이스 파일을 묵시적으로 생성하지 않습니다. 새 파일을 생성할 수 없는 경우 OperationalError 를 발생시킵니다:

>>> con = sqlite3.connect("file:nosuchdb.db?mode=rw", uri=True)
Traceback (most recent call last):
OperationalError: unable to open database file

이름이 지정된 공유 인메모리 데이터베이스 생성:

db = "file:mem1?mode=memory&cache=shared"
con1 = sqlite3.connect(db, uri=True)
con2 = sqlite3.connect(db, uri=True)
with con1:
    con1.execute("CREATE TABLE shared(data)")
    con1.execute("INSERT INTO shared VALUES(28)")
res = con2.execute("SELECT data FROM shared")
assert res.fetchone() == (28,)

con1.close()
con2.close()

매개변수 목록을 포함한 이 기능에 대한 자세한 내용은 SQLite URI documentation 에서 확인할 수 있습니다.

행 팩토리 생성 및 사용 방법¶

기본적으로 sqlite3 는 각 행을 tuple 로 표현합니다. 만약 tuple 이 요구 사항에 맞지 않는 경우, sqlite3.Row 클래스나 사용자 정의 row_factory 를 사용할 수 있습니다.

row_factory 는 Cursor 와 Connection 모두에 속성으로 존재하지만, 연결로부터 생성된 모든 커서가 동일한 행 팩토리를 사용하도록 Connection.row_factory 를 설정하는 것을 권장합니다.

Row`은 :class:!tuple`에 비해 메모리 오버헤드와 성능 영향이 최소화되면서 인덱스 기반 및 대소 문자를 구분하지 않는 이름 기반의 열 액세스를 제공합니다. Row`를 행 팩토리로 사용하려면, 이를 :attr:!row_factory` 속성에 할당하십시오:

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = sqlite3.Row

이제 쿼리는 Row 객체를 반환합니다:

>>> res = con.execute("SELECT 'Earth' AS name, 6378 AS radius")
>>> row = res.fetchone()
>>> row.keys()
['name', 'radius']
>>> row[0]         # 인덱스로 접근.
'Earth'
>>> row["name"]    # 이름으로 접근.
'Earth'
>>> row["RADIUS"]  # 열 이름은 대소 문자를 구분하지 않음.
6378
>>> con.close()

참고

위 예시와 같이 SELECT 문에서 FROM 절을 생략할 수 있습니다. 이러한 경우, SQLite는 주어진 별칭인 expr AS alias 를 사용하여 리터럴과 같은 표현식으로 정의된 열을 포함하는 단일 행을 반환합니다.

각 행을 열 이름이 값에 매핑된 dict 로 반환하는 사용자 정의 row_factory 를 생성할 수 있습니다.

def dict_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    return {key: value for key, value in zip(fields, row)}

이를 사용하면 쿼리가 이제 tuple 대신 dict 를 반환합니다.

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = dict_factory
>>> for row in con.execute("SELECT 1 AS a, 2 AS b"):
...     print(row)
{'a': 1, 'b': 2}
>>> con.close()

다음 행 팩토리는 네임드 튜플 을 반환합니다.

from collections import namedtuple

def namedtuple_factory(cursor, row):
    fields = [column[0] for column in cursor.description]
    cls = namedtuple("Row", fields)
    return cls._make(row)

namedtuple_factory() 는 다음과 같이 사용될 수 있습니다.

>>> con = sqlite3.connect(":memory:")
>>> con.row_factory = namedtuple_factory
>>> cur = con.execute("SELECT 1 AS a, 2 AS b")
>>> row = cur.fetchone()
>>> row
Row(a=1, b=2)
>>> row[0]  # 인덱스 기반 접근.
1
>>> row.b   # 속성 기반 접근.
2
>>> con.close()

몇 가지 수정을 거치면 위 레시피를 사용하여 namedtuple 대신 dataclass 나 다른 사용자 정의 클래스를 사용할 수 있습니다.

비 UTF-8 텍스트 인코딩 처리 방법¶

기본적으로 sqlite3 는 TEXT 데이터형의 SQLite 값을 변환하기 위해 str 을 사용합니다. 이는 UTF-8으로 인코딩된 텍스트에 잘 작동하지만, 다른 인코딩이나 잘못된 UTF-8의 경우 실패할 수 있습니다. 이러한 경우를 처리하려면 사용자 정의 text_factory 를 사용할 수 있습니다.

SQLite의 flexible typing 때문에, TEXT 데이터형의 테이블 열에서 비 UTF-8 인코딩이나 임의의 데이터를 발견하는 경우가 흔합니다. 이를 시연하기 위해, ISO-8859-2(Latin-2)로 인코딩된 텍스트가 포함된 데이터베이스(예: 체코어-영어 사전 항목 테이블)가 있다고 가정해 보겠습니다. 이 데이터베이스에 연결된 Connection 인스턴스 con 이 있다고 할 때, 다음과 같은 text_factory 를 사용하여 Latin-2로 인코딩된 텍스트를 디코딩할 수 있습니다:

con.text_factory = lambda data: str(data, encoding="latin2")

TEXT 테이블 열에 저장된 잘못된 UTF-8 또는 임의의 데이터의 경우, 유니코드 HOWTO 에서 가져온 다음 기술을 사용할 수 있습니다:

con.text_factory = lambda data: str(data, errors="surrogateescape")

참고

sqlite3 모듈 API는 서로게이트(surrogate)를 포함하는 문자열을 지원하지 않습니다.

유니코드 HOWTO

설명¶

트랜잭션 제어¶

sqlite3 는 데이터베이스 트랜잭션이 언제, 어떻게 열리고 닫히는지 제어하는 여러 방법을 제공합니다. autocommit 속성을 통한 트랜잭션 제어 을 권장하며, isolation_level 속성을 통한 트랜잭션 제어 은 Python 3.12 이전의 동작 방식을 유지합니다.

`autocommit` 속성을 통한 트랜잭션 제어¶

트랜잭션 동작을 제어하는 권장 방법은 Connection.autocommit 속성을 통한 것이며, 이는 가급적 connect() 의 autocommit 매개변수를 사용하여 설정해야 합니다.

autocommit 을 False 로 설정하는 것이 권장되며, 이는 PEP 249 준수 트랜잭션 제어를 의미합니다. 이는 다음을 뜻합니다:

sqlite3 는 트랜잭션이 항상 열려 있도록 보장하므로, connect(), Connection.commit(), 그리고 Connection.rollback() 은 묵시적으로 새 트랜잭션을 생성합니다(후자의 두 경우의 경우 대기 중인 트랜잭션을 닫은 직후에). sqlite3 는 트랜잭션을 열 때 BEGIN DEFERRED 문을 사용합니다.
트랜잭션은 commit() 을 사용하여 명시적으로 커밋해야 합니다.
트랜잭션은 rollback() 을 사용하여 명시적으로 롤백해야 합니다.
대기 중인 변경 사항이 있는 상태에서 데이터베이스가 close() 될 경우 묵시적 롤백이 수행됩니다.

autocommit 을 True 로 설정하여 SQLite의 autocommit mode 를 활성화할 수 있습니다. 이 모드에서 Connection.commit() 및 Connection.rollback() 은 아무런 효과가 없습니다. 주의할 점은 SQLite의 autocommit 모드는 PEP 249 준수 방식인 Connection.autocommit 속성과는 다르다는 것입니다. 로우 레벨(low-level) SQLite autocommit 모드를 확인하려면 Connection.in_transaction 을 사용하십시오.

autocommit 을 LEGACY_TRANSACTION_CONTROL 으로 설정하여 트랜잭션 제어 동작을 Connection.isolation_level 속성에 맡길 수 있습니다. 자세한 내용은 isolation_level 속성을 통한 트랜잭션 제어 을 참조하십시오.

`isolation_level` 속성을 통한 트랜잭션 제어¶

참고

트랜잭션을 제어하는 권장 방법은 autocommit 속성을 통한 것입니다. autocommit 속성을 통한 트랜잭션 제어 을 참조하십시오.

Connection.autocommit 이 LEGACY_TRANSACTION_CONTROL (기본값)로 설정된 경우 트랜잭션 동작은 Connection.isolation_level 속성을 사용하여 제어됩니다. 그렇지 않으면 isolation_level 은 아무런 효과가 없습니다.

연결 속성인 isolation_level 이 None 이 아닌 경우, execute() 및 executemany() 가 INSERT, UPDATE, DELETE 또는 REPLACE 문을 실행하기 전에 새로운 트랜잭션이 묵시적으로 열립니다. 다른 문장에 대해서는 묵시적인 트랜잭션 처리가 수행되지 않습니다. 대기 중인 트랜잭션을 커밋하거나 롤백하려면 각각 commit() 및 rollback() 메서드를 사용하십시오. isolation_level 속성을 통해 기저의 SQLite transaction behaviour —즉, sqlite3 가 어떤 종류의 BEGIN 문을 묵시적으로 실행할지 여부와 그 유형—을 선택할 수 있습니다.

isolation_level 이 None 으로 설정된 경우, 트랜잭션이 전혀 묵시적으로 열리지 않습니다. 이 설정은 하부 SQLite 라이브러리를 autocommit mode 로 유지하면서도 사용자가 명시적인 SQL 문을 사용하여 직접 트랜잭션을 처리할 수 있게 합니다. 하부 SQLite 라이브러리의 autocommit 모드는 in_transaction 속성을 통해 조회할 수 있습니다.

executescript() 메서드는 isolation_level 값에 관계없이 주어진 SQL 스크립트를 실행하기 전에 모든 대기 중인 트랜잭션을 묵시적으로 커밋합니다.

버전 3.6에서 변경: sqlite3 는 DDL 문 이전에 열린 트랜잭션을 묵시적으로 커밋하곤 했습니다. 현재는 더 이상 그렇지 않습니다.

버전 3.12에서 변경: 이제 트랜잭션을 제어하는 권장 방법은 autocommit 속성을 사용하는 것입니다.

sqlite3 — SQLite 데이터베이스를 위한 DB-API 2.0 인터페이스¶

튜토리얼¶

참조¶

모듈 함수¶

모듈 상수¶

Connection 객체¶

커서 객체¶

행 객체¶

블롭 객체¶

PrepareProtocol 객체¶

예외¶

SQLite 와 파이썬 형¶

기본 어댑터 및 변환기 (더 이상 권장되지 않음)¶

명령 줄 인터페이스¶

사용법 가이드¶

SQL 쿼리에서 값을 바인딩하기 위한 자리 표시자 사용 방법¶

사용자 정의 파이썬 타입을 SQLite 값으로 어댑트하는 방법¶

어댑터가 가능한 객체 작성 방법¶

어댑터 콜러블 등록 방법¶

SQLite 값을 사용자 정의 파이썬 타입으로 변환하는 방법¶

어댑터 및 변환기 레시피¶

연결 바로 가기 메서드 사용 방법¶

연결 컨텍스트 관리자 사용 방법¶

SQLite URI 작업 방법¶

행 팩토리 생성 및 사용 방법¶

비 UTF-8 텍스트 인코딩 처리 방법¶

설명¶

트랜잭션 제어¶

autocommit 속성을 통한 트랜잭션 제어¶

isolation_level 속성을 통한 트랜잭션 제어¶

분실물 보관소

`sqlite3` — SQLite 데이터베이스를 위한 DB-API 2.0 인터페이스¶

`autocommit` 속성을 통한 트랜잭션 제어¶

`isolation_level` 속성을 통한 트랜잭션 제어¶