# 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:

```
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. Start a local SurrealDB instance

```bash
surreal start --user root --pass secret
```

## 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
SURREALDB_HOST=http://localhost:8000
SURREALDB_NAMESPACE=dev
SURREALDB_NAME=myapp
SURREALDB_USER=root
SURREALDB_PASSWORD=secret
```

With those set, `surrealkit sync` picks them up automatically.

## Next steps

- [Sync](/docs/manage/schema-migration/sync.md): full reference for all sync options
- [Sync vs Rollouts](/docs/manage/schema-migration/getting-started/sync-vs-rollouts.md): when to move from Sync to the Rollouts workflow