エラーと診断

Calíopeで何が、いつ、どのデバイスでうまくいかなかったか。

場所： ワークスペース › ツール › エラー

「エラーログ」には、アプリの失敗が1件につき1行で保存されます。協定世界時のタイムスタンプ、発生したデバイス、影響を受けた領域、関係する接続プロファイル（あれば）が記録されます。

これはクエリーログではありません。クエリーログに保存されるのは、SQL文に対するサーバの応答（たとえば構文のERROR 1064）で、これはSQLを書けば普通に起きる結果です。エラーログに保存されるのは、アプリに起きたことです。開かない接続、切れるトンネル、書き込めないバックアップなどです。

オフラインでも動作します。これは意図的です。ログはローカルにあり、接続できないときこそ読めなければなりません。それが最も必要なときだからです。

決して保存されないもの：パスワードは、一部分でも保存されません。認証の失敗は、失敗したことと対象のプロファイルを記録するだけで、どの資格情報を使ったかは記録しません。サーバは、ホスト、ポート、ユーザではなく、プロファイルの別名で特定されます。

ひとりでに繰り返す失敗でログがあふれることはありません。ヘルスモニタは数秒ごとに各サーバに問い合わせるので、電源の切れたサーバがあると、一晩で同じ行が何千も残ってしまいます。そこで、最初の1回を記録し、問題が変わったとき、サーバが回復してまた失敗したとき、または6時間後も同じ状態のときに、もう一度記録します。1行しかないからといって、1回しか起きなかったとは限りません。

行をダブルクリック（iPadではタップ）すると詳細が開き、サポートに必要な技術的なテキストと、それをコピーするボタンが表示されます。エラーに専用の説明がある場合は、「解決方法を表示」ボタンがあります。

Apple Vision Pro：iPadと同じです。行を見てピンチすると開きます。

キーワード： エラー、ログ、診断、失敗、サポート

ログの同期の仕組みと、デバイスの外に出るもの。

場所： Calíope › 設定 › 一般

ログは個人のiCloudにミラーリングできるので、iPadで失敗したことがMacにも表示されます。各行には、それが起きたデバイスが記録されます。どの行を誰が書いたのか区別できない統合ログでは、診断の役に立たないからです。

スイッチは最初はオフで、それは見落としではありません。ローカルのログは、あなた自身のマシンにあるあなた自身のファイルです。アップロードすると、プロファイルの別名と、すべての失敗の技術的な詳細がデバイスの外に送られます。それは前提にせず、確認して決めることです。このスイッチは「設定」›「一般」にあり、記録を有効にするスイッチとは別です。一方は保存するかどうかを、もう一方は外に出すかどうかを決めます。

ほかの設定と一緒に移動しない理由。設定は、すべてで共有する上限1メガバイトの小さなiCloudストアを通って移動します。それがいっぱいになると、いっぱいにしたものだけでなくすべての同期が止まります。エラーログは使うほど大きくなるので、別の経路（CloudKit、レコードごと）を通ります。この経路なら、複数のデバイスが同時に書き込んでも互いに上書きしません。

保持期間。デフォルトは90日で、「設定」で変更できます。削除はローカルのファイルとiCloudの両方に適用されるので、ログを消去しても、iCloudに残ったコピーが次の同期で戻ってくることはありません。

オフにする。Calíopeは、すでにiCloudにあるコピーをどうするかを確認します。「オフにしてiCloudのコピーを残す」はほかのデバイスのためにそのまま残し、「オフにしてiCloudのコピーを削除」はすべてのデバイスから削除します。各デバイスがローカルに保持しているものはそのまま残ります。

ログ自体から。ツールのバーにある雲のボタンで、「設定」に行かなくても同じことができます。オンにするときは、すでにあるものを送るか（「既存のログをアップロード」）、これから失敗するものだけを送るか（「新しいエラーのみ」）を確認します。オフにするときは、先にiCloudにあるものをダウンロードするか（「iCloudからログをダウンロード」）を確認し、iCloudのコピーはそのまま残します。

キーワード： iCloud、同期、デバイス、プライバシー、保持期間

サーバが応答しませんでした：確認することと、その順序。

