---
name: using-nocodb
description: >
  Use when building, modifying, migrating, verifying, or documenting NocoDB
  bases, tables, fields, relations, views, API automation, admin accounts, or
  internal operations/CRM state. Use for live structured state work, not durable
  narrative memory or canonical documentation.
triggers:
  - "adjust nocodb"
  - "build this in nocodb"
  - "create a base in nocodb"
  - "change the schema in nocodb"
  - "migrate crm to nocodb"
  - "update our nocodb"
---

# Using NocoDB

## When to use
Use for routine record CRUD and structured-state work in an existing NocoDB base:
- read, create, update, or delete records
- look up schema before record work
- maintain CRM or internal-ops records without changing their structure
- document an already-approved schema decision for the target team

For a request to create or alter a base, table, field, relation, view, permission, migration, or cross-base structure, route to Iris and load `managing-nocodb`.

## Core modeling rule
Separate two questions before modeling:
1. **identity unification** — do we need one canonical person/company record?
2. **operational domain separation** — do permissions, audience, and workflow logic require separate surfaces?

If the user says a domain is fundamentally separate — e.g. **investor relationships are not sales relationships** — default to **separate NocoDB bases** instead of forcing a shared master.

Accept duplicate company/person records across those bases when that keeps:
- permissions clean
- operator mental model clear
- workflow logic simple

Do not keep arguing for unified People/Companies once the user has made the domain boundary explicit.

## Data-boundary rule
Keep in NocoDB:
- identity
- owner
- status / stage
- next action / next date
- short descriptive summary
- structured links

Move to GBrain:
- long notes
- relationship interpretation
- meeting nuance
- pass / objection reasoning
- durable narrative context

Move to the KB repo:
- approved schema documentation
- reusable operating policy
- stable runbooks or onboarding docs

Keep in Hindsight:
- short-term working continuity
- recent task residue that helps the next session but should not become shared truth

Do not store secrets or credentials in NocoDB unless the deployment has an explicit credentials registry with access controls.

## Documentation rule
When the user wants schemas documented:
- **one operational base = one document**
- do **not** combine Sales DB and Invest DB into one schema page when they are separate operating surfaces
- for team internal documentation, publish schema pages under the team's internal knowledge path, for example:
  - `internal-knowledge-base/system/schema/<name>`

## Direct API CRUD — all agents
Every agent performs routine NocoDB record work through the self-hosted REST API, using only its own profile's `NOCODB_URL`, `NOCODB_EMAIL`, and `NOCODB_PASSWORD`. NocoDB MCP is not used.

Allowed routine work:
- read, create, update, and delete records in an existing table
- query narrowly by a natural key before a write, to prevent duplicates
- read back the affected record and report the record ID and changed fields

For deletion, bulk updates, or ambiguous targets, establish the exact records/count and obtain explicit scope before the mutation. Never print or copy credentials into chat, Plane, GBrain, or project records.

## Schema and administration routing
Agents other than Iris must not create or alter bases, tables, fields, relations, views, permissions, or cross-base structure. Route those requests to Iris.

Iris uses the separate `managing-nocodb` skill for schema setup and broader administration; it does not replace routine API CRUD guidance here.

## Self-hosted API auth pattern
For this NocoDB deployment, the stable automation pattern is:
1. `POST /api/v1/auth/user/signin` with email + password
2. extract the returned token
3. send it in the `xc-auth` header for subsequent API calls

Do **not** assume bearer auth or `xc-token` for this user-session flow.

## Dedicated admin identity rule
For team NocoDB administration, prefer a dedicated Iris/admin account for schema work, password resets, and registry maintenance.

Do **not** use a human operator's personal NocoDB account for routine admin operations when a dedicated admin account exists.

If a dedicated admin account does not yet exist, bootstrap one first, verify login, and then continue the work under that identity.
See `references/nocodb-admin-account-bootstrap.md`.

## Legacy admin decommission rule
When the user wants an old NocoDB admin account retired and a dedicated Iris/admin account already exists:
1. verify the Iris/admin account can log in and reach the metadata API
2. if the old account is recorded in `ThirdPartyAccounts`, remove that credential row
3. **hard-delete** the legacy account from `nc_users_v2` when the user's intent is permanent removal
4. verify the old login now fails and the Iris/admin login still works

Do not stop at `blocked=true` when the user explicitly asked for deletion.

## Tool retirement / registry cleanup rule
When a tool is being fully retired from team operations and it is tracked in the Internal Ops Access Registry:
- remove the `ThirdPartyTools` row for that tool
- remove related `ThirdPartyAccounts` rows
- remove related `ThirdPartyTokens` rows if any exist
- verify zero matching registry rows remain after the infrastructure teardown

Do not leave retired tools in the registry as historical clutter unless the user explicitly asks to keep an archived record.

## Base creation pattern
Create a base with:
- `POST /api/v2/meta/workspaces/{workspaceId}/bases`
- payload with at least `title`

If you accidentally create duplicate bases while probing payloads, clean them up immediately before continuing.

