drizzle-orm-d1
| Type-safe ORM for Cloudflare D1 databases using Drizzle. Use when: building D1 database schemas, writing type-safe SQL queries, managing migrations with Drizzle Kit, defining table relations, implementing prepared statements, using D1 batch API, or encountering D1_ERROR, transaction errors, foreign key constraint failures, or schema inference issues.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- drizzle-orm-d1
- license
- MIT
- metadata
- { "keywords": [ "drizzle orm", "drizzle d1", "type-safe sql", "drizzle schema", "drizzle migrations", "drizzle kit", "orm cloudflare", "d1 orm", "drizzle typescript", "drizzle relations", "drizzle transactions", "drizzle query builder", "schema definition", "prepared statements", "drizzle batch", "migration management", "relational queries", "drizzle joins", "D1_ERROR", "BEGIN TRANSACTION d1", "foreign key constraint", "migration failed", "schema not found", "d1 binding error", "schema design", "database indexes", "soft deletes", "uuid primary keys", "enum constraints", "performance optimization", "naming conventions", "schema testing" ] }
- description
- | Type-safe ORM for Cloudflare D1 databases using Drizzle. Use when: building D1 database schemas, writing type-safe SQL queries, managing migrations with Drizzle Kit, defining table relations, implementing prepared statements, using D1 batch API, or encountering D1_ERROR, transaction errors, foreign key constraint failures, or schema inference issues.
02 资源文件 19
- 参考文档references/common-errors.md5.3 KB
- 参考文档references/error-catalog.md7.9 KB
- 参考文档references/links-to-official-docs.md1.8 KB
- 参考文档references/migration-workflow.md2.7 KB
- 参考文档references/query-builder-api.md3.9 KB
- 参考文档references/schema-patterns.md3.4 KB
- 参考文档references/wrangler-setup.md2.7 KB
- 脚本scripts/check-versions.sh1017 B
- 脚本templates/basic-queries.ts7.5 KB
- 脚本templates/basic-schema.ts2.9 KB
- 脚本templates/client.ts2.2 KB
- 脚本templates/cloudflare-worker-integration.ts7.7 KB
- 脚本templates/drizzle.config.ts2.2 KB
- 其他templates/migrations/0001_example.sql2.1 KB
- 参考文档templates/package.json1.1 KB
- 脚本templates/prepared-statements.ts7.3 KB
- 脚本templates/relations-queries.ts6.8 KB
- 脚本templates/schema.ts6.5 KB
- 脚本templates/transactions.ts6.8 KB
03 SKILL.md 正文
Drizzle ORM for Cloudflare D1
Status: Production Ready ✅ Last Updated: 2025-12-14 Latest Version: drizzle-orm@0.44.7, drizzle-kit@0.31.7 Dependencies: cloudflare-d1, cloudflare-worker-base
Quick Start (10 Minutes)
1. Install Drizzle
bun add drizzle-orm drizzle-kit
2. Configure Drizzle Kit
Create drizzle.config.ts:
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
schema: './src/db/schema.ts',
out: './migrations',
dialect: 'sqlite',
driver: 'd1-http',
dbCredentials: {
accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
token: process.env.CLOUDFLARE_D1_TOKEN!,
},
});
3. Define Schema
Create src/db/schema.ts:
import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { relations } from 'drizzle-orm';
export const users = sqliteTable('users', {
id: integer('id').primaryKey({ autoIncrement: true }),
email: text('email').notNull().unique(),
name: text('name').notNull(),
createdAt: integer('created_at', { mode: 'timestamp' }).$defaultFn(() => new Date()),
});
export const posts = sqliteTable('posts', {
id: integer('id').primaryKey({ autoIncrement: true }),
title: text('title').notNull(),
content: text('content').notNull(),
authorId: integer('author_id')
.notNull()
.references(() => users.id, { onDelete: 'cascade' }),
});
export const usersRelations = relations(users, ({ many }) => ({
posts: many(posts),
}));
4. Generate & Apply Migrations
bunx drizzle-kit generate # Generate SQL
bunx wrangler d1 migrations apply my-database --local # Apply local
bunx wrangler d1 migrations apply my-database --remote # Apply prod
5. Query in Worker
import { drizzle } from 'drizzle-orm/d1';
import { users } from './db/schema';
import { eq } from 'drizzle-orm';
export default {
async fetch(request: Request, env: { DB: D1Database }): Promise<Response> {
const db = drizzle(env.DB);
const allUsers = await db.select().from(users).all();
return Response.json(allUsers);
},
};
Critical Rules
Always Do
| Rule | Why |
|---|---|
Use drizzle-kit generate for migrations |
Never write SQL manually |
| Test migrations locally first | --local before --remote |
Use .get() for single results |
Returns first row or undefined |
Use db.batch() for transactions |
D1 doesn't support SQL BEGIN/COMMIT |
Use integer with mode: 'timestamp' for dates |
D1 has no native date type |
Use .$defaultFn() for dynamic defaults |
Not .default() for functions |
Never Do
| Rule | Why |
|---|---|
Use SQL BEGIN TRANSACTION |
D1 requires batch API (Error #1) |
Mix drizzle-kit migrate and wrangler apply |
Use Wrangler only |
Use drizzle-kit push for production |
Use generate + apply |
| Commit credentials in drizzle.config.ts | Use env vars |
Use .default() for function calls |
Use .$defaultFn() instead |
Top 5 Critical Errors
| # | Error | Solution |
|---|---|---|
| 1 | D1_ERROR: Cannot use BEGIN TRANSACTION |
Use db.batch([...]) instead of db.transaction() |
| 2 | FOREIGN KEY constraint failed |
Define cascading: .references(() => users.id, { onDelete: 'cascade' }) |
| 3 | env.DB is undefined |
Ensure binding in wrangler.jsonc matches env.DB |
| 4 | No such module "wrangler" |
Use import { drizzle } from 'drizzle-orm/d1' |
| 5 | Type instantiation excessively deep |
Use InferSelectModel<typeof users> for explicit types |
See: references/error-catalog.md for all 12 errors with complete solutions.
Common Patterns Summary
| Pattern | Use Case | Template |
|---|---|---|
| CRUD Operations | Basic database operations | templates/basic-queries.ts |
| Relations & Joins | Nested queries, manual joins | templates/relations-queries.ts |
| Batch Operations | Transactions (D1 batch API) | templates/transactions.ts |
| Schema Design | Naming, indexes, soft deletes | references/schema-patterns.md |
Configuration Summary
| File | Purpose | Template |
|---|---|---|
drizzle.config.ts |
Drizzle Kit configuration | templates/drizzle.config.ts |
wrangler.jsonc |
D1 binding setup | references/wrangler-setup.md |
package.json |
npm scripts for migrations | templates/package.json |
npm scripts:
{
"db:generate": "drizzle-kit generate",
"db:migrate:local": "wrangler d1 migrations apply my-database --local",
"db:migrate:remote": "wrangler d1 migrations apply my-database --remote"
}
Migration Workflow
| Step | Command | Notes |
|---|---|---|
| 1. Edit schema | Edit src/db/schema.ts |
Make changes |
| 2. Generate | npm run db:generate |
Creates SQL migration |
| 3. Test local | npm run db:migrate:local |
Verify locally |
| 4. Deploy code | npm run deploy |
Push to Cloudflare |
| 5. Apply prod | npm run db:migrate:remote |
Apply migration |
See: references/migration-workflow.md for complete workflow.
TypeScript Type Inference
import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
import { users } from './db/schema';
export type User = InferSelectModel<typeof users>;
export type NewUser = InferInsertModel<typeof users>;
When to Load References
| Reference | Load When... |
|---|---|
references/error-catalog.md |
Debugging D1 errors, transaction failures, binding issues |
references/schema-patterns.md |
Designing schemas, naming conventions, indexes, soft deletes |
references/migration-workflow.md |
Setting up or troubleshooting migrations |
references/query-builder-api.md |
Complex queries, operators, joins syntax |
references/wrangler-setup.md |
Configuring wrangler.jsonc for D1 |
references/common-errors.md |
Quick error lookup |
Bundled Resources
Templates: basic-schema.ts, basic-queries.ts, transactions.ts, relations-queries.ts, prepared-statements.ts, drizzle.config.ts, package.json
References: error-catalog.md, schema-patterns.md, migration-workflow.md, query-builder-api.md, wrangler-setup.md, common-errors.md, links-to-official-docs.md
Dependencies
{
"dependencies": {
"drizzle-orm": "^0.44.7"
},
"devDependencies": {
"drizzle-kit": "^0.31.7"
}
}
Secure Installation
When installing Drizzle ORM and D1 driver packages, follow supply chain security best practices:
- Block post-install scripts —
npm config set ignore-scripts true(or Bun: disabled by default) - Cooldown period — Wait 7 days for new package versions to be vetted by the community
- Audit before installing — Run
socket package score npm <pkg>or usesocket npm install <pkg>to check packages
Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
Official Documentation
- Drizzle ORM: https://orm.drizzle.team/
- Drizzle with D1: https://orm.drizzle.team/docs/connect-cloudflare-d1
- Drizzle Kit: https://orm.drizzle.team/docs/kit-overview
- GitHub: https://github.com/drizzle-team/drizzle-orm
Token Savings: ~65% (comprehensive patterns in references) Error Prevention: 100% (all 12 documented issues) Ready for production! ✅
04 同仓库更多 Skills
vss-summarize-video
Use to summarize a recorded video via the LVS summarization microservice (HITL-gated) with a VLM fallback. Not for report generation or live RTSP captioning.
vss-setup-video-analytics-api
Use to deploy the vss-video-analytics-api REST service standalone (config-source, data-log bind, Elasticsearch, optional Kafka). Not for full warehouse deploy.
vss-setup-behavior-analytics
Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.
vss-search-archive
Use this skill to run top-level VSS fusion search on archived video, or to ingest video files / RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).
vss-query-analytics
Use this skill when reading video-analytics metrics, incidents, alerts, and sensor data via the VA-MCP server (port 9901). Not for live VLM or incident-range narrative reports.
vss-manage-video-io-storage
Use to call the VIOS REST API (sensor list, timelines, clip extraction, snapshots, add/delete sensors and streams). Not for VLM inference or search.