docs for "chore: upload --0.2.0 schema update script" (#31)

Signed-off-by: usamoi <usamoi@outlook.com>

src/admin/upgrading.md

@@ -1,29 +1,101 @@
 # Upgrading
 
+There are two general steps for upgrading:
+
+* Upgrade schema.
+* Reindex indexes.
+
+## Upgrade schema
+
 If you update the extension to a new version, let's say it's `999.999.999`. This command helps you to update the schema of extension:
 
 ```sql
 ALTER EXTENSION vectors UPDATE TO '999.999.999';
 ```
 
-Then check the status of all vector indexes:
+If you're upgrading from `0.1.x`, please read [Upgrading from 0.1.x](#upgrade-from-01x).
+
+## Reindex indexes
+
+After an upgrade, you may need to do manual maintenance, or reindex all vector indexes or just do nothing.
+
+You could check the status of all vector indexes in this command:
+
+```sql
+SELECT indexname, idx_status FROM pg_vector_index_stat;
+```
+
+* If you see all values in the `idx_status` column are `NORMAL`:
+
+```
+ indexname   | idx_status 
+-------------+------------
+ t_val_idx_1 | NORMAL
+ t_val_idx_2 | NORMAL
+```
+
+You need to do nothing. Everything goes well.
+
+* If you see some values in the `idx_status` column are `UPGRADE`:
+
+```
+ indexname   | idx_status 
+-------------+------------
+ t_val_idx_1 | NORMAL
+ t_val_idx_2 | UPGRADE
+```
+
+You need to reindex vector indexes that needs upgrading.
 
 ```sql
-SELECT * FROM pg_vector_index_stat;
+REINDEX INDEX t_val_idx_2;
 ```
 
-If you see the error `The extension is upgraded so all index files are outdated.`, you need to delete the index files created by older versions. You can delete the folder with this command:
+* If you see an error: `The extension is upgraded so all index files are outdated.`.
+
+You need to delete the index files created by older versions. The files are in the `pg_vectors` folder under PostgreSQL data directory, or volume directory for Docker users.
 
 ```shell
-rm -rf $(psql -U postgres -tAqX -c $'SELECT CONCAT(CURRENT_SETTING(\'data_directory\'), \'/pg_vectors\');')
+rm -rf $(psql -U postgres -tAqX -c 'SHOW data_directory')/pg_vectors
+```
+
+Restart PostgreSQL and then get all vector indexes.
+
+```sql
+SELECT
+        I.relname AS indexname
+    FROM pg_index X JOIN
+         pg_class I ON I.oid = X.indexrelid JOIN
+         pg_am A ON A.oid = I.relam
+    WHERE A.amname = 'vectors';
 ```
 
-If you are using Docker, you can just delete `pg_vectors` folder under the volume directory too. Then you need to restart PostgreSQL.
+```
+ indexname
+-------------
+ t_val_idx_1
+ t_val_idx_2
+```
+
+Reindex all vector indexes.
+
+```sql
+REINDEX INDEX t_val_idx_1;
+REINDEX INDEX t_val_idx_2;
+```
 
-If you see the error `The extension is upgraded so this index is outdated.` when using an index or see the text `UPGRADE` in the view `pg_vector_index_stat`, you need to reindex these indexes.
+## Upgrade from 0.1.x
 
-Let's say the name of the index is `t_val_idx`, you will reindex them with this SQL:
+You need to follow these steps to make `ALTER EXTENSION vectors UPDATE TO '0.2.0'` work.
+
+Let's assume your `pgvecto.rs` version is `0.1.x` (replace `x` with a number).
 
 ```sql
-REINDEX INDEX t_val_idx;
+UPDATE pg_catalog.pg_extension SET extversion = '0.1.x' where extname = 'vectors';
+UPDATE pg_catalog.pg_extension SET extrelocatable = true where extname = 'vectors';
+ALTER EXTENSION vectors SET SCHEMA vectors;
+UPDATE pg_catalog.pg_extension SET extrelocatable = false where extname = 'vectors';
+ALTER EXTENSION vectors UPDATE TO '0.2.0';
 ```
+
+`pgvecto.rs` is installed in schema `vectors` from `0.2.0`, you may need to set `search_path` for the database.

src/developers/development.md

@@ -134,7 +134,7 @@ These steps are needed for a release:
 2. Push these changes to `main` branch.
     * Modify the latest version number in `/README.md` and `/docs/installation.md` to `99.99.99`.
     * Use `cargo pgrx schema` to generate a schema script and upload it to `/sql/vectors--99.99.99.sql`.
-    * Write a schema update script and upload it to `/sql/vectors--98.98.98--99.99.99.sql`.
+    * Write a schema update script and upload it to `/sql/vectors--98.98.98--99.99.99.sql`. You can check the validity of it with the help of `./tools/dump.sh`.
 3. Manually trigger `Release` CI.
 
 These steps are needed for a prerelease:

src/reference/schema.md

@@ -2,7 +2,7 @@
 
 Here is the schema provided by `pgvecto.rs`.
 
-# List of data types
+## List of data types
 
 | Name              | Description                                                          |
 | ----------------- | -------------------------------------------------------------------- |
@@ -53,6 +53,17 @@ Here is the schema provided by `pgvecto.rs`.
 | ------- | ----- | ----------------------- |
 | vectors | Index | pgvecto.rs vector index |
 
+## List of operator families
+
+| AM      | Operator family | Applicable types |
+| ------- | --------------- | ---------------- |
+| vectors | vector_cos_ops  | vector           |
+| vectors | vector_dot_ops  | vector           |
+| vectors | vector_l2_ops   | vector           |
+| vectors | vecf16_cos_ops  | vecf16           |
+| vectors | vecf16_dot_ops  | vecf16           |
+| vectors | vecf16_l2_ops   | vecf16           |
+
 ## List of operator classes
 
 | AM      | Input type | Operator class | Default? |
@@ -66,6 +77,6 @@ Here is the schema provided by `pgvecto.rs`.
 
 ## List of views
 
-| Name                 | Description                                  |
-| -------------------- | -------------------------------------------- |
-| pg_vector_index_stat | A view provided for vector index statistics. |
+| Name                 | Description                                 |
+| -------------------- | ------------------------------------------- |
+| pg_vector_index_stat | A view provided for vector index statistics |