매개 변수가 있는 쿼리 실행

매개 변수가 있는 쿼리를 사용하면 SQL에 자리 표시자를 유지하고 런타임에 값을 제공할 수 있습니다. PostgreSQL 확장은 이러한 값을 쿼리 매개 변수로 바인딩합니다. SQL 텍스트에 값을 붙여넣지 않습니다.

:name, $1 또는 ?와 같은 자리 표시자를 사용하는 도구 또는 애플리케이션 코드에서 복사한 SQL을 실행하려면 이 페이지를 사용하세요.

지원되는 자리 표시자 구문

쿼리 편집기는 문자열, 주석, 캐스트, 배열 조각, 달러 따옴표 붙은 본문 및 PostgreSQL JSON 연산자 외부에서 이러한 자리 표시자 스타일을 검색합니다.

이름이 지정된 자리 표시자

select id, email
from users
where id = :user_id;

명명된 자리 표시자는 대/소문자를 구분합니다. 동일한 이름의 반복된 항목은 하나의 표 행을 공유합니다.

PostgreSQL 위치 지정 플레이스홀더

select id, email
from users
where id = $1;

$N 자리 표시자는 이를 포함하는 문장 내에서 위치가 정해집니다.

Qmark 위치 자리 표시자

select id, email
from users
where active = ?;

? 자리 표시자는 왼쪽에서 오른쪽 순서로 작동합니다. 값 위치에서는 어디서나 A ?가 매개변수 역할을 하며, 여기에는 비교 연산자(>=, <=, <>) 뒤, CASE 분기, 그리고 LIMIT/OFFSET에서의 경우도 포함됩니다. PostgreSQL의 JSONB 연산??|자 및 ?& JSON 경로 연산 @? 자는 매개 변수가 아닌 연산자로 인식됩니다.

Important

문장마다 하나의 플레이스홀더 스타일만 사용하세요. :name와 $N를 혼용하거나 $N와 ?를 혼용하는 문은 실행 전에 거부됩니다.

매개 변수 탭 열기 및 사용

  1. 파일을 열거나 만들고 .sql 데이터베이스에 연결합니다.
  2. 쿼리 실행(PostgreSQL)을 실행하거나, 현재 문 실행(PostgreSQL)을 실행하거나, 선택한 SQL 범위를 실행합니다.
  3. SQL에 자리 표시자가 포함된 경우 매개 변수 탭이 아래쪽 패널에서 열립니다.
  4. 각 행에 대한 값을 입력하고 필요한 경우 형식을 선택한 다음 쿼리 실행을 선택합니다.
  5. 첫 번째 실행 후 값을 편집하고 실행을 다시 선택하여 쿼리를 반복합니다.

탭에는 각 고유한 명명된 자리 표시자에 대해 하나의 행과 각 위치 자리 표시자에 대해 하나의 행이 표시됩니다. 각 행에는 자리 표시자 이름 또는 인덱스, 값 입력, NULL 확인란, 형식 드롭다운 목록 및 사용 가능한 경우 행 작업이 포함됩니다.

여러 문으로 구성된 스크립트

참고(2026년 5월): 이 문서의 이전 버전에서는 문별 독립적 위치 인덱스를 잘못 설명했습니다. 동작은 변경되지 않았습니다. 설명서만 수정되었습니다.

위치 매개 변수($N, ?)는 실행된 스크립트에서 단일 값 배열을 공유합니다. 어떤 문에서든 $1(또는 첫 번째 ?)는 항상 다른 어떤 문에서든 $1와 동일한 값에 바인딩됩니다. 문 간에 동일한 위치 인덱스를 다시 사용하면 독립적인 값이 부여되지 않습니다. 다른 문에서 동일한 인덱스에 대해 다른 값이 필요한 경우 명명된 매개 변수(:name)를 대신 사용합니다.

명명된 공유 값이 해당 값을 사용하는 문 중 하나와 호환되지 않는 경우 PostgreSQL은 오류를 반환하고 그리드는 값을 유지하므로 다시 조정하고 실행할 수 있습니다.

NULL 값

NULL 확인란을 사용하여 SQLNULL을 바인딩합니다. 이 옵션을 선택하면 해당 행에 대한 값 필드가 무시됩니다.

NULL 확인란이 꺼져 있는 동안 리터럴 텍스트를 입력하면 값이 SQLNULL이 아닌 텍스트NULL로 바인딩된다는 경고가 표시됩니다.

매개 변수 형식 선택

형식 드롭다운 목록은 기본적으로 autoPostgreSQL에서 매개 변수 형식을 유추할 수 있도록 합니다. 클라이언트 쪽 유효성 검사 또는 더 명확한 바인딩을 원하는 경우 형식을 선택합니다.

  • text
  • integer
  • bigint
  • numeric
  • boolean
  • date
  • timestamp
  • timestamptz
  • uuid
  • json
  • jsonb

유효성 검사는 엄격하지 않습니다. 경고는 제출을 차단하지 않습니다. PostgreSQL은 실행 시 최종 유효성 검사기로 유지됩니다.

매개 변수를 사용하여 쿼리 계획 생성

