Getting Started
This guide will help you set up an5 in your project in under 5 minutes for Swift with Googlesheets.
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 Googlesheets (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=googlesheets://spreadsheet_id?credentials=./service-account.json
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
- Database Providers - Comprehensive guide for all 6 database providers
- Client Languages - Multi-language client generation reference
- CRUD Operations - Create, read, update, and delete data
- Schema Definition - Learn how to define your data models