fix: upgrade instructions (#203)

* fix: upgrade instructions

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

* fix: rename scripts to install

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

* fix: ipc error-handling

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

* feat: soft version

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

* chore: freebsd

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

---------

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

Author: usamoi

.github/workflows/release.yml

@@ -99,7 +99,7 @@ jobs:
           sudo apt-get -y install ruby-dev libarchive-tools
           sudo gem install --no-document fpm
           mkdir ./artifacts
-          cargo pgrx package
+          ./ci_package.sh
           if [[ "${{ matrix.arch }}" == "aarch64" ]]; then
             cargo build --target aarch64-unknown-linux-gnu --release --features "pg${{ matrix.version }}" --no-default-features
             mv ./target/aarch64-unknown-linux-gnu/release/libvectors.so ./target/release/vectors-pg${{ matrix.version }}/usr/lib/postgresql/${{ matrix.version }}/lib/vectors.so
@@ -116,6 +116,8 @@ jobs:
             --package ../vectors-pg${{ matrix.version }}_${{ github.event.inputs.version }}_${{ matrix.platform }}.deb \
             --architecture ${{ matrix.platform }} \
             .
+        env:
+          VERSION: ${{ matrix.version }}
       - name: Upload Release
         uses: actions/upload-release-asset@v1
         env:
@@ -167,9 +169,9 @@ jobs:
     strategy:
       matrix:
         include:
-          - { version: 14, latest: false }
-          - { version: 15, latest: false }
-          - { version: 16, latest: true }
+          - { version: 14 }
+          - { version: 15 }
+          - { version: 16 }
     steps:
       - name: Checkout
         uses: actions/checkout@v3

README.md

@@ -49,7 +49,7 @@ docker run \
   --name pgvecto-rs-demo \
   -e POSTGRES_PASSWORD=mysecretpassword \
   -p 5432:5432 \
-  -d tensorchord/pgvecto-rs:pg16-latest
+  -d tensorchord/pgvecto-rs:pg16-v0.1.13
 ```
 
 ## Development with envd

crates/c/build.rs

@@ -2,7 +2,7 @@ fn main() {
     println!("cargo:rerun-if-changed=src/c.h");
     println!("cargo:rerun-if-changed=src/c.c");
     cc::Build::new()
-        .compiler("/usr/bin/clang-16")
+        .compiler("clang-16")
         .file("./src/c.c")
         .opt_level(3)
         .debug(true)

crates/c/src/lib.rs

@@ -1,5 +1,3 @@
-#![feature(linkage)]
-
 mod c;
 
 #[allow(unused_imports)]

crates/service/src/prelude/error.rs

@@ -62,15 +62,29 @@ The given vector is invalid for input.
 ADVICE: Check if dimensions and scalar type of the vector is matched with the index.\
 ")]
     Unmatched2,
+    #[error("\
+IPC connection is closed unexpected.
+ADVICE: The error is raisen by background worker errors. \
+Please check the full PostgreSQL log to get more information.\
+")]
+    Ipc,
+    #[error("\
+The extension is upgraded. However, the index files is outdated.
+ADVICE: Please read `https://github.com/tensorchord/pgvecto.rs/blob/main/docs/upgrade.md`.\
+")]
+    Upgrade,
 }
 