자리 표시자를 포함하는 SQL에 대한 쿼리 계획을 시각화할 때 매개 변수 탭은 행을 반환하는 대신 쿼리 계획 시각화 도우미를 구동합니다. 실행 버튼에는 쿼리 계획 시각화가 표시되며, 처음 실행한 후에는 다시 시각화로 표시됩니다. 값을 입력하고 실행할 EXPLAIN 단추를 선택하고 쿼리 계획 시각화 도우미를 엽니다. 이 경로는 쿼리 결과를 반환하지 않습니다.

무시 사용하기

표에 유효한 PostgreSQL 연산자 등 SQL에 유지해야 하는 토큰이 표시되면 Ignore 를 사용합니다. 무시는 토큰이 바인딩 없이 유효한 SQL로 유지되는 경우에만 사용하도록 설정됩니다.

SQL 편집 및 다시 실행

매개 변수 탭을 열면 SQL을 편집하고 실행을 다시 선택할 수 있습니다. 확장은 자리 표시자를 다시 추출하고 새 템플릿 기반 SQL을 이전 지문과 비교합니다.

자리 표시자 집합이 변경되면 자리 표시자 추가 또는 제거와 같이 변경된 내용이 드리프트 배너에 요약되어 있습니다. 자리 표시자가 여전히 이름 또는 위치 인덱스별로 일치하는 경우 확장은 값을 앞으로 병합합니다. 모든 자리 표시자를 제거하면 표가 닫히고 쿼리가 정상적으로 실행됩니다.

트랜잭션 취소 및 복구

매개 변수가 있는 실행이 활성화되어 있는 동안 실행 단추는 중지 컨트롤( 취소라는 레이블이 지정됨)으로 변경됩니다. 취소하면 진행 중인 일괄 처리가 중단되고, 이후 일괄 처리를 건너뛰고, 값이 그대로 유지되는 매개 변수 탭이 열립니다. 취소된 실행은 실패가 아닌 취소된 일괄 처리 상태를 표시하므로 행이 오류로 강조 표시되지 않습니다.

확장은 사용자 시작 트랜잭션을 자동으로 롤백하지 않습니다. 취소로 인해 연결이 중단된 트랜잭션 상태로 남으면 매개 변수 탭에 실행 ROLLBACK이 포함된 복구 알림이 표시됩니다. 이를 선택하여 동일한 연결에서 명시적 ROLLBACK 연결을 실행한 다음 스크립트를 다시 실행합니다.

오류 검토 및 다시 시도

매개 변수가 있는 실행이 실패하면 매개 변수 탭은 값을 유지하고 데이터베이스 오류 요약과 함께 실패한 상태를 표시합니다. 메시지 보기를 선택하여 전체 메시지 세부 정보를 엽니다.

취소된 실행은 실패한 실행과 별도로 취소된 상태를 표시하며, 실행되지 않은 이후 일괄 처리는 건너뛴 것으로 표시됩니다.

값 또는 형식을 수정한 후 실행을 다시 선택합니다. 탭은 새 시도를 위해 이전 실패 상태, 취소 상태 및 행 강조 표시 상태를 지웁니다. 연결이 중단된 트랜잭션에 있는 경우 복구 알림이 다시 나타납니다.

쿼리 기록 값 보존

이 설정 pgsql.queryPlaceholders.historyValueRetention 은 매개 변수 값이 현재 세션의 메모리 내 쿼리 기록에 유지되는지 여부를 제어합니다.

Value 작동 방식
ask 매개 변수가 있는 실행이 성공할 때마다 묻습니다.
always 메시지를 표시하지 않고 세션 내 기록 항목에 대한 값을 유지합니다.
never 템플릿이 있는 SQL만 유지합니다.

활성 상태이면 ask 성공적으로 실행된 후 표시되는 프롬프트는 저장 (이 항목만 유지), 항상 저장 (설정 always도 전환), 건너뛰기 (템플릿화된 SQL만 해당) 및 다시 묻지 않음 (설정을 으로 전환)을 never제공합니다.

값은 메모리에만 유지되며 VS Code가 다시 로드되거나 작업 영역이 변경될 때 지워집니다. 매개 변수 값은 원격 분석 및 로그에서 수정됩니다.

준비 시 유의 사항

PREPARE ... AS SELECT $1 는 PostgreSQL 서버 쪽 위치 구문을 사용합니다. 확장은 PREPARE 문을 감지하고, 클라이언트에서 바인딩하는 대신 PostgreSQL용 PREPARE 본문 안에 플레이스홀더를 남겨 둡니다. 동일한 스크립트의 다른 문은 정상적으로 구문 분석됩니다.

지원되지 않는 MVP 사례

MVP에는 다음이 포함되지 않습니다.

  • 디스크에 저장되는 영구적인 값 이력
  • 편집기 세션에서 명명되거나 저장된 매개 변수 집합입니다.
  • 클라이언트 측 매개변수화된 실행으로서의 서버 측 PREPARE/EXECUTE 재사용
  • 지원되는 드롭다운 목록 형식을 초과하는 복합, 배열, 바이트, 범위, 간격, 열거형 또는 기타 형식 바인딩입니다.

관련 콘텐츠

  • Last updated on