Serverpodとは？4.0で変わった始め方とFlutterバックエンドの採用判断【2026年10月時点】

Serverpod（サーバーポッド）は、Flutterアプリのバックエンドを Dart で書くためのフレームワークで、ソースコードは GitHub で公開されています（本体のライセンスは OSI が認めるオープンソースライセンスではない SSPL。後述）。サーバーに書いたエンドポイントとモデルから Dart のクライアントコードが自動生成されるので、Flutter 側からはローカルの関数を呼ぶ感覚で client.todo.create('…') と書けます。データベースは PostgreSQL を型付きの ORM で扱います。

2026年9月14日に 4.0.0 が公開され、Docker・コード生成・サーバー・アプリを別々のターミナルで動かしていた開発手順は serverpod start の1コマンドに置き換わりました。検索上位には 1系の手順で書かれた解説も残っています。この記事では最新の安定版 4.0.3（2026年9月25日公開）を前提に、仕組み、導入、モデルとエンドポイントの書き方、テスト、デプロイ先、他の選択肢との選び分けをまとめます。コード例は、2026年10月3日（日本時間）に Dart 3.13.5 と serverpod_cli 4.0.3（macOS x64）でサーバー専用プロジェクトを作り、結合テストと HTTP 呼び出しで動作を確かめたものです。

まとめ：Serverpod 4.0の要点と採用判断

• 位置づけ：Flutter／Dart 向けのバックエンドフレームワーク。モデル（.spy.yaml）とエンドポイントから Dart クライアントを生成し、サーバーとアプリで同じ型を使えます。
• 現行版：4.0.3（2026年9月25日）。4.0 で serverpod start、Docker 不要の埋め込み PostgreSQL、AI エージェント向け MCP サーバーの同梱が入りました。Dart 3.12.2／Flutter 3.44.4 以上が必要です。
• 始め方：dart install serverpod_cli → serverpod create → serverpod start。dart pub global activate と docker compose up で始める解説は 3.4 以前のものです。
• デプロイ：公式の推奨は Serverpod Cloud（Starter 月5ドルから、最初のプロジェクトは1か月無料）。自前で運用する場合は生成済みの Dockerfile を使い、サーバーレスでは future call とヘルスメトリクスに制約があります。
• 採用判断：Flutter 専業のチームが、リレーショナルなデータとリアルタイム通信を Dart で書きたいなら第一候補です。クライアントの主役が Flutter 以外のとき、サーバーを Dart を書かないチームが運用するとき、Serverpod 自体を第三者向けクラウドサービスとして提供するとき（SSPL の対象）は別の選択肢を検討してください。

以下、仕組みから順に、実際のコマンドと出力を添えて説明します。

Serverpodの仕組み：サーバーとFlutterアプリで型を共有する構成

Serverpod の中心は「サーバーのコードからクライアントを生成する」ことです。serverpod create demo で作ったプロジェクトは Dart workspace になっていて、役割の違う3つのパッケージが並びます。

エンドポイントのクラス名から末尾の Endpoint を除いた名前がクライアント側の入口になり、TodoEndpoint の create は client.todo.create() として呼べます。戻り値の型もモデルのクラスごと共有されるので、サーバーでフィールド名を変えると Flutter 側はコンパイルエラーで気づけます。

呼び出しの実体：HTTP POSTとWebSocket

生成クライアントの通常のメソッド呼び出しは、API サーバー（既定ポート 8080）への HTTP POST です。4.0 からはメソッド名をボディではなく URL のパスに載せる形になりました（CHANGELOG 4.0.0）。そのため curl でも呼べます。

$ curl -s -X POST http://localhost:8080/todo/create \
    -H 'Content-Type: application/json' -d '{"title":"buy milk"}'
{"__className__":"Todo","id":1,"title":"buy milk","done":false,"createdAt":"2026-10-02T15:20:04.395893Z"}

レスポンスの __className__ は、生成クライアントがどのモデルに復元するかを判別するための印です。Stream を返すメソッドは HTTP ではなく、Serverpod が管理する共有の WebSocket 接続に載ります。既定のポートは API が 8080、Serverpod Insights（ログとヘルス情報を見るデスクトップアプリ）用が 8081、Web サーバーが 8082 です。

