@slates-integrations/postgresql 0.2.0-rc.6

package/README.md

@@ -0,0 +1,61 @@
+# <img src="https://provider-logos.metorial-cdn.com/postgresql.png" height="20"> Postgresql
+
+Query, insert, update, and delete data in PostgreSQL relational databases. Explore schemas and tables, manage schemas, tables, indexes, views, materialized views, and database roles, and poll tables for row changes using timestamp or incrementing columns.
+
+## Tools
+
+### Delete Rows
+
+Delete rows from a PostgreSQL table based on a WHERE condition. Supports returning the deleted rows and requires explicit confirmation for full-table deletes.
+
+### Describe Table
+
+Get detailed schema information for a specific table, including columns, data types, constraints, indexes, and foreign keys. Useful for understanding table structure before building queries or modifying schemas.
+
+### Execute SQL Query
+
+Execute an arbitrary SQL query against the PostgreSQL database. Supports all SQL operations including SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, and more. Returns column metadata and result rows for SELECT queries, or affected row counts for DML statements. Supports complex queries with joins, subqueries, CTEs, window functions, and aggregations.
+
+### Insert Rows
+
+Insert one or more rows into a PostgreSQL table. Provide the data as an array of objects where keys are column names and values are the data to insert. Supports inserting multiple rows in a single operation and can optionally return the inserted rows.
+
+### List Schemas
+
+List all schemas in the PostgreSQL database with their table counts and sizes. Useful for exploring the database structure and understanding the organization of tables across schemas.
+
+### Manage Schemas
+
+Create, rename, or drop PostgreSQL schemas. Drop operations require explicit confirmation and can optionally cascade to contained objects.
+
+### List Tables
+
+List all tables in the PostgreSQL database, optionally filtered by schema. Returns table names, schemas, row estimates, and size information. Also supports listing views and materialized views.
+
+### Manage Indexes
+
+Create or drop indexes on PostgreSQL tables. Supports B-tree, Hash, GIN, GiST, and other index types. Can create unique indexes, partial indexes with WHERE conditions, and multi-column indexes.
+
+### Manage Roles
+
+Manage PostgreSQL roles and their privileges. Supports creating and dropping roles, as well as granting and revoking privileges on databases, schemas, tables, and other objects.
+
+### Manage Table
+
+Create, alter, or drop a PostgreSQL table. Supports creating tables with columns, constraints, and foreign keys. For altering tables, supports adding columns, dropping columns, renaming columns, altering column types, and renaming the table.
+
+### Manage Views
+
+Create and drop PostgreSQL views or materialized views, and refresh materialized views. View definitions are restricted to a single read query for safer structured management.
+
+### Update Rows
+
+Update rows in a PostgreSQL table based on a WHERE condition. Specify the columns to update and their new values. Supports returning updated rows and allows complex WHERE conditions.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,109 @@
+# Slates Specification for PostgreSQL
+
+## Overview
+
+PostgreSQL is an open-source relational database management system used for storing, querying, and managing structured data. It supports SQL for data manipulation and definition, advanced data types, extensibility through plugins, and features like transactions, views, stored procedures, and triggers.
+
+## Authentication
+
+PostgreSQL uses a direct database connection model rather than API keys or OAuth. The primary method for remote client authentication is **password-based authentication** via a connection string.
+
+### Connection String Authentication
+
+To connect, the following credentials are required:
+
+- **Host**: The server hostname or IP address
+- **Port**: The port PostgreSQL listens on (default: `5432`)
+- **Database**: The name of the target database
+- **Username**: The database user
+- **Password**: The user's password
+
+The general format for a PostgreSQL connection string (URI) is: `postgresql://[user[:password]@][host][:port][/dbname][?options]`
+
+Example: `postgresql://user:password@localhost:5432/mydatabase`
+
+### SSL/TLS Encryption
+
+For a connection to be known SSL-secured, SSL usage must be configured on both the client and the server before the connection is made. The `sslmode` parameter controls SSL behavior:
+
+- `disable` — No SSL
+- `require` — Encrypt the connection, but don't verify the server certificate
+- `verify-ca` — Verify that the server is trustworthy by checking the certificate chain up to the root certificate stored on the client
+- `verify-full` — Also verify that the server host name matches the name stored in the server certificate
+
+Example with SSL: `postgresql://user:password@localhost:5432/mydatabase?sslmode=require`
+
+When using SSL with client certificates, additional parameters include `sslcert`, `sslkey`, and `sslrootcert` to specify file paths for the client certificate, private key, and root CA certificate respectively.
+
+### Password Hashing Methods
+
+The server may be configured to use different password verification schemes:
+
+- **SCRAM-SHA-256**: The most secure password-based authentication method in PostgreSQL. It uses the Salted Challenge Response Authentication Mechanism (SCRAM) with the SHA-256 hashing function.
+- **MD5**: Password is hashed with MD5 before transmission. Considered legacy.
+- **Plain password**: Sent in clear text; only safe over SSL.
+
+The hashing method is configured server-side and is typically transparent to the connecting client.
+
+## Features
+
+### Data Querying and Manipulation
+
+Execute SQL queries to read, insert, update, and delete data. Supports complex queries with joins, subqueries, aggregations, window functions, common table expressions (CTEs), and full-text search.
+
+### Schema Management
+
+Create and alter databases, schemas, tables, columns, indexes, constraints, and sequences. Supports a rich type system including JSON/JSONB, arrays, enums, geometric types, network address types, and user-defined types.
+
+### Stored Procedures and Functions
+
+Define reusable server-side logic using PL/pgSQL or other procedural languages (PL/Python, PL/Perl, etc.). Functions can return scalar values, rows, or sets of rows and can be used within queries.
+
+### Transactions
+
+Full ACID-compliant transaction support with configurable isolation levels (Read Committed, Repeatable Read, Serializable). Supports savepoints for partial rollbacks within a transaction.
+
+### Views and Materialized Views
+
+Create virtual tables (views) based on queries for simplified data access. Materialized views store query results physically and can be refreshed on demand for performance optimization.
+
+### Triggers
+
+Define automatic actions that execute before, after, or instead of INSERT, UPDATE, or DELETE operations on specific tables. Triggers are essentially callbacks at the database level that can execute a defined function before, after, or instead of identified operations on the table(s) you specify.
+
+### User and Permission Management
+
+Create and manage database roles (users and groups). Grant or revoke privileges at the database, schema, table, column, or function level. Supports row-level security policies for fine-grained access control.
+
+### Extensions
+
+PostgreSQL supports extensions that add functionality, such as PostGIS (geospatial), pg_trgm (trigram matching), hstore (key-value pairs), and many others. Extensions are installed per-database.
+
+### Import and Export
+
+Copy data in bulk using the `COPY` command, which supports CSV and binary formats for efficient data loading and extraction.
+
+## Events
+
+PostgreSQL provides two built-in mechanisms for event-driven data capture:
+
+### LISTEN/NOTIFY
+
+NOTIFY provides a simple interprocess communication mechanism for a collection of processes accessing the same PostgreSQL database. A payload string can be sent along with the notification, and higher-level mechanisms for passing structured data can be built by using tables in the database to pass additional data from notifier to listener(s).
+
+- Clients subscribe to named channels using the `LISTEN` command and receive notifications sent via `NOTIFY` or the `pg_notify()` function.
+- The payload from the message can be any text, up to 8kB in length.
+- Commonly combined with triggers to automatically emit notifications on INSERT, UPDATE, or DELETE events on specific tables.
+- If a NOTIFY is executed inside a transaction, the notify events are not delivered until and unless the transaction is committed.
+- It is crucial that an application using the PostgreSQL notification capabilities are capable of missing events. Notifications are only sent to connected client connections. If the listener disconnects, notifications during that time are lost.
+
+### Logical Replication (Change Data Capture)
+
+Logical replication is a method of replicating data objects and their changes, based upon their replication identity (usually a primary key). Logical replication uses a publish and subscribe model with one or more subscribers subscribing to one or more publications on a publisher node.
+
+- Captures all row-level changes (INSERT, UPDATE, DELETE) from specified tables via the Write-Ahead Log (WAL).
+- Since version 9.4, PostgreSQL offers logical replication, and Postgres versions 10 and later feature the default 'pgoutput' plugin. Older versions require manually installing plugins like `wal2json` or `decoderbufs`.
+- Requires `wal_level` to be set to `logical` on the server and the connecting user to have replication privileges.
+- Uses replication slots to track what data has been consumed, ensuring no changes are missed even if the consumer disconnects temporarily.
+- Table creation and modification steps are not captured by these events. Only DML operations are streamed.
+- Many managed PostgreSQL services, including AWS RDS, Google Cloud SQL, and Azure Database, support Logical Replication.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@slates-integrations/postgresql",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
+    "@slates/provider": "1.0.0-rc.11",
+    "@types/node": "^20",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "version": "0.2.0-rc.6"
+}

