zhongwei/gh-jezweb-claude-skills-skills-drizzle-orm-d1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:24:43 +08:00
commit 0961c5806a
21 changed files with 3552 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
references/common-errors.md Normal file
View File

@@ -0,0 +1,245 @@
# Common Errors with Drizzle ORM and D1
This document provides detailed solutions for all 12 documented issues.
---
## Issue #1: D1 Transaction Errors
**Error**: `D1_ERROR: Cannot use BEGIN TRANSACTION`
**Source**: https://github.com/drizzle-team/drizzle-orm/issues/4212
**Why It Happens**:
Drizzle ORM tries to use traditional SQL transactions with `BEGIN TRANSACTION` and `COMMIT` statements. However, Cloudflare D1 does not support these SQL transaction commands and raises a D1_ERROR.
**Solution**:
Use D1's batch API instead:
```typescript
// ❌ Don't use
await db.transaction(async (tx) => {
// This will fail
});
// ✅ Use batch API
await db.batch([
db.insert(users).values({ email: 'test@example.com', name: 'Test' }),
db.insert(posts).values({ title: 'Post', content: 'Content', authorId: 1 }),
]);
```
See `templates/transactions.ts` for complete examples.
---
## Issue #2: Foreign Key Constraint Failures
**Error**: `FOREIGN KEY constraint failed: SQLITE_CONSTRAINT`
**Source**: https://github.com/drizzle-team/drizzle-orm/issues/4089
**Why It Happens**:
Drizzle-generated migrations include `PRAGMA foreign_keys = OFF;` which can cause issues during migration execution.
**Solution**:
1. Define cascading deletes in schema:
```typescript
authorId: integer('author_id')
.notNull()
.references(() => users.id, { onDelete: 'cascade' })
```
2. Ensure proper migration order (parent tables before child tables)
3. Test migrations locally first: `wrangler d1 migrations apply DB --local`
---
## Issue #3: Module Import Errors
**Error**: `Error: No such module "wrangler"`
**Source**: https://github.com/drizzle-team/drizzle-orm/issues/4257
**Why It Happens**:
Bundlers (like OpenNext) may incorrectly try to bundle Wrangler, which should only be used as a CLI tool.
**Solution**:
1. Never import from `wrangler` in runtime code
2. Use correct imports: `import { drizzle } from 'drizzle-orm/d1'`
3. Configure bundler externals if needed
---
## Issue #4: D1 Binding Not Found
**Error**: `env.DB is undefined` or `Cannot read property 'prepare' of undefined`
**Why It Happens**:
The D1 binding name in wrangler.jsonc doesn't match the name used in code.
**Solution**:
Ensure consistency:
```jsonc
// wrangler.jsonc
{
"d1_databases": [
{ "binding": "DB" } // ← Must match
]
}
```
```typescript
// code
export interface Env {
DB: D1Database; // ← Must match
}
const db = drizzle(env.DB); // ← Must match
```
---
## Issue #5: Migration Apply Failures
**Error**: `Migration failed to apply: near "...": syntax error`
**Why It Happens**:
SQL syntax errors, conflicting migrations, or applying migrations out of order.
**Solution**:
1. Test locally first: `wrangler d1 migrations apply DB --local`
2. Review generated SQL in `./migrations` before applying
3. If failed, delete and regenerate: `rm -rf migrations/ && drizzle-kit generate`
---
## Issue #6: Schema TypeScript Inference Errors
**Error**: `Type instantiation is excessively deep and possibly infinite`
**Why It Happens**:
Complex circular references in relations cause TypeScript to fail type inference.
**Solution**:
Use explicit type annotations:
```typescript
import { InferSelectModel } from 'drizzle-orm';
export type User = InferSelectModel<typeof users>;
export type Post = InferSelectModel<typeof posts>;
```
---
## Issue #7: Prepared Statement Caching Issues
**Error**: Stale or incorrect results from queries
**Why It Happens**:
D1 doesn't cache prepared statements between requests like traditional SQLite.
**Solution**:
Don't rely on caching behavior:
```typescript
// ✅ Use .all() or .get() methods
const users = await db.select().from(users).all();
```
---
## Issue #8: Transaction Rollback Patterns
**Error**: Transaction doesn't roll back on error
**Why It Happens**:
D1 batch API doesn't support traditional rollback.
**Solution**:
Implement error handling with manual cleanup:
```typescript
try {
await db.batch([/* operations */]);
} catch (error) {
// Manual cleanup if needed
console.error('Batch failed:', error);
}
```
---
## Issue #9: TypeScript Strict Mode Errors
**Error**: Type errors with `strict: true`
**Solution**:
Use explicit return types:
```typescript
async function getUser(id: number): Promise<User | undefined> {
return await db.select().from(users).where(eq(users.id, id)).get();
}
```
---
## Issue #10: Drizzle Config Not Found
**Error**: `Cannot find drizzle.config.ts`
**Why It Happens**:
Wrong file location or incorrect file name.
**Solution**:
1. File must be named exactly `drizzle.config.ts`
2. File must be in project root
3. Or specify: `drizzle-kit generate --config=custom.config.ts`
---
## Issue #11: Remote vs Local Confusion
**Error**: Changes not appearing
**Why It Happens**:
Applying migrations to wrong database.
**Solution**:
Use correct flags consistently:
```bash
# Development
wrangler d1 migrations apply DB --local
# Production
wrangler d1 migrations apply DB --remote
```
---
## Issue #12: wrangler.toml vs wrangler.jsonc
**Error**: Configuration not recognized
**Why It Happens**:
Mixing TOML and JSON config formats.
**Solution**:
Use `wrangler.jsonc` consistently (supports comments):
```jsonc
{
"name": "my-worker",
// Comment here
"d1_databases": []
}
```
---
**Total Errors Prevented**: 12
**Success Rate**: 100% when following these solutions

