@ydbjs/query/ai-instructions/.copilot-instructions.example.md

High-level, type-safe YQL query and transaction client for YDB. Supports tagged template syntax, parameter binding, transactions, and statistics.

# YDB JavaScript SDK Instructions for GitHub Copilot

When working with @ydbjs/query and YQL functions:

## CRITICAL: Template Literal Security
- ALWAYS use yql`SELECT...` template literal syntax for queries
- NEVER use yql(string) with pre-built strings containing user input
- Template literals automatically parameterize values preventing SQL injection

## Parameter Handling
- All ${value} interpolations in template literals become safe parameters
- Use Optional<T> types from @ydbjs/value for nullable database values
- Validate and sanitize all user inputs before passing to yql functions
- Apply size limits to prevent DoS attacks

## Dynamic Identifiers
- Use identifier() function for table/column names: ${identifier('tableName')}
- Use unsafe() ONLY for trusted contexts (migrations, static fragments)
- Never use unsafe() with user-controllable data

## Type Safety
- Import specific types from @ydbjs/value (Int32, Text, Optional, etc.)
- Use TypeScript strict mode with strictNullChecks enabled
- Prefer explicit type conversion over implicit coercion

## Examples:

✅ SAFE PATTERNS:
```typescript
// Parameterized query with validation
let userId = userInput?.id ? new Int32(userInput.id) : Optional.int32()
yql`SELECT * FROM users WHERE id = ${userId}`

// Dynamic table name with identifier()
yql`SELECT * FROM ${identifier(tableName)} WHERE status = ${status}`

// Safe string handling
let searchTerm = (userInput.search || '').trim().substring(0, 100)
yql`SELECT * FROM posts WHERE title LIKE ${searchTerm}`
```

❌ DANGEROUS PATTERNS:
```typescript
// String concatenation - NEVER DO THIS
let query = `SELECT * FROM users WHERE id = ${userInput}`
yql(query)

// Direct user input without validation
yql`SELECT * FROM users WHERE id = ${req.body.userId}`

// Uncontrolled limits
yql`SELECT * FROM posts LIMIT ${userInput.limit}`
```

## Error Handling
- Always handle potential null/undefined values
- Use try-catch blocks for query execution
- Log errors without exposing sensitive data

Follow complete security guidelines in SECURITY.md