対象： MySQL MariaDB Aurora TiDB 8.5+ SQL Server PostgreSQL ClickHouse Redis Valkey 8.0+ Cassandra ScyllaDB

このエラーは、接続しようとしてもどのサーバとも通信できなかったことを意味します。そのホストとポートで何も待ち受けていないか、途中で何かが接続を妨げています。

可能性の高い順に：

1. プロファイルのホストとポート。コンテナで動くサーバは、エンジンのデフォルト（下記）とは別のポートを公開していることがよくあります。
2. サーバが動いているか。アクセスできるなら、サーバが動いているマシンで確認してください。
3. SSHトンネル（使っている場合）。トンネルの失敗は、「接続できない」という形で現れることがとてもよくあります。ログで、このエラーの直前にSSHのエラーがないか探してください。
4. ファイアウォールやネットワーク。切れたVPN、サーバのポートをフィルタする社内ネットワーク、クラウドのセキュリティグループの規則は、どれも同じこのエラーになります。
5. サーバが待ち受けているインターフェイス。127.0.0.1だけで待ち受けているサーバは、動いていても別のマシンからは到達できません。その場合の解決策はポートを開くことではなく、SSHトンネルです。

キーワード： 接続、拒否、ポート、ホスト、ファイアウォール、2003、1433、5432、1521、2484

接続はサーバに届いたものの、この場所からは資格情報が有効ではありません。

対象： MySQL MariaDB Aurora TiDB 8.5+ SQL Server PostgreSQL ClickHouse Redis Valkey 8.0+ Cassandra ScyllaDB

このエラーは半分は良い知らせです。ネットワークが動いていて、サーバが生きているということだからです。失敗しているのは身元の確認です。

原因は3つあり、直し方はそれぞれ違います：

- パスワードかユーザ名が、サーバが想定しているものと違う。接続マネージャで確認してください。パスワードを貼り付けたときは、先頭や末尾の空白に注意してください。
- アカウントは存在するが、このマシンからは使えない。アカウントがどこから接続できるかは、エンジンごとに決め方が違います。詳しくは下記のとおりです。
- アカウントに、そのデータベースに対する権限がない。メッセージにデータベース名がある場合、ユーザはログインできてもそのデータベースを使えません。そのデータベースに対するGRANTが足りません。

キーワード： アクセス、拒否、資格情報、パスワード、権限、1045、18456、28P01

削除されたか、名前が変わったか、あなたのアカウントからは見えないかのどれかです。

対象： MySQL MariaDB Aurora TiDB 8.5+ SQL Server PostgreSQL Cassandra ScyllaDB

Calíopeはプロファイルのデフォルトのデータベースでセッションを開くので、このエラーはたいてい、サーバが変わってそのデータベースがなくなったときに、そのサーバに接続すると現れます。

確認すること：

- 別のサーバ。似たプロファイルがいくつもあると、ステージング環境だと思って本番環境を見ていることがよくあります。

スキーマツリーを更新すると、サーバがいま実際に返す一覧が表示されます。

キーワード： データベース、不明、スキーマ、権限、1049、4060、3D000

操作の途中で切れました：起きる理由と、途中のまま残るもの。

接続は確立されたあとで切れました。大事なのは再接続すること（それは簡単です）ではなく、何が途中のまま残ったかを知ることです。

明示的なトランザクションの外で書き込みのSQL文が実行中だった場合、切れた位置によって、その文は完全に適用されたか、一部だけ適用されたか、まったく適用されていないかのどれかです。最後に送られた文はクエリーログでわかります。繰り返す前に、サーバで確認してください。

よくある原因：

- ネットワーク。Wi-Fiの切り替え、マシンのスリープ、VPNの再接続は、どれも予告なしに接続を切ります。

キーワード： 接続の切断、タイムアウト、wait_timeout、ネットワーク、2006、2013

SSH認証の失敗：鍵、パスワード、そして2台目のデバイスの場合。

トンネルはSSHサーバに届きましたが、認証できませんでした。データベースへの接続は、まだ試みられてもいません。

