Build a Database App

This walkthrough creates a Database App for customer records, registers its fields, and opens those records in Data Viewer.

Before you begin

You need an authenticated CLI and access to manage Apps in the destination Room. Include --scope-workspace <workspace_id> and --scope-room <room_id> when running as a signed-in person; see Authentication. You can also ask an Agent in that Room to follow these steps. This example uses a customer ID, name, and status. Database Apps can be private to the Room or shared with the workspace; public access requires a Custom App.

Agree on the shape of the data before creating anything: what the records are, their fields and relationships, who creates and edits them, and whether the standard record views are enough. If you need a custom interface or App-owned logic, create a Custom App instead (app create --runtime-kind custom_app).

1. Create the App

kylon workspace app create --name "Customer Manager" --provider-project-name customer-manager

Without --runtime-kind, this creates a Database App: no source repository, draft, or deployment. The command prints the App id used below. Add --pin only if you want a personal sidebar shortcut.

2. Provision the database and define the schema

Create the database, then its customer table:

kylon workspace app db provision <app_id>
kylon workspace app db query <app_id> --sql "CREATE TABLE customers (id VARCHAR(64) PRIMARY KEY, name VARCHAR(255) NOT NULL, status VARCHAR(32))"

Use --sql-file for longer scripts and one multi-row INSERT for seed data rather than a command per row. Table and column names use lower-case snake_case.

3. Register the records

Registration connects the database table to Data Viewer. Export a scaffold to app-registration.json:

kylon workspace app registration template <app_id> --output app-registration.json

For this new App, replace the scaffold with the following document and substitute the actual App ID in manifest.app.id:

{
  "runtime_kind": "database_app",
  "manifest": {
    "schema_version": "kylon.app_manifest.v1",
    "app": { "id": "<app_id>", "name": "Customer Manager", "version": "1.0.0" },
    "data": {
      "entities": [{
        "id": "customers",
        "label": "Customers",
        "record_id_field": "id",
        "title_field": "name",
        "fields": [
          { "id": "id", "label": "ID", "type": "text", "system": true },
          { "id": "name", "label": "Name", "type": "text", "required": true },
          { "id": "status", "label": "Status", "type": "text" }
        ]
      }]
    }
  },
  "data_model": {
    "schema_version": "kylon.app_data_model.v1",
    "entities": [{
      "id": "customers",
      "table": "customers",
      "id_column": "id",
      "fields": [
        { "id": "id", "column": "id" },
        { "id": "name", "column": "name" },
        { "id": "status", "column": "status" }
      ]
    }]
  }
}

Validate it, save it, and inspect the setup:

kylon workspace app register <app_id> --file app-registration.json --check
kylon workspace app register <app_id> --file app-registration.json
kylon workspace app registration status <app_id>

--check validates without saving. For an existing App, edit its exported registration rather than replacing it with this new-App example: registration replaces the full document. registration status reports the saved setup, not a live connectivity test. Use app db check <app_id> when investigating database connectivity; its output may include a sensitive connection URI.

4. Operate the App

Open the App from its Room. Data Viewer should show Customers with Name and Status fields. Add a customer such as “Acme” with status “active”. To work through the CLI, read the generated contract first:

kylon workspace app docs <app_id>

Use the method, path, and request body shown there. Save the required create body as record.json before running the POST example:

kylon workspace app api get <app_id> <api_path>
kylon workspace app api post <app_id> <api_path> --body-file record.json

People see the same records in Data Viewer. Shared view settings such as filters, sorting, and grouping are managed with app data-view:

kylon workspace app data-view list <app_id> --entity <entity_id>

For the registration above, the entity ID is customers and the status field ID is status. Create a saved view:

kylon workspace app data-view create <app_id> \
  --entity customers \
  --name "Active customers" \
  --view-type table \
  --config '{"filters":[{"field_id":"status","operator":"eq","value":"active"}]}'

Use app data-view update-default for the shared default view. Configuration uses snake_case keys such as field_id, group_by, and visible_field_ids. A view filters what is displayed; it does not prevent other App users from reading the records.

5. Review access

Check app show <app_id> and review the visibility before adding sensitive data. Workspace visibility admits every workspace member and Agent to the App’s exposed records. The home Room still controls management. An Agent widening visibility presents a human approval request. If you later need custom screens, business APIs, or public access, build a Custom App on this App rather than copying its records into a separate system.

Already have a legacy Table?

Upgrade it instead of rebuilding it. See Legacy Tables.

Automate on App record changes to start a run whenever a record is inserted or updated.

Getting Started

Concepts

Agents

Tutorials

CLI

Connections

Proxy

Build a Database App

Before you begin

1. Create the App

2. Provision the database and define the schema

3. Register the records

4. Operate the App

5. Review access

Already have a legacy Table?

Next

​Before you begin

​1. Create the App

​2. Provision the database and define the schema

​3. Register the records

​4. Operate the App

​5. Review access

​Already have a legacy Table?

​Next

Before you begin

1. Create the App

2. Provision the database and define the schema

3. Register the records

4. Operate the App

5. Review access

Already have a legacy Table?

Next