Serverpod 4.0での変更点：古い解説記事との差分

版ごとの主な変更点

pub.dev の公開日と CHANGELOG から、記事を読むときに版の見分けがつく変更をまとめます。

古い手順をそのまま試すと詰まる箇所は次のとおりです。

• CLI の導入は dart pub global activate serverpod_cli から dart install serverpod_cli に変わりました。
• モデルファイルは .spy.yaml の拡張子が必須です。.yaml のままだと serverpod generate がエラーで止まります。
• ローカルの DB に docker compose up は不要になりました。テンプレートは今も docker-compose.yaml を出力しますが、設定に dataPath があれば埋め込み PostgreSQL が使われます。
• serverpod create --mini は削除され、DB なしの構成は --no-database で作ります。
• 旧来のストリーミング API（ストリーミングセッション）は削除され、ストリーミングメソッドに一本化されました。

3.4系から4.0への移行手順

公式の移行ガイド（Upgrade to 4.0）は、先に最新の 3.4.x へ上げ、テストが通る状態をコミットしてから始めるよう求めています。手順の骨格は次のとおりです。

$ dart pub global deactivate serverpod_cli
$ dart install serverpod_cli
# 各 pubspec.yaml の serverpod 系パッケージを 4.0.x に固定し、SDK 制約を ^3.12.2 に
$ dart pub upgrade
$ serverpod generate
$ serverpod create-migration --tag "upgrade-4-0" --force

pubspec では serverpod_ で始まる全パッケージを同じ版に固定します。dev_dependencies の serverpod_test を上げ忘れると dart pub upgrade が失敗します。最後のマイグレーションに --force が要るのは、認証モジュールのレート制限テーブルを作り直すためで、カウンターが0に戻る以外の影響はないと説明されています。旧認証モジュール serverpod_auth は 4.0 でも動きますが、クライアントの初期化と Sign in with Apple の書き換えが必要です。

開発環境の準備：Flutter 3.44.4以上とserverpod_cli

Serverpod 4 は Flutter 3.44.4 以上（同梱の Dart 3.12.2 以上）を前提にしています。Flutter SDK 自体の入れ方は Flutterの環境構築｜Windows・macOS別のSDK導入とflutter doctor診断【2026年8月時点】 を参照してください。

$ flutter --version
$ dart pub global deactivate serverpod_cli   # 3.x以前を pub global で入れていた場合だけ
$ dart install serverpod_cli
$ serverpod version
Serverpod version: 4.0.3

macOS では dart install の導入先が PATH に無く、直後に serverpod が見つからないことがあります。案内のとおりシェルの設定に追記します。

# macOS の場合（dart install の導入先）
export PATH="$PATH":"$HOME/Library/Application Support/Dart/install/bin"

サーバーだけを作る場合でも、serverpod コマンドは起動時に Flutter の有無を確かめ、PATH に無いと「You need to have flutter installed and in your $PATH」で終了します。CLI のソースでは CI 環境と判定されたときだけこの確認を省きます。VS Code 拡張（モデルファイルのシンタックスハイライトと診断）と Serverpod Insights は任意です。

プロジェクト作成と起動：serverpod createからserverpod startまで

serverpod createのテンプレートとオプション

$ serverpod create demo                 # Flutter アプリ込み（既定の fullstack）
$ serverpod create demo -t server      # サーバーとクライアントだけ
$ serverpod create demo --no-database  # DB なし（旧 --mini の代わり）

主なオプションは次のとおりです。--ide を指定すると、Claude・Cursor・VS Code（この3つが既定）などのエージェント向けスキルと MCP サーバーの設定が書き込まれます。エージェントに任せて組む前提なら、対話式の serverpod quickstart も用意されています。Dart 側の MCP サーバーについては Flutter MCPサーバー（Dart MCP Server）とは？24ツールの内訳と既定オフの落とし穴【2026年8月時点】 で整理しています。

-t server で作った構成は次のとおりでした（fullstack では demo_flutter が加わります）。

