PolarDB:Chaves primárias e chaves únicas (para modo AUTO)

-- A common table
CREATE TABLE single_tbl(
  id bigint NOT NULL AUTO_INCREMENT,
  name varchar(30),
  PRIMARY KEY(id)
) SINGLE;

-- A broadcast table
CREATE TABLE brd_tbl(
  id bigint NOT NULL AUTO_INCREMENT,
  name varchar(30),
  PRIMARY KEY(id)
) BROADCAST;

Tabelas com particionamento automático

Todas as chaves primárias em uma tabela com particionamento automático são globais.

Exemplo 2: Chave primária global em uma tabela com particionamento automático

-- An automatic partitioned table
CREATE TABLE auto_tbl(
  id bigint NOT NULL AUTO_INCREMENT,
  name varchar(30),
  PRIMARY KEY(id)
);

Tabelas com particionamento manual

A classificação da chave primária como global ou local depende se as colunas da chave primária abrangem todas as colunas da chave de partição.

Chaves primárias globais

Se as colunas da chave primária incluírem todas as colunas da chave de partição, a chave primária será global.

Exemplo 3: Chave primária global em uma tabela com particionamento manual

A tabela key_tbl é particionada por (id, addr). Como a chave primária (id, name, addr) contém ambas as colunas da chave de partição, trata-se de uma chave primária global.

CREATE TABLE key_tbl(
  id bigint,
  name varchar(10),
  addr varchar(30),
  PRIMARY KEY(id, name, addr)
) PARTITION BY KEY(id, addr);

Chaves primárias locais

Caso as colunas da chave primária não incluam todas as colunas da chave de partição, a chave primária será local — exclusiva apenas dentro de cada partição, e não em toda a tabela.

Exemplo 4: Chave primária local em uma tabela com particionamento manual

A tabela list_tbl é particionada por city. Visto que a chave primária (order_id) não inclui city, ela é classificada como uma chave primária local.

CREATE TABLE list_tbl(
  order_id bigint,
  city varchar(50),
  name text,
  PRIMARY KEY(order_id)
) PARTITION BY LIST(city)
(
  PARTITION p1 VALUES IN ("Beijing"),
  PARTITION p2 VALUES IN ("Shanghai"),
  PARTITION p3 VALUES IN ("Guangzhou"),
  PARTITION p4 VALUES IN ("Shenzhen"),
  PARTITION p5 VALUES IN(DEFAULT)
);

Exemplo 5: Chaves primárias locais permitem valores duplicados entre partições

Como list_tbl direciona linhas com base em city, linhas com valores diferentes de city são armazenadas em partições distintas — cada uma aplicando a restrição de chave primária de forma independente.

1. Insira uma linha com order_id = 10001 e city = "Beijing". Ela será armazenada na partição p1.

   INSERT INTO list_tbl(order_id, city, name) VALUES (10001, "Beijing", "phone");
   -- Query OK, 1 row affected

2. Insira outra linha com o mesmo order_id e city = "Beijing". Ambas as linhas iriam para a partição p1, resultando em um conflito de chave primária.

   INSERT INTO list_tbl(order_id, city, name) VALUES (10001, "Beijing", "book");
   -- (1062, "ERR-CODE: [TDDL-4614][ERR_EXECUTE_ON_MYSQL] Error occurs when execute on GROUP 'TEST_DB_P00000_GROUP' ATOM 'dskey_test_db_p00000_group#polardbx-storage-0-master#11.167.60.147-1766#test_db_p00000': Duplicate entry '10001' for key 'PRIMARY' ")

3. Insira uma linha com o mesmo order_id, mas com city = "Shenzhen". Essa linha vai para a partição p4, evitando conflitos — agora existem duas linhas com order_id = 10001 na tabela.

   INSERT INTO list_tbl (order_id, city, name) VALUES (10001, "Shenzhen", "camera");
   -- Query OK, 1 row affected
   
   SELECT * FROM list_tbl;
   -- +----------+----------+--------+
   -- | order_id | city     | name   |
   -- +----------+----------+--------+
   -- | 10001    | Beijing  | phone  |
   -- | 10001    | Shenzhen | camera |
   -- +----------+----------+--------+
   -- 2 rows in set

Exemplo 6: Operações DDL que movem dados entre partições podem falhar devido a erros de chave primária duplicada

Ao modificar a política de particionamento de modo a mesclar partições contendo valores duplicados de chave primária, o PolarDB-X relata um conflito e a operação DDL falha.

Utilizando a tabela list_tbl do Exemplo 5 (que já possui duas linhas com order_id = 10001 nas partições p1 e p4), a instrução a seguir tenta mesclar Beijing e Shenzhen em uma única partição:

ALTER TABLE list_tbl
PARTITION BY LIST (city)
(
  PARTITION p1 VALUES IN ("Beijing", "Shenzhen"),
  PARTITION p2 VALUES IN ("Shanghai"),
  PARTITION p3 VALUES IN ("Guangzhou"),
  PARTITION p5 VALUES IN(DEFAULT)
);
-- (4700, "ERR-CODE: [TDDL-4700][ERR_SERVER] server error by Failed to execute the DDL task. Caused by: ERR-CODE: [TDDL-5321][ERR_GLOBAL_SECONDARY_INDEX_BACKFILL_DUPLICATE_ENTRY] Duplicated entry '10001' for key 'PRIMARY' ")

A falha na DDL ocorre porque colocar ambas as linhas com order_id = 10001 na mesma partição viola a restrição de chave primária local.

Para evitar esse problema, utilize o atributo AUTO_INCREMENT e permita que o PolarDB-X gere as chaves primárias — evite atribuir manualmente valores de chave primária em tabelas com chaves primárias locais.

