Data API Builder (DAB) CLI

This skill powers GitHub Copilot assistance for the Data API Builder (DAB) CLI tool. It provides conversational guidance for creating, configuring, validating, and running DAB projects that expose database objects as REST, GraphQL, and MCP endpoints.

Core Mental Model

DAB is driven by a JSON config file (typically dab-config.json) containing:

• •data-source: Database connection settings (type, connection string, provider options)
• •runtime: Endpoint configuration (REST/GraphQL/MCP paths, auth, CORS, host mode)
• •entities: Exposed tables/views/stored procedures with permissions, relationships, mappings, and policies

Recommended Workflow

1. •dab init — Create baseline config
2. •dab add — Add entities (tables/views/stored procedures)
3. •dab update — Evolve entities (permissions, relationships, mappings, policies)
4. •dab configure — Tune runtime and data-source settings
5. •dab validate — Preflight validation checks
6. •dab start — Run the DAB engine

Security Default

Always prefer environment variables for connection strings:

• •Use @env('ENV_VAR_NAME') in config/CLI arguments
• •Ask user before inlining secrets

Command Reference

1. dab init — Initialize Configuration

Purpose: Create a new DAB configuration file. This is typically the first step in a project.

Syntax:

dab init [options]

Critical Behavior:

• •Overwrites existing config files without merging
• •Recommend git usage or backups before running

Must Collect (ask if missing):

• •--database-type (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql)
• •--connection-string (direct value or @env('VAR_NAME'))

Common Options:

Important: Don't mix --*.enabled flags with legacy --*.disabled flags for the same subsystem.

Examples:

# Minimal (recommended, env var)
dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')"

# REST-only
dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --rest.enabled true \
  --graphql.enabled false

# MCP-only (agent scenarios)
dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --rest.enabled false \
  --graphql.enabled false \
  --mcp.enabled true \
  --mcp.path "/mcp"

# Production with auth
dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --host-mode production \
  --auth.provider AzureAD \
  --auth.issuer "https://login.microsoftonline.com/{tenant-id}/v2.0" \
  --auth.audience "https://example.com/api" \
  --cors-origin "https://app.example.com"

What to Say Next: "Config created! Next, add entities with dab add, then validate with dab validate."

2. dab add — Add Entity

Purpose: Add a new entity (table/view/stored procedure) to an existing config.

Syntax:

dab add <entity-name> [options]

Must Collect (ask if missing):

• •<entity-name> (logical API name, case-sensitive)
• •--source, -s (database object name, including schema)
• •--permissions, -p (at least one "role:actions" pair)

Source Types & Requirements:

Permission Model:

Actions:

• •Tables/Views: create, read, update, delete, *
• •Stored Procedures: execute, *

Common Options:

Examples:

# Add a table (anonymous read)
dab add Product \
  --source dbo.Products \
  --source.type table \
  --permissions "anonymous:read"

# Add a view (requires key fields)
dab add ProductSummary \
  --source dbo.vw_ProductSummary \
  --source.type view \
  --source.key-fields "ProductId,Region" \
  --permissions "anonymous:read"

# Add a stored procedure (execute)
dab add GetProductsByCategory \
  --source dbo.usp_GetProductsByCategory \
  --source.type stored-procedure \
  --permissions "anonymous:execute" \
  --graphql.operation query \
  --rest.methods GET,POST

# Add with field mappings and descriptions (v1.7+)
dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --fields.name "ProductID,ProductName,UnitPrice" \
  --fields.alias "product_id,product_name,price" \
  --fields.description "Unique identifier,Product display name,Unit price in USD" \
  --fields.primary-key "true,false,false"

# Add stored procedure with parameter metadata (v1.7+)
dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves orders within a date range" \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Start of range (inclusive),End of range (inclusive),Optional customer filter" \
  --parameters.required "true,true,false" \
  --parameters.default ",,null"

Common Mistake: --permissions is not repeatable in dab add. To add multiple roles:

1. •Add entity with one role in dab add
2. •Add additional roles with dab update

What to Say Next: "Entity added! Add more entities, or run dab validate to check the config."

3. dab update — Modify Entity

Purpose: Modify an existing entity's properties (permissions, relationships, mappings, policies, REST/GraphQL exposure, caching).

Syntax:

dab update <entity-name> [options]

Critical Behaviors:

• •Entity must already exist (case-sensitive match)
• •--permissions updates or adds the specified role
• •--map replaces entire mapping set (not additive)
• •--fields.include/--fields.exclude replace existing field lists

Option Groups:

Source

Permissions & Policies

Fields & Mappings

REST

GraphQL

Relationships

Relationships define how entities are connected (one-to-one, one-to-many, many-to-one, many-to-many).

Relationship Types:

• •One-to-one: cardinality: "one" (e.g., User → Profile)
• •One-to-many: cardinality: "many" (e.g., Category → Products)
• •Many-to-one: cardinality: "one" (e.g., Product → Category)
• •Many-to-many: cardinality: "many" with linking.object (e.g., Students ↔ Courses)

Cache

Parameters (Stored Procedures)

Other

Examples:

# Add/replace permissions for a role
dab update Product --permissions "admin:*"
dab update Product --permissions "authenticated:read,update"

# Add field mappings (replaces all existing mappings!)
dab update Product \
  --map "ProductName:name,UnitPrice:price,UnitsInStock:stock"

# Exclude sensitive fields
dab update User \
  --fields.exclude "PasswordHash,SecurityStamp,TwoFactorSecret"

# Change REST path
dab update Product --rest "products"

# Disable GraphQL for entity
dab update InternalData --graphql false

# Enable caching
dab update Product --cache.enabled true --cache.ttl 300

# One-to-many relationship: Category has many Products
dab update Category \
  --relationship "products" \
  --cardinality many \
  --target.entity Product \
  --relationship.fields "CategoryId:CategoryId"

# Many-to-many: Student to Course via Enrollments
dab update Student \
  --relationship "courses" \
  --cardinality many \
  --target.entity Course \
  --linking.object "dbo.Enrollments" \
  --linking.source.fields "StudentId" \
  --linking.target.fields "CourseId"

# Self-referencing: Employee has a Manager
dab update Employee \
  --relationship "manager" \
  --cardinality one \
  --target.entity Employee \
  --relationship.fields "ManagerId:EmployeeId"

# Row-level security: users can only read their own orders
dab update Order \
  --permissions "authenticated:read" \
  --policy-database "@item.UserId eq @claims.userId"

# Request policy: validate payload
dab update Order \
  --permissions "authenticated:create" \
  --policy-request "@item.Quantity gt 0 and @item.Quantity lt 100"

Common Mistakes:

• •Entity name mismatch (case-sensitive)
• •Incomplete relationship (missing --cardinality or --target.entity)
• •Wrong policy syntax (use OData-style expressions, not SQL)
• •Using --map without restating all desired mappings

What to Say Next: "Entity updated! Run dab validate to check the changes."

4. dab configure — Update Runtime/Data-Source

Purpose: Modify runtime and data-source properties that are not entity-specific.

Syntax:

dab configure [options]

Key Behaviors:

• •Does not change entities (use dab update for that)
• •Modifies global config: data-source, runtime endpoints, auth, host settings

When to Use:

• •Update database connection settings
• •Toggle/adjust REST/GraphQL/MCP runtime endpoints
• •Configure authentication provider
• •Set CORS origins
• •Change host mode

What to Ask:

1. •Which config file?
2. •What to change?
   • •Data-source (database type, connection string)
   • •Runtime (REST/GraphQL/MCP paths, auth, host mode, CORS)

Best Practice: Use small, focused dab configure commands to isolate failures.

Example Use Cases:

# Update connection string
dab configure --connection-string "@env('NEW_CONNECTION_STRING')"

# Enable MCP endpoint
dab configure --mcp.enabled true --mcp.path "/mcp"

