Prisma

Before you start

Use this recipe in the server project from the custom-server quick start or your existing backend. Make the database and storage environment variables available to the server and schema commands. The React Native project's deploy configuration is a separate step.

prismaAdapter supports PostgreSQL, MySQL 8.0.17 or later, and SQLite. CockroachDB and SQL Server are not supported.

Installation

Install Prisma and initialize your project.

npm install @hot-updater/server @hot-updater/aws @prisma/client@6.19.3

npm install --save-dev hot-updater prisma@6.19.3 dotenv

Initialize Prisma:

npx prisma@6.19.3 init --datasource-provider sqlite --generator-provider prisma-client-js --output ../src/generated/prisma
npx prisma generate

The explicit output generates the client in src/generated/prisma. Generate it before creating src/prisma.ts; the Hot Updater schema command loads that module while preparing the managed models.

For other databases, see Prisma's database documentation.

Setup

Create a database connection file:

import { PrismaClient } from "./generated/prisma";

export const prisma = new PrismaClient();

Hot Updater configuration

Create the Hot Updater instance:

import { createHotUpdater } from "@hot-updater/server";
import { prismaAdapter } from "@hot-updater/server/adapters/prisma"; 
import { apiKeys, insights } from "@hot-updater/server/plugins";
import { s3Storage } from "@hot-updater/aws";
import { prisma } from "./prisma";

export const hotUpdater = createHotUpdater({
  database: prismaAdapter({ prisma, provider: "sqlite" }), 
  plugins: [insights(), apiKeys()],
  storage: s3Storage({
    region: "auto",
    endpoint: process.env.R2_ENDPOINT,
    credentials: {
      accessKeyId: process.env.R2_ACCESS_KEY_ID!,
      secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    },
    bucketName: process.env.R2_BUCKET_NAME!,
  }),
});

prismaAdapter({ prisma, provider }) takes only these two options. It returns an engine database with the schema generator and migrator that hot-updater db runs. provider is "postgresql", "mysql" or "sqlite" and must match the Prisma datasource. The adapter runs Hot Updater's shared SQL core through Prisma's raw queries and interactive transactions. insights() records app events, and apiKeys() protects the client routes with the x-api-key header.

Schema generation

Generate the Prisma schema for Hot Updater tables.

npx hot-updater db generate src/hotUpdater.ts --yes

This command creates prisma/schema.prisma when it is missing or merges the Hot Updater models into the existing schema, between the BEGIN HOT-UPDATER MODELS and END HOT-UPDATER MODELS comments. The models cover core's tables and those of the server's plugins. The models have keys and named indexes and no relations. Fields whose column starts with an underscore get a hu prefix and map back to the column, such as hu_v to _v. On MySQL, ASCII key columns are VarBinary, which keeps every key within InnoDB's limit. Keep the generated models instead of replacing them with a handwritten schema.

Regenerate Prisma Client, apply the merged schema, then finish the migration:

npx prisma generate
npx prisma db push
npx hot-updater db migrate src/hotUpdater.ts --yes

Prisma creates the tables, or prisma migrate does when you use migrations. db migrate then sets the collations Prisma cannot declare on PostgreSQL and MySQL, so strings compare by their bytes, and writes the settings rows. It asks you to apply the tables first when they are missing, and it refuses a database created by an older Hot Updater schema instead of converting it.

The server checks the settings rows before its first read or write. Until they exist, it throws HotUpdaterSchemaMigrationRequiredError and its handlers answer 503. A running server checks again on its next request. Run the same steps again after upgrading Hot Updater.

CLI configuration

After the schema is applied, create the client API key using this same direct server configuration. Then connect the React Native project's CLI to the protected admin mount. Its storage configuration must match a server entry, and its plugins must list the server's plugins.

API endpoints

The adapter persists data; your framework mounts the HTTP handlers. Continue with the Hono, Express or Elysia recipe. See the handler boundaries and repository contract for client and admin access.

Finish with Set up your app and Test an OTA update.