サーバーレスPostgreSQL「Neon」完全入門。CLI構築からPython/TypeScript(ORM)連携まで徹底解説！

サーバーレスPostgreSQLとして注目を集める「Neon（Neon.tech）」。Vercelのダッシュボード連携などで目にする機会が増えましたが、「Vercel経由じゃなくても使えるの？」「CLIで自動構築できる？」といった疑問をお持ちの方も多いのではないでしょうか。

以下の記事で Vercel 経由で Neon を作成する手順を解説しました。

【第6回】Learn Next.js チュートリアル解説：PostgreSQL データベースの構築と環境構築（Vercel連携）

Learn Next.js 解説第6回 PostgreSQLデータベース構築！Vercel Storageを使ったPostgresの作成から、.envの安全な設定方法、シードスクリプトによる初期データの流し込み、SQLクエリ実行テストまで紹介します。

go-pro-world.net

2026.10.10

結論から言うと、NeonはVercelなしで単体作成でき、Linux（Ubuntu）のターミナル（CLI）からも完全に制御可能です。

本記事では、Neonの基本概要から各構築方法のメリデメ、CLIでの爆速構築手順、ブラウザでの確認方法、さらにはPython/TypeScriptでおすすめのORM（Object-Relational Mapping）までを体系的に解説します。

1. Neonとは？（概要）

Neon（ネオン）は、オープンソースのPostgreSQLをクラウド向けに再構築したサーバーレスPostgreSQLサービスです。

従来のPostgreSQLサーバー（Amazon RDSなど）は、常にインスタンスを起動しておく必要があり、アクセスが無い時間帯も固定でサーバー費用が発生していました。これに対しNeonは、「コンピュート（計算処理）」と「ストレージ（データ保存）」を完全に分離したモダンなアーキテクチャを採用しています。

標準のPostgreSQLと100%完全互換であるため、既存のPostgresツールやドライバー、SQLクエリがそのまま動作します。

2. Neonの主な特徴

Neonが世界中のエンジニアに選ばれている理由は、以下の4つの強力な特徴にあります。

① 自動スケールと「Scale-to-Zero（自動停止）」

アクセスがない時間帯は、データベースのコンピュート処理が自動的に停止（Scale-to-Zero）します。クエリのリクエストが来ると数秒で復帰するため、「使った分だけ支払う」という圧倒的なコストパフォーマンスを実現できます。

② データベースのブランチ機能（Database Branching）

Gitの「ブランチ」と同じ感覚で、データベースのコピー（分岐）を一瞬で作成できます。
本番環境（Mainブランチ）から一瞬で開発用・テスト用のブランチを作成できるため、本番データを壊すリスクなくマイグレーションや機能テストを行えます。

③ 組み込みのコネクションプーラー（PgBouncer）

サーバーレス環境（Cloudflare WorkersやVercel Edge Functionsなど）から大量の非同期接続が飛んできても、PgBouncerが標準で組み込まれているため、接続オーバーヘッドによるダウンを防ぎます。

④ 試しやすい料金プランと無料枠

Neonにはクレジットカード登録不要で試せる「Freeプラン」が用意されています。

ポイント:
有料プランへ移行しても固定の月額最低料金がないため、個人の趣味プロジェクトやテスト環境を維持するコストを最小限に抑えられます。

3. Neonの構築方法の種類とメリット解説

Neonをプロビジョニング（構築）する方法は主に5つあります。用途に合わせて最適なアプローチを選びましょう。

現在のトレンド（ベストプラクティス）

個人開発やローカルでのアジャイル開発では、「基本はCLI（neonctl）で素早く作成し、データ確認時だけWeb UIを開く」というスタイルの人気が高まっています。

4. Ubuntu（CLI）からNeonを構築するコマンド紹介

ここからは、実際にUbuntu（Linux）のターミナルから公式CLIツール neonctl を使ってデータベースを作成する手順を解説します。

ステップ1: CLIのインストールと認証