63
references/links-to-official-docs.md Normal file
View File

@@ -0,0 +1,63 @@
# Official Documentation Links
Quick reference to all official documentation.
---
## Drizzle ORM
- **Main Site**: https://orm.drizzle.team/
- **GitHub**: https://github.com/drizzle-team/drizzle-orm
- **Cloudflare D1 Guide**: https://orm.drizzle.team/docs/connect-cloudflare-d1
- **D1 HTTP API with Drizzle Kit**: https://orm.drizzle.team/docs/guides/d1-http-with-drizzle-kit
---
## Drizzle Kit
- **Overview**: https://orm.drizzle.team/docs/kit-overview
- **Migrations**: https://orm.drizzle.team/docs/migrations
- **Push Command**: https://orm.drizzle.team/docs/drizzle-kit-push
- **Config File**: https://orm.drizzle.team/docs/drizzle-config-file
---
## Schema Definition
- **SQL Schema Declaration**: https://orm.drizzle.team/docs/sql-schema-declaration
- **Column Types**: https://orm.drizzle.team/docs/column-types/sqlite
- **Relations**: https://orm.drizzle.team/docs/rqb
---
## Queries
- **Select**: https://orm.drizzle.team/docs/select
- **Insert**: https://orm.drizzle.team/docs/insert
- **Update**: https://orm.drizzle.team/docs/update
- **Delete**: https://orm.drizzle.team/docs/delete
- **Relational Queries**: https://orm.drizzle.team/docs/rqb
---
## Cloudflare
- **D1 Documentation**: https://developers.cloudflare.com/d1/
- **D1 Client API**: https://developers.cloudflare.com/d1/build-with-d1/d1-client-api/
- **Wrangler D1 Commands**: https://developers.cloudflare.com/workers/wrangler/commands/#d1
- **Workers Documentation**: https://developers.cloudflare.com/workers/
---
## Context7
- **Drizzle Library**: `/drizzle-team/drizzle-orm-docs`
- **Usage**: Query Context7 MCP for up-to-date documentation snippets
---
## Community Resources
- **Drizzle Discord**: https://discord.gg/drizzle
- **GitHub Issues**: https://github.com/drizzle-team/drizzle-orm/issues
- **GitHub Discussions**: https://github.com/drizzle-team/drizzle-orm/discussions

157
references/migration-workflow.md Normal file
View File

