{"_id":"@agent-runner/store-postgres","_rev":"2-4c8089ddf3fddc27f1bc65717c36a238","name":"@agent-runner/store-postgres","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agent-runner/store-postgres","version":"0.1.0","keywords":["agent-runner","postgres","postgresql","store","ai","agents"],"author":{"name":"Aaron Bidworthy"},"license":"MIT","_id":"@agent-runner/store-postgres@0.1.0","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"homepage":"https://github.com/aparry3/agent-runner#readme","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"dist":{"shasum":"e48bab07d76d491582c6d80b7a463742ae8ba520","tarball":"https://registry.npmjs.org/@agent-runner/store-postgres/-/store-postgres-0.1.0.tgz","fileCount":4,"integrity":"sha512-EFRapWN57hD0IcH1SSTd9MiAq0vHA+0Bpd71Ks3KLdOMIAjteNvXhEYs3+zWeDgVsN9NID83SygQ5uwx3smeKg==","signatures":[{"sig":"MEUCIQDFnepieCpWTVY8dvXYk1yc7+YnG/oKiszGIYlVndbf+AIgR7BzNiR47CanBxPxrgTC9bCfPPGgvnDOmItNKckKHa8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":42102},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"15bbcff48ae585a4816b8d26f0625634da2adbea","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"tsup"},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"repository":{"url":"git+https://github.com/aparry3/agent-runner.git","type":"git","directory":"packages/store-postgres"},"_npmVersion":"10.9.4","description":"PostgreSQL store adapter for agent-runner — multi-server production storage","directories":{},"_nodeVersion":"22.21.0","dependencies":{"pg":"^8.13.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","@types/pg":"^8.11.0","typescript":"^5.7.0","@agent-runner/core":"workspace:*"},"peerDependencies":{"@agent-runner/core":">=0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/store-postgres_0.1.0_1773227422672_0.5896825668815417","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-runner/store-postgres","version":"0.1.1","description":"PostgreSQL store adapter for agent-runner — multi-server production storage","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"pg":"^8.13.0"},"devDependencies":{"@types/pg":"^8.11.0","tsup":"^8.0.0","typescript":"^5.7.0","vitest":"^2.0.0","@agent-runner/core":"0.1.1"},"peerDependencies":{"@agent-runner/core":">=0.1.1"},"keywords":["agent-runner","postgres","postgresql","store","ai","agents"],"publishConfig":{"access":"public"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/store-postgres"},"homepage":"https://github.com/aparry3/agent-runner#readme","author":{"name":"Aaron Bidworthy"},"engines":{"node":">=20.0.0"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"_id":"@agent-runner/store-postgres@0.1.1","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"_integrity":"sha512-do4PeeaxgJVct5w4UJLcvXfIuKzDSrNUS6ynw/jPrnWGPwVHWyfgrug8qaJL5FlHJCxREsLHOGXhAHuXsgL8BA==","_resolved":"/tmp/6183b1afaec322ff99a4939115a16bbc/agent-runner-store-postgres-0.1.1.tgz","_from":"file:agent-runner-store-postgres-0.1.1.tgz","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-do4PeeaxgJVct5w4UJLcvXfIuKzDSrNUS6ynw/jPrnWGPwVHWyfgrug8qaJL5FlHJCxREsLHOGXhAHuXsgL8BA==","shasum":"b9de1c497867953f929fc5e7fdc0894d6f34d9d3","tarball":"https://registry.npmjs.org/@agent-runner/store-postgres/-/store-postgres-0.1.1.tgz","fileCount":6,"unpackedSize":51422,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC5EtP/Qt8qaPGqRLdkkzR9kYoZ65OcHXOv2dDgnj5L/wIgbxib73lLtSNS1af3Calt3h/nV1fWxvDMB8eC0VQI5q4="}]},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"directories":{},"maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/store-postgres_0.1.1_1773230666223_0.46838557791227675"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T11:10:22.572Z","modified":"2026-03-11T12:04:26.486Z","0.1.0":"2026-03-11T11:10:22.800Z","0.1.1":"2026-03-11T12:04:26.358Z"},"bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"author":{"name":"Aaron Bidworthy"},"license":"MIT","homepage":"https://github.com/aparry3/agent-runner#readme","keywords":["agent-runner","postgres","postgresql","store","ai","agents"],"repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/store-postgres"},"description":"PostgreSQL store adapter for agent-runner — multi-server production storage","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"readme":"# @agent-runner/store-postgres\n\n[![npm version](https://img.shields.io/npm/v/@agent-runner/store-postgres.svg)](https://www.npmjs.com/package/@agent-runner/store-postgres)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)\n\nPostgreSQL storage adapter for [agent-runner](https://github.com/aparry3/agent-runner). Production-ready persistent storage for multi-server deployments with automatic migrations, JSONB storage, connection pooling, and configurable table prefixes.\n\n## Install\n\n```bash\nnpm install @agent-runner/store-postgres @agent-runner/core\n# or\npnpm add @agent-runner/store-postgres @agent-runner/core\n# or\nyarn add @agent-runner/store-postgres @agent-runner/core\n```\n\n## Quick Start\n\n```typescript\nimport { createRunner, defineAgent } from \"@agent-runner/core\";\nimport { PostgresStore } from \"@agent-runner/store-postgres\";\n\nconst runner = createRunner({\n  store: new PostgresStore(\"postgresql://user:pass@localhost:5432/mydb\"),\n});\n\nrunner.registerAgent(defineAgent({\n  id: \"greeter\",\n  name: \"Greeter\",\n  systemPrompt: \"You are a friendly greeter.\",\n  model: { provider: \"openai\", name: \"gpt-4o-mini\" },\n}));\n\nconst result = await runner.invoke(\"greeter\", \"Hello!\");\nconsole.log(result.output);\n```\n\n## Usage\n\n### Connection String\n\nThe simplest way — pass a PostgreSQL connection string:\n\n```typescript\nconst store = new PostgresStore(\"postgresql://user:pass@localhost:5432/mydb\");\n```\n\n### Existing Connection Pool\n\nShare a `pg.Pool` across your application to manage connections centrally:\n\n```typescript\nimport pg from \"pg\";\nimport { PostgresStore } from \"@agent-runner/store-postgres\";\n\nconst pool = new pg.Pool({\n  connectionString: process.env.DATABASE_URL,\n  max: 20,\n  idleTimeoutMillis: 30000,\n});\n\nconst store = new PostgresStore({ connection: pool });\n\n// The store won't close this pool on shutdown (you own it)\n```\n\n### Pool Configuration\n\nPass a `pg.PoolConfig` object for fine-grained control:\n\n```typescript\nconst store = new PostgresStore({\n  connection: {\n    host: \"localhost\",\n    port: 5432,\n    database: \"mydb\",\n    user: \"myuser\",\n    password: \"mypassword\",\n    max: 10,\n    ssl: { rejectUnauthorized: false },\n  },\n});\n```\n\n### Table Prefix\n\nAvoid naming conflicts by customizing the table prefix (default: `ar_`):\n\n```typescript\nconst store = new PostgresStore({\n  connection: \"postgresql://localhost:5432/mydb\",\n  tablePrefix: \"myapp_\",\n});\n// Tables: myapp_agents, myapp_sessions, myapp_messages, etc.\n```\n\n### Skip Auto-Migration\n\nIf you manage migrations separately:\n\n```typescript\nconst store = new PostgresStore({\n  connection: \"postgresql://localhost:5432/mydb\",\n  skipMigration: true,\n});\n```\n\n## API Reference\n\n### `PostgresStore`\n\nImplements `UnifiedStore` from `@agent-runner/core` — provides `AgentStore`, `SessionStore`, `ContextStore`, and `LogStore` in a single class.\n\n#### Constructor\n\n```typescript\nnew PostgresStore(connectionString: string)\nnew PostgresStore(options: PostgresStoreOptions)\n```\n\n#### `PostgresStoreOptions`\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `connection` | `string \\| pg.Pool \\| pg.PoolConfig` | — | **Required.** Connection string, pool instance, or pool config |\n| `tablePrefix` | `string` | `\"ar_\"` | Prefix for all table names |\n| `skipMigration` | `boolean` | `false` | Skip automatic schema migration |\n\n#### Store Methods\n\n**AgentStore:**\n\n| Method | Description |\n|---|---|\n| `getAgent(id)` | Get an agent definition by ID |\n| `listAgents()` | List all agents (id, name, description) |\n| `putAgent(agent)` | Create or update an agent |\n| `deleteAgent(id)` | Delete an agent |\n\n**SessionStore:**\n\n| Method | Description |\n|---|---|\n| `getMessages(sessionId)` | Get all messages in a session |\n| `append(sessionId, messages)` | Append messages (creates session if needed) |\n| `deleteSession(sessionId)` | Delete a session and its messages |\n| `listSessions(agentId?)` | List sessions, optionally filtered by agent |\n\n**ContextStore:**\n\n| Method | Description |\n|---|---|\n| `getContext(contextId)` | Get all entries for a context bucket |\n| `addContext(contextId, entry)` | Add an entry to a context bucket |\n| `clearContext(contextId)` | Clear all entries in a context bucket |\n\n**LogStore:**\n\n| Method | Description |\n|---|---|\n| `log(entry)` | Write an invocation log |\n| `getLogs(filter?)` | Query logs with optional filters |\n| `getLog(id)` | Get a single log by ID |\n\n**Lifecycle:**\n\n| Method | Description |\n|---|---|\n| `close()` | Close the connection pool (only if the store created it) |\n| `pgPool` | Access the underlying `pg.Pool` for advanced queries |\n\n## Schema\n\nThe store creates the following tables automatically (prefixed with `ar_` by default):\n\n| Table | Description |\n|---|---|\n| `ar_agents` | Agent definitions stored as JSONB |\n| `ar_sessions` | Session metadata with timestamps |\n| `ar_messages` | Conversation messages with JSONB tool calls |\n| `ar_context_entries` | Shared context entries between agents |\n| `ar_invocation_logs` | Full invocation logs with token usage |\n| `ar_schema_version` | Migration version tracking |\n\n**Indexes** are created on session_id, agent_id, and timestamp columns for efficient querying.\n\n## Performance Notes\n\n- **JSONB storage** for agent definitions and tool calls — supports efficient querying and indexing\n- **Connection pooling** via `pg.Pool` — configure `max` connections based on your workload\n- **Transaction safety** — session message appends and deletes use transactions with rollback\n- **Async migrations** — schema migrations run automatically on first use, not on construction\n- **Shared pools** — pass an existing `pg.Pool` to avoid creating duplicate connections\n\n### Recommended Production Settings\n\n```typescript\nimport pg from \"pg\";\n\nconst pool = new pg.Pool({\n  connectionString: process.env.DATABASE_URL,\n  max: 20,                    // Max connections\n  idleTimeoutMillis: 30000,   // Close idle connections after 30s\n  connectionTimeoutMillis: 5000, // Fail fast on connection issues\n  ssl: process.env.NODE_ENV === \"production\"\n    ? { rejectUnauthorized: true }\n    : false,\n});\n\nconst store = new PostgresStore({ connection: pool });\n```\n\n## PostgreSQL Setup\n\nIf you need to create a database:\n\n```sql\nCREATE DATABASE mydb;\nCREATE USER myuser WITH PASSWORD 'mypassword';\nGRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;\n```\n\nOr with Docker:\n\n```bash\ndocker run -d \\\n  --name agent-runner-pg \\\n  -e POSTGRES_DB=mydb \\\n  -e POSTGRES_USER=myuser \\\n  -e POSTGRES_PASSWORD=mypassword \\\n  -p 5432:5432 \\\n  postgres:16\n```\n\n## Graceful Shutdown\n\n```typescript\nprocess.on(\"SIGTERM\", async () => {\n  await runner.shutdown();  // Cleans up MCP connections\n  await store.close();      // Closes the pg pool (if store-owned)\n  process.exit(0);\n});\n```\n\n## Examples\n\n### Split Stores\n\nUse PostgreSQL for agents and logs, but a different store for sessions:\n\n```typescript\nimport { createRunner, MemoryStore } from \"@agent-runner/core\";\nimport { PostgresStore } from \"@agent-runner/store-postgres\";\n\nconst pgStore = new PostgresStore(process.env.DATABASE_URL!);\n\nconst runner = createRunner({\n  agentStore: pgStore,\n  logStore: pgStore,\n  sessionStore: new MemoryStore(), // ephemeral sessions\n  contextStore: pgStore,\n});\n```\n\n### With Studio\n\n```typescript\nimport { createRunner } from \"@agent-runner/core\";\nimport { PostgresStore } from \"@agent-runner/store-postgres\";\nimport { createStudio } from \"@agent-runner/studio\";\n\nconst runner = createRunner({\n  store: new PostgresStore(process.env.DATABASE_URL!),\n});\n\n// Studio reads/writes through the same Postgres store\nconst studio = await createStudio(runner, { port: 4000 });\n```\n\n## Related Packages\n\n| Package | Description |\n|---|---|\n| [`@agent-runner/core`](../core) | Core SDK — createRunner, agents, tools, stores |\n| [`@agent-runner/store-sqlite`](../store-sqlite) | SQLite adapter for single-server deployments |\n| [`@agent-runner/studio`](../studio) | Development UI |\n\n## Contributing\n\nSee the main [CONTRIBUTING.md](https://github.com/aparry3/agent-runner/blob/main/CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [Aaron Bidworthy](https://github.com/aparry3)\n","readmeFilename":"README.md"}