# pgvector 入門：インストールから最初のベクトル検索まで（Docker・Supabase・AWS RDS/Aurora・Neon・Cloud SQL・Azure 対応）

> PostgreSQL でベクトル検索を始めるための pgvector 入門ガイド。Docker・Supabase・AWS RDS/Aurora・Neon・Google Cloud SQL/AlloyDB・Azure それぞれでの有効化手順、`CREATE EXTENSION vector` の権限とよくあるエラー、最初のテーブル作成・INSERT・距離演算子・kNN 検索・HNSW インデックスまでを、公式ドキュメントに忠実な実コードで最短解説します。

- 公開日: 2026-06-26
- 著者: 友田 陽大
- タグ: PostgreSQL, RAG, Supabase, AWS, パフォーマンス
- URL: https://tomodahinata.com/blog/pgvector-getting-started-installation-docker-supabase-rds-neon-guide

## 要点

- 拡張の名前は `vector`（プロジェクト名の pgvector ではない）。どのプラットフォームでも有効化は `CREATE EXTENSION vector;` の一行
- Docker は公式イメージ `pgvector/pgvector:pg17` が最短。マネージドは RDS/Aurora・Neon・Cloud SQL・Supabase が対応、Azure だけは `azure.extensions` の許可リスト登録が先に必要
- つまずきの9割は2つ：『control file が無い』＝バイナリ未インストール、『permission denied』＝権限不足（rds_superuser / cloudsqlsuperuser / azure_pg_admin）
- 最初の検索は `ORDER BY embedding <=> $1 LIMIT k` の形。テキスト埋め込みはコサイン距離 `<=>` が定番
- 型は vector / halfvec / bit / sparsevec の4つ。まず vector(次元) で始め、数百万行に育ったら HNSW インデックスを張る

---

「PostgreSQL でベクトル検索（意味検索）をやりたい」——その入口が **pgvector** です。専用のベクトルDBを増やさず、いま使っている Postgres に `vector` 型を1つ足すだけで、AIの埋め込みベクトルを保存して「意味が近い順」に検索できるようになります。

この記事は、その**最初の一歩**——**各プラットフォームでの有効化**と**最初のベクトル検索**——を最短で踏み出すための入門ガイドです。「RAGの全体設計」や「インデックスのチューニング」は別記事に譲り、本稿は**「動かす」ところまで**を、公式ドキュメントに忠実に、つまずきポイントを潰しながら案内します。

> **この記事のルール**：拡張名・SQL構文・各プラットフォームの有効化手順は **pgvector 公式 README と各クラウドの公式ドキュメント（2026年6月時点）** に基づきます。**マネージドサービスの pgvector バージョンはエンジンのマイナーに紐づき、本家より遅れます**。利用前に必ず**お使いのインスタンスで `pg_available_extensions` を確認**してください。本記事のバージョン・手順は変わり得ます。

---

## 1. 30秒で理解する pgvector

pgvector は **PostgreSQL の拡張（extension）** です。有効化すると次の3つが使えるようになります。

1. **`vector` 型**：埋め込みベクトル（`[0.1, -0.3, ...]` のような数値配列）を格納する列の型。
2. **距離演算子**：`<=>`（コサイン距離）など、ベクトル間の「近さ」を測る演算子。
3. **ANNインデックス**：HNSW / IVFFlat。数百万行でも高速に近傍を返す近似最近傍インデックス。

最重要の注意点を先に。**拡張の名前は `vector` です（`pgvector` ではありません）。** `pgvector` はプロジェクト名。SQLで有効化するときは、どのプラットフォームでも必ずこう書きます。

```sql
CREATE EXTENSION vector;        -- ✅ 正しい（拡張名は vector）
-- CREATE EXTENSION pgvector;   -- ❌ これは存在しないのでエラーになる
```

---

## 2. プラットフォーム別：pgvector を有効化する

「`CREATE EXTENSION vector;` を実行する」のは共通ですが、**その前提（バイナリのインストール／許可リスト／権限）**がプラットフォームで違います。あなたの環境の節だけ読めば十分です。

### Docker / セルフホスト

最短は**公式 Docker イメージ**です。イメージ名は `pgvector/pgvector`、タグは「Postgresメジャー + Debianベース」の形（例 `pg17`）。

```bash
# 公式イメージ（pgvector がプリインストール済みの Postgres）
docker pull pgvector/pgvector:pg17
docker run -d --name pg -e POSTGRES_PASSWORD="$PGPASSWORD" -p 5432:5432 pgvector/pgvector:pg17
```

