dab-docs-copilot-prompt

# DAB Docs Copilot Prompt Use this skill whenever you add, revise, or audit a `copilot-prompt` section in Data API builder (DAB) documentation. The goal is to produce prompts that let GitHub Copilot in agent mode build complete, runnable samples with minimal user interruption, consistent structure across pages, and enough detail to avoid common implementation failures. Prompts should default to the current VS Code workspace, ask as few questions as possible, and keep the implementing agent working until the sample runs end-to-end. ## When to use Use this skill for requests such as: - Add a **Use GitHub Copilot to recreate this sample** section to a DAB quickstart. - Rewrite an existing `copilot-prompt` block so it can build a complete project. - Make prompt sections consistent across related DAB quickstarts. - Add prompt guidance for DAB CLI, DAB MCP, MCP Inspector, SQL Commander, .NET Aspire, Docker Compose, Azure Container Apps, or Azure-Samples source repository reuse. - Audit prompts for finish-first behavior, cost-first Azure choices, validation coverage, and Microsoft Learn style. Do not use this skill for normal article prose unless the request includes a Copilot prompt or prompt-like instructions. ## Required inputs Before editing a docs `.md` page, confirm the author identity with a low-friction choice instead of forcing the user to retype values. For an existing page: - Read the page frontmatter first. - Treat the existing `author` and `ms.author` values as the default author identity for the edit. - Ask the user to confirm by offering choices such as: - Keep existing: `<author>` / `<ms.author>` - Use a different GitHub username and Microsoft alias - If the user keeps the existing identity, update only `ms.date` unless other frontmatter must change. - If either value is missing, offer values found in peer files as selectable suggestions and allow a custom entry. - Never guess or silently replace `author` or `ms.author`. For a new page: - Inspect peer files in the target folder and offer their `author` / `ms.author` pairs as selectable defaults. - Allow the user to enter a different GitHub username and Microsoft alias. - Do not create the page until the author identity is confirmed. Update the target page's `author`, `ms.author`, and `ms.date` frontmatter whenever you edit the prompt section. Before drafting, identify these inputs from the user request, the active file, peer docs, or the sample repository: - Target documentation file. - Prompt heading text. - Generated sample name and default subfolder name. - Source repository URL when the quickstart is backed by an Azure-Samples repository. - Current VS Code workspace root. Use it as the generated project root unless the user explicitly asks to write somewhere else. - Scenario type: local-only, Azure deployment, or local plus Azure. - Database type or decision point: SQL Server, PostgreSQL, MySQL, Azure SQL, Cosmos DB, or user-selected. - Authentication and authorization model. - Required tools: DAB CLI, Docker Compose, .NET Aspire, MCP Inspector, SQL Commander, Azure CLI, `sqlpackage`, MSAL, or Microsoft Entra app registrations. - Required validation evidence. - Related docs links that should appear in the prompt. If a required implementation variable is missing, make the prompt ask the downstream user for it. Do not leave vague placeholders for decisions that the implementing agent must make. ## Article integration pattern Add prompt sections near the end of the article, after the main sample/use instructions and before **Related content** or **Next step**. Use this structure: `````markdown ## Use GitHub Copilot to recreate this sample Open an empty folder in Visual Studio Code, switch GitHub Copilot to agent mode, and paste this prompt. ````copilot-prompt ... ```` ````` For a general quickstart that is not tied to a named sample, use: ```markdown ## Use GitHub Copilot to recreate this quickstart ``` Use a four-backtick outer fence with the `copilot-prompt` language tag so the prompt can contain nested triple-backtick code fences safely. ## Prompt structure A strong DAB docs prompt uses this sequence. ### 1. Mission statement Start with a direct agent-mode instruction that names the scenario, generated project, current workspace target, default subfolder, and major components. Include these details when relevant: - GitHub Copilot is running in agent mode. - The generated project should be complete and runnable under the current VS Code workspace. - DAB is the only API, GraphQL, and MCP layer over the database. - The project includes REST, GraphQL, MCP, a small web app, validation, and cleanup. - The implementation should be minimal but polished. Example: ```text You are GitHub Copilot running in agent mode. Recreate the Data API builder <scenario> sample as a complete, runnable project in the current VS Code workspace under `<sample-folder>`. Build <components>. DAB is the only API, GraphQL, and MCP layer over SQL. ``` ### 2. Source repository reuse When the quickstart has an Azure-Samples repository, include the source repository URL immediately after the mission statement. Tell the implementing agent to inspect or clone the repository before creating files when internet access is available. The prompt must say to reuse and adapt repository files as closely as possible, especially `web-app/`, `data-api/`, `database/`, `aspire-apphost/`, `mcp-inspector/`, `azure-infra/`, scripts, and README patterns. The goal is to implement the published quickstart, not to invent a different sample. Use this wording as a baseline: ```text Source repository: <repo-url>. If internet access is available, inspect or clone this repository before you create files. Reuse and adapt its files as closely as possible, especially `web-app/`, `data-api/`, `database/`, `aspire-apphost/`, `mcp-inspector/`, `azure-infra/`, scripts, and README patterns. The goal is to implement the published quickstart, not to invent a different sample. If the repository differs from this prompt or the current Data API builder docs, prefer the current docs for product behavior. ``` Known DAB 2.0 quickstart source repositories: - Quickstart 1 SQL authentication: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_anon-api_anon-db_sql_auth` - Quickstart 2 managed identity: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_anon-api_anon-db_entra` - Quickstart 3 Microsoft Entra provider: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_anon-api_entra-db_entra` - Quickstart 4 DAB database policies: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_entra-api_entra-db_entra-api_rls` - Quickstart 5 SQL row-level security: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_entra-api_entra-db_entra-db_rls` - Quickstart 6 On-Behalf-Of flow: `https://github.com/Azure-Samples/dab-2.0-quickstart-web_entra-api_entra-db_entra-obo` If no dedicated source repository exists, say so plainly. Link to the Azure-Samples DAB 2.0 repository list at `https://github.com/orgs/Azure-Samples/repositories?q=dab-2.0`, tell the implementing agent to reuse only matching shared patterns from the closest published sample, and tell it to otherwise implement from the article and current docs. Do not invent a source repository. ### 3. Question-driven plan Make the prompt ask only for values that the implementing agent can't safely infer before it creates files or runs commands. Use bullets because the questions are nonsequential. Do not ask for a root folder or project folder name; use the current VS Code workspace and the prompt's default subfolder unless the user explicitly asks to write somewhere else. Common questions: - Which database engine should Docker run: SQL Server, PostgreSQL, or MySQL? - Which Azure subscription, primary region, fallback region, and resource group should Azure deployment use? Default fallback region: `westus2`. - Which Microsoft Entra tenant, app registration name, redirect URI, scope, user, or group should I use? - Should the sample use the default demo schema or a custom schema? - Do you approve creating billable Azure resources if deployment starts? - Do you approve creating app registrations, client secrets, or new permissions if the scenario requires them? Ask only for values that are needed for the scenario and that can't be reasonably defaulted. Do not ask questions that the prompt can reasonably default, including schema choice, host ports, generated password choice, local-only workflow, database browser inclusion, API scope shape, claim mapping, or folder names. Tell the implementing agent to use best-guess defaults and proceed when doing so is safe. ### 4. Approval gate After the answers, require the implementing agent to show a checklist and ask for approval before implementation. Include phases such as: - Local scaffold - Local validation - Azure infrastructure - Azure deployment - Identity or database grants - End-to-end validation - Cleanup For Azure work, preserve approval boundaries: ```text Do not run any Azure command that creates or changes resources until the user explicitly approves the exact command set. ``` For local-only work, don't require a second approval after presenting the checklist. Tell the implementing agent to proceed with local files and local Docker or Aspire validation unless a true blocker appears. ### 5. Finish-first behavior Prompts must tell the implementing agent to finish. Avoid wording that tells the agent to stop for minor, recoverable conditions. Use this guidance for all prompts: ```text After approval, continue working without asking status-check questions. If a command, build, container, endpoint, or validation step fails, inspect the error, adjust the project, rerun the step, and continue. Keep iterating until the sample runs end-to-end or you hit a blocker that requires user action. ``` Use this guidance for Azure regional or service availability issues: ```text Prioritize finishing the project. Treat regional provisioning limits as expected adjustment points, not failures: if the primary region can't provision a required service or free SQL option, use the approved fallback region such as `westus2`, and continue the deployment. Ask the user only when both the primary and fallback regions can't satisfy the requirements, when a change would materially increase cost, when a new permission is required, or when you need approval for Azure commands that create or change resources beyond the already-approved plan. ``` Do not tell the downstream agent to halt for fallback-region issues that it can resolve with an approved fallback region. For configuration inconsistencies, prefer align-and-continue language: ```text If any artifact uses a different key, align the artifacts to the approved mapping and continue. Ask the user only if the intended mapping is ambiguous. ``` Do not report final URLs, asset locations, or success until validation proves the sample works. The implementing agent must directly verify database connectivity and query results, a 2xx DAB health response, and a successful web site response before it gives the developer final URLs or locations. ### 6. Cost-first defaults Every Azure-capable prompt should prefer the cheapest viable option. Include scenario-specific wording: - Use a free Azure SQL database offer when the subscription, region, and scenario support it. - Otherwise choose the lowest-cost SQL option that supports the required feature. - Use Azure Container Apps consumption. - Use minimal CPU and memory. - Use Basic Azure Container Registry. - Use minimal Log Analytics retention. - Avoid always-on or dedicated plans unless required. For local-only prompts, state that local Docker is the default and has no Azure cost. If the user asks for an Azure extension, apply the Azure cost-first guidance. ### 7. Prerequisites Tell the implementing agent to verify prerequisites and report only missing items. Common prerequisites: - .NET SDK - Docker Desktop running - PowerShell - Azure CLI signed in - `sqlpackage` - .NET Aspire tooling - DAB CLI - Node.js, if the web app tooling requires it If a tool is missing, the prompt should tell the implementing agent to install or restore it only after user approval when installation changes the environment. ### 8. Documentation links Inside `copilot-prompt` blocks, include full Microsoft Learn URLs. A developer copies the prompt out of the Learn page, so site-relative links such as `/azure/data-api-builder/command-line/` don't provide enough context. In article prose outside the prompt block, continue to follow the repo convention and use site-relative Learn links. Common prompt-safe DAB links: - DAB CLI reference: `https://learn.microsoft.com/azure/data-api-builder/command-line/` - `dab init`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-init` - `dab add`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-add` - `dab update`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-update` - `dab configure`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-configure` - `dab validate`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-validate` - `dab start`: `https://learn.microsoft.com/azure/data-api-builder/command-line/dab-start` - DAB MCP overview: `https://learn.microsoft.com/azure/data-api-builder/mcp/overview` - DAB configuration: `https://learn.microsoft.com/azure/data-api-builder/configuration/` - Deploy to Azure Container Apps: `https://learn.microsoft.com/azure/data-api-builder/deployment/azure-container-apps` ### 9. Generated project structure Require a predictable folder layout so samples look consistent. For local plus Azure SQL quickstarts, create this structure under the current VS Code workspace in the default sample subfolder: ```text - `azure-infra/` for Bicep, deployment scripts, cleanup scripts, and post-provision scripts. - `data-api/` for `dab-config.json` and a DAB Dockerfile that bakes the config into the image for Azure. - `database/` for a SQL Database Project or idempotent SQL scripts with seed data. - `web-app/` for static HTML, CSS, and JavaScript. - `aspire-apphost/` for the .NET Aspire AppHost. - `mcp-inspector/` for MCP Inspector notes or container assets. ``` For Docker-only quickstarts, create this structure under the current VS Code workspace in the default sample subfolder: ```text - `docker-compose.yml` for the selected database, DAB, MCP Inspector, and the web app. - `.env` for local passwords and connection strings. - `.gitignore` with `.env`, `**/bin`, and `**/obj`. - `database/` for selected-engine initialization scripts. - `data-api/dab-config.json` for DAB configuration. - `web-app/` for static HTML, CSS, and JavaScript. - `mcp-inspector/README.md` with the auto-connect URL. - `README.md` with run, validation, troubleshooting, and cleanup steps. ``` ### 10. Secrets-first handling Include secret hygiene early in the prompt: ```text Handle secrets first. Add `.env`, `**/bin`, and `**/obj` to `.gitignore` before writing secrets. Never print secret values. Use `@env('<CONNECTION_STRING_VAR>')` in `dab-config.json`. ``` For Docker Compose passwords, add: ```text Avoid `$` in Docker Compose passwords because Compose treats `$` as variable interpolation. ``` For Azure, add: - Use Azure Container Apps secrets or Key Vault references for secrets. - Do not inline secret values in scripts, config, or logs. - Use managed identity or delegated auth when the scenario requires passwordless access. ### 11. DAB CLI workflow Include exact DAB CLI commands for the scenario and validate after each meaningful config change. SQL Server example: ```dotnetcli dab init --config data-api/dab-config.json --database-type mssql --connection-string "@env('MSSQL_CONNECTION_STRING')" --host-mode Development --rest.enabled true --graphql.enabled true --mcp.enabled true dab add Todos --config data-api/dab-config.json --source dbo.Todos --source.type table --permissions "anonymous:read" --mcp.dml-tools true dab validate --config data-api/dab-config.json ``` When the article uses PostgreSQL or MySQL, provide the matching `--database-type` and `--source` values: ```dotnetcli dab init --config data-api/dab-config.json --database-type postgresql --connection-string "@env('DATABASE_CONNECTION_STRING')" --host-mode Development --rest.enabled true --graphql.enabled true --mcp.enabled true dab add Todo --config data-api/dab-config.json --source public.todos --source.type table --permissions "anonymous:*" --mcp.dml-tools true ``` ```dotnetcli dab init --config data-api/dab-config.json --database-type mysql --connection-string "@env('DATABASE_CONNECTION_STRING')" --host-mode Development --rest.enabled true --graphql.enabled true --mcp.enabled true dab add Todo --config data-api/dab-config.json --source todos --source.type table --permissions "anonymous:*" --mcp.dml-tools true ``` ### 12. Minimal DAB config shape When useful, include a minimal JSON shape so the implementing agent can write the config directly if CLI setup needs adjustment. ```json { "$schema": "https://dataapibuilder.azureedge.net/schemas/latest/dab.draft.schema.json", "data-source": { "database-type": "mssql", "connection-string": "@env('MSSQL_CONNECTION_STRING')" }, "runtime": { "rest": { "enabled": true, "path": "/api" }, "graphql": { "enabled": true, "path": "/graphql" }, "mcp": { "enabled": true, "path": "/mcp" }, "host": { "mode": "development", "cors": { "origins": ["http://localhost:5173"], "allow-credentials": false } } }, "entities": {} } ``` Prompts that generate a browser-based web app must explicitly configure DAB CORS. Do not let `dab init` leave `runtime.host.cors.origins` as `[]`. Include the exact web app origins, including scheme and port, for every environment the prompt creates: - Docker Compose local web app, for example `http://localhost:8000`. - Aspire local web app, for example `http://localhost:5173`. - Azure Container Apps or other deployed web FQDNs, for example `https://<web-app-fqdn>`. Use exact origins instead of relying on direct REST, GraphQL, or Swagger tests. Those direct requests can succeed while the browser blocks JavaScript fetch calls because DAB didn't return a matching `Access-Control-Allow-Origin` header. Keep `allow-credentials` set to `false` unless the sample intentionally uses browser credentials or cookies. For MSAL bearer-token SPAs, `allow-credentials` should usually remain `false` because the web app sends `Authorization: Bearer <token>` headers. ### 13. Local orchestration patterns Choose the orchestration pattern that matches the sample. #### .NET Aspire Use Aspire for quickstarts that already use AppHost orchestration. Key rules: - Use `.WaitForCompletion(sqlDatabaseProject)` when a SQL Database Project deploys schema. - Do not use only `.WaitFor(sqlDatabaseProject)` for run-to-completion SQL project deployment. - Add health checks for DAB, SQL Commander, and the web app when available. - Keep DAB config mounted read-only for local development. DAB container pattern: ```csharp