Getting Started

This guide will help you set up an5 in your project in under 5 minutes for Golang with Nbase.

For the current implementation and package maturity overview, see Feature Status.

Prerequisites

  • Node.js 18+ (Node 24 recommended for schema compiler and CLI)
  • Go 1.21+

  • Connection to Nbase (or local embedded setup)

Installation

# Standard database drivers
go get github.com/mattn/go-sqlite3

Generate Go structs and table clients with npm run generate.

Configuration

1. Set up Environment Variables

Edit .env and configure your database connection string:


DATABASE_URL=nbase://localhost:1307

2. Define Your Schema

Create .an5 files in the an5Schema/ directory:

// an5Schema/User.an5
model User {
  id        NVARCHAR(1000) @id @default(uuid())
  email     NVARCHAR(255)  @unique
  name      NVARCHAR(255)?
  createdAt DATETIME2      @default(now())
  
  @@map("users")
}

3. Generate Client Code

Run from the an5Orm/ repository directory:

npm run generate

This generates type-safe client code in an5Client/golang/.

4. Push Schema to Database

npm run db:push

This creates the tables in your database.

Your First Query

package main

import (
    "context"
    "fmt"
    "os"
    "an5client"
)

func main() {
    ctx := context.Background()
    db, err := an5client.NewAn5DbContext(ctx, os.Getenv("DATABASE_URL"))
    if err != nil {
        panic(err)
    }

    // Create a user
    user, err := db.User.Create(ctx, &an5client.UserCreateInput{
        Email: "john@example.com",
        Name:  "John Doe",
    })
    if err != nil {
        panic(err)
    }
    fmt.Printf("Created user: %+v\n", user)

    // Find all users
    users, err := db.User.FindMany(ctx, &an5client.UserFindManyArgs{})
    if err != nil {
        panic(err)
    }
    fmt.Printf("Retrieved %d users\n", len(users))
}

Project Structure

an5/
├── an5Schema/           # Schema definitions (.an5 files)
├── an5Client/           # Generated client code for all target languages
│   ├── typescript/
│   ├── python/
│   ├── dotnet/
│   ├── golang/
│   ├── rust/
│   ├── java/
│   ├── kotlin/
│   └── swift/
├── an5Orm.config.js     # ORM configuration & database mapping
└── .env                 # Environment variables & connection strings

Available Commands

Schema/database commands run from the an5Orm/ repository directory:

Command Where Description
npm run generate an5Orm/ Generate client code from schema
npm run db:push an5Orm/ Push schema to database
npm run db:pull an5Orm/ Pull schema from database
npm run db:seed an5Orm/ Seed database with sample data
npm run db:migrate diff an5Orm/ Compare schema with database
npm run db:migrate:generate an5Orm/ Generate migration SQL
npm run db:migrate:apply an5Orm/ Apply pending migration files
npm run db:migrate:rollback an5Orm/ Roll back migrations
npm run db:migrate:status an5Orm/ Show migration status

Next Steps