最も紛らわしいケース：もう一方のデバイスを設定したばかりの場合。プロファイルはiCloudで同期されますが、秘密鍵ファイルを読むためのアクセス権は同期されません。これは見落としではありません。そのアクセス権は*1台の*マシンのファイルシステムへの参照で、別のマシンでは意味がないからです。新しいデバイスでは、プロファイルで鍵ファイルをもう一度選ぶ必要があります。「同じプロファイルがMacでは動くのにiPadでは動かない」原因の第1位がこれです。

ほかの原因は、順に：

- SSHのユーザはデータベースのユーザではありません。2つは別々の身元で、名前が違うこともよくあります。
- 公開鍵がサーバにありません。そのマシンの、そのユーザの~/.ssh/authorized_keysに載っている必要があります。
- サーバでのファイルのアクセス権。ほかのユーザが読めるauthorized_keysは、サーバが理由を言わずに黙って無視します。
- 鍵のパスフレーズ。鍵が保護されている場合は入力が必要です。パスフレーズのない保護された鍵は、間違った鍵とまったく同じように振る舞います。

キーワード： SSH、認証、秘密鍵、authorized_keys、トンネル

正常な場合、そうでない場合、そして受け入れる前に確認する方法。

SSHサーバに初めて接続するとき、Calíopeはその鍵のフィンガープリントを保存します。あとの接続でサーバが別のものを提示すると、Calíopeは停止して警告します。

この警告は形式的な雑音ではありません。鍵が変わることは、あなたのマシンとサーバの間で通信が傍受されたときとまったく同じ見え方をします。新しい鍵を受け入れると、知らないうちに資格情報を渡してしまうかもしれません。

変更が正当な場合：

- サーバのオペレーティングシステムが再インストールされた。
- 仮想マシンやコンテナが作り直された。
- 名前やIPアドレスが別のマシンに割り当て直された（クラウドではよくあります）。

正しく確認する方法：そのマシンの管理者に、接続そのものとは別の経路（メッセージや電話など）でフィンガープリントを尋ね、警告に表示されているものと比べてください。一致すれば受け入れます。確認できなければ、受け入れないでください。

キーワード： SSH、ホスト鍵、フィンガープリント、セキュリティ、中間者攻撃

対応している形式と、ファイルがひとりでに読めなくなる理由。

Calíopeは独自のSSH実装を持ち、システムのsshを使わないため、対応する形式は決まっています。OpenSSH形式のed25519鍵とECDSA鍵です。

ファイルはあるのに読み込めない場合：

- アクセス権の期限が切れている可能性があります。Calíopeが扱えるのは、あなたがダイアログで自分で選んだファイルだけで、そのアクセス権は、無効になることもある参照として保存されています。ファイルを移動したり、フォルダの名前を変えたり、マシンをバックアップから復元したりした場合は、もう一度選ぶ必要があります。
- 古いRSA鍵の可能性があります。ed25519に変換してください。ed25519のほうが速く、短くもあります。
- 公開鍵を選んだ可能性があります。正しいファイルは、.pubで終わらないほうです。
- パスフレーズで保護されている可能性があります。その場合は、接続するときにパスフレーズを入力する必要があります。入力しないと鍵を復号できず、結果は読めないファイルと見分けがつきません。

キーワード： 秘密鍵、ed25519、ECDSA、OpenSSH、アクセス権、ブックマーク

数分ごとに切れる場合：ほとんどは、サーバがアイドル状態のセッションを閉じています。

トンネルは開いていましたが、閉じてしまいました。プロファイルを再接続すれば直りますが、頻繁に起きるなら、取り除ける具体的な原因があります。

最も多いのは、SSHサーバ自身がアイドル状態のセッションを閉じていることです。多くのsshdの設定では、ClientAliveIntervalとClientAliveCountMaxが、通信のない状態が数分続くと切断するように調整されています。データベースの作業セッションでは、何も送らずに読んでいる時間が長く続くので、アプリに戻ったとたんにトンネルが切れます。

ほかの原因：

- マシンがスリープした。スリープから復帰すると、それまでのネットワーク接続はもう有効ではありません。
- ネットワークの変更。Wi-Fiから有線LANへ、あるいは別のWi-Fiネットワークへ切り替えると、送信元アドレスが変わり、セッションが切れます。
- 複数の人が同じSSHユーザを共有している場合の、サーバの同時セッション数の上限。