package/slate.json

@@ -0,0 +1,18 @@
+{
+  "name": "@metorial/postgresql",
+  "description": "Query, insert, update, and delete data in PostgreSQL relational databases. Explore schemas and tables, manage schemas, tables, indexes, views, materialized views, and database roles, and poll tables for row changes using timestamp or incrementing columns.",
+  "categories": ["apis-and-http-requests"],
+  "skills": [
+    "execute SQL queries",
+    "manage database schemas",
+    "insert and update data",
+    "delete table rows",
+    "describe tables",
+    "create and alter tables",
+    "manage indexes",
+    "create and refresh views and materialized views",
+    "manage database roles",
+    "poll tables for row changes"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/postgresql.png"
+}

package/src/auth.ts

@@ -0,0 +1,134 @@
+import { SlateAuth } from '@slates/provider';
+import { z } from 'zod';
+import { postgresServiceError } from './lib/errors';
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      host: z.string().describe('PostgreSQL server hostname or IP address'),
+      port: z.number().describe('PostgreSQL server port'),
+      database: z.string().describe('Target database name'),
+      username: z.string().describe('Database username'),
+      password: z.string().describe('Database password'),
+      sslMode: z
+        .enum(['disable', 'require', 'verify-ca', 'verify-full'])
+        .describe('SSL connection mode'),
+      connectionString: z.string().describe('Full PostgreSQL connection URI')
+    })
+  )
+  .addCustomAuth({
+    type: 'auth.custom',
+    name: 'Connection String',
+    key: 'connection_string',
+
+    inputSchema: z.object({
+      connectionString: z
+        .string()
+        .describe(
+          'PostgreSQL connection URI (e.g., postgresql://user:password@host:5432/dbname?sslmode=require)'
+        )
+    }),
+
+    getOutput: async ctx => {
+      let connStr = ctx.input.connectionString.trim();
+      let parsed = parseConnectionString(connStr);
+
+      return {
+        output: {
+          host: parsed.host,
+          port: parsed.port,
+          database: parsed.database,
+          username: parsed.username,
+          password: parsed.password,
+          sslMode: parsed.sslMode,
+          connectionString: connStr
+        }
+      };
+    }
+  })
+  .addCustomAuth({
+    type: 'auth.custom',
+    name: 'Connection Parameters',
+    key: 'connection_params',
+
+    inputSchema: z.object({
+      host: z.string().describe('PostgreSQL server hostname or IP address'),
+      port: z.number().default(5432).describe('PostgreSQL server port (default: 5432)'),
+      database: z.string().describe('Target database name'),
+      username: z.string().describe('Database username'),
+      password: z.string().describe('Database password'),
+      sslMode: z
+        .enum(['disable', 'require', 'verify-ca', 'verify-full'])
+        .default('require')
+        .describe('SSL connection mode')
+    }),
+
+    getOutput: async ctx => {
+      let { host, port, database, username, password, sslMode } = ctx.input;
+      let encodedPassword = encodeURIComponent(password);
+      let encodedUsername = encodeURIComponent(username);
+      let sslParam = sslMode !== 'disable' ? `?sslmode=${sslMode}` : '';
+      let connectionString = `postgresql://${encodedUsername}:${encodedPassword}@${host}:${port}/${database}${sslParam}`;
+
+      return {
+        output: {
+          host,
+          port,
+          database,
+          username,
+          password,
+          sslMode,
+          connectionString
+        }
+      };
+    }
+  });
+
+let parseConnectionString = (
+  connStr: string
+): {
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+  sslMode: 'disable' | 'require' | 'verify-ca' | 'verify-full';
+} => {
+  // Parse postgresql://user:password@host:port/dbname?sslmode=require
+  let url: URL;
+  try {
+    url = new URL(connStr);
+  } catch {
+    throw postgresServiceError(
+      'Invalid PostgreSQL connection string format. Expected: postgresql://user:password@host:port/dbname'
+    );
+  }
+
+  if (url.protocol !== 'postgresql:' && url.protocol !== 'postgres:') {
+    throw postgresServiceError(
+      'Invalid PostgreSQL connection string protocol. Use postgresql:// or postgres://.'
+    );
+  }
+
+  let sslModeParam = url.searchParams.get('sslmode') || 'disable';
+  let validSslModes = ['disable', 'require', 'verify-ca', 'verify-full'] as const;
+  if (!validSslModes.includes(sslModeParam as (typeof validSslModes)[number])) {
+    throw postgresServiceError(
+      `Unsupported sslmode "${sslModeParam}". Supported values are disable, require, verify-ca, and verify-full.`
+    );
+  }
+
+  let port = url.port ? parseInt(url.port, 10) : 5432;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw postgresServiceError('Invalid PostgreSQL port in connection string.');
+  }
+
+  return {
+    host: url.hostname || 'localhost',
+    port,
+    database: url.pathname.replace(/^\//, '') || 'postgres',
+    username: decodeURIComponent(url.username || 'postgres'),
+    password: decodeURIComponent(url.password || ''),
+    sslMode: sslModeParam as (typeof validSslModes)[number]
+  };
+};