# Add CORS origins
dab configure --cors-origin "https://app.example.com,https://admin.example.com"

# Switch to development mode
dab configure --host-mode development

What to Say Next: "Configuration updated! Run dab validate to verify changes."

5. dab validate — Validate Configuration

Purpose: Check DAB config for errors before starting the engine.

Syntax:

dab validate [--config <path>]

Options:

Validation Stages:

1. •Schema validation — JSON structure and schema compliance
2. •Config properties — Logical consistency of settings
3. •Permissions — Role/action/policy correctness
4. •Database connection — Connectivity and env var resolution
5. •Entity metadata — Database objects/columns/params/relationships exist

Exit Codes:

• •0 — Valid
• •Non-zero — Invalid

Best Practices:

# Validate after every change
dab add Product --source dbo.Products --permissions "anonymous:read"
dab validate

# Validate before starting
dab validate && dab start

# CI/CD validation
dab validate --config dab-config.production.json

On Validation Failure:

1. •Ask user for the first error from output
2. •Identify the failing stage (schema, permissions, connectivity, etc.)
3. •Suggest targeted fix using dab update or dab configure
4. •Re-validate

What to Say Next: "Validation passed! Start the engine with dab start."

6. dab start — Start Runtime

Purpose: Start the DAB engine and expose configured endpoints.

Syntax:

dab start [options]

Options:

Prerequisites (check before starting):

1. •DAB CLI installed
2. •Config file exists
3. •Environment variables set (if using @env())
4. •Config validated (dab validate)

Success Indicators:

• •Logs show "Now listening on: http://localhost:5000" (or similar)
• •Runtime stays running until Ctrl+C

Examples:

# Start with default config
dab start

# Start with specific config
dab start --config dab-config.production.json

# Start with verbose logging
dab start --verbose

# Start with debug logging
dab start --LogLevel Debug

Important: DAB does not hot-reload config. Restart the runtime to apply changes.

What to Say Next: "DAB is running! Access endpoints at the displayed URL."

Conversational Decision Trees

User says: "init" or "create config"

Ask:

1. •Database type? (mssql, postgresql, mysql, cosmosdb_nosql, cosmosdb_postgresql)
2. •Config file name? (default: dab-config.json)
3. •Connection string inline or via @env()? (recommend @env())
4. •Which endpoints? (REST, GraphQL, MCP — defaults to all enabled)
5. •Host mode? (development or production)
6. •Auth provider? (optional: AzureAD, etc.)

Offer template:

dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --host-mode development

User says: "add entity" or "add table/view/stored procedure"

Ask:

1. •Entity name? (logical API name)
2. •Source object? (include schema, e.g., dbo.Products)
3. •Source type? (table, view, stored-procedure)
4. •Key fields? (required for views)
5. •Permissions? (at least one role:actions pair)
6. •REST/GraphQL exposure? (enable/disable, custom naming)

Offer templates:

# Table
dab add Product \
  --source dbo.Products \
  --permissions "anonymous:read"

# View
dab add ProductSummary \
  --source dbo.vw_ProductSummary \
  --source.type view \
  --source.key-fields "ProductId" \
  --permissions "anonymous:read"

# Stored procedure
dab add GetProducts \
  --source dbo.usp_GetProducts \
  --source.type stored-procedure \
  --permissions "anonymous:execute" \
  --graphql.operation query

User says: "change entity" or "update entity"

Ask:

1. •Which entity?
2. •What to change?
   • •Permissions (add/update role)
   • •Relationships (define/update)
   • •Mappings (rename fields)
   • •Policies (row-level security)
   • •REST/GraphQL exposure
   • •Caching
   • •Field inclusion/exclusion

Offer targeted commands based on answer.

User says: "add relationship" or "connect entities"

Ask:

