refactor(modules): split adapters, examples, and adapter tests into separate Go modules

.github/workflows/build.yml

@@ -13,7 +13,12 @@ jobs:
         with:
           go-version: ${{ matrix.go }}
           cache: false # depends on go.sum
-      - run: go mod tidy
+      - run: |
+          go mod tidy
+          (cd adapters/pgx && go mod tidy)
+          (cd adapters/ent && go mod tidy)
+          (cd examples && go mod tidy)
+          (cd adapter_tests && go mod tidy)
       - uses: ankane/setup-postgres@v1
         with:
           database: pgvector_go_test
@@ -24,5 +29,9 @@ jobs:
           cd pgvector
           make
           sudo make install
-      - run: go generate ./test/ent && go mod tidy
-      - run: go test -v
+      - run: (cd adapters/ent && go generate ./test && go mod tidy)
+      - run: go test -v ./...
+      - run: (cd adapters/pgx && go test -v ./...)
+      - run: (cd adapters/ent && go test -v ./...)
+      - run: (cd examples && go test -v ./...)
+      - run: (cd adapter_tests && go test -v ./...)

.gitignore

@@ -1,4 +1,5 @@
-/go.sum
-/test/ent/*
-!/test/ent/generate.go
-!/test/ent/schema
+go.sum
+go.work.sum
+/adapters/ent/test/*
+!/adapters/ent/test/generate.go
+!/adapters/ent/test/schema

README.md

@@ -14,6 +14,16 @@ Run:
 go get github.com/pgvector/pgvector-go
 ```
 
+Install adapter modules only when needed:
+
+```sh
+# pgx adapter
+go get github.com/pgvector/pgvector-go/adapters/pgx
+
+# ent helpers
+go get github.com/pgvector/pgvector-go/adapters/ent
+```
+
 And follow the instructions for your database library:
 
 - [pgx](#pgx)
@@ -40,7 +50,7 @@ Import the packages
 ```go
 import (
     "github.com/pgvector/pgvector-go"
-    pgxvec "github.com/pgvector/pgvector-go/pgx"
+    pgxvec "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 ```
 
@@ -92,7 +102,7 @@ _, err := conn.Exec(ctx, "CREATE INDEX ON items USING ivfflat (embedding vector_
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](pgx_test.go)
+See a [full example](adapter_tests/pgx_test.go)
 
 ## pg
 
@@ -145,7 +155,7 @@ _, err := conn.Exec(ctx, "CREATE INDEX ON items USING ivfflat (embedding vector_
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](pg_test.go)
+See a [full example](adapter_tests/pg_test.go)
 
 ## Bun
 
@@ -207,7 +217,7 @@ func (*Item) AfterCreateTable(ctx context.Context, query *bun.CreateTableQuery)
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](bun_test.go)
+See a [full example](adapter_tests/bun_test.go)
 
 ## Ent
 
@@ -216,7 +226,7 @@ Import the package
 ```go
 import (
     "github.com/pgvector/pgvector-go"
-    entvec "github.com/pgvector/pgvector-go/ent"
+    entvec "github.com/pgvector/pgvector-go/adapters/ent"
 )
 ```
 
@@ -278,7 +288,7 @@ func (Item) Indexes() []ent.Index {
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](ent_test.go)
+See a [full example](adapter_tests/ent_test.go)
 
 ## GORM
 
@@ -330,7 +340,7 @@ db.Exec("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lis
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](gorm_test.go)
+See a [full example](adapter_tests/gorm_test.go)
 
 ## sqlx
 
@@ -380,7 +390,7 @@ db.MustExec("CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
-See a [full example](sqlx_test.go)
+See a [full example](adapter_tests/sqlx_test.go)
 
 ## Reference
 
@@ -472,14 +482,22 @@ To get started with development:
 git clone https://github.com/pgvector/pgvector-go.git
 cd pgvector-go
 go mod tidy
+(cd adapters/pgx && go mod tidy)
+(cd adapters/ent && go mod tidy)
+(cd examples && go mod tidy)
+(cd adapter_tests && go mod tidy)
 createdb pgvector_go_test
-go generate ./test/ent
-go test -v
+(cd ./adapters/ent && go generate ./test)
+go test ./...
+(cd adapters/pgx && go test ./...)
+(cd adapters/ent && go test ./...)
+(cd adapter_tests && go test ./...)
 ```
 
 To run an example:
 
 ```sh
 createdb pgvector_example
-go run ./examples/loading
+cd examples
+go run ./loading
 ```

bun_test.go → adapter_tests/bun_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"context"
@@ -14,6 +14,16 @@ import (
 	"github.com/uptrace/bun/driver/pgdriver"
 )
 
+func pgUser() string {
+	if user := os.Getenv("PGUSER"); user != "" {
+		return user
+	}
+	if user := os.Getenv("USER"); user != "" {
+		return user
+	}
+	return "postgres"
+}
+
 type BunItem struct {
 	bun.BaseModel `bun:"table:bun_items"`
 
@@ -73,7 +83,7 @@ func TestBun(t *testing.T) {
 
 	pgconn := pgdriver.NewConnector(
 		pgdriver.WithDatabase("pgvector_go_test"),
-		pgdriver.WithUser(os.Getenv("USER")),
+		pgdriver.WithUser(pgUser()),
 		pgdriver.WithTLSConfig(nil), // sslmode=disable
 	)
 	sqldb := sql.OpenDB(pgconn)

ent_test.go → adapter_tests/ent_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"context"
@@ -8,8 +8,8 @@ import (
 	"entgo.io/ent/dialect/sql"
 	_ "github.com/lib/pq"
 	"github.com/pgvector/pgvector-go"
-	entvec "github.com/pgvector/pgvector-go/ent"
-	"github.com/pgvector/pgvector-go/test/ent"
+	entvec "github.com/pgvector/pgvector-go/adapters/ent"
+	ent "github.com/pgvector/pgvector-go/adapters/ent/test"
 )
 
 func TestEnt(t *testing.T) {

adapter_tests/go.mod

@@ -0,0 +1,56 @@
+module github.com/pgvector/pgvector-go/adapter_tests
+
+go 1.23.0
+
+replace github.com/pgvector/pgvector-go/adapters/ent => ../adapters/ent
+
+replace github.com/pgvector/pgvector-go/adapters/pgx => ../adapters/pgx
+
+require (
+	entgo.io/ent v0.14.3
+	github.com/go-pg/pg/v10 v10.11.0
+	github.com/jackc/pgx/v5 v5.7.2
+	github.com/jmoiron/sqlx v1.3.5
+	github.com/lib/pq v1.10.9
+	github.com/pgvector/pgvector-go v0.3.0
+	github.com/pgvector/pgvector-go/adapters/ent v0.0.0
+	github.com/pgvector/pgvector-go/adapters/pgx v0.0.0
+	github.com/uptrace/bun v1.1.12
+	github.com/uptrace/bun/dialect/pgdialect v1.1.12
+	github.com/uptrace/bun/driver/pgdriver v1.1.12
+	gorm.io/driver/postgres v1.5.4
+	gorm.io/gorm v1.25.5
+)
+
+require (
+	ariga.io/atlas v0.32.0 // indirect
+	github.com/agext/levenshtein v1.2.3 // indirect
+	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
+	github.com/bmatcuk/doublestar v1.3.4 // indirect
+	github.com/go-openapi/inflect v0.21.0 // indirect
+	github.com/go-pg/zerochecker v0.2.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/hcl/v2 v2.23.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
+	github.com/tmthrgd/go-hex v0.0.0-20190904060850-447a3041c3bc // indirect
+	github.com/vmihailenco/bufpool v0.1.11 // indirect
+	github.com/vmihailenco/msgpack/v5 v5.3.5 // indirect
+	github.com/vmihailenco/tagparser v0.1.2 // indirect
+	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	github.com/zclconf/go-cty v1.16.2 // indirect
+	github.com/zclconf/go-cty-yaml v1.1.0 // indirect
+	golang.org/x/crypto v0.36.0 // indirect
+	golang.org/x/mod v0.24.0 // indirect
+	golang.org/x/sync v0.12.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
+	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/tools v0.31.0 // indirect
+	mellium.im/sasl v0.3.1 // indirect
+)

gorm_test.go → adapter_tests/gorm_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"math"

pg_test.go → adapter_tests/pg_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"math"

pgx_test.go → adapter_tests/pgx_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"context"
@@ -10,7 +10,7 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/pgvector/pgvector-go"
-	pgxvec "github.com/pgvector/pgvector-go/pgx"
+	pgxvec "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 type PgxItem struct {

sqlx_test.go → adapter_tests/sqlx_test.go

@@ -1,4 +1,4 @@
-package pgvector_test
+package adapter_tests_test
 
 import (
 	"reflect"

adapter_tests/stub.go

@@ -0,0 +1,5 @@
+package adapter_tests
+
+func stub() {
+	// Empty stub
+}

adapters/ent/go.mod

@@ -0,0 +1,26 @@
+module github.com/pgvector/pgvector-go/adapters/ent
+
+go 1.23.0
+
+require (
+	entgo.io/ent v0.14.3
+	github.com/pgvector/pgvector-go v0.3.0
+)
+
+require (
+	ariga.io/atlas v0.32.0 // indirect
+	github.com/agext/levenshtein v1.2.3 // indirect
+	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
+	github.com/bmatcuk/doublestar v1.3.4 // indirect
+	github.com/go-openapi/inflect v0.21.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/hcl/v2 v2.23.0 // indirect
+	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
+	github.com/zclconf/go-cty v1.16.2 // indirect
+	github.com/zclconf/go-cty-yaml v1.1.0 // indirect
+	golang.org/x/mod v0.24.0 // indirect
+	golang.org/x/sync v0.12.0 // indirect
+	golang.org/x/text v0.23.0 // indirect
+	golang.org/x/tools v0.31.0 // indirect
+)

adapters/ent/test/generate.go

@@ -0,0 +1,3 @@
+package test
+
+//go:generate go run entgo.io/ent/cmd/ent generate --feature sql/execquery ./schema

adapters/pgx/go.mod

@@ -0,0 +1,17 @@
+module github.com/pgvector/pgvector-go/adapters/pgx
+
+go 1.23.0
+
+require (
+	github.com/jackc/pgx/v5 v5.7.2
+	github.com/pgvector/pgvector-go v0.3.0
+	github.com/x448/float16 v0.8.4
+)
+
+require (
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/stretchr/testify v1.8.2 // indirect
+	golang.org/x/crypto v0.36.0 // indirect
+	golang.org/x/text v0.23.0 // indirect
+)

examples/citus/main.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/pgvector/pgvector-go"
-	pgxvector "github.com/pgvector/pgvector-go/pgx"
+	pgxvector "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 func main() {

examples/disco/main.go

@@ -7,7 +7,7 @@ import (
 	"github.com/ankane/disco-go"
 	"github.com/jackc/pgx/v5"
 	"github.com/pgvector/pgvector-go"
-	pgxvector "github.com/pgvector/pgvector-go/pgx"
+	pgxvector "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 func main() {

examples/go.mod

@@ -0,0 +1,7 @@
+module github.com/pgvector/pgvector-go/examples
+
+go 1.23.0
+
+replace github.com/pgvector/pgvector-go/adapters/ent => ../adapters/ent
+
+replace github.com/pgvector/pgvector-go/adapters/pgx => ../adapters/pgx

examples/hybrid/main.go

@@ -9,7 +9,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/pgvector/pgvector-go"
-	pgxvector "github.com/pgvector/pgvector-go/pgx"
+	pgxvector "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 func main() {

examples/loading/main.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/pgvector/pgvector-go"
-	pgxvector "github.com/pgvector/pgvector-go/pgx"
+	pgxvector "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 func main() {

examples/openai/main.go

@@ -10,7 +10,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 	"github.com/pgvector/pgvector-go"
-	pgxvector "github.com/pgvector/pgvector-go/pgx"
+	pgxvector "github.com/pgvector/pgvector-go/adapters/pgx"
 )
 
 func main() {