Node.js環境（npx）が入っている場合は、インストール不要で即座にログイン可能です。
最初に npx をつければインストール不要でコマンド実行できます。

# アカウント認証（ブラウザが起動し承認を求められます）
npx neonctl auth

※グローバルにインストールして固定したい場合は npm install -g neonctl を実行します。そうすれば npx は不要です。

ステップ2: プロジェクト（データベース）の作成

Neonのシステムでは、「すべてのプロジェクトはいずれかのOrganization（組織）の中に所属する」というルールになっています。
以下のコマンドで、CLIを使って所属しているOrganization（組織）の一覧を簡単にリスト表示できます。

npx neonctl orgs list

もし別の組織をデフォルトに切り替えたくなった場合は、出力されたIDを指定して以下のコマンドを実行すれば変更できます。

npx neonctl link --org-id <組織ID>

ちなみに、NeonではCLIから直接新しい組織を作成するコマンドが用意されていないため、新しい組織を作成したい場合は、NeonのWeb管理画面から組織を作成し、CLIでその組織に切り替えるのがスムーズな手順となります。

Web画面で新しいOrganization（組織）を作成する

1. ブラウザで console.neon.tech にログインします。
2. 画面左上の組織名をクリックし、ドロップダウンメニューを開きます。
3. 「Create Organization」をクリックします。
4. 組織名を入力して作成を完了させます。

プロジェクト（データベース）を作成コマンドを実行する

プロジェクト名とリージョン（東京に近い aws-ap-southeast-1 など）を指定して以下のコマンドを実行するとデータベースのプロジェクトを作成できます。

# プロジェクトの作成
npx neonctl projects create --name my-neon-db --region-id aws-ap-southeast-1

コマンドの実行結果として、ターミナル上にプロジェクトIDや接続文字列（postgresql://…）が直接出力されます。

また自動で .env.local ファイルが作成され、その中に接続情報が保存されます。

DATABASE_URL="postgresql://..."
DATABASE_URL_UNPOOLED="postgresql://..."
NEON_BRANCH=main

現在リンクしているデータベースを変更する場合

以下のコマンドで現在リンクしているプロジェクトを変更することができます。

npx neonctl link

またプロジェクト作成時や、リンクプロジェクト変更時に以下の対話形式のメッセージが出たら、スキップして N を選んでも大丈夫です。

✔ Manage this project's Neon setup as code?
Adds a neon.ts you can edit and apply with `neon config apply`. … Y/n

Neonのデータベース設定（ブランチやロールなど）を、コード（neon.ts という設定ファイル）で管理できるようにしますか？と聞かれています

• 個人開発や通常のアプリ検証の場合: No で十分です。ファイルがごちゃつかずシンプルに進められます。
• IaC（インフラのコード管理）を試してみたい場合: Yes を選ぶと設定ファイルが生成されますが、ブログ記事の作成や通常のアプリ開発であれば No で進めて全く問題ありません。

Vercel連携のNeonでCLIからプロジェクトを作れない？「action restricted」の解決策

UbuntuのCLI（neonctl）を使ったデータベース構築手順を自分が実際に検証している最中で「あるハマりどころ」に遭遇しました。

遭遇したエラー：「organization is managed by Vercel」

ターミナルから以下のコマンドで新しいプロジェクトを作ろうとしたところ、次のようなエラーが発生しました。

npx neonctl projects create --name my-new-cli-test-db --region-id aws-ap-southeast-1
ERROR: action restricted; reason:"organization is managed by Vercel"

原因はVercel連携の仕組みにありました。

Vercel経由の組織は「CLIからの直接作成が制限されている」

過去にVercelのダッシュボード経由でNeonを利用したことがある場合、Neon側には自動的に「Vercelが管理する組織（Organization）」が紐づきます。

このVercel管理下にある組織では、安全性を保つため、Vercelの管理画面や連携機能以外（今回のCLIや外部API）からの勝手なプロジェクト作成や変更が制限（Restricted）されているのです。

解決策：Web UIで「個人用組織」を作って切り替える

