Manage Data Store

Create and evolve the tables, columns, indexes, and views of a structured knowledge base

What it does

manage_data_store lets an agent shape the schema of a data store (a structured knowledge base): create tables, add or alter columns, add indexes, create views, and inspect the current schema. Changes apply to the store’s own isolated Postgres database.

• create_store creates a brand-new data store (name + optional description) — no knowledge_base_id needed. Use it when work deserves its own store rather than adding unrelated tables to an existing one. Creation only: delete a store in Control Hub. To rename it or change its description, use manage_knowledge_bases update.

For an overview of structured data stores — what they are and when to use one — see Data Stores.

Parameters

Parameter	Type	Required	Description
knowledge_base_id	integer	Yes	The structured knowledge base to modify
action	string	Yes	One of create_store, create_table, add_column, alter_column, rename_table, rename_column, create_index, drop_index, add_constraint, drop_constraint, create_view, drop_column, drop_table, drop_view, describe
table	string	For most ops	Table (or view) name — lowercase snake_case
columns	array	create_table, add_column	Column definitions (name, type, nullable, default, primary_key, auto_id)
column	string	alter_column, drop_column, rename_column	Target column
new_type	string	alter_column	New column type
new_default	any	alter_column	New default value; null removes it
nullable	boolean	alter_column	false makes the column required, true makes it optional
auto_id	object	alter_column	Give an existing column database-assigned IDs (see below)
new_name	string	rename_table, rename_column	New name. Renaming preserves the primary key, unique constraints and indexes — unlike dropping and recreating
index_columns	array	create_index	Columns to index
unique	boolean	No	Make a create_index unique
where	string	No	Limit a create_index to some rows, e.g. is_deleted = false
name	string	Some ops	Optional name for create_index and add_constraint; the name to remove for drop_index and drop_constraint
constraint	object	add_constraint	The rule to add (see below)
view_sql	string	create_view	A full SELECT computed server-side (joins, aggregates, window functions, CTEs)
confirm	boolean	For drops	Required true for every drop_* action

Key behaviors

• A primary key is added for you. create_table adds an id primary key automatically unless you define your own.
• Views give apps aggregation power. create_view stores an agent-authored SELECT that apps read like a table — the way to let an app show a rollup or join over a large table without pulling every row. Views run with the reading role’s privileges, so they stay safely scoped to the store.
• Rules hold for every writer. A rule added with add_constraint or a unique index is enforced by the database itself, so it applies to agents, apps, and people editing rows alike, not just to the agent that set it up.
• Rules check existing rows first. If rows already break a new rule, the call fails and says how many and which. Fix those rows, or pass not_valid: true to enforce the rule on new and changed rows only.
• Destructive changes are gated. Every drop_* action requires confirm: true, because a published app may depend on what it removes.
• Locked stores refuse structure changes. If the store’s creator has locked it, every operation except describe fails unless the requesting user is its creator or an org admin. Rows stay writable through write_data_store. manage_knowledge_bases list shows locked and canEdit for locked stores.
• Every change is audited, and the store’s cached schema — which the agent sees in its context — refreshes automatically after each change.

Common use cases

Create a table

operation: create_table
knowledge_base_id: 954
table: project_stages
columns:
  - { name: stage_name, type: text, nullable: false }
  - { name: status, type: text, nullable: false }
  - { name: sort_order, type: integer, nullable: false }

Number records automatically (TAR-0001, TAR-0002, …)

action: create_table
knowledge_base_id: 954
table: thesis
columns:
  - { name: thesis_id, type: text, primary_key: true, auto_id: { prefix: "TAR-", pad: 4 } }
  - { name: title, type: text, nullable: false }

The database assigns the next number on every insert, so two writers can’t take the same one. pad is a minimum: after TAR-9999 comes TAR-10000. Use auto_id: {} for plain numbers. To switch an existing column over, call alter_column with auto_id; numbering continues after the highest ID already in the column.

Require every row to point at a real record

action: add_constraint
knowledge_base_id: 954
table: deal
constraint:
  type: foreign_key
  columns: [company_id]
  references: { table: company, columns: [company_id] }

The referenced columns must be the other table’s primary key or have a unique index. Add on_delete: cascade or on_delete: set null to choose what happens to deals when their company is deleted. By default, the delete is refused.

Limit a column to a set of values or a range

action: add_constraint
knowledge_base_id: 954
table: deal
constraint: { type: check, columns: [status], allowed_values: [Active, Passed, Closed] }

Use min and max for ranges, such as { type: check, columns: [ownership_pct], min: 0, max: 1 }.

Allow only one primary contact per company

action: create_index
knowledge_base_id: 954
table: company_role
index_columns: [company_id]
unique: true
where: is_primary

Create a view for an app to chart

operation: create_view
knowledge_base_id: 954
table: stage_summary
view_sql: SELECT status, count(*) AS n FROM project_stages GROUP BY status

Related

• Query Data Store — read data with SQL
• Write Data Store — insert, update, delete, upsert
• Data Stores — the feature overview