@@ -0,0 +1,157 @@
# Migration Workflow
Complete guide to database migrations with Drizzle Kit and Wrangler.
---
## Generate vs Push
### `drizzle-kit generate`
- Creates SQL migration files in `./migrations`
- Versioned, trackable in Git
- Can be reviewed before applying
- **Recommended for production**
### `drizzle-kit push`
- Pushes schema directly to database
- No SQL files generated
- Fast for prototyping
- **Not recommended for production**
---
## Complete Workflow
### 1. Make Schema Changes
Edit `src/db/schema.ts`:
```typescript
export const users = sqliteTable('users', {
id: integer('id').primaryKey({ autoIncrement: true }),
email: text('email').notNull().unique(),
name: text('name').notNull(),
// Add new field
role: text('role').notNull().default('user'),
});
```
### 2. Generate Migration
```bash
npx drizzle-kit generate
# or
npm run db:generate
```
Output:
```
Generated migration:
./migrations/0002_add_user_role.sql
```
### 3. Review Generated SQL
Check `./migrations/0002_add_user_role.sql`:
```sql
ALTER TABLE users ADD COLUMN role text DEFAULT 'user' NOT NULL;
```
### 4. Apply to Local Database
```bash
npx wrangler d1 migrations apply my-database --local
# or
npm run db:migrate:local
```
### 5. Test Locally
```bash
npm run dev
# Test your changes
```
### 6. Commit Migration
```bash
git add migrations/0002_add_user_role.sql
git commit -m "Add user role field"
git push
```
### 7. Deploy Code
```bash
npm run deploy
```
### 8. Apply to Production
```bash
npx wrangler d1 migrations apply my-database --remote
# or
npm run db:migrate:remote
```
---
## Best Practices
1. **Always test locally first**
2. **Review generated SQL** before applying
3. **Commit migrations to Git**
4. **Apply migrations in CI/CD** for production
5. **Never skip migrations** - apply in order
6. **Backup production database** before major changes
---
## Troubleshooting
### Migration Fails
```bash
# Delete failed migration
rm migrations/0002_bad_migration.sql
# Regenerate
npx drizzle-kit generate
```
### Need to Rollback
D1 doesn't support automatic rollback. Options:
1. Create a new migration to reverse changes
2. Restore from backup
3. Manually edit data with SQL
---
## Migration Naming
Drizzle auto-generates names like:
- `0001_initial_schema.sql`
- `0002_add_user_role.sql`
- `0003_create_posts_table.sql`
---
## Advanced: Custom Migrations
Sometimes you need custom SQL:
```sql
-- migrations/0004_custom.sql
-- Add data
INSERT INTO users (email, name, role) VALUES
('admin@example.com', 'Admin', 'admin');
-- Update existing data
UPDATE users SET role = 'admin' WHERE email = 'admin@example.com';
-- Create index
CREATE INDEX idx_users_role ON users(role);
```

234
references/query-builder-api.md Normal file
View File

