{"record":{"id":"7e9fde7b65a416ee","repo":"pathwaycom/pathway","slug":"pw-io-mysql-read-requires-at-least-one-primary-key","errorCode":null,"errorMessage":"pw.io.mysql.read requires at least one primary key column in the schema. Mark the column(s) that form the table's primary key with pw.column_definition(primary_key=True).","messagePattern":"pw\\.io\\.mysql\\.read requires at least one primary key column in the schema\\. Mark the column\\(s\\) that form the table's primary key with pw\\.column_definition\\(primary_key=True\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/io/mysql/__init__.py","lineNumber":191,"sourceCode":"    >>> persistence_config = pw.persistence.Config(  # doctest: +SKIP\n    ...     backend=pw.persistence.Backend.filesystem(\"./PStorage\")\n    ... )\n    >>> table = pw.io.mysql.read(  # doctest: +SKIP\n    ...     \"mysql://testuser:testpass@localhost:3306/testdb\",\n    ...     table_name=\"my_table\",\n    ...     schema=MySchema,\n    ...     name=\"my_mysql_source\",\n    ... )\n    >>> pw.io.jsonlines.write(table, \"output.jsonl\")  # doctest: +SKIP\n    >>> pw.run(persistence_config=persistence_config)  # doctest: +SKIP\n    \"\"\"\n    _check_entitlements(\"mysql\")\n\n    schema, api_schema = read_schema(schema)\n\n    primary_key_columns = schema.primary_key_columns()\n    if not primary_key_columns:\n        raise ValueError(\n            \"pw.io.mysql.read requires at least one primary key column in the schema. \"\n            \"Mark the column(s) that form the table's primary key with \"\n            \"pw.column_definition(primary_key=True).\"\n        )\n\n    pk_dtypes = schema._dtypes()\n    nullable_pks = [\n        name for name in primary_key_columns if isinstance(pk_dtypes[name], dt.Optional)\n    ]\n    if nullable_pks:\n        raise ValueError(\n            f\"pw.io.mysql.read primary_key column(s) {nullable_pks} are declared \"\n            \"nullable; primary-key columns must be non-nullable so the connector \"\n            \"can derive a unique row identity. NULL values would collide on the \"\n            \"same Pathway key and change tracking would silently merge unrelated \"\n            \"rows.\"\n        )\n","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/io/mysql/__init__.py#L173-L209","documentation":"Pathway's MySQL connector tracks row changes by mapping each source row to a Pathway table key, which requires the schema to declare at least one primary-key column. This ValueError is raised at pw.io.mysql.read() call time when schema.primary_key_columns() is empty, telling you to mark the key column(s) with pw.column_definition(primary_key=True).","triggerScenarios":"Calling pw.io.mysql.read(connection_string, table_name, schema=MySchema) where MySchema declares no column with primary_key=True.","commonSituations":"Reusing a schema written for csv/jsonlines input where keys are optional; assuming the connector infers the key from the MySQL table DDL; quick-start schemas copied from tutorials without key annotations.","solutions":["Mark the MySQL table's primary-key column(s) in the Pathway schema with pw.column_definition(primary_key=True).","For a composite MySQL primary key, mark every column of the composite.","If no natural key exists, pick a unique NOT NULL column (e.g. an AUTO_INCREMENT id) and mark it."],"exampleFix":"# before\nclass MySchema(pw.Schema):\n    id: int\n    payload: str\n\n# after\nclass MySchema(pw.Schema):\n    id: int = pw.column_definition(primary_key=True)\n    payload: str","handlingStrategy":"validation","validationCode":"assert schema.primary_key_columns(), (\n    \"pw.io.mysql.read requires primary_key=True on the key column(s)\"\n)","typeGuard":"def is_keyed_schema(schema) -> bool:\n    return bool(schema.primary_key_columns())","tryCatchPattern":"try:\n    table = pw.io.mysql.read(conn, table_name, schema=MySchema)\nexcept ValueError as e:\n    if \"primary key column\" in str(e):\n        raise SystemExit(\"Mark the MySQL table's PK with pw.column_definition(primary_key=True)\") from e\n    raise","preventionTips":["Mark primary keys in every schema destined for CDC-capable connectors (mysql, mssql, postgres).","Smoke-test new schemas with a one-line assertion before wiring them into pipelines.","Mirror the source table's PRIMARY KEY DDL in the Pathway schema by convention."],"tags":["mysql","primary-key","schema","cdc","pathway"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}