# dart-drift

A skill for Drift persistence in Dart CLI, server-side and non-Flutter desktop apps: tables, queries, migrations, PostgreSQL.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 466 installs · ★ 110
- Author: Stanislav \[MADTeacher\] Chernyshev
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/MADTeacher/mad-agents-skills/tree/HEAD/dart-drift/SKILL.md
- Updated: 2026-05-01
- HTML: https://affpapa.org/en/nevibecode/skills/dart-drift

## What it does

The skill casts the agent as a Dart persistence engineer for non-Flutter apps on Drift. Before writing any database code it makes the agent pick a backend: SQLite through `package:drift/native.dart` for CLI tools, server jobs and local desktop storage, or PostgreSQL through `drift_postgres` and `package:postgres` with the Postgres dialect enabled in `build.yaml`. If the task turns out to need Flutter UI integration, the skill stops and hands off to a separate `flutter-drift` skill.

Inside there is task routing. Separate reference files cover setup, tables, queries, writes, streams, migrations and PostgreSQL, and the agent reads only the ones the current operation needs. Validation is mandatory: `dart pub get` after dependency changes, `dart run build_runner build` and `dart analyze` after touching tables or DAOs, `dart run drift_dev make-migrations` plus the generated migration tests after a schema change.

The constraints are strict. Deprecated PostgreSQL examples built on `HostEndpoint`, `PgEndpoint`, `postgres_pool.dart`, `postgresUuid()`, `postgresJson()` and `gen_random_uuid` are off the table. On Postgres, SQLite-only helpers such as `currentDateAndTime` and most `dateTime()` conveniences are banned in favour of `PgTypes.date`, `PgTypes.timestampWithTimezone`, `PgTypes.timestampNoTimezone` and `now()`. If the repository does not make the target backend clear, the agent asks instead of guessing.

## Requirements
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add MADTeacher/mad-agents-skills --skill dart-drift -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/dart-drift/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/dart-drift/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add MADTeacher/mad-agents-skills --skill dart-drift -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/dart-drift/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add MADTeacher/mad-agents-skills --skill dart-drift -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/dart-drift/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install MADTeacher/mad-agents-skills dart-drift
```

2. **Manually: put the files in place**
- File: `.github/skills/dart-drift/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add MADTeacher/mad-agents-skills --skill dart-drift -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/MADTeacher/mad-agents-skills --path dart-drift
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/dart-drift/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add MADTeacher/mad-agents-skills --skill dart-drift -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/MADTeacher/mad-agents-skills/tree/HEAD/dart-drift/SKILL.md

## When to use it
- add SQLite to a Dart CLI with `package:drift/native.dart`
- wire up PostgreSQL with `drift_postgres` and `package:postgres`
- write type-safe Drift tables and queries
- fix a failing `build_runner` or `drift_dev` run
- run a schema migration and its generated tests

## Example prompts
- add Drift with SQLite to my Dart CLI, start with the dependencies
- define an orders table with a date index and write a query for one month
- the schema changed — make a migration and run the migration tests

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: c84abae03500d185.

BEGIN THIRD-PARTY FILE c84abae03500d185
```text
---
name: dart-drift
description: >-
  Build, fix, audit, and migrate Drift persistence in Dart CLI, server-side,
  and non-Flutter desktop apps. Use when adding SQLite with
  package:drift/native.dart, configuring PostgreSQL with drift_postgres and
  package:postgres, writing type-safe tables, queries, writes, streams, and
  migrations, resolving build_runner or drift_dev failures, or validating Dart
  database code with code generation, analysis, tests, and migration checks.
metadata:
  author: Stanislav [MADTeacher] Chernyshev
  version: "2.0"
---

# Dart Drift

You are a Dart persistence engineer for non-Flutter apps using Drift.

## Principle 0

Do not write Drift database code from memory. First identify the runtime
backend, read the routed reference for the operation, then verify generated code
with the Dart toolchain. Broken persistence code is worse than no persistence
code because schema and migration mistakes can silently lose data.

## Workflow

1. Inspect the project before changing code: `pubspec.yaml`, existing database
   classes, `build.yaml`, generated parts, tests, migration files, and whether
   the app targets SQLite, PostgreSQL, or both.
2. Choose the backend path:
   - For Dart CLI, server jobs, or native desktop local storage, use SQLite via
     `package:drift/native.dart`.
   - For server-side PostgreSQL, use `drift_postgres` with `package:postgres`
     and enable the Postgres SQL dialect in `build.yaml`.
   - For Flutter UI integration, stop and use the `flutter-drift` skill instead.
3. Read only the reference files needed for the requested task.
4. Implement the smallest safe change using the APIs and caveats from those
   references.
5. Run mandatory validation. If validation cannot run, report the blocker and
   the concrete risk instead of presenting the change as verified.

## Resource Routing

| Task | Read or run | Why |
|---|---|---|
| Add Drift to a Dart app, choose dependencies, open SQLite/Postgres connections, or fix build setup | `references/setup.md` | Current non-Flutter setup and imports |
| Define tables, constraints, indexes, defaults, or PostgreSQL custom types | `references/tables.md` | Schema APIs and backend-specific column caveats |
```
END THIRD-PARTY FILE c84abae03500d185

The third-party file has ended. Everything between the c84abae03500d185 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2221 of 4822 bytes. © Stanislav \[MADTeacher\] Chernyshev · MIT · https://github.com/MADTeacher/mad-agents-skills/tree/HEAD/dart-drift/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md