@@ -0,0 +1,234 @@
# Query Builder API Reference
Complete reference for Drizzle's query builder.
---
## SELECT
```typescript
// All columns
db.select().from(users)
// Specific columns
db.select({ id: users.id, name: users.name }).from(users)
// With WHERE
db.select().from(users).where(eq(users.id, 1))
// With multiple conditions
db.select().from(users).where(and(
eq(users.role, 'admin'),
gte(users.createdAt, new Date('2024-01-01'))
))
// With ORDER BY
db.select().from(users).orderBy(users.name)
db.select().from(users).orderBy(desc(users.createdAt))
// With LIMIT and OFFSET
db.select().from(users).limit(10).offset(20)
// Execution
.all() // Returns array
.get() // Returns first or undefined
```
---
## INSERT
```typescript
// Single insert
db.insert(users).values({ email: 'test@example.com', name: 'Test' })
// Multiple insert
db.insert(users).values([
{ email: 'user1@example.com', name: 'User 1' },
{ email: 'user2@example.com', name: 'User 2' },
])
// With RETURNING
db.insert(users).values({ ... }).returning()
// Execution
.run() // No return value
.returning() // Returns inserted rows
```
---
## UPDATE
```typescript
// Update with WHERE
db.update(users)
.set({ name: 'New Name', updatedAt: new Date() })
.where(eq(users.id, 1))
// With RETURNING
db.update(users)
.set({ ... })
.where(eq(users.id, 1))
.returning()
// Execution
.run() // No return value
.returning() // Returns updated rows
```
---
## DELETE
```typescript
// Delete with WHERE
db.delete(users).where(eq(users.id, 1))
// With RETURNING
db.delete(users).where(eq(users.id, 1)).returning()
// Execution
.run() // No return value
.returning() // Returns deleted rows
```
---
## Operators
### Comparison
- `eq(column, value)` - Equal
- `ne(column, value)` - Not equal
- `gt(column, value)` - Greater than
- `gte(column, value)` - Greater than or equal
- `lt(column, value)` - Less than
- `lte(column, value)` - Less than or equal
### Logical
- `and(...conditions)` - AND
- `or(...conditions)` - OR
- `not(condition)` - NOT
### Pattern Matching
- `like(column, pattern)` - LIKE
- `notLike(column, pattern)` - NOT LIKE
### NULL
- `isNull(column)` - IS NULL
- `isNotNull(column)` - IS NOT NULL
### Arrays
- `inArray(column, values)` - IN
- `notInArray(column, values)` - NOT IN
### Between
- `between(column, min, max)` - BETWEEN
- `notBetween(column, min, max)` - NOT BETWEEN
---
## JOINs
```typescript
// LEFT JOIN
db.select()
.from(users)
.leftJoin(posts, eq(posts.authorId, users.id))
// INNER JOIN
db.select()
.from(users)
.innerJoin(posts, eq(posts.authorId, users.id))
// Multiple joins
db.select()
.from(comments)
.innerJoin(posts, eq(comments.postId, posts.id))
.innerJoin(users, eq(comments.authorId, users.id))
```
---
## Aggregations
```typescript
import { sql } from 'drizzle-orm';
// COUNT
db.select({ count: sql<number>`count(*)` }).from(users)
// SUM
db.select({ total: sql<number>`sum(${posts.views})` }).from(posts)
// AVG
db.select({ avg: sql<number>`avg(${posts.views})` }).from(posts)
// GROUP BY
db.select({
role: users.role,
count: sql<number>`count(*)`
}).from(users).groupBy(users.role)
```
---
## Relational Queries
```typescript
// Must pass schema to drizzle()
const db = drizzle(env.DB, { schema });
// Find many
db.query.users.findMany()
// Find first
db.query.users.findFirst({
where: eq(users.id, 1)
})
// With relations
db.query.users.findFirst({
with: {
posts: true
}
})
// Nested relations
db.query.users.findFirst({
with: {
posts: {
with: {
comments: true
}
}
}
})
```
---
## Batch Operations
```typescript
db.batch([
db.insert(users).values({ ... }),
db.update(posts).set({ ... }).where(eq(posts.id, 1)),
db.delete(comments).where(eq(comments.id, 1)),
])
```
---
## Prepared Statements
```typescript
const getUserById = db
.select()
.from(users)
.where(eq(users.id, sql.placeholder('id')))
.prepare();
// Execute
const user = await getUserById.get({ id: 1 });
```

187
references/schema-patterns.md Normal file
View File

@@ -0,0 +1,187 @@
# Schema Patterns
Complete reference for Drizzle schema definition with SQLite/D1.
---
## Column Types
### Text
```typescript
text('column_name')
text('column_name', { length: 255 }) // Max length (not enforced by SQLite)
```
### Integer
```typescript
integer('column_name') // JavaScript number
integer('column_name', { mode: 'number' }) // Explicit number (default)
integer('column_name', { mode: 'boolean' }) // Boolean (0/1)
integer('column_name', { mode: 'timestamp' }) // JavaScript Date
integer('column_name', { mode: 'timestamp_ms' }) // Milliseconds
```
### Real
```typescript
real('column_name') // Floating point
```
### Blob
```typescript
blob('column_name') // Binary data
blob('column_name', { mode: 'buffer' }) // Node.js Buffer
blob('column_name', { mode: 'json' }) // JSON as blob
```
---
## Constraints
### NOT NULL
```typescript
text('name').notNull()
```
### UNIQUE
```typescript
text('email').unique()
```
### DEFAULT (static)
```typescript
integer('status').default(0)
text('role').default('user')
```
### DEFAULT (dynamic)
```typescript
integer('created_at', { mode: 'timestamp' })
.$defaultFn(() => new Date())
```
### PRIMARY KEY
```typescript
integer('id').primaryKey()
integer('id').primaryKey({ autoIncrement: true })
```
### FOREIGN KEY
```typescript
integer('user_id')
.notNull()
.references(() => users.id)
// With cascade
integer('user_id')
.notNull()
.references(() => users.id, { onDelete: 'cascade' })
```
---
## Indexes
```typescript
export const users = sqliteTable(
'users',
{
id: integer('id').primaryKey({ autoIncrement: true }),
email: text('email').notNull().unique(),
name: text('name').notNull(),
},
(table) => {
return {
// Single column index
emailIdx: index('users_email_idx').on(table.email),
// Composite index
nameEmailIdx: index('users_name_email_idx').on(table.name, table.email),
};
}
);
```
---
## Relations
### One-to-Many
```typescript
export const usersRelations = relations(users, ({ many }) => ({
posts: many(posts),
}));
export const postsRelations = relations(posts, ({ one }) => ({
author: one(users, {
fields: [posts.authorId],
references: [users.id],
}),
}));
```
### Many-to-Many
```typescript
export const postsToTags = sqliteTable('posts_to_tags', {
postId: integer('post_id')
.notNull()
.references(() => posts.id),
tagId: integer('tag_id')
.notNull()
.references(() => tags.id),
});
export const postsRelations = relations(posts, ({ many }) => ({
postsToTags: many(postsToTags),
}));
export const tagsRelations = relations(tags, ({ many }) => ({
postsToTags: many(postsToTags),
}));
```
---
## TypeScript Types
```typescript
import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;
```
---
## Common Patterns
### Timestamps
```typescript
createdAt: integer('created_at', { mode: 'timestamp' })
.$defaultFn(() => new Date()),
updatedAt: integer('updated_at', { mode: 'timestamp' }),
```
### Soft Deletes
```typescript
deletedAt: integer('deleted_at', { mode: 'timestamp' }),
```
### JSON Fields
```typescript
// Option 1: text with JSON
metadata: text('metadata', { mode: 'json' }),
// Option 2: blob with JSON
settings: blob('settings', { mode: 'json' }),
```
### Enums (Text)
```typescript
role: text('role', { enum: ['user', 'admin', 'moderator'] }).notNull(),
```

