From ebaf26ef974d0b435e3dde410ec60466a145e76b Mon Sep 17 00:00:00 2001 From: Usamoi Date: Mon, 22 Jan 2024 10:56:04 +0800 Subject: [PATCH] docs for "chore: upload --0.2.0 schema update script" (#31) Signed-off-by: usamoi --- src/admin/upgrading.md | 88 +++++++++++++++++++++++++++++++---- src/developers/development.md | 2 +- src/reference/schema.md | 19 ++++++-- 3 files changed, 96 insertions(+), 13 deletions(-) diff --git a/src/admin/upgrading.md b/src/admin/upgrading.md index 0902dd0..21346b8 100644 --- a/src/admin/upgrading.md +++ b/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. diff --git a/src/developers/development.md b/src/developers/development.md index 7cc3b0e..0da5631 100644 --- a/src/developers/development.md +++ b/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: diff --git a/src/reference/schema.md b/src/reference/schema.md index cadf069..fc574d8 100644 --- a/src/reference/schema.md +++ b/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 |