README: add information about v2 and format upgrade

README.md

@@ -86,16 +86,16 @@ differences.
 
 ## RocksDB Compatibility
 
-Pebble strives for forward compatibility with RocksDB 6.2.1 (the latest version
-of RocksDB used by CockroachDB). Forward compatibility means that a DB generated
-by RocksDB 6.2.1 can be upgraded for use by Pebble. Pebble versions in the `v1`
-series may open DBs generated by RocksDB 6.2.1. Since its introduction, Pebble
-has adopted various backwards-incompatible format changes that are gated behind
-new 'format major versions'. The Pebble `master` branch does not support opening
-DBs generated by RocksDB. DBs generated by RocksDB may only be used with recent
-versions of Pebble after migrating them through format major version upgrades
-using previous versions of Pebble. See the below section of format major
-versions.
+Pebble `v1` strives for forward compatibility with RocksDB 6.2.1 (the latest
+version of RocksDB used by CockroachDB). Forward compatibility means that a DB
+generated by RocksDB 6.2.1 can be upgraded for use by Pebble. Pebble versions in
+the `v1` series may open DBs generated by RocksDB 6.2.1. Since its introduction,
+Pebble has adopted various backwards-incompatible format changes that are gated
+behind new 'format major versions'. Pebble `v2` and newer does not support
+opening DBs generated by RocksDB. DBs generated by RocksDB may only be used with
+recent versions of Pebble after migrating them through format major version
+upgrades using previous versions of Pebble. See the below section of format
+major versions.
 
 Even the RocksDB-compatible versions of Pebble only provide compatibility with
 the subset of functionality and configuration used by CockroachDB. The scope of
@@ -157,10 +157,13 @@ range of Pebble versions support that format.
 | FormatMinTableFormatPebblev1       |   9   | No         | v1             |
 | FormatPrePebblev1Marked            |  10   | Background | v1             |
 | FormatSSTableValueBlocks           |  12   | No         | v1             |
-| FormatFlushableIngest              |  13   | No         | v1, master     |
-| FormatPrePebblev1MarkedCompacted   |  14   | Blocking   | v1, master     |
-| FormatDeleteSizedAndObsolete       |  15   | No         | v1, master     |
-| FormatVirtualSSTables              |  16   | No         | v1, master     |
+| FormatFlushableIngest              |  13   | No         | v1, v2, master |
+| FormatPrePebblev1MarkedCompacted   |  14   | Blocking   | v1, v2, master |
+| FormatDeleteSizedAndObsolete       |  15   | No         | v1, v2, master |
+| FormatVirtualSSTables              |  16   | No         | v1, v2, master |
+| FormatSyntheticPrefixSuffix        |  17   | No         | v2, master     |
+| FormatFlushableIngestExcises       |  18   | No         | v2, master     |
+| FormatColumnarBlocks               |  19   | No         | v2, master     |
 
 Upgrading to a format major version with 'Background' in the migration
 column may trigger background activity to rewrite physical file
@@ -171,18 +174,30 @@ writes if upgrading a live database through
 `RatchetFormatMajorVersion`, but the method call will not return until
 the migration is complete.
 
+Upgrading existing stores can be performed via the `RatchetFormatMajorVersion`
+method. If the database does not use a custom comparer, merger, or block
+property collectors, the `pebble` tool can also be used, at the latest version
+that supports the format. For example:
+```
+# WARNING: only use if no custom comparer/merger/property collector are necessary.
+go run github.com/cockroachdb/pebble/cmd/[email protected] db upgrade <db-dir>
+```
+
 For reference, the table below lists the range of supported Pebble format major
 versions for CockroachDB releases.
 
-| CockroachDB release | Earliest supported                 | Latest supported          |
-|---------------------|------------------------------------|---------------------------|
-| 20.1 through 21.1   | FormatMostCompatible               | FormatMostCompatible      |
-| 21.2                | FormatMostCompatible               | FormatSetWithDelete       |
-| 21.2                | FormatMostCompatible               | FormatSetWithDelete       |
-| 22.1                | FormatMostCompatible               | FormatSplitUserKeysMarked |
-| 22.2                | FormatMostCompatible               | FormatPrePebblev1Marked   |
-| 23.1                | FormatSplitUserKeysMarkedCompacted | FormatFlushableIngest     |
-| 23.2                | FormatSplitUserKeysMarkedCompacted | FormatVirtualSSTables     |
+| CockroachDB release | Earliest supported                 | Latest supported            |
+|---------------------|------------------------------------|-----------------------------|
+| 20.1 through 21.1   | FormatMostCompatible               | FormatMostCompatible        |
+| 21.2                | FormatMostCompatible               | FormatSetWithDelete         |
+| 21.2                | FormatMostCompatible               | FormatSetWithDelete         |
+| 22.1                | FormatMostCompatible               | FormatSplitUserKeysMarked   |
+| 22.2                | FormatMostCompatible               | FormatPrePebblev1Marked     |
+| 23.1                | FormatSplitUserKeysMarkedCompacted | FormatFlushableIngest       |
+| 23.2                | FormatPrePebblev1Marked            | FormatVirtualSSTables       |
+| 24.1                | FormatFlushableIngest              | FormatSyntheticPrefixSuffix |
+| 24.2                | FormatVirtualSSTables              | FormatSyntheticPrefixSuffix |
+| 24.3                | FormatSyntheticPrefixSuffix        | FormatColumnarBlocks        |
 
 ## Pedigree
 

format_major_version.go

@@ -197,8 +197,6 @@ const (
 	// block.
 	FormatColumnarBlocks
 
-	// TODO(msbutler): add major version for synthetic suffixes
-
 	// -- Add new versions here --
 
 	// FormatNewest is the most recent format major version.