wasp/web/docs/data-model/backends.md

title
Databases

import { Required } from '@site/src/components/Tag'

Entities, Operations and Automatic CRUD together make a high-level interface for working with your app's data. Still, all that data has to live somewhere, so let's see how Wasp deals with databases.

Supported Database Backends

Wasp supports multiple database backends. We'll list and explain each one.

SQLite

The default database Wasp uses is SQLite.

SQLite is a great way for getting started with a new project because it doesn't require any configuration, but Wasp can only use it in development. Once you want to deploy your Wasp app to production, you'll need to switch to PostgreSQL and stick with it.

Fortunately, migrating from SQLite to PostgreSQL is pretty simple, and we have a guide to help you.

PostgreSQL

PostgreSQL is the most advanced open-source database and one of the most popular databases overall. It's been in active development for 20+ years. Therefore, if you're looking for a battle-tested database, look no further.

To use Wasp with PostgreSQL, you'll have to ensure a database instance is running during development. Wasp needs access to your database for commands such as wasp start or wasp db migrate-dev and expects to find a connection string in the DATABASE_URL environment variable.

We cover all supported ways of connecting to a database in the next section.

Migrating from SQLite to PostgreSQL

To run your Wasp app in production, you'll need to switch from SQLite to PostgreSQL.

1. Set the app.db.system field to PostgreSQL.

app MyApp {
  title: "My app",
  // ...
  db: {
    system: PostgreSQL,
    // ...
  }
}

2. Delete all the old migrations, since they are SQLite migrations and can't be used with PostgreSQL, as well as the SQLite database by running wasp clean:

rm -r migrations/
wasp clean

3. Ensure your new database is running (check the section on connecting to a database to see how). Leave it running, since we need it for the next step.
4. In a different terminal, run wasp db migrate-dev to apply the changes and create a new initial migration.
5. That is it, you are all done!

Connecting to a Database

Assuming you're not using SQLite, Wasp offers two ways of connecting your app to a database instance:

1. A ready-made dev database that requires minimal setup and is great for quick prototyping.
2. A "real" database Wasp can connect to and use in production.

Using the Dev Database Provided by Wasp

The command wasp start db will start a default PostgreSQL dev database for you.

Your Wasp app will automatically connect to it, just keep wasp start db running in the background. Also, make sure that:

• You have Docker installed and in PATH.
• The port 5432 isn't taken.

Connecting to an existing database

If you want to spin up your own dev database (or connect to an external one), you can tell Wasp about it using the DATABASE_URL environment variable. Wasp will use the value of DATABASE_URL as a connection string.

The easiest way to set the necessary DATABASE_URL environment variable is by adding it to the .env.server file in the root dir of your Wasp project (if that file doesn't yet exist, create it).

Alternatively, you can set it inline when running wasp (this applies to all environment variables):

DATABASE_URL=<my-db-url> wasp ...

This trick is useful for running a certain wasp command on a specific database. For example, you could do:

DATABASE_URL=<production-db-url> wasp db seed myProductionSeed

This command seeds the data for a fresh staging or production database. To more precisely understand how seeding works, keep reading.

Seeding the Database

Database seeding is a term used for populating the database with some initial data.

Seeding is most commonly used for two following scenarios:

1. To put the development database into a state convenient for working and testing.
2. To initialize any database (dev, staging, or prod) with essential data it requires to operate. For example, populating the Currency table with default currencies, or the Country table with all available countries.

Writing a Seed Function

You can define as many seed functions as you want in an array under the app.db.seeds field:

app MyApp {
  // ...
  db: {
    // ...
    seeds: [
      import { devSeedSimple } from "@src/dbSeeds.js",
      import { prodSeed } from "@src/dbSeeds.js"
    ]
  }
}

app MyApp {
  // ...
  db: {
    // ...
    seeds: [
      import { devSeedSimple } from "@src/dbSeeds.js",
      import { prodSeed } from "@src/dbSeeds.js"
    ]
  }
}

Each seed function must be an async function that takes one argument, prisma, which is a Prisma Client instance used to interact with the database. This is the same Prisma Client instance that Wasp uses internally and thus includes all of the usual features (e.g., password hashing).

Since a seed function falls under server-side code, it can import other server-side functions. This is convenient because you might want to seed the database using Actions.

Here's an example of a seed function that imports an Action:

import { createTask } from './actions.js'
import { sanitizeAndSerializeProviderData } from 'wasp/server/auth'

export const devSeedSimple = async (prisma) => {
  const user = await createUser(prisma, {
    username: 'RiuTheDog',
    password: 'bark1234',
  })

  await createTask(
    { description: 'Chase the cat' },
    { user, entities: { Task: prisma.task } }
  )
}

async function createUser(prisma, data) {
  const newUser = await prisma.user.create({
    data: {
      auth: {
        create: {
          identities: {
            create: {
              providerName: 'username',
              providerUserId: data.username,
              providerData: sanitizeAndSerializeProviderData({
                hashedPassword: data.password
              }),
            },
          },
        },
      },
    },
  })

  return newUser
}

import { createTask } from './actions.js'
import { sanitizeAndSerializeProviderData } from 'wasp/server/auth'
import { type AuthUser } from 'wasp/auth'
import { PrismaClient } from '@prisma/client'

export const devSeedSimple = async (prisma: PrismaClient) => {
  const user = await createUser(prisma, {
    username: 'RiuTheDog',
    password: 'bark1234',
  })

  await createTask(
    { description: 'Chase the cat', isDone: false },
    { user, entities: { Task: prisma.task } }
  )
};

async function createUser(
  prisma: PrismaClient,
  data: { username: string, password: string }
): Promise<AuthUser> {
  const newUser = await prisma.user.create({
    data: {
      auth: {
        create: {
          identities: {
            create: {
              providerName: 'username',
              providerUserId: data.username,
              providerData: sanitizeAndSerializeProviderData<'username'>({
                hashedPassword: data.password
              }),
            },
          },
        },
      },
    },
  })

  return newUser
}

Running seed functions

Run the command wasp db seed and Wasp will ask you which seed function you'd like to run (if you've defined more than one).