1. •Source entity name?
2. •Target entity name?
3. •Relationship name? (how it appears in API, e.g., "products", "category", "courses")
4. •Relationship type?
   • •One-to-many: Parent has many children (e.g., Category → Products)
   • •Many-to-one: Child belongs to parent (e.g., Product → Category)
   • •One-to-one: Single record to single record (e.g., User → Profile)
   • •Many-to-many: Requires join table (e.g., Students ↔ Courses)
5. •Which fields connect them? (foreign key to primary key)
6. •For many-to-many: What's the join table name?

Offer templates:

# One-to-many: Category has many Products
dab update Category \
  --relationship "products" \
  --cardinality many \
  --target.entity Product \
  --relationship.fields "CategoryId:CategoryId"

# Many-to-one: Product belongs to Category
dab update Product \
  --relationship "category" \
  --cardinality one \
  --target.entity Category \
  --relationship.fields "CategoryId:CategoryId"

# Many-to-many: Student has many Courses
dab update Student \
  --relationship "courses" \
  --cardinality many \
  --target.entity Course \
  --linking.object "dbo.Enrollments" \
  --linking.source.fields "StudentId" \
  --linking.target.fields "CourseId"

# Self-referencing: Employee has a Manager
dab update Employee \
  --relationship "manager" \
  --cardinality one \
  --target.entity Employee \
  --relationship.fields "ManagerId:EmployeeId"

User says: "configure" or "change runtime"

Ask:

1. •Which config file?
2. •What to change?
   • •Database connection
   • •REST/GraphQL/MCP settings
   • •Auth provider
   • •CORS origins
   • •Host mode

Confirm it's not an entity change (use dab update for that).

User says: "validate" or "check config"

Ask:

1. •Which config file? (default: dab-config.json)
2. •Are required env vars set?

If validation fails:

1. •Ask for first error from output
2. •Identify stage (schema, permissions, connectivity, etc.)
3. •Suggest fix

User says: "start" or "run"

Ask:

1. •Which config file?
2. •Are env vars set?
3. •Has config been validated?

Offer:

dab validate && dab start

Quick Reference Templates

New Project

# 1. Create config
dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --host-mode development

# 2. Add entity
dab add Product \
  --source dbo.Products \
  --permissions "anonymous:read"

# 3. Validate and start
dab validate && dab start

Common Patterns

Add Table with Multiple Roles

dab add Product --source dbo.Products --permissions "anonymous:read"
dab update Product --permissions "authenticated:*"
dab update Product --permissions "admin:*"

One-to-Many Relationship (Parent → Children)

# Category has many Products
dab update Category \
  --relationship "products" \
  --cardinality many \
  --target.entity Product \
  --relationship.fields "CategoryId:CategoryId"

# Effect: Category API responses include nested "products" array
# GraphQL: category { products { productId name } }
# REST: GET /api/Category/1?$expand=products

Many-to-One Relationship (Child → Parent)

# Product belongs to Category
dab update Product \
  --relationship "category" \
  --cardinality one \
  --target.entity Category \
  --relationship.fields "CategoryId:CategoryId"

# Effect: Product API responses include nested "category" object
# GraphQL: product { category { categoryId name } }
# REST: GET /api/Product/1?$expand=category

Bidirectional Relationships (Both Directions)

# Add both relationships for full navigation
dab update Category \
  --relationship "products" \
  --cardinality many \
  --target.entity Product \
  --relationship.fields "CategoryId:CategoryId"

dab update Product \
  --relationship "category" \
  --cardinality one \
  --target.entity Category \
  --relationship.fields "CategoryId:CategoryId"

Many-to-Many Relationship (via Join Table)

# Student has many Courses through Enrollments
dab update Student \
  --relationship "courses" \
  --cardinality many \
  --target.entity Course \
  --linking.object "dbo.Enrollments" \
  --linking.source.fields "StudentId" \
  --linking.target.fields "CourseId"

# Course has many Students through Enrollments
dab update Course \
  --relationship "students" \
  --cardinality many \
  --target.entity Student \
  --linking.object "dbo.Enrollments" \
  --linking.source.fields "CourseId" \
  --linking.target.fields "StudentId"

