Orkestia
Proud to collaborate with Microsoft for Startups
Sign in

Neon Postgres, connected once

Connect a Neon project to Orkestia. Queries and lifecycle stay workflows, with the same identity as the rest of the catalog.

Orkestia2 min readUpdated

Orkestia is the backbone that connects software, AI, and the real world. Neon is serverless Postgres you may already run. This post is the connection: one API key, then projects, branches, roles, databases, and queries as typed workflows.

AppData is a different store. It is where an Orkestia app keeps records that belong to the app. Neon is the Postgres account you already have. Connect Neon when the database is yours. Use AppData when the record belongs to the app on Orkestia. AppData: records that belong to the app.

Connect

Create a Neon API key in the Neon console. In Orkestia, add a connection with that key. Orkestia calls Neon's console API as Bearer. The provider tests the key and reports the account. Resource work, projects, branches, roles, databases, ad-hoc queries, lives in neon.* workflows, not in the connection test.

The key stays on the connection. It does not go in initial_data.

Create an account, then add Neon from Connections. Types: the catalog.

What you can run

Typical jobs:

  • Provision a project
  • Create a branch per environment
  • Create a role or a database
  • Run a query you declared in the workflow input

Each job is a schema-checked run with an actor and a history. Retry resumes the same id. Browse neon. in the catalog for the live names. Do not trust a remembered type from last month. The catalog is the source of truth.

From MCP

whoami()
list_workflow_types(prefix="neon.")
get_workflow_schema("<type>")
get_workflow_prerequisites("<type>")
start_workflow(workflow_type="<type>", initial_data={...})
watch_workflow(workflow_id)

Start with a read. Branch and role creates are not read_only. Read the schema twice if you need to.

Branch per environment, as a workflow

A common Neon habit is one project and a branch per environment. In Orkestia that is not a click in Neon's UI. It is a run: schema for the create-branch type, connection_uuid, parent branch, name. The run history is how you show someone the branch existed at 14:02 and who started it.

Queries you send through neon.* are also runs. That is slower than a direct psql, and that is the point. The agent does not get a connection string in the chat. It gets a workflow that already has permission.

If you wanted a SQL window over app records instead, that is AppData, not Neon. Keep the two accounts separate in your head and in Connections.

hello@orkestia.dev

  • neon
  • data
  • connections