🎸

Using Superflare

Models (D1)

Models are a handy way to interact with your D1 database. They provide a layer of abstraction between your database and your application, allowing you to define relationships between models and easily query for data.

Superflare provides a schema builder which is a wrapper around native D1 migrations. This allows you to define your database schema using a fluent API, and then automatically generate models and type definitions for your database tables.

import { Schema } from "superflare";

export default () => {
  return Schema.create("posts", (table) => {
    table.increments("id");
    table.string("title");
    table.timestamps();
  });
};

When you run npx superflare migrate, Superflare will compile a TypeScript migration to a SQL migration file which is used by Wrangler to modify your D1 database:

create table posts (
  id integer primary key,
  title text not null,
  createdAt timestamp not null default current_timestamp
  updatedAt timestamp not null default current_timestamp
);

Models are defined as TypeScript classes. Model class names correspond directly to the table names in the database. For example, a posts table would have a corresponding Post model:

import { Model } from "superflare";

export class Post extends Model {
  toJSON(): PostRow {
    return super.toJSON();
  }
}

Model.register(Post);

export interface Post extends PostRow {}

Model class names

Model class names are automatically converted to pluralized versions when referencing table names. For example, a Post model would have a corresponding posts table, and a Person model would have a corresponding people table.

Superflare provides utilities to help you keep your model's type definition in sync with your database.

Type definitions are created as an interface for each model and stored in superflare.env.d.ts. For example, the Post model will have a corresponding PostRow interface defined by Superflare.

Autogenerated types

Do not manually modify any code within superflare.env.d.ts. It is automatically generated by Superflare and will be overwritten when you run npx superflare migrate.

When you migrate your database, Superflare will automatically update your interfaces to match the new database schema.

npx superflare migrate

When you create a new table in a migration, you can run the following command to generate a new corresponding model for the table with types:

npx superflare migrate --create

Generated types on build

superflare.env.d.ts is gitignored by default. When running your Superflare app in a CI environment, you should run npx superflare migrate before attempting to build the project to prevent TypeScript errors.

Registering Models

You must call Model.register after defining each model. This is how Superflare knows which models to load when you run Jobs and other background tasks.

Creating Models

You can create a new model by running the following command:

npx superflare generate model Post

By default, a new model will be created in the app/models directory. You can change this by passing the --path flag:

npx superflare generate model Post --path app/my-models

You can also create a migration for your new model at the same time by passing the --migration or -m flag:

npx superflare generate model Post --migration

Using Models

Learn more about using Superflare models

Previous
Design Principles