{"id":42788,"library":"genkitx-cloud-sql-pg","title":"Genkit Cloud SQL for PostgreSQL Plugin","description":"Genkit AI framework plugin for Cloud SQL for PostgreSQL, providing vector storage, indexing, and retrieval using PostgreSQL's pgvector extension. Current stable version is 1.36.0, released as part of the Genkit monorepo with monthly releases. Key differentiators: tight integration with Genkit's AI toolkit, supports custom SQL column mappings, metadata filtering, and batch indexing. Allows using Cloud SQL as a vector database for embeddings without additional infrastructure.","status":"active","version":"1.36.0","language":"javascript","source_language":"en","source_url":"https://github.com/genkit-ai/genkit","tags":["javascript","genkit","genkit-retriever","genkit-plugin","genkit-indexer","cloud-sql-connector","cloud-sql-pg","vector","embedding","typescript"],"install":[{"cmd":"npm install genkitx-cloud-sql-pg","lang":"bash","label":"npm"},{"cmd":"yarn add genkitx-cloud-sql-pg","lang":"bash","label":"yarn"},{"cmd":"pnpm add genkitx-cloud-sql-pg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for connecting to Cloud SQL instances using IAM authentication or SSL.","package":"@google-cloud/cloud-sql-connector","optional":false}],"imports":[{"note":"The correct package is aliased as '@genkit-ai/cloud-sql-pg', not the npm name 'genkitx-cloud-sql-pg'.","wrong":"import { PostgresEngine } from 'genkitx-cloud-sql-pg';","symbol":"PostgresEngine","correct":"import { PostgresEngine } from '@genkit-ai/cloud-sql-pg';"},{"note":"The plugin is ESM and must be imported, not required. postgres is a default export from the plugin.","wrong":"const postgres = require('@genkit-ai/cloud-sql-pg');","symbol":"postgres","correct":"import { postgres } from '@genkit-ai/cloud-sql-pg';"},{"note":"Used to define a retriever reference for your table. Must be passed to ai.retrieve() as the retriever option.","wrong":"","symbol":"postgresRetrieverRef","correct":"import { postgresRetrieverRef } from '@genkit-ai/cloud-sql-pg';"}],"quickstart":{"code":"import { genkit } from 'genkit';\nimport { PostgresEngine, postgres, postgresRetrieverRef, postgresIndexerRef } from '@genkit-ai/cloud-sql-pg';\nimport { textEmbedding004 } from '@genkit-ai/vertexai';\nimport { Document } from 'genkit/retriever';\nimport { vertexAI } from '@genkit-ai/vertexai';\n\nconst engine = await PostgresEngine.fromInstance(\n  process.env.PROJECT_ID ?? 'my-project',\n  process.env.REGION ?? 'us-central1',\n  process.env.INSTANCE_NAME ?? 'my-instance',\n  process.env.DATABASE_NAME ?? 'my-db',\n  { user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASS ?? '' }\n);\n\nconst ai = genkit({\n  plugins: [\n    vertexAI({ location: 'us-central1' }),\n    postgres([{\n      tableName: 'documents',\n      engine,\n      embedder: textEmbedding004,\n      contentColumn: 'content',\n      embeddingColumn: 'embedding',\n      idColumn: 'id',\n      metadataColumns: ['source', 'category'],\n      ignoreMetadataColumns: ['created_at'],\n      metadataJsonColumn: 'metadata',\n    }]),\n  ],\n});\n\nconst indexerRef = postgresIndexerRef({ tableName: 'documents' });\nconst retrieverRef = postgresRetrieverRef({ tableName: 'documents' });\n\nawait ai.index({\n  indexer: indexerRef,\n  documents: [\n    new Document({\n      content: [{ text: 'Sample document' }],\n      metadata: { source: 'web', category: 'info' },\n    }),\n  ],\n});\n\nconst result = await ai.retrieve({\n  retriever: retrieverRef,\n  query: 'Sample',\n});\nconsole.log(result);","lang":"typescript","description":"Shows full setup: connecting to Cloud SQL PG, configuring the plugin with an embedder, indexing documents, and retrieving similar ones."},"warnings":[{"fix":"Check latest Genkit docs; use PostgresEngine.fromTable() if available.","message":"The constructor PostgresEngine.fromInstance() may be deprecated in favor of fromTable() or other methods in future versions.","severity":"deprecated","affected_versions":"<1.36.0"},{"fix":"Use the correct import path '@genkit-ai/cloud-sql-pg'.","message":"The package name in npm is 'genkitx-cloud-sql-pg' but all imports must use '@genkit-ai/cloud-sql-pg'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update genkit to ^1.36.0.","message":"The plugin only works with Genkit v1.36.0 or later due to peer dependency.","severity":"gotcha","affected_versions":"<1.36.0"},{"fix":"Update imports to '@genkit-ai/cloud-sql-pg'.","message":"In version 0.x, the plugin was exported from 'genkitx-cloud-sql-pg' directly. After 1.0, the package was moved to '@genkit-ai/cloud-sql-pg'.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.36.0':31 'addit':72 'ai':8,49 'allow':61 'batch':59 'cloud':2,12,63,86,90 'cloud-sql-connector':85 'cloud-sql-pg':89 'column':54 'connector':88 'current':27 'custom':52 'databas':68 'differenti':43 'embed':70,94 'extens':26 'filter':57 'framework':9 'genkit':1,7,37,47,75,77,80,83 'genkit-index':82 'genkit-plugin':79 'genkit-retriev':76 'index':19,60,84 'infrastructur':73 'integr':45 'javascript':74 'key':42 'map':55 'metadata':56 'monorepo':38 'month':40 'part':34 'pg':92 'pgvector':25 'plugin':6,10,81 'postgresql':5,15,23 'provid':16 'releas':32,41 'retriev':21,78 'sql':3,13,53,64,87,91 'stabl':28 'storag':18 'support':51 'tight':44 'toolkit':50 'typescript':95 'use':22,62 'vector':17,67,93 'version':29 'without':71","created_at":"2026-06-05T16:56:39.758532+00:00","updated_at":"2026-06-05T16:56:39.758532+00:00","problems":[{"fix":"npm install genkitx-cloud-sql-pg then import { PostgresEngine } from 'genkitx-cloud-sql-pg'; (if using aliasing) or use the correct alias '@genkit-ai/cloud-sql-pg'.","cause":"The package was installed with npm as 'genkitx-cloud-sql-pg' but imported with the wrong name.","error":"Error: Cannot find module '@genkit-ai/cloud-sql-pg'"},{"fix":"Use ESM import: import { PostgresEngine } from '@genkit-ai/cloud-sql-pg';","cause":"Importing default incorrectly (e.g., const PostgresEngine = require('...').default) in CJS context.","error":"TypeError: PostgresEngine.fromInstance is not a function"},{"fix":"Pass an embedder like textEmbedding004 from '@genkit-ai/vertexai'.","cause":"The embedder option in plugin configuration is missing or invalid.","error":"Error: plugin postgres requires a valid embedder"},{"fix":"Create the table manually with appropriate columns (e.g., id, content, embedding, metadata). Reference Genkit docs for schema.","cause":"The PostgreSQL table does not exist; the plugin does not auto-create tables.","error":"Error: table 'documents' does not exist"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/genkit-ai/genkit#readme","github":"https://github.com/genkit-ai/genkit","docs":null,"changelog":null,"pypi":null,"npm":"genkitx-cloud-sql-pg","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}