Database Examples

This directory contains code examples extracted from the database documentation, following the document normalization principle of maintaining single sources of truth.

Purpose

All code examples that appear in multiple documentation files are stored here and referenced by those files. This ensures:

• Consistency: One authoritative version of each example
• Maintainability: Update examples in one place
• Clarity: Documentation focuses on concepts, not duplicated code

Examples Index

Basic Usage

File: basic-usage.md
Topics: Simple queries, authentication, create/verify patterns
Referenced by: best-practices.md, patterns.md

Transactions

File: transactions.md
Topics: Transaction setup/teardown, savepoints, retry logic
Referenced by: best-practices.md, patterns.md

Error Handling

File: error-handling.md
Topics: ZodError handling, PostgreSQL error codes, validation
Referenced by: best-practices.md, patterns.md

Testing

File: testing.md
Topics: Test fixtures, factories, migration tests
Referenced by: testing.md, best-practices.md

Migrations

File: migrations.md
Topics: SQL patterns, rollbacks, testing migrations
Referenced by: migrations.md, schema-organization.md

Cursor Pagination

File: cursor-pagination.md
Topics: Cursor encoding/decoding, pagination strategies
Referenced by: cursor-patterns.md, patterns.md

Usage in Documentation

Documentation files reference these examples using links:

For complete example, see [Basic Usage Examples](./examples/basic-usage.md#example-1-simple-query).

or with context:

**Example**: See [Transaction with Savepoints](./examples/transactions.md#example-2-transaction-with-savepoints)

In this task, use a simple transaction:
```typescript
// Brief inline example specific to current context

## Guidelines

### When to Add Examples

Add to this directory when:
- ✅ Example appears in 2+ documentation files
- ✅ Example is > 20 lines
- ✅ Example demonstrates a complete pattern
- ✅ Example is self-contained and runnable

### When to Keep Examples Inline

Keep in documentation when:
- ✅ Example is < 20 lines
- ✅ Example only used in one place
- ✅ Example is highly context-specific
- ✅ Example is conceptual, not literal code

### Example File Structure

Each example file should:
1. Start with a brief description
2. List which files reference it
3. Organize examples with clear headers
4. Include helpful comments in code
5. Show complete, working code

## Contributing

When adding examples:
1. Create descriptive example file names
2. Use numbered examples (Example 1, Example 2, etc.)
3. Include context about when to use each pattern
4. Add entry to this README
5. Update referencing documentation files