既存の Postgres にソースから入れる場合（`pg_config` が PATH に必要）：

```bash
cd /tmp
git clone --branch v0.8.3 https://github.com/pgvector/pgvector.git
cd pgvector && make && sudo make install
```

OSパッケージでも入ります（`NN` は Postgres メジャー）。

```bash
sudo apt install postgresql-17-pgvector     # Debian/Ubuntu（PGDG apt）
sudo dnf install pgvector_17                 # RHEL/Fedora（PGDG yum）
brew install pgvector                        # macOS
```

最後に、対象のデータベースで一度だけ実行します。

```sql
CREATE EXTENSION vector;
```

### Supabase

ダッシュボードの **Database → Extensions** で「vector」を検索してトグルをONにするか、SQLエディタで実行します。Supabase の慣習では `extensions` スキーマに入れます。

```sql
create extension vector with schema extensions;
```

### AWS RDS for PostgreSQL / Aurora PostgreSQL

pgvector は RDS / Aurora の **trusted extension（信頼済み拡張）** として提供されます。バイナリは導入済みなので、有効化するだけです。

```sql
-- まず使えるバージョンを確認（マネージドは本家より遅れることがある）
SELECT * FROM pg_available_extensions WHERE name = 'vector';

CREATE EXTENSION IF NOT EXISTS vector;
```

- **権限**：PostgreSQL **13以降**なら、データベースへの `CREATE` 権限があれば `rds_superuser` でなくても trusted extension を入れられます（12以前は `rds_superuser` が必要）。
- **HNSWインデックス**を使うには pgvector **0.5.0 以降**が必要。古いマイナーだと未対応のことがあるので、上の `pg_available_extensions` で確認してください。

### Neon

全プランで利用可。追加設定も特別な権限も不要です。

```sql
CREATE EXTENSION IF NOT EXISTS vector;
-- 一つ前のバージョンに固定したいとき
-- CREATE EXTENSION vector VERSION '0.7.4';
```

### Google Cloud SQL for PostgreSQL / AlloyDB

Cloud SQL はフラグ不要で有効化できます。**作成できるのは `cloudsqlsuperuser` ロールのメンバー**（デフォルトの `postgres` ユーザーは保持）。

```sql
CREATE EXTENSION vector;                  -- 名前は vector（pgvector ではない）
```

**AlloyDB** は pgvector に加えて Google 独自の **ScaNN** インデックスも使えます。`CASCADE` で `vector` も同時に入ります。

```sql
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;  -- alloydb_scann + vector
```

### Azure Database for PostgreSQL — Flexible Server

Azure だけは**2段階**です。**先に許可リスト（`azure.extensions`）へ登録**してから `CREATE EXTENSION` します。許可リストでも名前は `vector`。

```bash
# 1) サーバーパラメータ azure.extensions に VECTOR を許可（CLIの例）
az postgres flexible-server parameter set \
  --resource-group <rg> --server-name <server> \
  --name azure.extensions --value vector
```

```sql
-- 2) 対象DBで有効化（権限: azure_pg_admin）
CREATE EXTENSION vector;
```

### 早見表：有効化コマンドと必要権限

| プラットフォーム | 事前準備 | 有効化 | 必要権限 |
| --- | --- | --- | --- |
| Docker / セルフホスト | イメージ or `make install` | `CREATE EXTENSION vector;` | superuser |
| Supabase | （導入済み） | `create extension vector with schema extensions;` | （UI/SQLで可） |
| RDS / Aurora | （導入済み・trusted） | `CREATE EXTENSION vector;` | `CREATE` on DB（PG13+）／`rds_superuser`（PG≤12） |
| Neon | 不要 | `CREATE EXTENSION vector;` | 特別な権限不要 |
| Cloud SQL / AlloyDB | （導入済み） | `CREATE EXTENSION vector;` | `cloudsqlsuperuser` |
| Azure Flexible Server | `azure.extensions` に登録 | `CREATE EXTENSION vector;` | `azure_pg_admin` |

---

## 3. 確認とよくあるエラー

有効化できたかは、どの環境でも同じSQLで確認できます。

```sql
SELECT extversion FROM pg_extension WHERE extname = 'vector';   -- 入っていればバージョンが返る
SELECT * FROM pg_available_extensions WHERE name = 'vector';    -- 入れられるバージョン
```