demo/
  pubspec.yaml            Dart workspace のルート
  AGENTS.md               AI エージェント向けの指示書
  demo_server/
    bin/main.dart         起動点
    config/               development / staging / production / test / passwords.yaml
    lib/src/greetings/    サンプルのエンドポイントとモデル
    migrations/           生成されたマイグレーション
    Dockerfile
    docker-compose.yaml
  demo_client/            serverpod generate が生成する Dart クライアント
  demo_flutter/           Flutter アプリ（fullstack のときだけ）

serverpod startと埋め込みPostgreSQL

serverpod start はコード生成の監視、サーバー、DB、Flutter アプリをまとめて起動するターミナル UI です。ファイルを保存するたびにコードを生成し直してサーバーをホットリロードし、R でホットリスタート、M でマイグレーションの作成と適用ができます。

DB は、設定ファイルに dataPath があればサーバーと一緒に起動・停止する埋め込み PostgreSQL になります。初回起動時に OS 別のバイナリをユーザー単位のキャッシュへダウンロードし、macOS では ~/Library/Caches/serverpod/pg-binaries に PostgreSQL 16.13.0 が入りました。バックアップもレプリケーションもないので、用途は開発とテストに限られます。本番は dataPath を外して、マネージドの PostgreSQL へ host と port で接続します。

# demo_server/config/development.yaml（抜粋）
database:
  host: localhost
  port: 8090
  name: demo
  user: postgres
  dataPath: .serverpod/development/pgdata   # この行があると埋め込み PostgreSQL

$ cd demo
$ serverpod start                                  # TUI で生成・サーバー・アプリをまとめて起動
$ cd demo_server && dart bin/main.dart --apply-migrations   # TUI を使わず起動する場合
$ serverpod database start                         # psql などで中身を見たいとき（サーバー停止中に）

埋め込み DB はサーバーと TCP でなく Unix ドメインソケットで接続するため、複数プロジェクトを同時に動かしてもポートがぶつかりません。その代わり psql や pgAdmin の通常の TCP 接続設定では入れないので、中身を見るときはサーバーを止めて serverpod database start で TCP 待ち受けの DB だけを起動します。

モデルとエンドポイントの実装：Todo APIの最小構成

以下はローカルで動きを確かめるための最小例です。Endpoint の requireLogin は既定で false なので、このままでは誰でも全件を読み書きできます。公開する前に requireLogin を true にして所有者の条件で絞り込み、toggle のような読み取り後の更新は、トランザクションと行ロック（3.4 で追加）で競合を防いでください。

モデルは lib 配下の任意の場所に .spy.yaml で書きます。table キーを付けると DB のテーブルに対応し、Todo.db 経由の ORM メソッドが生成されます。

# demo_server/lib/src/todos/todo.spy.yaml
### タスク1件を表すモデル
class: Todo
table: todo
fields:
  title: String
  done: bool, default=false
  createdAt: DateTime, default=now
indexes:
  todo_created_idx:
    fields: createdAt

エンドポイントは Endpoint を継承したクラスで、各メソッドは第1引数に Session を取り、Future か Stream を返します。引数と戻り値に使う代表的な型は、基本型、.spy.yaml で定義したモデル、それらの List・Map・Set です（4.0 からは dynamic も使えます）。

// demo_server/lib/src/todos/todo_endpoint.dart
import 'package:serverpod/serverpod.dart';

import '../generated/protocol.dart';

class TodoEndpoint extends Endpoint {
  Future<Todo> create(Session session, String title) async {
    return Todo.db.insertRow(session, Todo(title: title));
  }

  Future<List<Todo>> list(Session session) async {
    return Todo.db.find(session, orderBy: (t) => t.createdAt.desc());
  }

  Future<Todo?> toggle(Session session, int id) async {
    final todo = await Todo.db.findById(session, id);
    if (todo == null) return null;
    return Todo.db.updateRow(session, todo.copyWith(done: !todo.done));
  }

  Stream<int> countdown(Session session, int from) async* {
    for (var i = from; i >= 0; i--) {
      yield i;
    }
  }
}

保存するとコード生成が走ります（serverpod start を使わない場合は手で実行）。テーブルを足したのでマイグレーションも作ります。生成された SQL は次のとおりで、int の id は bigserial、default=now は CURRENT_TIMESTAMP に変換されました。

