SQL Server インジェストのトラブルシューティング

このページでは、Databricks Lakeflow Connect の Microsoft SQL Server コネクタに関する一般的な問題とその解決方法について説明します。

すべてのマネージドインジェストパイプラインに適用される一般的なトラブルシューティングガイダンスについては、「マネージドインジェストパイプラインのトラブルシューティング」を参照してください。

データベースまたはテーブルに対して CDC が有効になっているかどうかを確認する

データベース <database-name> に対して CDC が有効かどうかを確認するには:

select is_cdc_enabled from sys.databases where name='<database-name>';

テーブル <schema-name>.<table-name>に対して CDC が有効になっているかどうかを確認するには:

select t.is_tracked_by_cdc
from sys.tables t join sys.schemas s on t.schema_id = s.schema_id
where s.name='<schema-name>' and t.name='<table-name>';

データベースまたはテーブルに対して変更の追跡が有効になっているかどうかを確認する

データベース \<database-name\> に対して変更追跡が有効かどうかを確認するには:

select ctdb.*

from sys.change_tracking_databases ctdb join sys.databases db

    on db.database_id  = ctdb.database_id

where db.name = '<MyDatabaseName>'

テーブルの <schema-name>.<table-name>に対して変更の追跡が有効になっているかどうかを確認するには:

select s.name schema_name, t.name table_name, ct.*

from sys.change_tracking_tables ct join sys.tables t

    on ct.object_id = t.object_id

    join sys.schemas s on t.schema_id = s.schema_id

where s.name = '<MySchemaName>' and t.name = '<MyTableName>'

テーブルトークンの待機中にタイムアウトする

ゲートウェイから情報が提供されるのを待機している間に、インジェストパイプラインがタイムアウトする場合があります。これは、以下の理由が考えられます。

以前のバージョンのゲートウェイを実行している。
必要な情報の生成中にエラーが発生しました。ゲートウェイドライバーのログでエラーを確認します。

注

完全更新フローにより、完全更新操作中のタイムアウトエラーの発生が大幅に減少します。完全更新動作 (CDC) を参照してください。

既定の認証: 既定の資格情報を構成できません

このエラーが発生した場合は、現在のユーザー資格情報の検出に問題があります。以下を置き換えてみてください。

w = WorkspaceClient()

次と置き換えます。

w = WorkspaceClient(host=input('Databricks Workspace URL: '), token=input('Token: '))

Databricks SDK for Python ドキュメントの「Authentication」(認証) も参照してください。

tech.replicant.common.ExtractorException: com.microsoft.sqlserver.jdbc.SQLServerException: 列名 'SERIAL_NUMBER' が無効です。

古いバージョンの内部テーブルを使用している場合は、このエラーが発生する可能性があります。接続されたデータベースで以下を実行します。

drop table dbo.replicate_io_audit_ddl_trigger_1;

PERMISSION_DENIED: クラスターを作成する権限がありません。管理者に問い合わせてください。

Unrestricted cluster creation の権限を付与してもらうには、Databricks アカウント管理者に問い合わせてください。

DLT エラーコード: INGESTION_GATEWAY_INTERNAL_ERROR

ドライバーログ内の stdout ファイルを確認します。

ソーステーブルの名前付けの競合

Ingestion pipeline error: "org.apache.spark.sql.catalyst.ExtendedAnalysisException: Cannot have multiple queries named `XYZ_snapshot_load` for `XYZ`. Additional queries on that table must be named. Note that unnamed queries default to the same name as the table.

これは、同じインジェストパイプラインによって同じ宛先スキーマに取り込まれる、異なるソーススキーマの XYZ という名前の複数のソーステーブルが原因で名前の競合が発生していることを示します。

これらの競合するテーブルを別の宛先スキーマに書き込む複数のゲートウェイとパイプラインのペアを作成します。

互換性のないスキーマ変更

互換性のないスキーマ変更により、インジェストパイプラインが INCOMPATIBLE_SCHEMA_CHANGE エラーで失敗します。レプリケーションを続行するには、影響を受けるテーブルの完全更新をトリガーします。

注

Databricks は、互換性のないスキーマ変更によりインジェストパイプラインが失敗したときに、スキーマ変更前のすべての行が取り込まれたことを保証できません。

