---
title: "New databases"
description: "Start a new SurrealDB project with SurrealKit from the beginning, writing schema files and syncing to a local database."
canonical_url: "https://surrealdb.com/docs/operate/schema-migration/getting-started/new-databases"
section: "SurrealKit schema migration"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# New databases

Start a new SurrealDB project with SurrealKit from the beginning, writing schema files and syncing to a local database.

If you are starting a new project, SurrealKit can manage your schema from the very first definition. This guide walks through initialising a project, writing your first schema file, and pushing it to a local SurrealDB instance.

## 1. Initialise the project

In the root of your repository, run:

```bash
surrealkit init
```

This creates a `database/` directory with the following layout:

```text
database/
├── schema/
├── seed/
├── tests/
└── rollouts/
```

## 2. Write a schema file

Create a `.surql` file inside `database/schema/`. Each file can contain one or more `DEFINE` statements.

```surql
-- database/schema/users.surql
DEFINE TABLE user SCHEMAFULL;
DEFINE FIELD email ON user TYPE string ASSERT string::is_email($value);
DEFINE FIELD created_at ON user TYPE datetime DEFAULT time::now();
DEFINE INDEX unique_email ON user FIELDS email UNIQUE;
```

Schema files can be organised by table, by domain, or kept in a single file. SurrealKit applies everything in `database/schema/` together.

## 3. Point at a database

Create a [SurrealDB Cloud instance](/docs/operate/instances.md) if you do not have one, and read its endpoint:

```bash
surreal cloud instance endpoint my-instance
```

Any SurrealDB endpoint works here. Cloud is used throughout these pages because it needs no setup of its own.

## 4. Sync your schema

```bash
surrealkit --user root --pass secret sync
```

SurrealKit reads every file in `database/schema/`, applies the `DEFINE` statements to the database, and records a content hash for each file in an internal `__entity` metadata table. Future syncs only re-apply files that have changed.

## 5. Enable watch mode during development

Pass `--watch` to keep SurrealKit running and automatically re-sync whenever a schema file changes:

```bash
surrealkit --user root --pass secret sync --watch
```

## Vite integration

If your project uses Vite, the `vite-plugin-surrealkit` package runs sync automatically when the dev server starts:

```bash
npm install --save-dev vite-plugin-surrealkit
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { surrealkitPlugin } from 'vite-plugin-surrealkit';

export default defineConfig({
    plugins: [
        surrealkitPlugin(),
    ],
});
```

The plugin watches `database/schema/**/*.surql` and re-syncs on any change, with debouncing to avoid overlapping runs.

## Storing connection details

Rather than passing flags on every command, store your local connection details in a `.env` file at the project root:

```bash title=".env"
SURREALDB_HOST=wss://production-6xk2.aws-euw1.surreal.cloud
SURREALDB_NAMESPACE=dev
SURREALDB_NAME=myapp
SURREALDB_USER=root
SURREALDB_PASSWORD=secret
```

With those set, `surrealkit sync` picks them up automatically. SurrealKit reads `.env` and `.env.local` from the working directory.

Project settings that are not connection details - template variables, type generation, schema modules and targets - live in [`surrealkit.toml`](/docs/operate/schema-migration/configuration.md) instead.

## Next steps

- [Sync](/docs/operate/schema-migration/sync.md): full reference for all sync options
- [Sync vs Rollouts](/docs/operate/schema-migration/getting-started/sync-vs-rollouts.md): when to move from Sync to the Rollouts workflow
- [Seeding](/docs/operate/schema-migration/seeding.md): add starting data to the database

## Learn more about this topic

- [Schema migrations in SurrealDB: A local dev workflow](https://surrealdb.com/blog/schema-migrations-in-surrealdb-a-local-dev-workflow#getting-started) (Blog, section "Getting started")
- [6: SurrealKit and the first table](https://surrealdb.com/learn/schemas/page-06#why-files-instead-of-the-shell) (SurrealDB University, section "Why files instead of the shell?")
- [7: Activities and seed data](https://surrealdb.com/learn/schemas/page-07) (SurrealDB University)