-- A common table
CREATE TABLE single_tbl(
  serial_id bigint,
  name varchar(30),
  UNIQUE KEY(serial_id)
) SINGLE;

-- A broadcast table
CREATE TABLE brd_tbl(
  serial_id bigint,
  name varchar(30),
  UNIQUE KEY(serial_id)
) BROADCAST;

Tabelas com particionamento automático

Todas as chaves únicas em uma tabela com particionamento automático são globais.

Exemplo 8: Chave única global em uma tabela com particionamento automático

-- An automatic partitioned table
CREATE TABLE auto_tbl(
  serial_id bigint,
  name varchar(30),
  UNIQUE KEY(serial_id)
);

Tabelas com particionamento manual

Chaves únicas globais

Quando as colunas da chave única incluem todas as colunas da chave de partição, a chave única é global.

Exemplo 9: Chave única global em uma tabela com particionamento manual

A tabela hash_tbl é particionada por type_id. A chave única (inner_id, type_id) inclui a coluna da chave de partição type_id, caracterizando-a como uma chave única global.

CREATE TABLE hash_tbl(
  type_id int,
  inner_id int,
  UNIQUE KEY(inner_id, type_id)
) PARTITION BY HASH(type_id);

Exemplo 10: Chave única global usando um índice secundário global

Um GSI único é sempre uma chave única global, independentemente da chave de partição da tabela. Em key_tbl, u_sid é um GSI único em serial_id — ele garante que serial_id seja exclusivo em todas as partições, mesmo que a tabela seja particionada por type_id.

CREATE TABLE key_tbl(
  type_id int,
  serial_id int,
  UNIQUE GLOBAL INDEX u_sid(serial_id) PARTITION BY HASH(serial_id)
) PARTITION BY HASH(type_id);

Chaves únicas locais

Se as colunas da chave única não incluírem todas as colunas da chave de partição, a chave única será local.

Exemplo 11: Chave única local em uma tabela com particionamento manual

A tabela range_tbl é particionada por order_time. Como a chave única (serial_id) não inclui order_time, ela é uma chave única local.

CREATE TABLE range_tbl(
  id int primary key auto_increment,
  serial_id int,
  order_time datetime NOT NULL,
  UNIQUE KEY(serial_id)
) PARTITION BY RANGE(order_time)
(
  PARTITION p1 VALUES LESS THAN ('2022-12-31'),
  PARTITION p2 VALUES LESS THAN ('2023-12-31'),
  PARTITION p3 VALUES LESS THAN (MAXVALUE)
);

Exemplo 12: Chaves únicas locais permitem valores duplicados entre partições

Dado que range_tbl roteia linhas por order_time, linhas com valores distintos de order_time vão para partições diferentes — cada uma impondo a restrição de chave única independentemente.

1. Insira uma linha com serial_id = 20001 e order_time = '2022-01-01'. O registro ficará na partição p1.

   INSERT INTO range_tbl(serial_id, order_time) VALUES (20001, '2022-01-01');
   -- Query OK, 1 row affected

2. Tente inserir outra linha com o mesmo serial_id e order_time = '2022-01-02'. Ambas as linhas seriam direcionadas à partição p1, causando um conflito de chave única.

   INSERT INTO info_tbl(serial_id, order_time) VALUES (20001, '2022-01-02');
   -- (1062, "ERR-CODE: [TDDL-4614][ERR_EXECUTE_ON_MYSQL] Error occurs when execute on GROUP 'D25_000001_GROUP' ATOM 'dskey_d25_000001_group#polardbx-storage-1-master#11.167.60.147-1766#d25_000001': Duplicate entry '20001' for key 'serial_id' ")

3. Insira uma linha com o mesmo serial_id e order_time = '2024-01-01'. Esta linha vai para a partição p3, então não há conflito — agora existem duas linhas com serial_id = 20001 na tabela.

   INSERT INTO range_tbl(serial_id, order_time) VALUES (20001, '2024-01-01');
   -- Query OK, 1 row affected
   
   SELECT * FROM range_tbl;
   -- +----+-----------+---------------------+
   -- | id | serial_id | order_time          |
   -- +----+-----------+---------------------+
   -- |  2 |     20001 | 2024-01-01 00:00:00 |
   -- |  1 |     20001 | 2022-01-01 00:00:00 |
   -- +----+-----------+---------------------+
   -- 2 rows in set

Exemplo 13: Operações DDL que movem dados entre partições podem falhar devido a erros de chave única duplicada

Ao alterar a política de particionamento de forma que linhas com valores duplicados de chave única sejam colocadas na mesma partição, o PolarDB-X reporta um conflito e a DDL falha.

Considerando a tabela range_tbl do Exemplo 12 (que já tem duas linhas com serial_id = 20001 nas partições p1 e p3), converter a tabela para uma tabela comum reuniria todas as linhas em um único local:

ALTER TABLE range_tbl SINGLE;
-- (4700, "ERR-CODE: [TDDL-4700][ERR_SERVER] server error by Failed to execute the DDL task. Caused by: ERR-CODE: [TDDL-5321][ERR_GLOBAL_SECONDARY_INDEX_BACKFILL_DUPLICATE_ENTRY] Duplicated entry '200001' for key 'PRIMARY' ")

A DDL falha porque uma tabela comum exige unicidade em todas as linhas, condição violada pelos valores duplicados de serial_id.

Para prevenir isso, certifique-se de que os valores de chaves únicas locais não estejam duplicados antes de executar operações DDL que envolvam redistribuição de dados.