NON_INCREMENTAL_SCHEMA_CHANGE（非インクリメンタルスキーマ変更）

NON_INCREMENTAL_SCHEMA_CHANGE: Column '<column>' was added to table '<table>'. A full refresh is required to continue incremental ingestion.

このエラーは、増分インジェストがアクティブな間に新しい列がソーステーブルに追加されたときに発生します。コネクタは変更履歴データから新しい列の値をバックフィルできないため、完全な更新が必要です。

影響を受けるテーブルの完全な更新を実行して、インジェストを再開します。ターゲットテーブルの完全な更新を参照してください。

MISSING_TABLE_IN_SOURCE

MISSING_TABLE_IN_SOURCE: Table '<schema>.<table>' could not be found in the source database.

このエラーは、ソースデータベースで以前に使用できたテーブルが見つからない場合に発生します。一般的な原因には、次のようなものがあります。

テーブルの名前が変更されたか、ソースで削除されました。
メンテナンス期間中など、テーブルは一時的に使用できません。

解決するには、以下を行います。

テーブルが一時的に使用できない場合は、メンテナンスが完了するまで待ってから、パイプラインを再試行します。
テーブルの名前が変更または再作成された場合は、影響を受けるテーブルの完全な更新を実行します。
テーブルが意図的に削除された場合は、パイプラインから削除します。

Azure Storage へのアクセス時の HTTP 403 エラー

もしパイプラインがINTERNAL_ERROR: Server returned HTTP response code: 403 for URLのようなエラーで失敗した場合、コンピュートがSQL Serverコネクターで使うAzureストレージエンドポイントにアクセスできない可能性があります。

Azure Databricksノートブックで以下のテストを実行して問題を特定してください。共有アクセス署名(SAS)トークンを取得するために dbutils.secrets を使いましょう。ハードコーディングは避けてください。

DFSエンドポイント(ADLS Gen2)へのアクセスをテストする

以下のスニペットは、Azure Data Lake Storage(ADLS)Gen2エンドポイント、別名分散ファイルシステム(DFS)エンドポイントへのリスト、読み取り、書き込みを行います。プレースホルダーの値をストレージアカウント、コンテナ、シークレットの詳細に置き換え、SASトークンがDFSエンドポイントに到達できるか確認します:

storage_account = "<storage-account>"
container = "<container>"
sas_token = dbutils.secrets.get(scope="<scope>", key="<key>")

spark.conf.set(
    f"fs.azure.sas.{container}.{storage_account}.dfs.core.windows.net",
    sas_token
)

base_path = f"abfss://{container}@{storage_account}.dfs.core.windows.net/"

# List contents
display(dbutils.fs.ls(base_path))

# Read a file
df = spark.read.format("parquet").load(base_path + "<path-to-file>")
display(df.limit(10))

# Write a test file
df.write.format("delta").save(base_path + "_connectivity_test")

ブロブエンドポイントへのアクセスをテストする

DFSテストが成功してもパイプラインが失敗した場合、コネクターはブロブエンドポイントを使っている可能性があります。以下のスニペットは、同じリスト、読み取り、書き込みチェックをブロブエンドポイントに対して実行します。

storage_account = "<storage-account>"
container = "<container>"
sas_token = dbutils.secrets.get(scope="<scope>", key="<key>")

spark.conf.set(
    f"fs.azure.sas.{container}.{storage_account}.blob.core.windows.net",
    sas_token
)

base_path = f"wasbs://{container}@{storage_account}.blob.core.windows.net/"

# List files
display(dbutils.fs.ls(base_path))

# Read a file
df = spark.read.format("parquet").load(base_path + "<path-to-file>")
display(df.limit(10))

# Write a test file
df.write.format("delta").save(base_path + "_connectivity_test")

どちらかのテストで403エラーが返された場合、SASトークンが必要な権限を欠いているか、正しいエンドポイントをカバーしていない可能性があります。 SASトークンが少なくともコンテナの 読み取り および リスト 権限を与えているか確認し、必要に応じて再生成してください。

TLS サーバー証明書エラー

TLS サーバー証明書の検証エラーのトラブルシューティングについては、 TLS 証明書エラーのトラブルシューティングを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-03