Postgres Docs (#345)

* Postgres Docs

* Examples!

Author: evantahler

pages/toolkits/_meta.ts

@@ -30,6 +30,9 @@ export default {
   sales: {
     title: "Sales",
   },
+  databases: {
+    title: "Databases",
+  },
   "-- Submit your toolkit": {
     type: "separator",
     title: "Submit your toolkit",

pages/toolkits/databases/_meta.ts

@@ -0,0 +1,3 @@
+export default {
+  postgres: "Postgres",
+};

pages/toolkits/databases/postgres.mdx

@@ -0,0 +1,97 @@
+# Postgres
+
+import ToolInfo from "@/components/ToolInfo";
+import Badges from "@/components/Badges";
+import TabbedCodeBlock from "@/components/TabbedCodeBlock";
+import TableOfContents from "@/components/TableOfContents";
+import ToolFooter from "@/components/ToolFooter";
+
+<ToolInfo
+  description="Enable agents to interact with PostgreSQL databases (read only)."
+  author="Arcade"
+  codeLink="https://github.com/ArcadeAI/arcade-ai/tree/main/toolkits/postgres"
+  authType="database connection string"
+  versions={["0.1.0"]}
+/>
+
+<Badges repo="arcadeai/arcade-postgres" />
+
+The Arcade Postgres toolkit provides a pre-built set of tools for interacting with PostgreSQL databases in a read-only manner.
+
+<Note>
+This toolkit is meant to be an example of how to build a toolkit for a database, and is not intended to be used in production.  For production use, we recommend forking this repository and building your own toolkit with use-case specific tools.
+</Note>
+
+
+This repository demonstrates a few concepts to aid in LLM-powered database interactions.
+* Re-use an existing database pool for all tool calls
+* Enforce read-only access to the database
+* Hint to the LLM that both table and schema discovery is required before executing a query
+* Enforce a limit on the number of rows returned by a query
+
+## Available Tools
+
+<TableOfContents
+  headers={["Tool Name", "Description"]}
+  data={
+    [
+      ['Postgres.DiscoverTables', "Discover all tables in a PostgreSQL database."],
+      ['Postgres.GetTableSchema', "Get the schema of a table in a PostgreSQL database."],
+      ['Postgres.ExecuteQuery', "Execute a query on a PostgreSQL database."],
+    ]
+  }
+/>
+
+Note that all tools require the `DATABASE_CONNECTION_STRING` secret to be set.
+
+## Postgres.DiscoverTables
+
+Discover all tables in a PostgreSQL database.
+
+<TabbedCodeBlock
+  tabs={[
+    {
+      label: "Call the Tool",
+      content: {
+        Python: [
+          "/examples/integrations/toolkits/postgres/discover_tables_example_call_tool.py",
+        ],
+        JavaScript: ["/examples/integrations/toolkits/postgres/discover_tables_example_call_tool.js"],
+      },
+    }
+  ]}
+/>
+## Postgres.GetTableSchema
+
+Get the schema of a table in a PostgreSQL database.
+
+<TabbedCodeBlock
+  tabs={[
+    {
+      label: "Call the Tool",
+      content: {
+        Python: [
+          "/examples/integrations/toolkits/postgres/get_table_schema_example_call_tool.py",
+        ],
+        JavaScript: ["/examples/integrations/toolkits/postgres/get_table_schema_example_call_tool.js"],
+      },
+    }
+  ]}
+/>
+## Postgres.ExecuteQuery
+
+<TabbedCodeBlock
+  tabs={[
+    {
+      label: "Call the Tool",
+      content: {
+        Python: [
+          "/examples/integrations/toolkits/postgres/execute_query_example_call_tool.py",
+        ],
+        JavaScript: ["/examples/integrations/toolkits/postgres/execute_query_example_call_tool.js"],
+      },
+    }
+  ]}
+/>
+
+Execute a query on a PostgreSQL database.  Be sure that your agent runs the `Postgres.DiscoverTables` and `Postgres.GetTableSchema` tools before executing a query.

public/examples/integrations/toolkits/postgres/discover_tables_example_call_tool.js

@@ -0,0 +1,16 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Postgres.DiscoverTables";
+
+const toolInput = {};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(response.output.value);

public/examples/integrations/toolkits/postgres/discover_tables_example_call_tool.py

@@ -0,0 +1,17 @@
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+TOOL_NAME = "Postgres.DiscoverTables"
+
+user_id = "{arcade_user_id}"
+
+tool_input = {}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=user_id,
+)
+
+print(response.output.value)

public/examples/integrations/toolkits/postgres/execute_query_example_call_tool.js

@@ -0,0 +1,18 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Postgres.ExecuteQuery";
+
+const toolInput = {
+  query: "SELECT * FROM users",
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(response.output.value);

public/examples/integrations/toolkits/postgres/execute_query_example_call_tool.py

@@ -0,0 +1,19 @@
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+TOOL_NAME = "Postgres.ExecuteQuery"
+
+user_id = "{arcade_user_id}"
+
+tool_input = {
+    "query": "SELECT * FROM users",
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=user_id,
+)
+
+print(response.output.value)

public/examples/integrations/toolkits/postgres/get_table_schema_example_call_tool.js

@@ -0,0 +1,19 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const USER_ID = "{arcade_user_id}";
+const TOOL_NAME = "Postgres.GetTableSchema";
+
+const toolInput = {
+  schema_name: "public",
+  table_name: "users",
+};
+
+const response = await client.tools.execute({
+  tool_name: TOOL_NAME,
+  input: toolInput,
+  user_id: USER_ID,
+});
+
+console.log(response.output.value);

public/examples/integrations/toolkits/postgres/get_table_schema_example_call_tool.py

@@ -0,0 +1,20 @@
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+TOOL_NAME = "Postgres.GetTableSchema"
+
+user_id = "{arcade_user_id}"
+
+tool_input = {
+    "schema_name": "public",
+    "table_name": "users",
+}
+
+response = client.tools.execute(
+    tool_name=TOOL_NAME,
+    input=tool_input,
+    user_id=user_id,
+)
+
+print(response.output.value)