From c38d12e121ba2f7e1cf8f9559f10fa1b4e422f20 Mon Sep 17 00:00:00 2001 From: David Nastasi Date: Tue, 3 Jun 2025 23:11:45 -0300 Subject: [PATCH 1/3] docs(go): added document for postgresql plugin --- .../docs/go/docs/plugins/postgresql.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 src/content/docs/go/docs/plugins/postgresql.md diff --git a/src/content/docs/go/docs/plugins/postgresql.md b/src/content/docs/go/docs/plugins/postgresql.md new file mode 100644 index 00000000..0497f03a --- /dev/null +++ b/src/content/docs/go/docs/plugins/postgresql.md @@ -0,0 +1,188 @@ +--- +title: Postgresql plugin +description: Learn how to configure and use the Genkit Postgresql plugin for Go to integrate with pgvector extension. +--- + +The Postgresql plugin provides indexer and retriever implementatons that use the [Google Cloud SQL for Postgresql](https://cloud.google.com/sql/docs/postgres) and [pgvector](https://github.com/pgvector/pgvector) extension. + +## Configuration + +To use this plugin, follow these steps: + +1. Import the plugin + + ```go + import "github.com/firebase/genkit/go/plugins/postgresql" + ``` + +2. Create a `PostgresEngine` instance: + + - Using basic authentication + ```go + pEngine, err := NewPostgresEngine(ctx, + WithUser('user'), + WithPassword('password'), + WithAlloyDBInstance('my-project', 'us-central1', 'my-cluster', 'my-instance'), + WithDatabase('my-database') + ``` + - Using email authentication + ```go + pEngine, err := NewPostgresEngine(ctx, + WithCloudSQLInstance('my-project', 'us-central1', 'my-cluster', 'my-instance'), + WithDatabase('my-database'), + WithIAMAccountEmail('mail@company.com')) + ``` + - Using custom pool + ```go + pool, err := pgxpool.New(ctx, "add_your_connection_string") + if err != nil { + return err + } + + pEngine, err := NewPostgresEngine(ctx, + WithDatabase("db_test"), + WithPool(pool)) + + ``` + +3. Create the Postgres plugin + - Using plugin method Init + + + ```go + postgres := &postgresql.Postgres{ + engine: pEngine, + } + + if err := (postgres).Init(ctx, g); err != nil { + return err + } + ``` + + - Using the genkit method init + + ```go + postgres := &postgresql.Postgres{ + engine: pEngine, + } + + g, err := genkit.Init(ctx, genkit.WithPlugins(postgres)) + + if err != nil { + return err + } + + ``` + +## Usage + +To add documents to a Postgresql index, first create an index definition that specifies the features of the table: + +```go +cfg := &postgresql.Config{ + TableName: 'documents', + SchemaName: 'public', + ContentColumn: "content", + EmbeddingColumn: "embedding", + MetadataColumns: []string{"source", "category"}, + IDColumn: "custom_id", + MetadataJSONColumn: "custom_metadata", + Embedder: embedder, + EmbedderOptions: nil, +} + +indexer, err := postgresql.DefineIndexer(ctx, g, postgres, cfg) +if err != nil { + return err +} + +d1 := ai.DocumentFromText( + "The product features include..." , + map[string]any{ + "source": "website", + "category": "product-docs", + "custom_id": "doc-123"}) + +err := ai.Index(ctx, indexer, ai.WithIndexerDocs(d1)) +if err != nil { + return err +} + +``` + +It's also posible to use the Index method from Indexer + +```go + +cfg := &postgresql.Config{ + TableName: 'documents', + SchemaName: 'public', + ContentColumn: "content", + EmbeddingColumn: "embedding", + MetadataColumns: []string{"source", "category"}, + IDColumn: "custom_id", + MetadataJSONColumn: "custom_metadata", + Embedder: embedder, + EmbedderOptions: nil, +} + +indexer, err := postgresql.DefineIndexer(ctx, g, postgres, cfg) +if err != nil { + return err +} + + +reqIndexer := &ai.IndexerRequest{ + Documents: []*ai.Document{d1}, + Options: nil} + +err = indexer.Index(ctx, reqIndexer) + +``` + +Similarly, to retrieve documents from an index, first create a retriever +definition: + +```go +retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) +if err != nil { + retrun err +} + +d2 := ai.DocumentFromText( "The product features include..." , nil) + +resp, err := retriever.Retrieve(ctx, &ai.RetrieverRequest{ + Query: d2, + k:5, + filter: "source='website' AND category='product-docs'" +}) + +if err != nil { + retrun err +} +``` + +It's also posible to use the Retrieve method from Retriever + +```go +retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) +if err != nil { + retrun err +} + +d2 := ai.DocumentFromText( "The product features include..." , nil) + +retrieverOptions := &postgresql.RetrieverOptions{ + k:5, + filter: "source='website' AND category='product-docs'" +} + +resp, err := ai.Retrieve(ctx, retriever,ai.WithDocs(d2), &ai.WithConfig(retrieverOptions)) +if err != nil { + retrun err +} +``` + + +See the [Retrieval-augmented generation](/go/docs/rag) page for a general +discussion on using indexers and retrievers for RAG. From b388bf3129aa6d71d5227ce3f61f7dbb5016dd3d Mon Sep 17 00:00:00 2001 From: David Nastasi Date: Tue, 10 Jun 2025 23:46:06 -0300 Subject: [PATCH 2/3] fix: wrong method in postgres engine --- src/content/docs/go/docs/plugins/postgresql.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/go/docs/plugins/postgresql.md b/src/content/docs/go/docs/plugins/postgresql.md index 0497f03a..3a55ee68 100644 --- a/src/content/docs/go/docs/plugins/postgresql.md +++ b/src/content/docs/go/docs/plugins/postgresql.md @@ -22,13 +22,13 @@ To use this plugin, follow these steps: pEngine, err := NewPostgresEngine(ctx, WithUser('user'), WithPassword('password'), - WithAlloyDBInstance('my-project', 'us-central1', 'my-cluster', 'my-instance'), + WithCloudSQLInstance('my-project', 'us-central1', 'my-instance'), WithDatabase('my-database') ``` - Using email authentication ```go pEngine, err := NewPostgresEngine(ctx, - WithCloudSQLInstance('my-project', 'us-central1', 'my-cluster', 'my-instance'), + WithCloudSQLInstance('my-project', 'us-central1', 'my-instance'), WithDatabase('my-database'), WithIAMAccountEmail('mail@company.com')) ``` From e1a75f0148dc6fa5030c9307088df7e7bb00b104 Mon Sep 17 00:00:00 2001 From: David Nastasi Date: Thu, 19 Jun 2025 17:01:50 -0300 Subject: [PATCH 3/3] chore: plugin doc updated --- .../docs/go/docs/plugins/postgresql.md | 69 +++++-------------- 1 file changed, 17 insertions(+), 52 deletions(-) diff --git a/src/content/docs/go/docs/plugins/postgresql.md b/src/content/docs/go/docs/plugins/postgresql.md index 3a55ee68..9a00a5e9 100644 --- a/src/content/docs/go/docs/plugins/postgresql.md +++ b/src/content/docs/go/docs/plugins/postgresql.md @@ -76,7 +76,7 @@ To use this plugin, follow these steps: ## Usage -To add documents to a Postgresql index, first create an index definition that specifies the features of the table: +To add documents to a Postgresql index, first create a retrieve definition that specifies the features of the table: ```go cfg := &postgresql.Config{ @@ -91,64 +91,29 @@ cfg := &postgresql.Config{ EmbedderOptions: nil, } -indexer, err := postgresql.DefineIndexer(ctx, g, postgres, cfg) +doc, retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) if err != nil { - return err -} - -d1 := ai.DocumentFromText( - "The product features include..." , - map[string]any{ - "source": "website", - "category": "product-docs", - "custom_id": "doc-123"}) - -err := ai.Index(ctx, indexer, ai.WithIndexerDocs(d1)) -if err != nil { - return err -} - -``` - -It's also posible to use the Index method from Indexer - -```go - -cfg := &postgresql.Config{ - TableName: 'documents', - SchemaName: 'public', - ContentColumn: "content", - EmbeddingColumn: "embedding", - MetadataColumns: []string{"source", "category"}, - IDColumn: "custom_id", - MetadataJSONColumn: "custom_metadata", - Embedder: embedder, - EmbedderOptions: nil, + retrun err } -indexer, err := postgresql.DefineIndexer(ctx, g, postgres, cfg) -if err != nil { - return err +docs := []*ai.Document{{ + Content: []*ai.Part{{ + Kind: ai.PartText, + ContentType: "text/plain", + Text: "The product features include...", + }}, + Metadata: map[string]any{"source": "website", "category": "product-docs", "custom_id": "doc-123"}, + }} + +if err := doc.Index(ctx, docs); err != nil { + return err } - -reqIndexer := &ai.IndexerRequest{ - Documents: []*ai.Document{d1}, - Options: nil} - -err = indexer.Index(ctx, reqIndexer) - ``` -Similarly, to retrieve documents from an index, first create a retriever -definition: +Similarly, to retrieve documents from an index, use the retrieve method: ```go -retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) -if err != nil { - retrun err -} - d2 := ai.DocumentFromText( "The product features include..." , nil) resp, err := retriever.Retrieve(ctx, &ai.RetrieverRequest{ @@ -162,10 +127,10 @@ if err != nil { } ``` -It's also posible to use the Retrieve method from Retriever +It's also possible to use the Retrieve method from Retriever ```go -retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) +_, retriever, err := postgresql.DefineRetriever(ctx, g, postgres, cfg) if err != nil { retrun err }