Alternatively, run the command wasp db seed <seed-name> to choose a specific seed function right away, for example:

wasp db seed devSeedSimple

Check the API Reference for more details on these commands.

:::tip You'll often want to call wasp db seed right after you run wasp db reset, as it makes sense to fill the database with initial data after clearing it. :::

Prisma Configuration

Wasp uses Prisma to interact with the database. Prisma is a "Next-generation Node.js and TypeScript ORM" that provides a type-safe API for working with your database.

Prisma Preview Features

Prisma is still in active development and some of its features are not yet stable. To use them, you have to enable them in the app.db.prisma.clientPreviewFeatures field:

app MyApp {
  // ...
  db: {
    system: PostgreSQL,
    prisma: {
      clientPreviewFeatures: ["postgresqlExtensions"]
    }
  }
}

Read more about Prisma preview features in the Prisma docs.

PostgreSQL Extensions

PostgreSQL supports extensions that add additional functionality to the database. For example, the hstore extension adds support for storing key-value pairs in a single column.

To use PostgreSQL extensions with Prisma, you have to enable them in the app.db.prisma.dbExtensions field:

app MyApp {
  // ...
  db: {
    system: PostgreSQL,
    prisma: {
      clientPreviewFeatures: ["postgresqlExtensions"]
      dbExtensions: [
        { name: "hstore", schema: "myHstoreSchema" },
        { name: "pg_trgm" },
        { name: "postgis", version: "2.1" },
      ]
    }
  }
}

Read more about PostgreSQL configuration in Wasp in the API Reference.

API Reference

You can tell Wasp which database to use in the app declaration's db field:

The app.db Field

Here's an example that uses the app.db field to its full potential:

app MyApp {
  title: "My app",
  // ...
  db: {
    system: PostgreSQL,
    seeds: [
      import devSeed from "@src/dbSeeds.js"
    ],
    prisma: {
      clientPreviewFeatures: ["extendedWhereUnique"]
    }
  }
}

app MyApp {
  title: "My app",
  // ...
  db: {
    system: PostgreSQL,
    seeds: [
      import devSeed from "@src/dbSeeds.js"
    ],
    prisma: {
      clientPreviewFeatures: ["extendedWhereUnique"]
    }
  }
}

app.db is a dictionary with the following fields (all fields are optional):

• system: DbSystem

  The database system Wasp should use. It can be either PostgreSQL or SQLite. The default value for the field is SQLite (this default value also applies if the entire db field is left unset). Whenever you modify the db.system field, make sure to run wasp db migrate-dev to apply the changes.

• seeds: [ExtImport]

  Defines the seed functions you can use with the wasp db seed command to seed your database with initial data. Read the Seeding section for more details.

• prisma: PrismaOptions

  Additional configuration for Prisma.

  app MyApp {
    // ...
    db: {
      // ...
      prisma: {
        clientPreviewFeatures: ["postgresqlExtensions"],
        dbExtensions: [
          { name: "hstore", schema: "myHstoreSchema" },
          { name: "pg_trgm" },
          { name: "postgis", version: "2.1" },
        ]
      }
    }
  }
  

  It's a dictionary with the following fields:

  • clientPreviewFeatures : [string]

    Allows you to define Prisma client preview features, like for example, "postgresqlExtensions".

  • dbExtensions: DbExtension[]

    It allows you to define PostgreSQL extensions that should be enabled for your database. Read more about PostgreSQL extensions in Prisma.

    For each extension you define a dict with the following fields:

    • name: string

      The name of the extension you would normally put in the Prisma file.

      extensions = [hstore(schema: "myHstoreSchema"), pg_trgm, postgis(version: "2.1")]
      //              👆 Extension name
      

    • map: string

      It sets the map argument of the extension. Explanation for the field from the Prisma docs:

      This is the database name of the extension. If this argument is not specified, the name of the extension in the Prisma schema must match the database name.

    • schema: string

      It sets the schema argument of the extension. Explanation for the field from the Prisma docs:

      This is the name of the schema in which to activate the extension's objects. If this argument is not specified, the current default object creation schema is used.

    • version: string

      It sets the version argument of the extension. Explanation for the field from the Prisma docs:

      This is the version of the extension to activate. If this argument is not specified, the value given in the extension's control file is used.

CLI Commands for Seeding the Database

Use one of the following commands to run the seed functions:

• wasp db seed

  If you've only defined a single seed function, this command runs it. If you've defined multiple seed functions, it asks you to choose one interactively.

• wasp db seed <seed-name>

  This command runs the seed function with the specified name. The name is the identifier used in its import expression in the app.db.seeds list. For example, to run the seed function devSeedSimple which was defined like this:

  app MyApp {
    // ...
    db: {
      // ...
      seeds: [
        // ...
        import { devSeedSimple } from "@src/dbSeeds.js",
      ]
    }
  }
  

  app MyApp {
    // ...
    db: {
      // ...
      seeds: [
        // ...
        import { devSeedSimple } from "@src/dbSeeds.js",
      ]
    }
  }
  

  Use the following command:

  wasp db seed devSeedSimple