start here

start using PostgreSQL with your agents

sign up, open a project, and add PostgreSQL to its setup script in settings → server.

Start 7-day trial with PostgreSQL
integrationstechnologyupdated
schematic diagram of the work aldena agents do through PostgreSQL
PostgreSQL

postgresql ai agent: a real database in each conversation's own sandbox

add postgresql to a project's setup script and its agents run psql, apply migrations, seed data, and run the test suite against a database that project owns alone.

runs on
conversation sandbox
installed by
setup script
category
datastore

a database is the usual reason an agent cannot finish a task. it can write the migration but not apply it, or write the query but not run it. installing postgresql in each conversation's sandbox removes that gap: the database runs on the same machine as the checkout.

what agents do with it

once the setup script has run, psql and a running postgresql service are in the conversation's sandbox. agents apply the app's migrations, seed fixtures, run the test suite against a live database, and inspect the result with psql rather than reasoning about what the schema probably looks like. a query that returns the wrong rows is something they can see and iterate on.

the shape of the isolation

the database belongs to one project. two projects never share a filesystem or a server, so a destructive migration in one cannot reach another client's data, and a schema pinned for one engagement does not have to match anyone else's. that is the same boundary that holds for credentials and connected accounts.

example tasks

  • 01

    write the migration for the new column and prove it applies cleanly.

    the agent writes the migration, applies it against the project's database, checks the schema with psql, and rolls it back and forward again before showing you the diff.

    writebashread
  • 02

    this query is slow. find out why.

    it seeds representative data in the conversation's sandbox, runs explain analyze against the real planner, and reports the plan rather than an opinion about indexes.

    bashgrepedit

what to know before installing

the project needs a sandbox, and a database plus an application is the case where the standard size or larger earns its place. settings → server shows the setup script's last run with its exit code and output, so a failed install surfaces its error.

how to install PostgreSQL

PostgreSQL goes in the project's setup script, not once per team and not on your laptop.

  1. give the project a sandbox

    PostgreSQL runs in each conversation's sandbox, on your team's own sandbox provider account. an owner or admin connects a provider once on the team's providers page, then picks it and a default size for the project, at creation or later in settings → server. a project with no sandbox has nowhere to run it.

  2. add it to the setup script

    settings → server holds the project's setup script, a bash script that runs once on each new sandbox, in /project, with sudo. add PostgreSQL's install commands there and save.

  3. the next sandbox runs it

    the script runs when a conversation's sandbox is created or reused, on the conversation's first turn. settings shows the last run with its exit code and output, and a failed run leaves the sandbox usable rather than blocking the project.

  4. agents use it through bash

    from then on every agent in the project reaches PostgreSQL with the bash tool, on the same filesystem as the checkout they are working in. the conversation's sandbox keeps it between turns, sleeping when idle and waking with the next one.

where PostgreSQL actually lives

each conversation in a project gets its own sandbox on your team's sandbox provider account, and the project's setup script in settings → server decides what is on it. two projects never share a filesystem, so a version pinned for one client cannot collide with another's.

the sandbox provider bills its machine time to your team's account while it runs, and aldena adds nothing. the sizes are on isolated projects, and what agents may run in the sandbox is governed by the project's tool permissions.

faq

is this my production database?

no, and that is the point. installing postgresql puts a server in each conversation's own sandbox, so agents run migrations and tests against a database nobody else depends on. your production database stays where it is and is never reachable from the project unless you put a credential there yourself.

what should the setup script do for postgresql?

add the postgresql apt repository, install the server package, and enable the service so it comes back up when the sandbox wakes. end with psql --version, and settings → server shows exactly what landed in the last run's output.

can an agent run migrations against it?

yes. the database listens in the conversation's own sandbox, so an agent runs the app's migration command through the bash tool, checks the schema with psql, and reruns the suite. nothing about that touches another project.

does the data survive between sessions?

only within a conversation. each conversation's sandbox keeps its files between turns, sleeping when idle and waking with the next one, so a seeded database is still seeded tomorrow. a new conversation gets its own sandbox, and the setup script runs on it again. a conversation left quiet for 7 days gives its sandbox back, and its next turn starts fresh.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.