Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PostgresEngine
✓ import { PostgresEngine } from '@genkit-ai/cloud-sql-pg';
✗ import { PostgresEngine } from 'genkitx-cloud-sql-pg';
The correct package is aliased as '@genkit-ai/cloud-sql-pg', not the npm name 'genkitx-cloud-sql-pg'.
postgres
✓ import { postgres } from '@genkit-ai/cloud-sql-pg';
✗ const postgres = require('@genkit-ai/cloud-sql-pg');
The plugin is ESM and must be imported, not required. postgres is a default export from the plugin.
postgresRetrieverRef
✓ import { postgresRetrieverRef } from '@genkit-ai/cloud-sql-pg';
Used to define a retriever reference for your table. Must be passed to ai.retrieve() as the retriever option.
Shows full setup: connecting to Cloud SQL PG, configuring the plugin with an embedder, indexing documents, and retrieving similar ones.
import { genkit } from 'genkit';
import { PostgresEngine, postgres, postgresRetrieverRef, postgresIndexerRef } from '@genkit-ai/cloud-sql-pg';
import { textEmbedding004 } from '@genkit-ai/vertexai';
import { Document } from 'genkit/retriever';
import { vertexAI } from '@genkit-ai/vertexai';
const engine = await PostgresEngine.fromInstance(
process.env.PROJECT_ID ?? 'my-project',
process.env.REGION ?? 'us-central1',
process.env.INSTANCE_NAME ?? 'my-instance',
process.env.DATABASE_NAME ?? 'my-db',
{ user: process.env.DB_USER ?? 'postgres', password: process.env.DB_PASS ?? '' }
);
const ai = genkit({
plugins: [
vertexAI({ location: 'us-central1' }),
postgres([{
tableName: 'documents',
engine,
embedder: textEmbedding004,
contentColumn: 'content',
embeddingColumn: 'embedding',
idColumn: 'id',
metadataColumns: ['source', 'category'],
ignoreMetadataColumns: ['created_at'],
metadataJsonColumn: 'metadata',
}]),
],
});
const indexerRef = postgresIndexerRef({ tableName: 'documents' });
const retrieverRef = postgresRetrieverRef({ tableName: 'documents' });
await ai.index({
indexer: indexerRef,
documents: [
new Document({
content: [{ text: 'Sample document' }],
metadata: { source: 'web', category: 'info' },
}),
],
});
const result = await ai.retrieve({
retriever: retrieverRef,
query: 'Sample',
});
console.log(result);
Errors
Common errors & fixes
Error: Cannot find module '@genkit-ai/cloud-sql-pg'
The package was installed with npm as 'genkitx-cloud-sql-pg' but imported with the wrong name.
fixnpm 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'. TypeError: PostgresEngine.fromInstance is not a function
Importing default incorrectly (e.g., const PostgresEngine = require('...').default) in CJS context.
fixUse ESM import: import { PostgresEngine } from '@genkit-ai/cloud-sql-pg'; Error: plugin postgres requires a valid embedder
The embedder option in plugin configuration is missing or invalid.
fixPass an embedder like textEmbedding004 from '@genkit-ai/vertexai'.
Error: table 'documents' does not exist
The PostgreSQL table does not exist; the plugin does not auto-create tables.
fixCreate the table manually with appropriate columns (e.g., id, content, embedding, metadata). Reference Genkit docs for schema.
Audit
Dependencies
@google-cloud/cloud-sql-connectorrequiredRequired for connecting to Cloud SQL instances using IAM authentication or SSL.