psql なら `\dx` で一覧、`\dx vector` で詳細。つまずきの大半は次の2つです。**意味を知っていれば即座に切り分けられます。**

| エラー | 本当の意味 | 対処 |
| --- | --- | --- |
| `could not open extension control file ".../vector.control": No such file or directory` | **バイナリが未インストール**（権限の問題ではない） | `make install` / 正しいPGメジャーのパッケージ / pgvector入りDockerイメージを使う |
| `permission denied to create extension "vector"` | **ロールの権限不足** | superuser / `rds_superuser` / `cloudsqlsuperuser` / `azure_pg_admin`、または DBへの `CREATE` 権限を付与 |
| `extension "vector" is not allow-listed for "azure.extensions" setting` | Azure で**許可リスト未登録** | `azure.extensions` に `vector` を追加してから再実行 |

---

## 4. 最初のベクトル検索

有効化できたら、いよいよ検索です。**テーブル作成 → 投入 → kNN検索**の最小フローを通します。

```sql
-- 1) 埋め込みを格納するテーブル。vector(3) の 3 は次元数（実際は埋め込みモデルの出力次元に合わせる）
CREATE TABLE items (
    id        bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    content   text NOT NULL,
    embedding vector(3) NOT NULL
);

-- 2) 投入。ベクトルは '[...]' のテキストリテラルで渡す
INSERT INTO items (content, embedding) VALUES
    ('りんご', '[1, 2, 3]'),
    ('みかん', '[1, 2, 4]'),
    ('自動車', '[9, 8, 1]');

-- 3) クエリベクトルに「意味が近い順」で上位2件（kNN検索）
SELECT id, content, embedding <=> '[1, 2, 3]' AS distance
FROM items
ORDER BY embedding <=> '[1, 2, 3]'   -- 小さいほど近い
LIMIT 2;
```

### 距離演算子：用途に合わせて選ぶ

ベクトルの「近さ」をどう測るかは演算子で選びます。**埋め込みモデルが想定する距離に合わせる**のが鉄則です。

| 演算子 | 距離 | 主な用途 |
| --- | --- | --- |
| `<=>` | コサイン距離 | **テキスト埋め込みの定番**（向きで意味を測る） |
| `<->` | L2（ユークリッド）距離 | 正規化していないベクトル全般 |
| `<#>` | 負の内積 | 内積ベースのモデル |
| `<+>` | L1（マンハッタン）距離 | L1空間 |
| `<~>` / `<%>` | ハミング / ジャッカード距離 | `bit` 型（バイナリベクトル） |

OpenAI の `text-embedding-3-*` のようなテキスト埋め込みなら、まず **`<=>`（コサイン距離）** を選んでおけば間違いありません。

> **実データではどうなる？**：上の `'[1,2,3]'` は説明用の手書きベクトルです。実際は埋め込みモデル（OpenAI・Cohere・自前モデルなど）にテキストを渡して得た数百〜数千次元のベクトルを `INSERT` します。アプリ側からの渡し方は、[TypeScript × Drizzle の型安全な実装](/blog/pgvector-typescript-drizzle-orm-nextjs-type-safe-vector-search-guide)で詳しく扱います。

---

## 5. 4つのベクトル型と次元の上限

pgvector には用途別に4つの型があります。**まず `vector` で始め、必要になったら他を検討**すれば十分です（YAGNI）。

| 型 | 1要素のサイズ | インデックス可能な次元 | 使いどころ |
| --- | --- | --- | --- |
| `vector(n)` | 4バイト（float32） | 最大 **2,000** | **標準。まずこれ** |
| `halfvec(n)` | 2バイト（float16） | 最大 **4,000** | メモリ半減・高次元 |
| `bit(n)` | 1ビット | 最大 **64,000** | バイナリ量子化（ハミング距離） |
| `sparsevec(n)` | 非ゼロのみ格納 | 非ゼロ最大 **16,000** | スパース表現（SPLADE等） |

`vector(n)` の `n` は**埋め込みモデルの出力次元と一致させる**必要があります（ズレると `INSERT` で次元不一致エラー＝型で守られる利点）。OpenAI の `text-embedding-3-large` は3072次元ですが、`dimensions` パラメータで短縮でき、私のプロジェクトでは1024次元で運用しています（理由は[RAG設計の記事](/blog/pgvector-postgres-production-rag-hybrid-search)で詳述）。

---

## 6. 最初のインデックス（HNSW）