# Effect: Both sides can navigate through junction table
# GraphQL: student { courses { courseId name } }
# GraphQL: course { students { studentId name } }

Self-Referencing Relationship (Hierarchy)

# Employee has a Manager (also an Employee)
dab update Employee \
  --relationship "manager" \
  --cardinality one \
  --target.entity Employee \
  --relationship.fields "ManagerId:EmployeeId"

# Employee has many DirectReports
dab update Employee \
  --relationship "directReports" \
  --cardinality many \
  --target.entity Employee \
  --relationship.fields "EmployeeId:ManagerId"

Composite Key Relationship

# OrderItem links to Order via OrderId + LineNumber
dab update OrderItem \
  --relationship "order" \
  --cardinality one \
  --target.entity Order \
  --relationship.fields "OrderId:OrderId,LineNumber:LineNumber"

Row-Level Security

dab update Order \
  --permissions "authenticated:read" \
  --policy-database "@item.UserId eq @claims.userId"

REST-Only Endpoint

dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --rest.enabled true \
  --graphql.enabled false \
  --mcp.enabled false

MCP-Only Endpoint (Agent Scenarios)

dab init \
  --database-type mssql \
  --connection-string "@env('DATABASE_CONNECTION_STRING')" \
  --rest.enabled false \
  --graphql.enabled false \
  --mcp.enabled true

Consistency Rules

1. •Always recommend dab validate before dab start
2. •Use environment variables for connection strings (security)
3. •Require .gitignore with .env, **\bin, and **\obj entries before adding secrets
4. •Azure deployments: build custom Docker image with embedded dab-config.json pushed to ACR — never use Azure Files, storage accounts, or volume mounts
5. •Stored procedures use execute permission, not read
6. •Views require explicit key fields via --source.key-fields
7. •Field mappings (--map) replace all existing mappings (not additive)
8. •Entity changes use dab update, runtime changes use dab configure
9. •Permissions in dab add are not repeatable — add first role in dab add, others in dab update
10. •Policy syntax is OData-style, not SQL (e.g., eq, gt, and, @item, @claims)
11. •Relationships are defined on source entity via dab update (not dab add)
12. •Cardinality many creates array, one creates nested object in API responses
13. •Many-to-many requires junction table specified via --linking.object
14. •Both entities must exist before creating relationships between them

Common Troubleshooting

"Entity doesn't exist"

• •Check entity name (case-sensitive)
• •Verify entity was added with dab add

"Relationship target entity not found"

• •Ensure target entity exists in config
• •Check entity name spelling (case-sensitive)
• •Cannot reference entities in different config files (multi-file limitation)

"Relationship validation failed"

• •Verify field names match actual database columns
• •Check that source and target fields are compatible types
• •For many-to-many: ensure linking table exists
• •Ensure both source and target fields are specified

"Validation failed: connection"

• •Verify environment variable is set
• •Check connection string format
• •Test database connectivity

"Validation failed: permissions"

• •Check role names (match auth provider roles)
• •Verify action names (create, read, update, delete, execute, *)
• •Check policy syntax (OData-style)

"Validation failed: entity metadata"

• •Verify database object exists (table/view/stored procedure)
• •Check schema name (e.g., dbo.TableName)
• •For views: ensure --source.key-fields are specified

"Runtime won't start"

• •Run dab validate first
• •Check port availability
• •Verify environment variables are set

Version-Specific Features

v1.7+ Only (RC/Prerelease)

• •--description (entity and field descriptions)
• •--fields.name, --fields.alias, --fields.description, --fields.primary-key
• •--parameters.name, --parameters.description, --parameters.required, --parameters.default
• •--mcp.enabled, --mcp.path (MCP endpoint support)

To install v1.7 RC:

dotnet tool install microsoft.dataapibuilder --prerelease

References

• •DAB CLI Overview
• •dab init
• •dab add
• •dab update
• •dab configure
• •dab validate
• •dab start
• •DAB Installation