[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-09-05 (世界標準時間)。"],[],[],null,["# Primary key migration overview\n\nThis page describes how Spanner works with primary keys and offers\nprimary key migration strategies for the following use cases:\n\n- [Migrating UUID key databases](#migrate-uuid)\n- [Migrating single-instance databases with sequential keys](#sequential-keys)\n- [Migrating sequential key databases with live cutover support](#sequential-keys-live-cutover)\n- [Migrating sequential key databases with application logic dependencies](#dependent-application-logic)\n\nA typical approach to primary keys is to use surrogate keys such as auto-incrementing\nnumbers. Such primary keys provide flexibility to optimize your keys now and in the future,\neven if your business logic changes. In a single-instance database at\nlow volume, sequential keys perform well. However, in a distributed system,\nsequential keys don't scale well.\n\nSequential primary keys in Spanner\n----------------------------------\n\nIn Spanner, every table has a primary key consisting of one or more\ncolumns of the table. Your table's primary key uniquely identifies each row\nin a table. Spanner uses the primary key to distribute groups of rows,\ncalled splits, across compute nodes in a Spanner instance. This is\ncalled range sharding and allows Spanner to parallelize queries and\nscale.\n\nWhen you have rows with primary keys whose values are in close proximity,\nsuch as monotonic auto-incrementing keys, they tend to land in the same split. This\ncan create a hotspot, where the split can use all available compute and memory\nresources. A hotspot might result in increased latency,\npotentially leading to timeouts and aborted transactions.\n\nTo take advantage of Spanner's scalability and to avoid hotspots,\nSpanner offers built-in solutions as alternatives to auto-incrementing primary keys.\n\nPrimary key recommendations\n---------------------------\n\nThe default recommendation for primary keys in Spanner is to use\nUniversally Unique Identifier Version 4 (UUIDv4) values. UUIDs are 128-bit identifiers\nthat use 122 bits of random data. UUIDv4 values have a huge range of values and\nare effectively unique regardless of where they are generated. This makes them\ngood candidates for non-hotspotting primary keys in Spanner.\n\nYou may want to use integer primary keys as they take less space and reduce the\ncomplexity of application changes that you'll have to do. You can use a positive\nbit-reversed sequence to generate unique primary key values that uniformly\ndistribute across the positive 64-bit integer space.\n\nFor more information on choosing a\nprimary key to prevent hotspots, see [Schema design best practices](/spanner/docs/schema-design#primary-key-prevent-hotspots).\n\nMigration strategies\n--------------------\n\nDepending on your application use case and needs, you can deploy a primary key\nmigration strategy. Each of these migration strategies:\n\n- Ensure the fidelity and correctness of the migrated primary keys.\n- Minimize downstream application changes, such as changing types or primary key values.\n- Implement Spanner best practices for performance and scalability.\n- Spanner only changes the method for how new data is generated, and doesn't affect existing data.\n\n### Migrating UUID key databases\n\nConsider that you are migrating from a database that uses\nUUID primary keys into Spanner.\nConfigure existing UUID keys as strings in your source database and import them\ninto Spanner as-is. UUID values, v4 in particular,\nare effectively unique regardless of where they are generated.\n\nYou can use the\n`GENERATE_UUID()` function ([GoogleSQL](/spanner/docs/reference/standard-sql/utility-functions#generate_uuid),\n[PostgreSQL](/spanner/docs/reference/postgresql/functions-and-operators#utility))\non Spanner to migrate UUID key databases.\n\nFor instructions on migrating UUID key databases,\nsee [Migrate UUID key columns](/spanner/docs/migrating-primary-keys#migrate-uuid-key-columns).\n\n### Migrating single-instance databases that have sequential keys\n\nConsider that you are migrating from a single-instance database that uses sequential monotonic keys,\nsuch as [`AUTO_INCREMENT`](https://dev.mysql.com/doc/refman/8.0/en/example-auto-increment.html) in MySQL,\n[`SERIAL`](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL)\nin PostgreSQL, or the standard\n`IDENTITY` type in SQL Server or Oracle.\n\nConfigure the Spanner `SEQUENCE` object to skip the values in the range of\nexisting keys and generate new bit-reversed keys. Bit-reversed keys generated\nby the Spanner `SEQUENCE` object are always greater than zero,\nand are uniformly distributed across the positive 64-bit integer space.\n\nFor instructions on migrating databases that have sequential keys,\nsee [Migrate\nauto-generated sequential primary keys](/spanner/docs/migrating-primary-keys#migrate-auto-generated-sequential-keys).\n\n### Migrating sequential key databases that have live cutover support\n\nConsider that you are migrating from a single instance database that uses sequential monotonic keys\nto Spanner and support replication scenarios,for example,\nyou want to do a live cutover between the database systems.\n\nConfigure the Spanner `SEQUENCE` object to skip the entire value range\nof existing keys in your source database and generate new bit reversed keys\non Spanner. Bit reversed keys generated by the Spanner\n`SEQUENCE` object are always greater than zero, but not ordered.\n\nFor instructions on migrating databases that have live cutover support,\nsee [Use Spanner and your source database](/spanner/docs/migrating-primary-keys#use-spanner-source-db).\n\n### Migrating sequential key databases that have application logic dependencies\n\nConsider that you are migrating from a database that uses sequential monotonic keys and your application\nlogic relies on the primary key order to determine recency or to\nsequence newly created data.\n\nCreate a composite key that combines a uniformly distributed value, such as\na shard ID or a hash, as the first component and a sequential number as\nthe second component. This preserves the ordered key values,\nwithout causing a hotspot at scale.\n\nFor instructions on migrating sequential key databases with application logic\ndependencies,\nsee [Migrate your own primary keys](/spanner/docs/migrating-primary-keys#migrate-own-primary-keys).\n\nWhat's next\n-----------\n\n- To view detailed migration workflows, see [Migrate primary keys](/spanner/docs/migrating-primary-keys)."]]