数件なら全件スキャンで十分ですが、**数百万行になると毎回のフルスキャンが破綻**します。そこで近似最近傍（ANN）インデックスを張ります。迷ったら **HNSW**（継続的な追加に強く、空テーブルにも先に張れる）。

```sql
-- コサイン距離で検索するなら vector_cosine_ops（距離演算子と演算子クラスを必ず揃える）
CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

-- 検索精度↔速度は、インデックス再構築なしでランタイムに調整できる
SET hnsw.ef_search = 100;   -- 既定40。大きいほど高再現率・低速
```

インデックスが効いているかは `EXPLAIN` で確認します（`Index Scan using ..._hnsw_...` が出ればOK）。

```sql
EXPLAIN ANALYZE
SELECT id FROM items ORDER BY embedding <=> '[1,2,3]' LIMIT 5;
```

> **重要**：インデックスは「`ORDER BY embedding <演算子> ... LIMIT k`」という形にだけ効きます。`m` / `ef_construction` / `ef_search` といったパラメータの意味や、HNSW と IVFFlat の選び方、再現率の測り方は、専用記事 [pgvector チューニング完全ガイド](/blog/pgvector-index-tuning-hnsw-ivfflat-quantization-iterative-scan-guide) に体系化しています。

---

## 7. 次に読むべき記事（ここから本番へ）

「動いた」次は、目的に応じてこの順で深掘りすると最短です。

- **RAG（社内文書にAIが答える）を作りたい** → [pgvector で作る本番RAG](/blog/pgvector-postgres-production-rag-hybrid-search)（埋め込みの置き場所・ハイブリッド検索・冪等インジェスト）
- **検索が遅い／精度が出ない** → [pgvector チューニング完全ガイド](/blog/pgvector-index-tuning-hnsw-ivfflat-quantization-iterative-scan-guide)（HNSW/IVFFlat・量子化・再現率の計測）
- **専用ベクトルDBと迷っている** → [pgvector vs Pinecone/Qdrant/Weaviate/Milvus 技術選定](/blog/pgvector-vs-pinecone-qdrant-weaviate-milvus-vector-database-comparison-guide)
- **TypeScript / Next.js で型安全に実装したい** → [pgvector × Drizzle ORM × Next.js](/blog/pgvector-typescript-drizzle-orm-nextjs-type-safe-vector-search-guide)

---

## まとめ：最短チェックリスト

- **拡張名は `vector`**。有効化はどの環境でも `CREATE EXTENSION vector;` の一行。
- **プラットフォーム差は「前提」だけ**：Docker は公式イメージ `pgvector/pgvector:pg17`、Azure だけ `azure.extensions` 許可が先。マネージドのバージョンは `pg_available_extensions` で確認。
- **エラーは2系統**：`control file が無い`＝バイナリ未導入、`permission denied`＝権限不足。
- **最初の検索**：`vector(n)` 列 → `INSERT '[...]'` → `ORDER BY embedding <=> $1 LIMIT k`。テキストは `<=>`。
- **規模が出たら HNSW**：`USING hnsw (embedding vector_cosine_ops)`、精度は `hnsw.ef_search` で調整。

pgvector の良さは、**いま使っている PostgreSQL の中で、使い慣れた SQL・権限・バックアップのまま**ベクトル検索を始められることです。私は [生成AI音声チャットボット](/case-studies/ai-voice-chatbot) で、専用ベクトルDBを増設せず RDS 上の pgvector に業務データと埋め込みを集約し、本番RAGを一人 × 生成AI（Claude Code）で設計・実装・運用まで通しました。

**「自社のデータでAIの意味検索を始めたいが、どこに・どう載せるか分からない」——その入口から本番運用までを一気通貫で伴走できます。** お気軽にご相談ください。

---

### 参考（公式ドキュメント）

- [pgvector（GitHub・README）](https://github.com/pgvector/pgvector) — インストール（Docker / ソース / OSパッケージ）・`CREATE EXTENSION vector`・型と距離演算子・HNSW / IVFFlat
- [Supabase — pgvector](https://supabase.com/docs/guides/database/extensions/pgvector) ／ [AWS RDS 拡張](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Extensions.html) ／ [Neon — pgvector](https://neon.com/docs/extensions/pgvector) ／ [Google Cloud SQL 拡張](https://cloud.google.com/sql/docs/postgres/extensions) ／ [Azure Flexible Server で pgvector を使う](https://learn.microsoft.com/azure/postgresql/extensions/how-to-use-pgvector)