$ serverpod generate
$ serverpod create-migration
 • Server migration created: migrations/20261002151754155

-- migrations/20261002151754155/migration.sql（抜粋）
CREATE TABLE "todo" (
    "id" bigserial PRIMARY KEY,
    "title" text NOT NULL,
    "done" boolean NOT NULL DEFAULT false,
    "createdAt" timestamp without time zone NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX "todo_created_idx" ON "todo" USING btree ("createdAt");

生成されたクライアントからは、普通の非同期関数として呼べます。下は Dart の CLI プログラムから呼んだ結果で、Flutter アプリでも client の作り方以外は同じです。

// demo_client を使う Dart プログラム（Flutter アプリからも同じ書き方）
import 'package:demo_client/demo_client.dart';

Future<void> main() async {
  final client = Client('http://localhost:8080/');
  final t = await client.todo.create('write article');
  print('created id=${t.id} done=${t.done}');
  final toggled = await client.todo.toggle(t.id!);
  print('toggled done=${toggled?.done}');
  final values = await client.todo.countdown(3).toList();
  print('stream=$values');
  client.close();
}

// 実行結果
// created id=2 done=false
// toggled done=true
// stream=[3, 2, 1, 0]

4.0.3 の Flutter テンプレートでは、lib/client.dart の initializeClient() が Client(await serverUrl)..connectivityMonitor = FlutterConnectivityMonitor() を作り、main() がそれを呼んでアプリ全体で使い回します。実機から手元のサーバーを呼ぶときは localhost ではなく PC の IP アドレスを --dart-define=SERVER_URL=… で渡します。

データベース操作：ORMのCRUDとマイグレーション

ORMの主なメソッド

SQL を書かずに、モデルごとに生成される Model.db のメソッドで読み書きします。条件と並び順はラムダで列を指定するので、列名の打ち間違いはコンパイル時に分かります。

並び順は 4.0 から t.createdAt.desc() のように列に対して書くのが推奨になり、Order オブジェクトを手で作る書き方は非推奨になりました。リレーションはフィールドに relation を付けて表します。下は Company 側だけの抜粋で、参照先の Employee モデル（table 付き）も別ファイルに定義する必要があります。

# 1対多：Company が複数の Employee を持つ
class: Company
table: company
fields:
  name: String
  employees: List<Employee>?, relation

マイグレーションの作成と適用

serverpod create-migration は現在のモデル定義と直前のマイグレーションを比べ、差分を migrations/<タイムスタンプ>/migration.sql に書き出します。適用は、serverpod start なら M キー、直接起動なら --apply-migrations 付きで起動したときです。実測でも、起動ログに「Applied database migration: 20261002151754155」と出てからリクエストを受け付けました。

リアルタイム通信と認証：ストリーミングメソッドとserverpod_auth_idp

ストリーミングメソッドの接続管理とping間隔

戻り値か引数に Stream を使ったメソッドは、ストリーミングメソッドとして共有の WebSocket 上でやり取りされます。前述の countdown は、クライアントで toList() すると [3, 2, 1, 0] を受け取りました。呼び出しごとに専用の Session が作られ、クライアントが購読をやめるかメソッドが終わると閉じます。サーバーは開いている接続に既定で30秒ごとに ping を送ります。ロードバランサーのアイドルタイムアウトがそれより短い場合は、環境変数 SERVERPOD_WEBSOCKET_PING_INTERVAL（秒）で間隔を縮めます。

認証プロバイダーとトークン方式

3.0 で作り直された認証モジュール serverpod_auth_idp は、トークンの扱いを JWT とサーバー側セッションから選べます。4.0 の fullstack テンプレートにはメール認証が最初から組み込まれており、main.dart の2か所を書き換えるだけでサインイン画面が出ます。

Web クライアントでは、トークンが JavaScript から読めるストレージに置かれるのが既定です。4.0 で追加された Cookie モードを使うと httpOnly Cookie に移せます。サーバー設定に authCookie セクションを1項目以上書き（子のない authCookie: だけでは無効のまま）、allowedOrigins に Web アプリのオリジンを列挙し、initializeClient() で cookieAuth を有効にします。http://localhost で試すときは authCookie.secure を false にします。JWT 方式で Cookie に入るのはリフレッシュトークンで、短命のアクセストークンはメモリに保持されます（公式：Web authentication）。

結合テスト：withServerpodで埋め込みDBごと検証

4.0 では serverpod_test の withServerpod を使ったテストが素の dart test で動き、DB も埋め込み PostgreSQL が自動で立ち上がります。withServerpod のグループごとにランダムな名前の DB が作られて終了時に消えるので、テスト同士でデータが混ざりません。

// demo_server/test/integration/todo_endpoint_test.dart
import 'package:test/test.dart';

import 'test_tools/serverpod_test_tools.dart';

void main() {
  withServerpod('Todo endpoint', (sessionBuilder, endpoints) {
    test('create -> list -> toggle', () async {
      final a = await endpoints.todo.create(sessionBuilder, 'buy milk');
      expect(a.done, isFalse);
      final all = await endpoints.todo.list(sessionBuilder);
      expect(all.map((t) => t.title), contains('buy milk'));
      final t = await endpoints.todo.toggle(sessionBuilder, a.id!);
      expect(t!.done, isTrue);
      expect(await endpoints.todo.toggle(sessionBuilder, 999999), isNull);
    });

    test('countdown streams values', () async {
      final values = await endpoints.todo.countdown(sessionBuilder, 3).toList();
      expect(values, [3, 2, 1, 0]);
    });
  });
}

$ dart test test/integration/todo_endpoint_test.dart
00:16 +1: Todo endpoint countdown streams values
00:16 +2: All tests passed!

初回はバイナリの展開を含めて約16秒で2件とも通りました。今回の実測では、テスト終了後も .serverpod/test/pgdata の postgres プロセスが残っていたため pg_ctl stop で止めました。手元で繰り返すときはプロセスの残りを確認してください。

デプロイ先の選び方：Serverpod Cloud・Docker・サーバーレス

公式ドキュメントの推奨は、Serverpod チームが運営する Serverpod Cloud です。自前で運用する場合は、生成済みの Dockerfile でコンテナにするか、Dart をそのまま実行します。費用の目安は次のとおりです（Cloud は Serverpod Cloud の料金表、GCP は 公式ドキュメントの概算。2026年10月3日時点）。

$ serverpod cloud launch                              # 初回：Cloud CLI 導入・ログイン・プロジェクト紐付け・デプロイ
$ serverpod cloud password set geminiApiKey "..."     # passwords.yaml の値を本番へ
$ serverpod cloud deploy                              # 2回目以降

passwords.yaml 自体はアップロードされず、launch の途中で選んだ値だけが Cloud 側のシークレットに写されます。

自前で運用する場合、サーバーには3つのロールがあります。1台またはクラスタなら既定の monolith で、ヘルスチェックや future call などの保守処理も担います。サーバーレス（Cloud Run 等）では serverless ロールで受信だけを担当させ、future call とヘルスチェックが必要なら maintenance ロールを毎分 cron で起動します。サーバーレスではインスタンスがいつ破棄されてもおかしくないため、メモリ上の状態やサーバー内キャッシュは保持も台数間の共有も保証されません（共有キャッシュは Redis で持てます）。WebSocket で状態を持つ構成はクラスタ向きです。

$ docker build -f demo_server/Dockerfile .           # プロジェクトのルートで実行
$ dart bin/main.dart --mode production --role serverless
$ dart bin/main.dart --mode production --role maintenance   # サーバーレス時は毎分 cron で起動

なお、GitHub の README には今も「GCP と AWS 向けの Terraform スクリプトが付属する」と書かれていますが、4.0 のプロジェクトテンプレートに Terraform の定義は含まれず、リポジトリ内で見つかるのは旧サンプル（examples/legacy）だけでした。現行ドキュメントのデプロイ章も Serverpod Cloud、自前ホスティング、コミュニティ製の VPS 向けツール serverpod_vps（Docker Compose）の3本です。Terraform で AWS に載せる解説は 2系・3系のテンプレートを前提に読んでください。

採用判断：Firebase・Supabase・Dart Frogとの比較と向かないケース

Flutter のバックエンド候補は、サーバーコードを書く量とデータの形で分かれます。

Firebase 側の選択肢は Cloud Functions for Firebaseとは｜トリガー設計と第2世代の実装判断【2026年8月時点】 と FlutterからCloud Functionsを呼ぶ手順｜cloud_functions 6.5のhttpsCallable・エラー処理・ストリーミング、Supabase の変更通知は Supabase Realtimeの実装｜3方式の使い分けとRLS併用・同時接続の上限、認証は Supabase Authとは：非対称JWT鍵とRLS連携で組む認証実装の設計判断 で詳しく扱っています。

Serverpod が最も効くのは、アプリもサーバーも同じチームが Dart で書き、PostgreSQL のリレーションとトランザクションを使い、WebSocket の双方向通信も欲しい場合です。モデルを1か所で定義すれば、テーブル・サーバーのクラス・Flutter のクラスが揃って変わります。BaaS のルール言語や別言語の関数と、アプリ側の型を二重に管理する手間がなくなります。

逆に、次の条件に当てはまるなら採用を見送ります。

• クライアントの主役が Flutter 以外：生成されるクライアントは Dart パッケージです。React などの Web フロントからは curl と同じく HTTP を手で組むことになり、型共有の利点が消えます。
• サーバーを Dart を書かないチームが運用する：障害対応やライブラリ選定まで Dart の知識が要ります。Node.js や Go の運用体制がすでにあるなら、そちらの方が保守の人手を確保しやすくなります。
• Serverpod を第三者向けのクラウドサービスとして提供する：serverpod 本体のパッケージは SSPL です（条件は下のよくある質問を参照）。
• 既存の 3.4 系本番をすぐ上げたい：4.0.0 から 4.0.3 までの11日間に、maintenance ロールでマイグレーション適用に失敗したときに終了コード1で終わらなかった不具合などが直されています。ステージングでマイグレーション適用と認証の挙動を確かめてから移すのが安全です。

Serverpodについてよくある質問

Serverpod Cloudの料金はいくらですか？

2026年10月3日時点で、Starter が月5ドル、Growth が月20ドル＋従量、Enterprise が月799ドル＋従量です。最初のプロジェクトにはクレジットカード不要の1か月無料トライアルが付きます。

Serverpodの開発にDockerは必要ですか？

4.0 で新規作成したプロジェクトでは不要です。設定の dataPath により埋め込み PostgreSQL が起動します。3.4 以前から移行したプロジェクトは Docker の PostgreSQL をそのまま使い続けることもでき、本番で自前運用するならコンテナ化に Dockerfile を使います。

Flutter以外のクライアントからServerpodのAPIを呼べますか？

呼べます。通常のメソッドは POST /エンドポイント名/メソッド名 に JSON の引数を送る HTTP 呼び出しで、curl からの実行でもモデルの JSON が返りました。ただし生成されるのは Dart クライアントなので、他の言語では型定義とストリーミングの扱いを自前で書くことになります。

Serverpodは商用利用できますか？

できます。serverpod パッケージは SSPL、クライアント用を含むそれ以外のパッケージは BSD-3 です。GitHub の README は、自社サーバーの運用は制限なく行え、Serverpod を第三者向けクラウドサービスとして提供しない限り問題にならないと説明しています。

DartからPostgreSQLにつなぐにはServerpodが必要ですか？

必要ありません。pub.dev の postgres パッケージ（2026年10月1日公開の 3.5.18 が最新）で直接つなげます。Serverpod 4.0.3 もこのパッケージ（^3.5.16）を内部で使っています。テーブル定義の自動生成、マイグレーション、クライアントとの型共有まで欲しいときに Serverpod を選びます。

関連記事

• FlutterからCloud Functionsを呼ぶ手順｜cloud_functions 6.5のhttpsCallable・エラー処理・ストリーミング
• Cloud Functions for Firebaseとは｜トリガー設計と第2世代の実装判断【2026年8月時点】
• Supabase Authとは：非対称JWT鍵とRLS連携で組む認証実装の設計判断
• Flutterの環境構築｜Windows・macOS別のSDK導入とflutter doctor診断【2026年8月時点】
• Flutter MCPサーバー（Dart MCP Server）とは？24ツールの内訳と既定オフの落とし穴【2026年8月時点】