Welcome to Vespa by HiveOps, your next-generation database-as-a-service platform designed for speed, scalability, and simplicity. This guide walks you through creating a database stack, initializing your project, and writing your first app using Vespa.

📦 Step 1: Create a Secure App and Database Stack

Before you begin coding, you need to set up your environment through the HiveOps Console:

Create a Secure App
- Navigate to the Apps page in the HiveOps Console.
- Create a new Secure App and copy the Access Token, you'll need this later.
Create a Vespa Database Stack
- Go to the Databases page and create a new stack.
- Copy the Stack Hive Resource Number (HRN), which identifies your database.

🛠️ Step 2: Initialize the Project

Open your terminal in the root of your project directory and run:

npx @hiveops/cli@latest vespa init

You’ll be prompted to provide:

The Stack Hive Resource Number from the console.
The Access Token for your secure app.
Whether to bootstrap sample models (recommended for first-time users).

What’s Generated

Once initialization is complete, the following will be added to your project:

📄 `package.json`

If not already present, a package.json file will be created and updated with these scripts:

"scripts": {
  "vespa:generate": "hive vespa generate -p ts",
  "vespa:apply": "hive vespa apply",
  "vespa:generate-and-apply": "hive vespa generate-and-apply -p ts"
}

📦 `Dependencies`

@hiveops/node@latest is added as a dependency.
@hiveops/cli@latest is added as a dev dependency.

📁 `src/models.hcl`

model User = {
  firstName: string = 1
  lastName: string = 2
  email: string = 4
  age: int = 5
}

model Post = {
  userId: string = 1
  title: string = 2
  body: string = 3
}

⚙️ Step 3: Compile and Apply Models

You can now run the following commands:

npm run vespa:generate

➜ Compiles models.hcl into TypeScript code under src/vespa.
npm run vespa:apply

➜ Applies the model schema to your Vespa database.
npm run vespa:generate-and-apply

➜ Does both of the above in a single step.

Once applied, you can view and inspect your schema in the console.

🧪 Step 4: Write Your First Script

Install required dependencies:

npm install --save @faker-js/faker dotenv

Create a src/main.ts file:

import { faker } from "@faker-js/faker";
import { configDotenv } from "dotenv";
import { postRepository, userRepository, vespaInit } from "./vespa";

configDotenv();

const start = async () => {
  vespaInit();

  const firstName = faker.person.firstName();
  const lastName = faker.person.lastName();
  const email = faker.internet.email({ firstName, lastName });

  const user = await userRepository.saveOne({
    firstName,
    lastName,
    email,
    age: faker.number.int({ min: 21, max: 45 }),
  });
  console.log(user);

  if (!user) {
    console.error("User not found");
    return;
  }

  const post = await postRepository.saveOne({
    userId: user._vespa_id,
    title: faker.lorem.words(3),
    body: faker.lorem.paragraph(),
  });

  console.log(post);

  const posts = await postRepository.findMany({});
  console.log(posts);
};

start().catch(console.error);

Now run your script with ts-node src/main.ts

✅ You’re All Set!

You’ve now:

Created a secure Vespa database stack
Bootstrapped your project
Generated and applied a schema
Written your first data persistence script