From f33b5fc164210dee7431aad3270423bf37312a2f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 21:12:09 +0000 Subject: [PATCH 1/9] Initial plan From 1bc232d59cc239b58341a5a3c2aeb37351eff674 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 21:14:30 +0000 Subject: [PATCH 2/9] Add Copilot instructions file for repository Co-authored-by: Aniruddh25 <3513779+Aniruddh25@users.noreply.github.com> --- .github/copilot-instructions.md | 214 ++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..468b13cf7f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,214 @@ +# Data API builder (DAB) - Copilot Instructions + +## Project Overview + +Data API builder (DAB) is an open-source, no-code tool that creates secure, full-featured REST and GraphQL endpoints for databases. It's a CRUD data API engine that runs in a container—on Azure, any other cloud, or on-premises. + +### Key Technologies +- **Language**: C# / .NET +- **.NET Version**: .NET 8.0 (see `global.json`) +- **Supported Databases**: Azure SQL, SQL Server, SQLDW, Cosmos DB, PostgreSQL, MySQL +- **API Types**: REST, GraphQL +- **Deployment**: Cross-platform (Azure, AWS, GCP, on-premises) + +## Project Structure + +``` +data-api-builder/ +├── src/ +│ ├── Auth/ # Authentication logic +│ ├── Cli/ # Command-line interface (dab CLI) +│ ├── Cli.Tests/ # CLI tests +│ ├── Config/ # Configuration handling +│ ├── Core/ # Core engine components +│ ├── Service/ # Main DAB service/runtime +│ ├── Service.GraphQLBuilder/ # GraphQL schema builder +│ ├── Service.Tests/ # Integration tests +│ └── Azure.DataApiBuilder.sln # Main solution file +├── config-generators/ # Config file generation helpers +├── docs/ # Documentation +├── samples/ # Sample configurations and projects +├── schemas/ # JSON schemas for config validation +├── scripts/ # Build and utility scripts +└── templates/ # Project templates +``` + +## Building and Testing + +### Prerequisites +- .NET 8.0 SDK or later +- Database server for testing (SQL Server, PostgreSQL, MySQL, or Cosmos DB) + +### Building the Project + +```bash +# Build the entire solution +dotnet build src/Azure.DataApiBuilder.sln + +# Clean and rebuild +dotnet clean src/Azure.DataApiBuilder.sln +dotnet build src/Azure.DataApiBuilder.sln +``` + +### Running Tests + +DAB uses integration tests that require database instances with proper schemas. + +**SQL-based tests:** +```bash +# MsSql tests +dotnet test --filter "TestCategory=MsSql" + +# PostgreSQL tests +dotnet test --filter "TestCategory=PostgreSql" + +# MySQL tests +dotnet test --filter "TestCategory=MySql" +``` + +**CosmosDB tests:** +```bash +dotnet test --filter "TestCategory=CosmosDb_NoSql" +``` + +**Test Configuration:** +- Test database schemas are in `src/Service.Tests/DatabaseSchema-.sql` +- Config files are `src/Service.Tests/dab-config..json` +- Connection strings should use `@env('variable_name')` syntax - never commit connection strings + +### Running Locally + +1. Open the solution: `src/Azure.DataApiBuilder.Service.sln` +2. Copy a config file from `src/Service.Tests/dab-config..json` to `src/Service/` +3. Update connection string (use environment variables) +4. Set `Azure.DataApiBuilder.Service` as startup project +5. Select debug profile: `MsSql`, `PostgreSql`, `CosmosDb_NoSql`, or `MySql` +6. Build and run + +## Code Style and Conventions + +### Formatting +- **Tool**: `dotnet format` (enforced in CI) +- **Indentation**: 4 spaces for C# code, 2 spaces for YAML/JSON +- **Line endings**: LF (Unix-style) +- **Character encoding**: UTF-8 +- **Trailing whitespace**: Removed +- **Final newline**: Required + +### Running Code Formatter + +```bash +# Format all files +dotnet format src/Azure.DataApiBuilder.sln + +# Verify formatting (CI check) +dotnet format src/Azure.DataApiBuilder.sln --verify-no-changes +``` + +### C# Conventions +- **Usings**: Sort system directives first, no separation between groups +- **Type preferences**: Use language keywords (`int`, `string`) over BCL types (`Int32`, `String`) +- **Naming**: Follow standard .NET naming conventions +- **`this.` qualifier**: Not used unless necessary + +### SQL Query Formatting +When adding or modifying generated SQL queries in tests: +- **PostgreSQL**: Use https://sqlformat.org/ (remove unnecessary double quotes) +- **SQL Server**: Use https://poorsql.com/ (enable "trailing commas", indent string: `\s\s\s\s`) +- **MySQL**: Use https://poorsql.com/ (same as SQL Server, max line width: 100) + +## Testing Guidelines + +### Test Organization +- Integration tests validate the engine's query generation and database operations +- Tests are organized by database type using TestCategory attributes +- Each database type has its own config file and schema + +### Adding New Tests +- Work within the existing database schema (SQL) or GraphQL schema (CosmosDB) +- Add tests to the appropriate test class +- Use base class methods and helpers for engine operations +- Format any generated SQL queries using the specified formatters +- Do not commit connection strings to the repository + +### Test Database Setup +1. Create database using the appropriate server +2. Run the schema script: `src/Service.Tests/DatabaseSchema-.sql` +3. Set connection string in config using `@env()` syntax +4. Run tests for that specific database type + +## Configuration Files + +### DAB Configuration +- Config files use JSON format with schema validation +- Schema files are in the `schemas/` directory +- Use `@env('variable_name')` to reference environment variables +- Never commit connection strings or secrets + +### Config Generation +Use the ConfigGenerators directory for automated config file creation: +```bash +# Build with config generation +dotnet build -p:generateConfigFileForDbType= +``` +Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql` + +## Security Practices + +- **Never commit secrets**: Use environment variables with `@env()` syntax +- **Connection strings**: Always use `.env` files (add to `.gitignore`) +- **Authentication**: Supports AppService, EasyAuth, StaticWebApps, JWT +- **Authorization**: Role-based permissions in config +- **Set-session-context**: Available for SQL Server row-level security + +## API Development + +### REST API +- Base path: `/api` (configurable) +- Follows Microsoft REST API Guidelines +- Request body validation available +- Health endpoint: `/health` +- Swagger UI in development mode: `/swagger` + +### GraphQL API +- Base path: `/graphql` (configurable) +- Introspection enabled in development mode +- Nitro UI in development mode: `/graphql` +- Schema generated from database metadata + +## Common Commands + +```bash +# Install DAB CLI globally +dotnet tool install microsoft.dataapibuilder -g + +# Initialize a new config +dab init --database-type --connection-string "@env('connection_string')" --host-mode development + +# Add an entity to config +dab add --source --permissions "anonymous:*" + +# Start DAB locally +dab start + +# Validate a config file +dab validate +``` + +## Contributing + +- Sign the Contributor License Agreement (CLA) +- Follow the Microsoft Open Source Code of Conduct +- Use issue templates when reporting bugs or requesting features +- Include configuration files, logs, and hosting model in issue reports +- Run `dotnet format` before committing +- Do not commit connection strings or other secrets + +## References + +- [Official Documentation](https://learn.microsoft.com/azure/data-api-builder/) +- [Samples](https://aka.ms/dab/samples) +- [Known Issues](https://learn.microsoft.com/azure/data-api-builder/known-issues) +- [Feature Roadmap](https://github.com/Azure/data-api-builder/discussions/1377) +- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md) +- [GraphQL Specification](https://graphql.org/) From c5c815d7f52046850547c54a87113e8d1acd6b0e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 30 Jan 2026 21:18:40 +0000 Subject: [PATCH 3/9] Fix file and directory name references in Copilot instructions Co-authored-by: Aniruddh25 <3513779+Aniruddh25@users.noreply.github.com> --- .github/copilot-instructions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 468b13cf7f..5f8e00d77f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -78,7 +78,7 @@ dotnet test --filter "TestCategory=CosmosDb_NoSql" ### Running Locally -1. Open the solution: `src/Azure.DataApiBuilder.Service.sln` +1. Open the solution: `src/Azure.DataApiBuilder.sln` 2. Copy a config file from `src/Service.Tests/dab-config..json` to `src/Service/` 3. Update connection string (use environment variables) 4. Set `Azure.DataApiBuilder.Service` as startup project @@ -146,7 +146,7 @@ When adding or modifying generated SQL queries in tests: - Never commit connection strings or secrets ### Config Generation -Use the ConfigGenerators directory for automated config file creation: +Use the config-generators directory for automated config file creation: ```bash # Build with config generation dotnet build -p:generateConfigFileForDbType= @@ -159,7 +159,7 @@ Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql` - **Connection strings**: Always use `.env` files (add to `.gitignore`) - **Authentication**: Supports AppService, EasyAuth, StaticWebApps, JWT - **Authorization**: Role-based permissions in config -- **Set-session-context**: Available for SQL Server row-level security +- **set-session-context**: Available for SQL Server row-level security ## API Development From b47066acefb0d09333d0bd7cf2b36089fad6247c Mon Sep 17 00:00:00 2001 From: Aniruddh Munde Date: Fri, 30 Jan 2026 17:00:32 -0800 Subject: [PATCH 4/9] Apply suggestions from code review --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5f8e00d77f..ae3ff48f6c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Project Overview -Data API builder (DAB) is an open-source, no-code tool that creates secure, full-featured REST and GraphQL endpoints for databases. It's a CRUD data API engine that runs in a container—on Azure, any other cloud, or on-premises. +Data API builder (DAB) is an open-source, no-code tool that creates secure, full-featured REST, GraphQL endpoints for databases. It's a CRUD data API engine that runs in a container—on Azure, any other cloud, or on-premises. It also supports creation of DML and Custom MCP tools for a SQL MCP Server backed by a SQL database. ### Key Technologies - **Language**: C# / .NET From 296be18ed923c57d5bf5f3639a201d60c76aaa73 Mon Sep 17 00:00:00 2001 From: Aniruddh Munde Date: Fri, 30 Jan 2026 17:00:43 -0800 Subject: [PATCH 5/9] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ae3ff48f6c..5821895157 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,7 +8,7 @@ Data API builder (DAB) is an open-source, no-code tool that creates secure, full - **Language**: C# / .NET - **.NET Version**: .NET 8.0 (see `global.json`) - **Supported Databases**: Azure SQL, SQL Server, SQLDW, Cosmos DB, PostgreSQL, MySQL -- **API Types**: REST, GraphQL +- **API Types**: REST, GraphQL, MCP - **Deployment**: Cross-platform (Azure, AWS, GCP, on-premises) ## Project Structure From 5ff047ce17a3ed1903d3fa6a05526a79f8f133f6 Mon Sep 17 00:00:00 2001 From: Aniruddh Munde Date: Fri, 30 Jan 2026 17:01:53 -0800 Subject: [PATCH 6/9] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5821895157..b240658133 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Project Overview -Data API builder (DAB) is an open-source, no-code tool that creates secure, full-featured REST, GraphQL endpoints for databases. It's a CRUD data API engine that runs in a container—on Azure, any other cloud, or on-premises. It also supports creation of DML and Custom MCP tools for a SQL MCP Server backed by a SQL database. +Data API builder (DAB) is an open-source, no-code tool that creates secure, full-featured REST, GraphQL endpoints for databases. It's a CRUD data API engine that runs in a container—on Azure, any other cloud, or on-premises. It also supports creation of DML and Custom MCP tools to build a SQL MCP Server backed by a SQL database. ### Key Technologies - **Language**: C# / .NET From 9cdf0231e6eef1dd554ce0d75319be232daa6aa6 Mon Sep 17 00:00:00 2001 From: Aniruddh Munde Date: Fri, 30 Jan 2026 17:02:11 -0800 Subject: [PATCH 7/9] Update .github/copilot-instructions.md --- .github/copilot-instructions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b240658133..b42f33d489 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -175,7 +175,9 @@ Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql` - Introspection enabled in development mode - Nitro UI in development mode: `/graphql` - Schema generated from database metadata - +### MCP tools +- Base Path: `/mcp` (configurable) +- Discover tools with MCP Inspector ## Common Commands ```bash From 1eaaa4b5005895dbe74f115775af448b3ea8b920 Mon Sep 17 00:00:00 2001 From: Aniruddh Munde Date: Fri, 30 Jan 2026 20:26:03 -0800 Subject: [PATCH 8/9] Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b42f33d489..0b3c282036 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -168,7 +168,7 @@ Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql` - Follows Microsoft REST API Guidelines - Request body validation available - Health endpoint: `/health` -- Swagger UI in development mode: `/swagger` +- Swagger UI in development mode: `/{REST_PATH}/openapi` (default: `/api/openapi`) ### GraphQL API - Base path: `/graphql` (configurable) From 64f0261ab6e354a8a2c53574175a68d00aab94de Mon Sep 17 00:00:00 2001 From: Jerry Nixon <1749983+JerryNixon@users.noreply.github.com> Date: Mon, 2 Feb 2026 10:12:57 -0700 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0b3c282036..f6ede86db0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -175,7 +175,7 @@ Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql` - Introspection enabled in development mode - Nitro UI in development mode: `/graphql` - Schema generated from database metadata -### MCP tools +### MCP Tools - Base Path: `/mcp` (configurable) - Discover tools with MCP Inspector ## Common Commands