OracleデータベースにCSVなどの外部ファイルを取り込むとき、「SQL*Loader」という名前は耳にするけれど、ctlファイルやエラーへの対応に不安を感じていませんか？
私自身、最初は「ファイルはあるのになぜか入らない…」と毎回つまずいてばかりでした。
この記事では、SQLLoaderを使った基本的な取り込み手順から、ctlファイルの書き方、よくあるエラーとその原因の見つけ方まで、初学者が最初に知っておきたいポイントをわかりやすく整理しています。
まずは小さなCSVで動かすところから、一歩ずつ理解を深めていきましょう。
この記事を読むとわかること
- ctlファイルの基本構成と書き方の注意点
- SQLLoader実行時によくあるエラーとその対処法
- CSV取り込み時の文字コードや改行コードの落とし穴と対策
SQLLoaderの基本と最初に知っておくべきこと
SQL*Loader（sqlldr）は、CSVなどのテキストファイルからOracleデータベースにデータを一括で取り込むためのユーティリティツールです。
内部的には「どのファイルをどの形式で、どのテーブルに入れるのか」といった指示を、コントロールファイルctlファイルに書いて実行します。なので、最初にctlファイルの構造と役割をざっくり把握しておくと、後々のトラブルにも強くなります。
ただ、「ctlファイルって何を書けばいいの？」と感じるのが普通です。
実際に使うと、見た目はシンプルですが細かいルールに縛られる場面が多めで、特にCSVファイル側の形式とOracle側の型が合ってないと、すぐにエラーになります。
最初は小さなCSVとテストテーブルで動かしてみるのが鉄則です。
CSVをOracleに取り込む仕組みの全体像
SQL*Loaderの仕組みを一言でまとめると、「外部ファイルを、指定された定義（ctlファイル）に従ってテーブルに流し込む」というものです。
操作の流れを理解するだけでも、エラー時のイメージが変わってきます。
- 入力ファイル（CSVなど）を用意
- 制御ファイル（.ctl）で取り込みルールを定義
- sqlldr コマンドで実行
- ログ・badファイルで結果を確認
実行後にはログファイル、badファイル（失敗データ）、discardファイル（無視データ）が出力されます。
特にログファイルは「どこで止まったか」の情報が入っており、読み慣れるとかなり心強い存在になります。
ctlファイルと実行コマンドの関係
ctlファイルはSQLLoaderの心臓部ともいえます。
ここにどのテーブルにどんな形式でデータを入れるのかを記述します。最低限、以下のような構成になっています。
LOAD DATA
INFILE 'sample.csv'
INTO TABLE users
FIELDS TERMINATED BY ','
OPTIONALLY ENCLOSED BY '"'
(
id,
name,
email
)このctlを実行するには、以下のようなコマンドを使います。
sqlldr userid=user/pass@db control=import.ctl log=import.logこのコマンドで初めて、「CSVとDBの接続」「取り込みルールの読み込み」「ログ出力」が一気に動きます。なので、パスやファイル名のちょっとしたミスがすぐにエラーに直結します。
よくあるSQL*Loaderエラーと原因の見つけ方
SQL*Loaderはエラーの内容をログファイルに詳細に書き出してくれます。
ただ、正直最初はそのメッセージがピンと来ないことも多いです。特に「ORA-」から始まる番号のエラーや、ctlファイルの構文エラーは読みづらいものも多い。なので、自分なりにエラーの“読み解き方”を持つことが大事になります。
ORA-エラーとログファイルの読み方
たとえば、取り込み時に「ORA-01722: invalid number」が出たとします。
これは「数値型のカラムに文字列が入ってしまった」ケースが大半です。ログファイルの中には、どの行・どのフィールドで問題が起きたかが書かれています。
Record 5: Rejected – Error on table USERS, column ID.
ORA-01722: invalid number
この「Record 5」は、CSVの6行目（1行目はヘッダー）を意味します。ここを起点に、CSVファイル側のデータを確認してみると、文字列が入っていた…なんてことが多いです。
ctlファイルの典型的な文法ミス
ctlファイルはちょっとした記述ミスでも止まります。
特によくあるのが、カンマ区切りやカラム定義のカッコ漏れなどです。
FIELDS TERMINATED BY ‘,’ OPTIONALLY ENCLOSED BY ‘”‘
(
id,
name ← 最後のカラムにカンマを付けてしまう
)
この場合、name, ) のように見なされて構文エラーになります。ctlファイルのエラーは実行時に表示されるものの、ログファイルを見ないと詳しい原因はわかりにくいです。
編集後は一度全文を読み返す習慣があるとミスが減らせます。
文字コードや改行コードの落とし穴
WindowsでCSVを作るときにありがちなのが、文字コード（Shift-JIS）や改行コード（CRLF）の影響で取り込みが失敗するケースです。
特にUTF-8が前提になっている環境でShift-JISのまま読み込もうとすると、「意味不明な文字列」扱いになります。
対応としては、iconvやエディタでの変換が有効です。
iconv -f sjis -t utf8 input.csv > utf8_input.csvまた、改行コードもLF（Unix）にしておいた方が安定します。trコマンドやVSCodeのエンコード設定で対応できる場面も多いです。
実際に起きたエラーとその解決法5選
この章では、実際の現場で筆者が経験したエラーとその対処法を具体的に紹介します。特に「最初にハマりやすいもの」だけを厳選しました。
「ORA-01722」数値変換エラーの原因と対処
このエラーは、数値型カラムに文字列が入ってしまった場合によく出ます。
原因としては、CSV上では "123a" のような文字列や、NULLを意図して空にしたつもりがスペースになっていた…というのがよくあります。
"123a" を NUMBER カラムに入れようとしてエラーになります。解決には、対象カラムのデータを事前にチェックして「数字以外が入っていないか」を確認するのが有効です。
「invalid number of arguments」になる理由
このエラーは、ctlファイルの記述ミスが主な原因です。
特に、カラム数とCSVの列数が一致していない場合に出ることが多いです。
FIELDS TERMINATED BY ‘,’
(id, name)
上記で、CSVが id,name,email の3列だった場合、email分が指定されていないためエラーになります。
特に「末尾のカラムを抜かしてた」とか「1つ余計に定義してた」などのミスが多いです。
「file not found」パス指定ミスと対処法
INFILE 'data.csv' のファイルが見つからないというのは、意外とよくある落とし穴です。原因は、パスの相対指定とsqlldrを実行する場所のズレによるものです。
対処法としては、絶対パスで指定してしまうのが確実です。
INFILE '/home/user/data/input.csv'また、Windows環境ならバックスラッシュに注意が必要です。
INFILE 'C:\\Users\\User\\Documents\\input.csv'「field in data file exceeds maximum length」の回避策
これは、CSVの1列に想定以上の長さの文字列が入っていたケースです。
たとえば、varchar2(50)のカラムに100文字のデータを入れようとした場合に起きます。
対処法は2つ。事前にCSVの値の長さをチェックするか、もしくはCTLでCHAR(100)など明示的に指定して回避します。
この指定で、SQLLoader側で「一旦は文字列として受け取る」ことができます。
SKIP・ERRORSの扱いミス
大量データのインポート時にSKIPやERRORSを指定すると、便利な反面で「思ったよりデータが入ってない」ことがあります。
sqlldr control=sample.ctl skip=1 errors=0このようにskip=1を指定すると、最初の1レコードがスキップされます。
ヘッダー回避には便利ですが、データがずれているように見える場合もあるので注意が必要です。
ちょっとした工夫と確認ポイント
最初の頃は、毎回「どこでエラーになったんだ？」と混乱していました。
でも少しずつ慣れてくると、事前にチェックできるポイントが見えてきます。以下は、自分が「これやっといてよかったな」と感じた工夫です。
ctlファイルは定数で試すとトラブルが減る
最初のctl作成時は、CSVではなく定数を使って動作確認すると、エラー原因を切り分けやすいです。
INTO TABLE test_table
VALUES (
1, 'test', 'test@example.com'
)このようにして、一度「ファイルに関係ない状態」で流れが通るかをチェックすることで、ctlの構文ミスやテーブル定義の問題が洗い出しやすくなります。
ファイルの文字コード確認で防げる初期ミス
特にWindowsで作ったCSVは、文字コードがUTF-8でないことが多く、それが原因で「文字化け→取り込み失敗」につながります。VSCodeやfileコマンドで事前に確認すると安全です。
file input.csvもしShift-JISだったら、iconvでUTF-8に変換するのが定番です。
ログとbadファイルの中身を必ず見るべき理由
実運用上、一番大事なのがこれだと思います。
エラーが出たら、必ずimport.logや.badファイルの中身を見てください。badファイルには「取り込みに失敗したデータ」がそのまま出ているので、原因調査の強力な手がかりになります。
逆に、ログを見ずに何度も実行しても、根本原因は見えてこないままです。少し面倒ですが「とりあえず中身を開いてみる」だけで、解決が早まることが本当に多いです。
まとめ
SQLLoaderは、仕組みを理解し、ctlファイルやCSVの形式に注意することで、非常に強力なデータ取り込みツールになります。エラー時もログやbadファイルを確認することで、確実に原因を追えるようになります。
私自身、最初は戸惑いの連続でしたが、少しずつコツを掴むことで安定した運用ができるようになりました。
完璧を目指すよりも、まずは動かしてみることから試してみてはいかがでしょうか？