-pub trait FriendlyErrorLike {
-    fn friendly(self) -> !;
+pub trait FriendlyErrorLike: Sized {
+    fn convert(self) -> FriendlyError;
+    fn friendly(self) -> ! {
+        panic!("pgvecto.rs: {}", self.convert());
+    }
 }
 
 impl FriendlyErrorLike for FriendlyError {
-    fn friendly(self) -> ! {
-        panic!("pgvecto.rs: {}", self);
+    fn convert(self) -> FriendlyError {
+        self
     }
 }
 

crates/service/src/worker/metadata.rs

@@ -0,0 +1,46 @@
+use serde::{Deserialize, Serialize};
+use std::error::Error;
+use std::path::Path;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum MetadataError {
+    #[error("Invalid version.")]
+    InvalidVersion,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Metadata {
+    #[serde(default)]
+    pub version: Option<u64>,
+    #[serde(default)]
+    pub soft_version: Option<u64>,
+}
+
+impl Metadata {
+    const VERSION: u64 = 1;
+    const SOFT_VERSION: u64 = 1;
+}
+
+impl Metadata {
+    pub fn write(path: impl AsRef<Path>) {
+        let metadata = Metadata {
+            version: Some(Self::VERSION),
+            soft_version: Some(Self::SOFT_VERSION),
+        };
+        let contents = serde_json::to_string(&metadata).unwrap();
+        std::fs::write(path, contents).unwrap();
+    }
+    pub fn read(path: impl AsRef<Path>) -> Result<(), Box<dyn Error>> {
+        use MetadataError::*;
+        let contents = std::fs::read_to_string(path)?;
+        let metadata = serde_json::from_str::<Metadata>(&contents)?;
+        if Self::VERSION != metadata.version.ok_or(InvalidVersion)? {
+            return Err(Box::new(InvalidVersion));
+        }
+        if Self::SOFT_VERSION <= metadata.soft_version.ok_or(InvalidVersion)? {
+            return Err(Box::new(InvalidVersion));
+        }
+        Ok(())
+    }
+}

crates/service/src/worker/mod.rs

@@ -1,4 +1,5 @@
 pub mod instance;
+pub mod metadata;
 
 use self::instance::Instance;
 use crate::index::IndexOptions;
@@ -16,14 +17,6 @@ use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
 
-fn magic() -> &'static [u8] {
-    &[1, 4, 53, 23, 34, 92, 34, 23]
-}
-
-fn check(data: &[u8]) -> bool {
-    magic() == data
-}
-
 pub struct Worker {
     path: PathBuf,
     protect: Mutex<WorkerProtect>,
@@ -33,7 +26,6 @@ pub struct Worker {
 impl Worker {
     pub fn create(path: PathBuf) -> Arc<Self> {
         std::fs::create_dir(&path).unwrap();
-        std::fs::write(path.join("magic"), magic()).unwrap();
         std::fs::create_dir(path.join("indexes")).unwrap();
         let startup = FileAtomic::create(path.join("startup"), WorkerStartup::new());
         let indexes = HashMap::new();
@@ -42,17 +34,18 @@ impl Worker {
         });
         let protect = WorkerProtect { startup, indexes };
         sync_dir(&path);
+        self::metadata::Metadata::write(path.join("metadata"));
         Arc::new(Worker {
             path,
             protect: Mutex::new(protect),
             view: ArcSwap::new(view),
         })
     }
+    pub fn check(path: PathBuf) -> bool {
+        self::metadata::Metadata::read(path.join("metadata")).is_ok()
+    }
     pub fn open(path: PathBuf) -> Arc<Self> {
         let startup = FileAtomic::<WorkerStartup>::open(path.join("startup"));
-        if !check(&std::fs::read(path.join("magic")).unwrap_or_default()) {
-            panic!("Please delete the directory pg_vectors in Postgresql data folder. The files are created by older versions of postgresql or broken.");
-        }
         clean(
             path.join("indexes"),
             startup.get().indexes.keys().map(|s| s.to_string()),

docs/installation.md

@@ -5,7 +5,7 @@
 We have prebuild image at [tensorchord/pgvecto-rs](https://hub.docker.com/r/tensorchord/pgvecto-rs). You can try it with
 
 ```
-docker run --name pgvecto-rs-demo -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d tensorchord/pgvecto-rs:pg16-latest
+docker run --name pgvecto-rs-demo -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d tensorchord/pgvecto-rs:pg16-v0.1.13
 ```
 
 Connect to the database and enable the extension.

docs/upgrade.md

@@ -0,0 +1,51 @@
+# Upgrade
+
+## `The extension is upgraded. However, the index files is outdated.`
+
+You may see this error if you upgrade the extension. On this condition, you should follow these steps:
+
+* Delete the old index folder.
+
+You can delete the folder with this command:
+
+```shell
+rm -rf $(psql -U postgres -tAqX -c $'SELECT CONCAT(CURRENT_SETTING(\'data_directory\'), \'/pg_vectors\');')
+```
+
+If you are using Docker, you can just delete `pg_vectors` folder under the volume directory too.
+
+You need to restart PostgreSQL.
+
+* Reindex.
+
+You can list all indexes that needed to be reindexed with this command:
+
+```sql
+SELECT
+    I.oid AS indexrelid,
+    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 get the result like this:
+
+```
+ indexrelid | indexname  
+------------+------------
+      17988 | t_val_idx
+      17989 | t_val_idx1
+      17990 | t_val_idx2
+      17991 | t_val_idx3
+```
+
+You will reindex them with this SQL:
+
+```sql
+REINDEX INDEX t_val_idx;
+REINDEX INDEX t_val_idx1;
+REINDEX INDEX t_val_idx2;
+REINDEX INDEX t_val_idx3;
+```

scripts/ci_package.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -e
+
+cargo pgrx package