{"record":{"id":"ec705a427b721ef8","repo":"pathwaycom/pathway","slug":"external-diff-column-is-only-supported-for-the-sn","errorCode":null,"errorMessage":"_external_diff_column is only supported for the snapshot table type","messagePattern":"_external_diff_column is only supported for the snapshot table type","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/io/postgres/__init__.py","lineNumber":877,"sourceCode":"                \"stream_of_changes mode. Rename the column(s) in your \"\n                \"schema or switch to output_table_type='snapshot' \"\n                \"which does not append these metadata columns.\"\n            )\n\n    data_storage = api.DataStorage(\n        storage_type=\"postgres\",\n        connection_string=_connection_string_from_settings(postgres_settings),\n        max_batch_size=max_batch_size,\n        table_name=table_name,\n        schema_name=schema_name,\n        table_writer_init_mode=init_mode_from_str(init_mode),\n        snapshot_maintenance_on_output=is_snapshot_mode,\n        tls_settings=tls.settings,\n    )\n\n    if not is_snapshot_mode:\n        if _external_diff_column is not None:\n            raise ValueError(\n                \"_external_diff_column is only supported for the snapshot table type\"\n            )\n        if primary_key is not None:\n            raise ValueError(\n                \"primary_key can only be specified for the snapshot table type\"\n            )\n    else:\n        # Snapshot mode requires at least one primary-key column —\n        # the writer's INSERT ... ON CONFLICT (...) DO UPDATE\n        # statement is malformed without one. If we let an empty list\n        # reach the engine it would error out only AFTER ``init_mode``\n        # has already mutated the destination (CREATE TABLE for\n        # ``\"replace\"`` / ``\"create_if_not_exists\"``), and under\n        # multi-worker (PATHWAY_THREADS > 1) the worker that loses the\n        # CREATE race observes the partially-created table and\n        # surfaces a less specific error instead — making any\n        # message-based test flaky. Reject at call time so no DB side\n        # effect happens.","sourceCodeStart":859,"sourceCodeEnd":895,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/io/postgres/__init__.py#L859-L895","documentation":"Raised by pw.io.postgres.write() when _external_diff_column is passed while output_table_type is not \"snapshot\". The external diff column (which exposes the +1/-1 change flag to the pipeline) is only implemented for the snapshot writer; in stream mode diff information is already persisted as the appended diff column.","triggerScenarios":"pw.io.postgres.write(table, parts, \"tbl\", _external_diff_column=table.d) with default output_table_type (stream_of_changes).","commonSituations":"Advanced users wiring the change flag into the dataflow and forgetting the snapshot requirement; internal/experimental API usage copied between connectors.","solutions":["Add output_table_type=\"snapshot\" and a primary_key=[...] to the write call.","If you need the raw diff in stream semantics, read the appended diff column from the destination table instead of using _external_diff_column."],"exampleFix":"# before\npw.io.postgres.write(t, parts, \"tbl\", _external_diff_column=t.d)\n# after\npw.io.postgres.write(t, parts, \"tbl\", output_table_type=\"snapshot\", primary_key=[t.k], _external_diff_column=t.d)","handlingStrategy":"validation","validationCode":"if _external_diff_column is not None:\n    assert output_table_type == \"snapshot\", \"_external_diff_column requires snapshot mode\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat _external_diff_column as snapshot-mode-only API surface.","Centralize connector configuration in one builder function that validates mode/argument combinations."],"tags":["postgres","pathway","snapshot","api-misuse"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}