Versioning

FumaDB uses your code as version control. Automatic database migration works by comparing your schemas, which is more accurate than introspecting databases.

Update Schema

Schema is immutable. To update your schema:

1. establish a new version by copying the old schema file.
2. update the version field and perform other changes.
3. append it to the schemas array.

import { fumadb } from "fumadb";
import { v1 } from "@/schema/v1";
import { v2 } from "@/schema/v2";

const ChatDB = fumadb({
  namespace: "fuma-chat",
  schemas: [v1, v2],
});

Schema Version

The version field follows semantic versioning and always starts from 1.0.0.

export const v1 = schema({
  version: "1.0.0",
});

A new major version indicates the database migration may interrupt a running production server, this happens when:

• Renaming columns & tables.
• Updating column data type, foreign constraint, unique index.
• Data Loss: Dropping tables & columns.

Rules

There's some rules when updating your schema.

Adding Column

Either make it nullable or specify a default value.

import { table, column, idColumn } from "fumadb/schema";

export const users = table("users", {
  id: idColumn("id", "varchar(255)", { default: "auto" }),
  name: column("name", "string"),
  email: column("email", "string", { nullable: true }),
});

Updating Column

• Do not change the ID column of a table: including its name, data type, etc.
• Avoid changing data types of columns: There could be edge cases that the database cannot convert existing column values.
• Avoid renaming tables/columns: Even if you do, only update the database name instead of column name, otherwise automatic migration may fails.

import { table, column, idColumn } from "fumadb/schema";

export const users = table("users", {
  id: idColumn("id", "varchar(255)", { default: "auto" }),
  // avoid:
  name: column("name", "varchar(255)"),
  username: column("name", "varchar(255)"),
  // instead:
  name: column("name", "varchar(255)"),
  name: column("username", "varchar(255)"),
});