## Table creation pattern
Create a table with:
- `POST /api/v2/meta/bases/{baseId}/tables`
- include a required `columns` array

Important:
- table creation fails if `columns` is omitted
- use a minimal first column, then add the rest incrementally

## Column creation pattern
Add fields with:
- `POST /api/v2/meta/tables/{tableId}/columns`

Useful field types confirmed in this deployment:
- `SingleLineText`
- `LongText`
- `URL`
- `Email`
- `PhoneNumber`
- `SingleSelect`
- `MultiSelect`
- `Checkbox`
- `Date`
- `DateTime`
- `Number`

## Relation creation pattern
For one-to-many style entity links, the clean pattern is:
- create the **has-many / Links** side once on the parent table
- `POST /api/v2/meta/tables/{tableId}/columns`
- payload shape: `uidt=Links`, `type=hm`, plus `parentId` and `childId`

NocoDB will auto-generate the reverse link on the child side.

Do not create both sides manually unless you confirm the reverse link is missing — otherwise you risk duplicate relations.

## Build order rule
When building a new CRM base:
1. entity tables first
2. round / deal / pipeline tables second
3. engagement / message / update tables third
4. relations after the tables exist
5. views / kanban / review filters after schema is stable

## Verification rule
After making changes:
- list bases and confirm the intended base ids
- if multiple bases share the same title, identify the live one by model/table count instead of trusting the title alone
- list tables in each base
- inspect each table's columns and relations
- verify legacy bases are clearly marked if kept as backup

Do not report the job done until the live base/table counts and relations match the intended schema.

## GBrain coverage rule
When the user asks whether CRM information is represented in GBrain, check the current **entity-brain topology**, not the old evidence hierarchy.

Audit the live entity surface that should exist in GBrain:
- companies / firms
- people
- deals
- partnerships
- investment relations when present
- projects when present

For the standard pattern in this package, the safe default is:
- `SalesCompanies` -> `companies/<slug>`
- `SalesPeople` -> `people/<slug>`
- `Deals` -> `deals/<slug>`
- `Partnerships` -> `partnerships/<slug>`
- investment data -> `investment-relations/<slug>` when that table exists
- project entities -> `projects/<slug>` when that table exists

Populate `gbrain_slug` on every table that has that field, then verify both:
- slug coverage in NocoDB
- file/page existence in GBrain

Do not answer "yes, it's in GBrain" based only on company/person coverage if deal / partnership / project context is still missing.

## Legacy CRM split migration rule
When splitting a legacy combined CRM into separate Sales / Invest bases:
1. build the new bases first
2. migrate the structured rows into the target base
3. create the pipeline kanban views
4. ingest durable narrative business memory into GBrain
5. keep the old combined CRM labelled as a backup until the user says to retire it

Do not stop after just the schema build if the user asked for live migration.

## Kanban creation fallback
If the REST view-creation path is unclear in practice, use the NocoDB metadata tables directly as a fallback for self-hosted admin work.

Confirmed in this deployment:
- `nc_views_v2.type = 4` corresponds to Kanban views
- `nc_kanban_view_v2.fk_grp_col_id` must point at the grouping `SingleSelect` column
- `nc_kanban_view_columns_v2` controls card field visibility

Use this only after the table and grouping column are already in place, and verify the created view in metadata before reporting success.

## References
- See `references/nocodb-api-patterns.md` for concrete request shapes and payload examples.
- See `references/nocodb-sales-invest-split-migration.md` for the split-CRM migration and GBrain-ingestion pattern.
- See `references/nocodb-admin-account-bootstrap.md` for the dedicated-admin creation/elevation flow and the `ThirdPartyAccounts` vs `ThirdPartyTokens` registry split.

## Quality Bar
Before reporting success:
- Did I preserve the user's domain boundaries instead of forcing a unified CRM model?
- Did I verify the live base/table/column/relation state after writes, not just assume API success?
- Did I identify the active base by id or structure when duplicate titles exist?
- Did I keep live state in NocoDB and route durable narrative memory to GBrain when appropriate?
- Did I document schema decisions in the KB repo only when the user asked for reusable docs?
- Did I avoid using a human personal admin account when a dedicated admin identity exists?

## Fallback Behavior
- If NocoDB API auth fails: verify the self-hosted sign-in flow and `xc-auth` header before trying other token styles.
- If a REST metadata path is unclear: inspect existing metadata tables or use the UI only after preserving the intended schema plan.
- If relation/view creation through the API is unreliable: fall back to metadata-table changes only after the tables and grouping columns exist, then verify in NocoDB.
- If the requested change touches production data: take a backup or export first, and report the rollback path.
- If the target base is ambiguous: stop and identify the live base before writing.

## Pitfalls
- Do not default to a combined CRM surface when the user explicitly wants domain separation.
- Do not document multiple distinct bases on one combined schema page.
- Do not assume `xc-token` or bearer auth when `xc-auth` is the working session token path.
- Do not create relation pairs twice; one side may auto-generate the other.
- Do not stop after writing schema docs if the user asked to actually change live NocoDB.