Skip to content

Commit 6f62845

Browse files
CopilotAniruddh25CopilotJerryNixon
authored
Add Copilot repository instructions (#3090)
## Why make this change? Per GitHub best practices, Copilot coding agent uses `.github/copilot-instructions.md` to understand repository context, conventions, and workflows. Without this, the agent lacks project-specific knowledge for optimal assistance. ## What is this change? Created `.github/copilot-instructions.md` containing: - **Project context**: .NET 8 C# service supporting 6 database types (SQL Server, PostgreSQL, MySQL, Cosmos DB, etc.) - **Build/test commands**: Database-specific test categories, `dotnet format` requirements, schema setup - **Code conventions**: 4-space indent, LF endings, `dotnet format` enforcement, SQL query formatting per engine - **Security patterns**: `@env()` syntax for connection strings, never commit secrets - **Project structure**: Core/Auth/CLI/Service/GraphQLBuilder organization - **Common workflows**: Config generation, local development setup, CLI usage Key details for AI assistance: - Integration tests require specific database schemas from `src/Service.Tests/DatabaseSchema-<engine>.sql` - Config files use JSON with `@env('var_name')` for secrets - Different SQL formatters per database engine (sqlformat.org for Postgres, poorsql.com for SQL Server/MySQL) ## How was this tested? - N/A - Documentation only, no code changes ## Sample Request(s) - N/A - Documentation only, no runtime behavior changes > [!WARNING] > > <details> > <summary>Firewall rules blocked me from connecting to one or more addresses (expand for details)</summary> > > #### I tried to connect to the following addresses, but was blocked by firewall rules: > > - `gh.io` > - Triggering command: `/home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js` (dns block) > > If you need me to access, download, or install something from one of these locations, you can either: > > - Configure [Actions setup steps](https://gh.io/copilot/actions-setup-steps) to set up my environment, which run before the firewall is enabled > - Add the appropriate URLs or hosts to the custom allowlist in this repository's [Copilot coding agent settings](https://github.com/Azure/data-api-builder/settings/copilot/coding_agent) (admins only) > > </details> <!-- START COPILOT ORIGINAL PROMPT --> <details> <summary>Original prompt</summary> > > ---- > > *This section details on the original issue you should resolve* > > <issue_title>✨ Set up Copilot instructions</issue_title> > <issue_description>Configure instructions for this repository as documented in [Best practices for Copilot coding agent in your repository](https://gh.io/copilot-coding-agent-tips). > > <Onboard this repo></issue_description> > > ## Comments on the Issue (you are @copilot in this section) > > <comments> > </comments> > </details> <!-- START COPILOT CODING AGENT SUFFIX --> - Fixes #3089 <!-- START COPILOT CODING AGENT TIPS --> --- 💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey). --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: Aniruddh25 <[email protected]> Co-authored-by: Aniruddh Munde <[email protected]> Co-authored-by: Copilot <[email protected]> Co-authored-by: Jerry Nixon <[email protected]>
1 parent 93a088f commit 6f62845

1 file changed

Lines changed: 251 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# Data API builder (DAB) - Copilot Instructions
2+
3+
## Project Overview
4+
5+
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.
6+
7+
### Key Technologies
8+
- **Language**: C# / .NET
9+
- **.NET Version**: .NET 8.0 (see `global.json`)
10+
- **Supported Databases**: Azure SQL, SQL Server, SQLDW, Cosmos DB, PostgreSQL, MySQL
11+
- **API Types**: REST, GraphQL, MCP
12+
- **Deployment**: Cross-platform (Azure, AWS, GCP, on-premises)
13+
14+
## Project Structure
15+
16+
```
17+
data-api-builder/
18+
├── src/
19+
│ ├── Auth/ # Authentication logic
20+
│ ├── Cli/ # Command-line interface (dab CLI)
21+
│ ├── Cli.Tests/ # CLI tests
22+
│ ├── Config/ # Configuration handling
23+
│ ├── Core/ # Core engine components
24+
│ ├── Service/ # Main DAB service/runtime
25+
│ ├── Service.GraphQLBuilder/ # GraphQL schema builder
26+
│ ├── Service.Tests/ # Integration tests
27+
│ └── Azure.DataApiBuilder.sln # Main solution file
28+
├── config-generators/ # Config file generation helpers
29+
├── docs/ # Documentation
30+
├── samples/ # Sample configurations and projects
31+
├── schemas/ # JSON schemas for config validation
32+
├── scripts/ # Build and utility scripts
33+
└── templates/ # Project templates
34+
```
35+
36+
## Building and Testing
37+
38+
### Prerequisites
39+
- .NET 8.0 SDK or later
40+
- Database server for testing (SQL Server, PostgreSQL, MySQL, or Cosmos DB)
41+
42+
### Building the Project
43+
44+
```bash
45+
# Build the entire solution
46+
dotnet build src/Azure.DataApiBuilder.sln
47+
48+
# Clean and rebuild
49+
dotnet clean src/Azure.DataApiBuilder.sln
50+
dotnet build src/Azure.DataApiBuilder.sln
51+
```
52+
53+
### Running Tests
54+
55+
DAB uses integration tests that require database instances with proper schemas.
56+
57+
**SQL-based tests:**
58+
```bash
59+
# MsSql tests
60+
dotnet test --filter "TestCategory=MsSql"
61+
62+
# PostgreSQL tests
63+
dotnet test --filter "TestCategory=PostgreSql"
64+
65+
# MySQL tests
66+
dotnet test --filter "TestCategory=MySql"
67+
```
68+
69+
**CosmosDB tests:**
70+
```bash
71+
dotnet test --filter "TestCategory=CosmosDb_NoSql"
72+
```
73+
74+
**Test Configuration:**
75+
- Test database schemas are in `src/Service.Tests/DatabaseSchema-<engine>.sql`
76+
- Config files are `src/Service.Tests/dab-config.<engine>.json`
77+
- Connection strings should use `@env('variable_name')` syntax - never commit connection strings
78+
79+
### Running Locally
80+
81+
1. Open the solution: `src/Azure.DataApiBuilder.sln`
82+
2. Copy a config file from `src/Service.Tests/dab-config.<engine>.json` to `src/Service/`
83+
3. Update connection string (use environment variables)
84+
4. Set `Azure.DataApiBuilder.Service` as startup project
85+
5. Select debug profile: `MsSql`, `PostgreSql`, `CosmosDb_NoSql`, or `MySql`
86+
6. Build and run
87+
88+
## Code Style and Conventions
89+
90+
### Formatting
91+
- **Tool**: `dotnet format` (enforced in CI)
92+
- **Indentation**: 4 spaces for C# code, 2 spaces for YAML/JSON
93+
- **Line endings**: LF (Unix-style)
94+
- **Character encoding**: UTF-8
95+
- **Trailing whitespace**: Removed
96+
- **Final newline**: Required
97+
- Refer to `.\src\.editorconfig` for additional formatting conventions.
98+
99+
### Running Code Formatter
100+
101+
```bash
102+
# Format all files
103+
dotnet format src/Azure.DataApiBuilder.sln
104+
105+
# Verify formatting (CI check)
106+
dotnet format src/Azure.DataApiBuilder.sln --verify-no-changes
107+
```
108+
109+
### C# Conventions
110+
- **Usings**: Sort system directives first, no separation between groups
111+
- **Type preferences**: Use language keywords (`int`, `string`) over BCL types (`Int32`, `String`)
112+
- **Naming**: Follow standard .NET naming conventions
113+
- **`this.` qualifier**: Not used unless necessary
114+
115+
### SQL Query Formatting
116+
When adding or modifying generated SQL queries in tests:
117+
- **PostgreSQL**: Use https://sqlformat.org/ (remove unnecessary double quotes)
118+
- **SQL Server**: Use https://poorsql.com/ (enable "trailing commas", indent string: `\s\s\s\s`)
119+
- **MySQL**: Use https://poorsql.com/ (same as SQL Server, max line width: 100)
120+
121+
## Testing Guidelines
122+
123+
### Test Organization
124+
- Integration tests validate the engine's query generation and database operations
125+
- Tests are organized by database type using TestCategory attributes
126+
- Each database type has its own config file and schema
127+
128+
### Adding New Tests
129+
- Work within the existing database schema (SQL) or GraphQL schema (CosmosDB)
130+
- Add tests to the appropriate test class
131+
- Use base class methods and helpers for engine operations
132+
- Format any generated SQL queries using the specified formatters
133+
- Do not commit connection strings to the repository
134+
135+
### Test Database Setup
136+
1. Create database using the appropriate server
137+
2. Run the schema script: `src/Service.Tests/DatabaseSchema-<engine>.sql`
138+
3. Set connection string in config using `@env()` syntax
139+
4. Run tests for that specific database type
140+
141+
## Configuration Files
142+
143+
### DAB Configuration
144+
- Config files use JSON format with schema validation
145+
- Schema files are in the `schemas/` directory
146+
- Use `@env('variable_name')` to reference environment variables
147+
- Never commit connection strings or secrets
148+
149+
### Config Generation
150+
Use the config-generators directory for automated config file creation:
151+
```bash
152+
# Build with config generation
153+
dotnet build -p:generateConfigFileForDbType=<database_type>
154+
```
155+
Supported types: `mssql`, `postgresql`, `cosmosdb_nosql`, `mysql`
156+
157+
## Security Practices
158+
159+
- **Never commit secrets**: Use environment variables with `@env()` syntax
160+
- **Connection strings**: Always use `.env` files (add to `.gitignore`)
161+
- **Authentication**: Supports AppService, EasyAuth, StaticWebApps, JWT
162+
- **Authorization**: Role-based permissions in config
163+
- **set-session-context**: Available for SQL Server row-level security
164+
165+
## API Development
166+
167+
### REST API
168+
- Base path: `/api` (configurable)
169+
- Follows Microsoft REST API Guidelines
170+
- Request body validation available
171+
- Health endpoint: `/health`
172+
- Swagger UI in development mode: `/{REST_PATH}/openapi` (default: `/api/openapi`)
173+
174+
### GraphQL API
175+
- Base path: `/graphql` (configurable)
176+
- Introspection enabled in development mode
177+
- Nitro UI in development mode: `/graphql`
178+
- Schema generated from database metadata
179+
### MCP Tools
180+
- Base Path: `/mcp` (configurable)
181+
- Discover tools with MCP Inspector
182+
183+
## Common Commands
184+
185+
```bash
186+
# Install DAB CLI globally
187+
dotnet tool install microsoft.dataapibuilder -g
188+
189+
# Initialize a new config
190+
dab init --database-type <type> --connection-string "@env('connection_string')" --host-mode development
191+
192+
# Add an entity to config
193+
dab add <entity_name> --source <schema.table> --permissions "anonymous:*"
194+
195+
# Start DAB locally
196+
dab start
197+
198+
# Validate a config file
199+
dab validate
200+
```
201+
202+
## Contributing
203+
204+
- Sign the Contributor License Agreement (CLA)
205+
- Follow the Microsoft Open Source Code of Conduct
206+
- Use issue templates when reporting bugs or requesting features
207+
- Include configuration files, logs, and hosting model in issue reports
208+
- Run `dotnet format` before committing
209+
- Do not commit connection strings or other secrets
210+
211+
### Commit Signing
212+
213+
All commits should be signed to receive the verified badge on GitHub. Configure GPG or SSH signing:
214+
215+
**GPG Signing:**
216+
```bash
217+
# Generate a GPG key
218+
gpg --full-generate-key
219+
220+
# List keys and copy the key ID
221+
gpg --list-secret-keys --keyid-format=long
222+
223+
# Configure Git to use the key
224+
git config --global user.signingkey <KEY_ID>
225+
git config --global commit.gpgsign true
226+
227+
# Add GPG key to GitHub account
228+
gpg --armor --export <KEY_ID>
229+
```
230+
231+
**SSH Signing:**
232+
```bash
233+
# Generate an SSH key
234+
ssh-keygen -t ed25519 -C "[email protected]"
235+
236+
# Configure Git to use SSH signing
237+
git config --global gpg.format ssh
238+
git config --global user.signingkey ~/.ssh/id_ed25519.pub
239+
git config --global commit.gpgsign true
240+
241+
# Add SSH key to GitHub account as signing key
242+
```
243+
244+
## References
245+
246+
- [Official Documentation](https://learn.microsoft.com/azure/data-api-builder/)
247+
- [Samples](https://aka.ms/dab/samples)
248+
- [Known Issues](https://learn.microsoft.com/azure/data-api-builder/known-issues)
249+
- [Feature Roadmap](https://github.com/Azure/data-api-builder/discussions/1377)
250+
- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md)
251+
- [GraphQL Specification](https://graphql.org/)

0 commit comments

Comments
 (0)