「アクティビティ」パネルには、トンネルが生きている間はアクティブなモードとして表示されるので、まだ開いているかどうかがひと目でわかります。

キーワード： SSH、トンネル、切断、ClientAliveInterval、アイドル

接続を受け付けてから閉じたか、鍵を提示しないまま応答しませんでした：たいていは、SSHではないポートです。

相手側はTCP接続を受け付けたあとでそれを閉じたか、SSH鍵を提示しないまま15秒間何も返しませんでした。Calíopeはそこで止まります。閉じられた場合はおよそ1秒以内に、応答がない場合は15秒後にエラーになります。

よくある原因
- SSHではないポート。最も多いのは、データベースのポートをトンネルのSSHポートとして入力してしまうことです。プロファイルで確認してください。SSHは通常22です。
- サーバが新しい接続を拒否している。sshdは、MaxStartupsの上限を超えた接続を、挨拶する前に切ります。同時接続が多いときや、誰かがパスワードを次々に試しているときに起きます。
- 間にあるファイアウォールやプロキシが、接続を受け付けてから切っている。

以前のバージョンのCalíopeは、この場合エラーを出さずに「接続中」のままでした。現在はこのメッセージで失敗します。

キーワード： SSH、トンネル、ポート、MaxStartups、ファイアウォール、タイムアウト

CalíopeがiCloudに求めるものと、それがないと動かなくなるもの。

Calíopeは、プロファイル、設定、そして（有効にした場合は）ログを、デバイスからデバイスへ運ぶのにiCloudを使います。有効なアカウントがないと、それらはすべてローカルに留まります。

確認すること：

1. 「システム設定」でiCloudにサインインしていること。
2. アカウントだけでなく、iCloud Driveがオンになっていること。
3. iCloud Driveの使用を許可されたアプリの一覧にCalíopeがあること。これは見落としがちです。アカウントに問題がなくても、アプリのチェックが外れていることがあります。

その間も何も失われません。すべてはこのデバイスに保存されたままで、もう一方への複製が行われないだけです。iCloudが戻れば、同期は自動で追いつきます。

キーワード： iCloud、アカウント、iCloud Drive、同期、コンパニオン

アップロードに失敗してもデータは失われません。繰り返す場合の対処法。

まず、何も失われていません。Calíopeが同期するものはすべてこのデバイスにコピーがあり、アップロードは追加のコピーです。ここでの失敗は、もう一方のデバイスがデータを見るのが遅れるという意味で、削除されたという意味ではありません。

一度だけ起きて再発しないなら、ほぼ確実にネットワークが原因です。自動で再試行します。

繰り返し起きる場合：

- アカウントのストレージを確認してください。iCloudがいっぱいだと、このエラーが毎回起きます。
- 書き込みが続きすぎていないか確認してください。CalíopeはiCloudのレート制限を超えないようにアップロードをまとめていますが、非常に大きなログの最初のアップロードには、何回か試行が必要になることがあります。
- 失敗している同期を一度オフにして、オンに戻してください。有効にし直すと、すべてを最初からアップロードします。

何かに触る前に、コピーを取ってください。「設定」には設定全体の書き出しがあります。同期の有効化がうまくいかないと、コンテナの接続ファイルが空のファイルに置き換わることがあるため、この機能があります。これは仮説ではなく、実際に起きて確かめた事例です。

キーワード： iCloud、同期、失敗、再試行、バックアップ

Calíopeで容量を使っているものと、大事なものを失わずに減らせるもの。

Calíopeがデフォルトで保存するiCloudのデータはごくわずかです。接続プロファイルと設定は数キロバイトです。

使うほど大きくなるのはログです。ただし、有効にした場合だけです。クエリーログとエラーログです。どちらも「設定」で保持期間を変更でき、それを短くするのが、見ていたものを失わずに容量を取り戻す最も直接的な方法です。

効果の大きい順に、減らせるもの：

1. クエリーログの保持日数。群を抜いて大きいものです。すべてのSQL文の全文を保存しています。
2. エラーログの保持日数。
3. AIアシスタントの履歴（同期している場合）。

3つのどれかをそのツールから消去すると、iCloudのコピーも削除されます。だから容量は本当に戻り、次の同期で元に戻ることもありません。