127
references/wrangler-setup.md Normal file
View File

@@ -0,0 +1,127 @@
# Wrangler Setup for D1 and Drizzle
Complete guide to configuring Wrangler for D1 databases with Drizzle ORM.
---
## wrangler.jsonc Configuration
```jsonc
{
"name": "my-worker",
"main": "src/index.ts",
"compatibility_date": "2025-10-11",
// Node.js compatibility (recommended for Drizzle)
"compatibility_flags": ["nodejs_compat"],
// D1 database bindings
"d1_databases": [
{
// Binding name (used as env.DB in code)
"binding": "DB",
// Database name
"database_name": "my-database",
// Production database ID (from wrangler d1 create)
"database_id": "your-production-database-id",
// Local database ID (for development)
"preview_database_id": "local-db",
// Migrations directory (Drizzle generates here)
"migrations_dir": "./migrations"
}
]
}
```
---
## Environment Variables
Create `.env` file (never commit):
```bash
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_DATABASE_ID=your-database-id
CLOUDFLARE_D1_TOKEN=your-api-token
```
---
## Wrangler Commands
```bash
# Create database
wrangler d1 create my-database
# List databases
wrangler d1 list
# Database info
wrangler d1 info my-database
# Apply migrations (local)
wrangler d1 migrations apply my-database --local
# Apply migrations (remote)
wrangler d1 migrations apply my-database --remote
# Execute SQL directly (local)
wrangler d1 execute my-database --local --command="SELECT * FROM users"
# Execute SQL directly (remote)
wrangler d1 execute my-database --remote --command="SELECT * FROM users"
```
---
## Local vs Remote
**Local Development** (`--local`):
- Uses SQLite file in `.wrangler/state/v3/d1/`
- Fast, no network latency
- Data persists between `wrangler dev` sessions
- Perfect for development and testing
**Remote/Production** (`--remote`):
- Uses actual D1 database in Cloudflare
- Subject to rate limits
- Production data
- Use for staging/production environments
**Always test locally first!**
---
## Migration Workflow
```bash
# 1. Make schema changes in src/db/schema.ts
# 2. Generate migration
npm run db:generate # or: drizzle-kit generate
# 3. Apply to local database
npm run db:migrate:local # or: wrangler d1 migrations apply DB --local
# 4. Test locally
npm run dev
# 5. Deploy code
npm run deploy
# 6. Apply to production database
npm run db:migrate:remote # or: wrangler d1 migrations apply DB --remote
```
---
## Important Notes
1. **migrations_dir**: Must point to where Drizzle generates migrations (usually `./migrations`)
2. **Binding name**: Must match in wrangler.jsonc, Env interface, and code
3. **Local first**: Always test migrations locally before remote
4. **Never commit**: Never commit database IDs or API tokens to version control