> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL용 vsql_rest 확장 기능

> vsql_rest 확장 기능은 서버 프로세스 안에서 MySQL 테이블을 HTTP 엔드포인트로 제공하며, URL 필터, 저장 함수 호출, JWT 인증, 행 수 상한을 지원합니다.

`vsql_rest`는 데이터베이스 프로세스 안에서 HTTP로 테이블을 제공합니다.
클라이언트는 연결 대신 URL로 행을 읽고, 쿼리 매개변수로 필터링하며, `/rpc/`
아래에서 저장 함수를 호출합니다. 작성할 애플리케이션도, 실행할 두 번째 프로세스도
없습니다.

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) |
| **라이선스** | GPL-2.0 |
| **기능 단계** | 미리 보기 |

> [!WARNING]
>
> 이 확장 기능은 미리 보기 기능을 사용하므로 `vsql_allow_preview_extensions`가
> `ON`이어야 합니다. 서버를 `--vsql_allow_preview_extensions=ON`으로 시작하거나
> `SET PERSIST vsql_allow_preview_extensions = ON`을 실행하세요. 그렇지 않으면
> `INSTALL EXTENSION`이 거부됩니다.

## 설치

설치 스크립트, Docker 이미지 또는 릴리스 tarball로 VillageSQL을 설치했다면
`vsql_rest.veb`는 이미 서버의 `lib/veb/` 디렉터리에 있습니다. 문 하나로 서버에
설치하세요:

```sql theme={null}
INSTALL EXTENSION vsql_rest;
```

설치되었는지 확인합니다:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_rest';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_rest      |
+----------------+
```

직접 빌드하려면 [저장소](https://github.com/villagesql/vsql-rest)의 빌드
지침을 따르세요.

## 추가되는 기능

SQL 함수는 추가하지 않습니다. `SET GLOBAL`로 구성하며, 응답하는 모든 요청은
HTTP로 들어옵니다.

| 설정 | 기본값 | 제어 대상 |
| - | - | - |
| `vsql_rest.vsql_rest_enabled` | `OFF` | 리스너 실행 여부 |
| `vsql_rest.schema` | 비어 있음 | 제공할 데이터베이스. 설정하기 전까지 모든 테이블 및 RPC 요청은 `503`(코드 `VSQL0007`)을 받음 |
| `vsql_rest.allowed_tables` | 비어 있음 | 접근할 수 있는 테이블. 비어 있으면 모든 테이블 |
| `vsql_rest.table_methods` | 비어 있음 | 각 테이블이 허용하는 HTTP 메서드. `table:GET,POST\|table2:GET` 형식으로 작성. 비어 있으면 모든 테이블에서 `GET`, `POST`, `PATCH`, `DELETE` |
| `vsql_rest.allowed_routines` | 비어 있음 | `/rpc/` 아래에서 호출할 수 있는 함수. 비어 있으면 모든 함수 |
| `vsql_rest.port` | `3000` | HTTP 포트 |
| `vsql_rest.ssl_port` | `3443` | HTTPS 포트 |
| `vsql_rest.ssl_cert`, `vsql_rest.ssl_key` | 비어 있음 | HTTPS용 인증서와 키 |
| `vsql_rest.require_auth` | `OFF` | 요청에 JWT가 필요한지 여부 |
| `vsql_rest.jwt_secret`, `vsql_rest.jwt_public_key` | 비어 있음 | 그 JWT를 검증하는 방법 |
| `vsql_rest.max_rows` | `1000` | 요청에 `?limit`이 없을 때 돌아오는 행 수 |
| `vsql_rest.schema_ttl` | `60` | 캐시된 테이블 레이아웃을 재사용하는 시간(초). `vsql_rest.schema`를 바꾸거나 `vsql_rest_enabled`를 껐다 켜면 다음 요청에서 다시 만듦 |

## 예제

리스너는 시작할 때 데이터베이스 레이아웃을 캐시하고 `schema_ttl`초 동안
유지하므로, 테이블을 먼저 만듭니다:

```sql theme={null}
CREATE DATABASE extdocs;
USE extdocs;

CREATE TABLE people (id INT PRIMARY KEY, name VARCHAR(32));

INSERT INTO people VALUES
    (1, 'Jonathan Smith'),
    (2, 'John Smyth'),
    (3, 'Joan Smithe'),
    (4, 'Peter Brown');
```

그런 다음 데이터베이스와 테이블을 지정하고 리스너를 켭니다:

```sql theme={null}
SET GLOBAL vsql_rest.schema = 'extdocs';
SET GLOBAL vsql_rest.allowed_tables = 'people';
SET GLOBAL vsql_rest.vsql_rest_enabled = ON;
```

HTTP로 테이블을 읽습니다:

```bash theme={null}
curl http://127.0.0.1:3000/people
```

```json theme={null}
[{"id":1,"name":"Jonathan Smith"},{"id":2,"name":"John Smyth"},{"id":3,"name":"Joan Smithe"},{"id":4,"name":"Peter Brown"}]
```

쿼리 매개변수로 필터링합니다:

```bash theme={null}
curl "http://127.0.0.1:3000/people?id=eq.2"
```

```json theme={null}
[{"id":2,"name":"John Smyth"}]
```

설정을 끄면 포트가 닫힙니다:

```sql theme={null}
SET GLOBAL vsql_rest.vsql_rest_enabled = OFF;
```

> [!WARNING]
>
> 기본값은 인증을 끄고, 모든 테이블을 제공하며, 지원하는 모든 HTTP 메서드(`GET`,
> `POST`, `PATCH`, `DELETE`)를 허용하고, 리스너는 시작하는 순간부터 모든
> 인터페이스에 바인딩됩니다. 그러면 호스트에 접근할 수 있는 모든 것이 스키마의
> 모든 테이블을 읽고 쓸 수 있습니다. 리스너를 켜기 전에 `allowed_tables`,
> `table_methods`, `require_auth`를 설정하고, JWT 비밀 값이나 공개 키를 구성하고,
> 포트를 방화벽 뒤에 두세요. 바인드 주소 설정은 없습니다.

> [!NOTE]
>
> `SET PERSIST`로 쓴 설정은 재시작 후에도 유지되지만, `UNINSTALL EXTENSION`이
> 이를 삭제합니다. 제거 후 다시 설치하면 모든 설정이 기본값으로 돌아가며, 재시작해도
> 이전 값은 돌아오지 않습니다.

> [!NOTE]
>
> 모든 문자열 설정은 서버를 통해 다시 읽히며, 서버는 최대 1022바이트를
> 반환합니다. 이보다 긴 `schema`, `allowed_tables`, `allowed_routines`,
> `table_methods`, `jwt_secret` 또는 `jwt_public_key`는 모든 요청을 `500`으로
> 실패하게 하고, 이보다 긴 `ssl_cert`나 `ssl_key`는 리스너가 시작되지 못하게
> 합니다.

## 참고 항목

* [테이블을 REST API로 제공하기](https://villagesql.com/docs/en/guides/rest-api-from-tables.md) — 필터, 테이블별 메서드, 먼저 바꿔야 할 기본값
* [확장 기능 관리](https://villagesql.com/docs/ko/extensions/managing.md) — 확장 기능 설정을 읽고 쓰는 방법
* [미리 보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities.md) — 미리 보기 플래그가 켜는 것과 보장하는 것
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) — 소스, 전체 경로 구문, 알려진 제한 사항


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.