このどれも、作業中のデータには触れません：データベースはそれぞれのサーバにあり、CalíopeがiCloudにコピーすることはありません。

キーワード： iCloud、ストレージ、クォータ、保持期間、ログ、クリーンアップ

App Storeのアプリでファイルへのアクセスがどう機能するか。

Calíopeは、App Storeの要件であるサンドボックスの中で動作します。パスを指定してファイルを開くことはできず、開くダイアログや保存ダイアログで明示的に選んだファイルだけを開けます。

このことから、初めてだと驚く実際上の結果が生じます。パスを手で入力するだけでは足りません。ファイルが存在し、自分のものであっても、ダイアログを通していなければアプリからは見えません。

アクセス権の与え方：「開く…」または「別名で保存…」でファイルやフォルダを開きます。それ以降、Calíopeはアクセス権を保存し、確認せずに再利用できます。

もう一度与える必要があるとき：

- ファイルやそのフォルダを移動したり、名前を変えたりした場合。
- マシンをバックアップから復元した場合。
- 別のデバイスの場合。このアクセス権は意図的に同期されません。別のマシンでは意味がないからです。

SSHの秘密鍵や、スケジュールされたバックアップのフォルダを、デバイスごとに選び直す必要があるのも同じ理由です。

キーワード： アクセス権、サンドボックス、ファイル、アクセス、App Store、セキュリティ

以前は使えたファイルが、何もしていないのに開けなくなる理由。

ダイアログでファイルを選ぶと、Calíopeはそのパスではなくアクセス権を保存します。これはシステムが発行する参照で、期限切れになることがあります。そうなると、ファイルが同じ場所にあっても、アプリはもう開けません。

無効になる原因：

- ファイルを移動する、名前を変える、作り直す。
- パスの途中にあるフォルダの名前を変える。
- マシンをバックアップから復元する。
- ファイルが外部ボリュームやネットワークボリュームにあり、それが取り外された。

そして、不具合ではなく決まりである場合もあります：このアクセス権はデバイス間で同期されません。不注意からではありません。このアクセス権は*ある特定の*マシンのファイルシステムへの参照で、別のマシンでは何も指さず、それを持ち込むと、目に見える説明のない失敗が起きます。典型的なのは、理由のわからないSSH認証の失敗です。

直し方はいつも同じです：ファイルをもう一度選んでください。ほかには何も失われません。もう一度アクセスを許可するだけです。

キーワード： アクセス権、期限切れ、ブックマーク、ファイル、デバイス、同期

何を止めるのか、なぜ止めるのか、そして確信があるときにそれでも実行する方法。

セーフモードは、SQL文を送る前に調べ、ALTER、CREATE、DELETE、DROP、GRANT、TRUNCATE、UPDATE、REPLACE、RENAMEのいずれかを含むものを、WHEREの有無にかかわらず止めます。見ているのは被害ではなく単語で、エディタ、ターミナル、SQLプレーヤーのどれにも同じように適用されます。

権限の制限ではありません。あなたのアカウントには、それを実行する権利が十分あるかもしれません。セーフモードがするのは、それが本当に意図したことかを確認させることです。一瞬のミスのためにあります。実行前に中途半端に選択したせいでWHEREが抜け落ちたDELETEのようなミスです。

それでも実行するには、SQLエディタのバーでセーフモードをオフにして、もう一度実行します。スイッチが設定の奥ではなく目に見える場所にあるのは、オフにすることを意識的で一時的な操作にするためです。

実用的なアドバイス：本番環境のプロファイルではオンに、開発用のプロファイルではオフにしておきます。設定はプロファイルごと、さらにその中のエディタのタブごとに保存されるので、毎回覚えておく必要はありません。

キーワード： セーフモード、DROP、DELETE、WHERE、保護

入力する場所、保存される場所、そして設定と一緒に移動しない理由。

場所： Calíope › 設定 › AIアシスタント

SQLアシスタントは外部のプロバイダを使い、それと通信するにはあなた自身のAPIキーが必要です。キーは「設定」›「AIアシスタント」で入力します。

保存場所：アプリのファイルではなく、システムのキーチェーンです。そのため、設定のバックアップにも通常の同期にも、デフォルトでは含まれません。シークレットがこのデバイスの外に出るのは、あなたが明示的に求め、そのときに選んだパスワードで暗号化した場合だけです。