package/src/config.ts

@@ -0,0 +1,16 @@
+import { SlateConfig } from '@slates/provider';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(
+  z.object({
+    defaultSchema: z
+      .string()
+      .default('public')
+      .describe('Default schema to use for queries when not explicitly specified'),
+    queryTimeout: z.number().default(30000).describe('Query timeout in milliseconds'),
+    maxRows: z
+      .number()
+      .default(1000)
+      .describe('Maximum number of rows to return from queries by default')
+  })
+);

package/src/index.ts

@@ -0,0 +1,36 @@
+import { Slate } from '@slates/provider';
+import { spec } from './spec';
+import {
+  executeQuery,
+  listTables,
+  describeTable,
+  insertRows,
+  updateRows,
+  deleteRows,
+  manageTable,
+  manageIndexes,
+  listSchemas,
+  manageRoles,
+  manageSchemas,
+  manageViews
+} from './tools';
+import { tableChanges, inboundWebhook } from './triggers';
+
+export let provider = Slate.create({
+  spec,
+  tools: [
+    executeQuery,
+    listTables,
+    describeTable,
+    insertRows,
+    updateRows,
+    deleteRows,
+    manageTable,
+    manageIndexes,
+    listSchemas,
+    manageRoles,
+    manageSchemas,
+    manageViews
+  ],
+  triggers: [inboundWebhook, tableChanges]
+});