Getting Started

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

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

Prerequisites

  • Node.js 18+ (Node 24 recommended for schema compiler and CLI)
  • Swift 5.9+ (Xcode 15+)

  • Connection to Sqlserver (or local embedded setup)

Installation

// Package.swift
dependencies: [
    // The runtime SwiftPM package is the `swift/` directory inside the
    // an5ORM/an5Adapters repository. SwiftPM takes a package's identity from the
    // last path component, so this one is identified as `swift` — and the
    // generated client ships in a directory with that same name, which would
    // make the two resolve to one package. Put the generated client under a
    // different directory name (a copy or a symlink is enough):
    //
    //   git clone https://github.com/an5ORM/an5Adapters.git Vendor/an5-adapters
    //   ln -s "$PWD/an5Client/swift" Vendor/an5-client
    .package(path: "Vendor/an5-adapters/swift"),
    .package(path: "Vendor/an5-client"),
],
targets: [
    .executableTarget(
        name: "App",
        dependencies: [
            .product(name: "An5Adapters", package: "swift"),
            .product(name: "An5Client", package: "an5-client"),
        ]),
]

There is no tagged SwiftPM release to point a URL dependency at yet: the runtime lives in a subdirectory of that repository rather than at its root, and the repository carries no matching tag. Depend on it by path as above. Generate the typed Swift client with npm run generate; see Feature Status for the packaging gap.

Configuration

1. Set up Environment Variables

Edit .env and configure your database connection string:


DATABASE_URL=sqlserver://localhost:1433;database=mydb;user=sa;password=yourpassword;trustServerCertificate=true

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/swift/.

4. Push Schema to Database

npm run db:push

This creates the tables in your database.

Your First Query

import An5Client

let db = try An5Db(connectionString: try An5Config.connectionString())

let user = try db.user.create(User(email: "john@example.com", name: "John Doe"))
print("Created user: \(user.id ?? "unknown")")

let users = try db.user.findMany()
print("Found \(users.count) 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