Search the site

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

DATA

Database

Start on a SQLite file and move to Postgres or MySQL with one line.

Your models create their tables through dartvel db migrate.

ON THIS PAGE

Use SQLite locally

Connect to Postgres or MySQL

Read and write through your data models

Migrate production safely

Storage engine reference

Add a tenant column to existing rows

Seed data and inspect schemas

Status

Use SQLite locally

A web-server binary opens local SQLite automatically. To choose a different file, put DATABASE_URL in .env and the generated backend opens it for your data models, jobs and schedules.

# .env
DATABASE_URL=sqlite:dartvel.db

Copy code to clipboard

SQLite turns on WAL mode and foreign keys.

A binary from dartvel build web-server needs no DATABASE_URL. It keeps a SQLite file in dartvel_data beside itself, and DARTVEL_DATA_DIR moves that folder.

dartvel db migrate reads dartvel.database in pubspec.yaml, shown under the migrate section below.

Connect to Postgres or MySQL

Moving is one line. Set DATABASE_URL where the backend runs, and set the same engine as dartvel.database.provider so dartvel db migrate writes statements for it.

DATABASE_URL=postgres://shop:secret@db.internal/shop?sslmode=require

Copy code to clipboard

SQLite

DATABASE_URL: sqlite:path/to/file.db

dartvel.database.provider: sqlite

PostgreSQL

DATABASE_URL: postgres:// or postgresql://

dartvel.database.provider: postgres

MySQL and MariaDB

DATABASE_URL: mysql:// or mariadb://

dartvel.database.provider: mysql

sslmode defaults to prefer. It also takes disable, require, verify-ca and verify-full.

DATABASE_URL is read from the environment, then the supervisor's credentials, then .env, like any secret.

Web, worker and cron processes all open it, so they share your data, your jobs and your schedules.

Read and write through your data models

Every read and write goes through a data model. The same calls run on every engine above.

final Article article = Article(
  slug: 'hello-world',
  title: 'Hello, world',
  body: 'The first article.',
  tags: 'news',
  published: false,
  authorId: 'user-1',
  editorNotes: 'Check the title',
);
await article.save();

final List<Article> all = await Article.all();
final Article? found = await Article.find('hello-world');

final Article published = await found!.copyWith(published: true).save();
await published.destroy();

Copy code to clipboard

Use the generated data model for every create, update and delete. Storage configuration belongs to the framework.

Create tables with dartvel db migrate

dartvel db migrate            # apply to the SQLite file
dartvel db migrate --plan     # classify each change, apply none
dartvel db migrate --dry-run  # plan and gate, apply nothing

Copy code to clipboard

Generation writes each model's schema. You write no migration files.

On SQLite it creates missing tables and adds missing columns. It never drops a column.

On Postgres and MySQL it writes .dart_tool/dartvel_migration.sql for you to apply.

# pubspec.yaml
dartvel:
  database:
    provider: sqlite     # the default
    path: dartvel.db     # the default

Copy code to clipboard

Migrate production safely

dartvel db migrate --production
dartvel db migrate --dry-run --against snapshot
dartvel db migrate --production --allow-blocking="backfill window"

Copy code to clipboard

--production refuses a blocking change unless you pass --allow-blocking with a reason.

The reason is logged to .dartvel/db/schema_overrides.jsonl.

--against snapshot rehearses against .dartvel/db/production.snapshot.json.

Partial

Spec section: Schema Evolution

Planned work and implementation limits

No command captures a production snapshot yet.

Expand and contract steps are planned, and not run as SQL.

Storage engine reference

Application data is read and written through generated data models. The framework keeps storage engine contracts behind those calls.

Partial

Spec section: Storage-Neutral Records

Planned work and implementation limits

Routing generated data models through the storage-neutral engine contract is Planned. The SQLite, Postgres and MySQL data model paths are built.

A MongoDB engine is Planned.

Add a tenant column to existing rows

dartvel db migrate --tenant acme

Copy code to clipboard

Adding tenantScoped: true to a model with rows needs to know whose rows they are. --orphan-existing-rows hides them instead, for a staging database.

Seed data and inspect schemas

dartvel db seed          # runs lib/database/seed.dart or tool/seed.dart
dartvel db pull --local  # suggests @DVModel classes from drift, isar or sqflite

Copy code to clipboard

Status

Built

Spec section: Database

Implementation notes

dartvel db migrate applies changes to SQLite only.

FSL-1.1-MIT licensed. Built with Dartvel.

Dartvel is made by

To the bottom