この制限を回避し、CLIから自由にデータベースを作るためには、Vercelとは別の「個人用Organization」を新しく用意して切り替えるのが最もスマートな解決策です。

• Vercel用組織: Vercelにデプロイするプロダクトのデータベース管理用（基本はWebやVercel連携にお任せ）
• 個人用組織（Personal）: CLIやスクリプト、ローカル環境での実験・検証用

このように組織を分ける（あるいはCLIのリンク先を切り替える）ことで、Vercelの便利さとCLIの爆速開発体験を両立させることができます。もし同じエラーで手が止まってしまったら、ぜひ試してみてください！

ステップ3: 接続文字列（ConnectionString）の取得

設定した環境変数を後から確認したい場合は、以下のコマンドで一発取得できます。

# 接続文字列の表示
npx neonctl connection-string

これを開発中のアプリケーションの .env ファイルに DATABASE_URL として貼り付ければ準備完了です。

5. ブラウザ（Web UI）での確認方法

CLIで構築したプロジェクトは、当然ながらWeb管理画面にもリアルタイムで反映されています。

1. 公式サイトへアクセス: console.neon.tech にログインします。
2. ダッシュボードの確認: CLIで作った my-neon-db が一覧に表示されていることを確認できます。
3. データ閲覧と操作:
   • SQL Editor: ブラウザ上で直接クエリを実行・テストできます。
   • Tables: テーブル構造や追加されたレコードをGUIで視覚的に管理できます。
   • Branches: ブランチの作成やデータの分岐状態をグラフィカルに確認可能です。

💡 裏技（CLIからブラウザを一瞬で開く） CLIで操作中にWeb UIで確認したくなった場合は、ターミナルで以下のコマンドを打つとデフォルトブラウザで直接該当プロジェクトが開きます。

npx neonctl open

6. Python & TypeScriptのおすすめORM紹介

Neonは純粋なPostgreSQLであるため、基本的にはあらゆる言語のドライバーやORMに対応しています。ここでは、Neonのサーバーレス特性と相性の良い最新のおすすめORMを紹介します。

【TypeScript】おすすめORM

1. Drizzle ORM（★最もおすすめ）

• 特徴: 超軽量かつ高速。SQLに近い直感的な書き方でありながら、TypeScriptの型補完が強力に効きます。
• Neonとの相性: Neon公式の @neondatabase/serverless ドライバーと完全統合されており、WebSocketやHTTP経由の超低レイテンシな接続が可能です。

2. Prisma

• 特徴: schema.prisma によるわかりやすいデータモデル定義と、圧倒的なドキュメント・エコシステムが魅力。
• Neonとの相性: 接続プール（PgBouncer）を設定することで安定して動きますが、サーバーレス環境ではDrizzleよりやや動作が重くなる傾向があります。

【Python】おすすめORM

1. SQLModel（★FastAPIユーザーにおすすめ）

• 特徴: FastAPIの作者が作ったORMで、SQLAlchemy と Pydantic を組み合わせた仕様になっています。
• Neonとの相性: APIのレスポンス定義（型チェック）とDBモデルを1つのクラスで共通化できるため、開発スピードが飛躍的に向上します。

2. SQLAlchemy (v2.0+)

• 特徴: Python界におけるデファクトスタンダード（標準）のORM。
• Neonとの相性: psycopg3 や asyncpg などの非同期ドライバーと組み合わせることで、NeonのPostgresに対しても堅牢で複雑なトランザクション処理を実行できます。

まとめ

NeonはVercel専用のツールではなく、単体で圧倒的な柔軟性とコストパフォーマンスを誇る独立したサーバーレスPostgreSQLです。

特にUbuntuなどのCLI環境（neonctl）を使った爆速プロビジョニングと、ブラウザダッシュボードによる直感的な確認作業を組み合わせた運用は、個人開発やプロトタイピングにおける強力な武器になります。

まずは無料枠を使って、CLIからのデータベース作成とブランチ体験を試してみてはいかがでしょうか。