別のデバイスを設定したばかりで、そこでアシスタントが動かないなら、これが理由です。キーはデバイスごとに入力するか、「設定」でキーチェーンの同期を有効にする必要があります。

Calíopeはこの関係の間に入りません。キーはあなたのもので、プロバイダに直接送られ、利用料はあなたのアカウントに請求されます。だから、利用上限や残高はここではなく、プロバイダのダッシュボードで管理します。

キーワード： APIキー、アシスタント、AI、キーチェーン、プロバイダ

プロバイダの利用上限と、Calíopeで調整できること。

クォータを決めるのはCalíopeではありません。設定したAIプロバイダが、あなたのプランと残高に応じて決めます。

同じエラーになる、2つの異なる上限：

- レート。短時間にリクエストが多すぎる場合です。1分待てば解消します。
- 利用額。クレジットか、その期間の利用枠を使い切った場合です。プロバイダのダッシュボードで補充する必要があります。

ここで調整できること：「設定」›「AIアシスタント」で、回答あたりの最大トークン数（最も多く消費するもの）を下げたり、より安いモデルに切り替えたりできます。長い会話もコストが上がります。履歴がリクエストのたびに一緒に送られるからです。新しい会話を始めると、その後のリクエストのコストが下がります。

プログラムのほかの部分は、これまでとまったく同じように動作します。アシスタントはツールのひとつにすぎず、SQLエディタ、バックアップ、カタログでの作業はどれもアシスタントに依存していません。

キーワード： クォータ、上限、トークン、モデル、コスト、プロバイダ

データベースが中間の状態で残ります：どこで止まったかを確かめる方法と、すべきこと。

場所： ワークスペース › ツール › バックアップ

対象： MySQL MariaDB Aurora TiDB 8.5+ SQL Server PostgreSQL

復元は、ファイルをSQL文ごとに適用します。途中で止まった場合、そこまでに適用されたものは適用されたままです。データベースが自動でロールバックすることはありません。

まず、問題ないと思い込まないでください。途中まで復元されたデータベースには、完全なテーブル、空のテーブル、存在しないテーブルが混在し、一見すると動いているように見えることがあります。

確認する場所：エラーの技術的な詳細に、どのSQL文で止まったかが書かれています。たいていは次のどれかです。

- すでに存在していたテーブル。空でないデータベースに復元すると、最初に重複したCREATE TABLEで衝突します。

- 64 MBを超えるSQL文。Calíopeはそうした文を読み込みません。そのようなファイルはSQLに見えないため、復元はそこで止まります。

抜け出す方法：最もきれいなのは、データベースを削除して、空のデータベースに最初から復元することです。途中から再開するには、何が適用されたかを正確に知る必要がありますが、ファイルにはその情報がありません。

キーワード： 復元、バックアップ、DEFINER、max_allowed_packet、途中、GO、バッチ

表示されている行をテキストファイルに書き出す方法と、ログファイルの場所。

場所： ワークスペース › ツール › エラー

「書き出す」は、フィルタを適用した状態で表示されている行を、プレーンテキストのファイルに保存します。行がないときは、ボタンは無効になります。

リストの下部には、ログファイルのパスがあります。Macでは「Finderに表示」でそのフォルダが開き、Mac以外では「パスをコピー」でパスがコピーされます。

キーワード： 書き出し、エラーログ、テキストファイル、パス、Finder

ログがオフのときに起きること：何も保存されず、リストは空に見えるのではなく、オフであることを表示します。

場所： ワークスペース › ツール › エラー

Calíopeは、「設定」の「一般」タブにある「アプリケーションのエラーを記録」をオフにしない限り、エラーを記録します。オフの間は何も保存されず、リストが空のとき、ツールは空のログを表示するのではなく「記録はオフです」と表示します（空のリストは、エラーがなかったことを示しているように見えてしまうからです）。もう一度オンにするための「記録をオンにする」ボタンもあります。

このスイッチは、ログのiCloud同期（「ほかのデバイスのエラーを見る」）とは別のものです。

キーワード： エラーログ、オフにする、オンにする、エラーを記録、設定