ActiveSo

Local first, synced with Turso Cloud

Every ActiveSo database is a local Turso file that syncs with Turso Cloud. activeso.OpenSync(ctx, config) is the only way to open one: it opens the file at Path, downloads the remote state when the file is empty, and returns a *Sync. Sync is database-wide, so Pull, Push, and Stats live on that handle, not on models.

SyncConfig takes Path and RemoteURL (both required) and AuthToken, plus optional Namespace, ClientName, BusyTimeoutMs, and SkipBootstrap to leave an empty local file empty until you call Pull yourself. Writes through models stay local until you call Push or Sync; ActiveSo never pushes for you. Always release the database with sync.Close() — closing the *sql.DB directly leaves the database files open.

Bring your own schema

ActiveSo reads and writes tables that already exist. It does not create or migrate your schema — create and change tables with whatever migration tooling you prefer. Model uses plural snake_case table names by default, with English inflection for common and irregular forms: User maps to users, City to cities, and Person to people. Implement TableName() string when your database uses a specific name.

type User struct {
	activeso.Record `activeso:"timestamps"`

	ID        string            `db:"id"`
	Email     string            `db:"email" activeso:"not_null,unique"`
	Embedding activeso.Vector32 `db:"embedding"`
}

CREATE TABLE users (
	id         TEXT PRIMARY KEY,
	email      TEXT NOT NULL,
	embedding  BLOB,
	created_at TEXT NOT NULL,
	updated_at TEXT NOT NULL
);

CREATE UNIQUE INDEX users_email
	ON users (email);

Every persisted field needs a db tag naming its column. ActiveSo does not guess column names, so activeso.Model[T](db) panics at setup when an exported field has none; use db:"-" to exclude one. Columns in the table but not the struct are ignored, so you can add columns ahead of a deploy or drop a field's column later. The embedded Record holds ActiveSo's runtime persistence binding and is not a column.

Plain strings, numbers, and booleans read SQL NULL as their Go zero value, and a Vector32 reads NULL as a nil vector. Use sql.NullString, sql.NullInt64, sql.NullFloat64, or sql.NullBool when your application must distinguish NULL from an empty or zero value — ActiveSo retains Valid when loading and saving.

Timestamps, when you opt in

Record promotes CreatedAt and UpdatedAt, but ActiveSo only manages them when you add the timestamps hint to the embedded Record. With the hint, the table must have created_at and updated_at columns holding UTC timestamp text. They need no defaults or triggers.

user, err := userModel.Create(ctx, User{Email: "hello@null.live"})
// user.CreatedAt and user.UpdatedAt are UTC time.Time values
fmt.Println(user.CreatedAt, user.UpdatedAt)

user.Email = "updated@null.live"
if err := user.Save(ctx); err != nil {
	return err
}
fmt.Println(user.UpdatedAt)

If either column is missing, the first operation fails with an activeso.ErrSchemaMismatch error naming both; a stored value that is not valid UTC timestamp text (YYYY-MM-DD HH:MM:SS or RFC3339) fails when read. Without the hint, ActiveSo never touches those columns and the Go fields stay zero. Timestamps are metadata, not an authorization boundary: raw SQL outside ActiveSo does not refresh updated_at, and Bind does not load timestamps.

Hints describe your table

Hints live in the activeso struct tag and describe what your table already enforces. Hints never change the database — Verify checks them. An unknown or malformed hint makes activeso.Model[T](db) panic, so mistakes surface during setup.

If no field has primary_key, ActiveSo uses the field mapped to id. Exactly one primary key is required, using strings, booleans, signed integers, uint8–uint32, or floats; uint and uint64 are rejected because Turso stores integers as signed 64-bit values. A primary key satisfies not_null and index. On the embedded Record, the only hint is timestamps.

type City struct {
	activeso.Record

	ID       string `db:"id"`
	Name     string `db:"name" activeso:"not_null,index"`
	RegionID string `db:"region_id" activeso:"not_null,belongs_to=regions(id),on_delete=cascade"`
}

Foreign keys are enforced on every ActiveSo write outside a transaction. Create, Save, and Delete turn on PRAGMA foreign_keys for the exact pooled connection that runs the write, so a model cannot persist orphaned rows or delete a referenced parent. Your own direct SQL on sync.DB() is not covered. Writes on a *sql.Tx run as-is, because SQLite ignores the pragma once a transaction has begun, so a transaction from sync.DB().BeginTx does not enforce foreign keys. Take one connection, enable the pragma on it, and run statements or begin transactions there.

conn, err := sync.DB().Conn(ctx)
if err != nil {
	return err
}
defer conn.Close()
if _, err := conn.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
	return err
}
tx, err := conn.BeginTx(ctx, nil)

Verify catches drift

Because ActiveSo trusts your tables, it can check that they match your model. There are two levels, and neither ever changes the database.

if err := userModel.Verify(ctx); err != nil {
	var schemaError *activeso.SchemaError
	if errors.As(err, &schemaError) {
		for _, problem := range schemaError.Problems {
			log.Println(problem)
			// hint unique on email, but no unique index covers exactly that column
		}
	}
	return err
}

A field type ActiveSo cannot map to a column is reported unless it implements driver.Valuer and sql.Scanner. A clean Verify also lets later operations skip their first-use structural check, which matters most inside transactions.

Transactions you control

ActiveSo accepts any activeso.Executor: *sql.DB, *sql.Tx, or *sql.Conn. You begin, commit, and roll back; ActiveSo only runs statements on the executor you give it. Every write and the single-record read has a transaction twin.

tx, err := db.BeginTx(ctx, nil)
if err != nil {
	return err
}
defer tx.Rollback()

user, err := userModel.CreateTx(ctx, tx, User{Email: "hello@null.live"})
if err != nil {
	return err
}
user.Email = "updated@null.live"
if err := user.SaveTx(ctx, tx); err != nil {
	return err
}

return tx.Commit()

txUsers := userModel.Using(tx)
matches, err := txUsers.Where("email LIKE ?", "%@null.live").All(ctx)
for _, match := range matches {
	match.Email = "migrated@null.live"
	if err := match.Save(ctx); err != nil { // runs on tx
		return err
	}
}

Foreign keys inside a transaction depend on its connection. SQLite ignores PRAGMA foreign_keys after a transaction begins, so a *sql.Tx from db.BeginTx can commit orphaned rows. For models with belongs_to, take a connection, enable the pragma, and begin the transaction on it — see Hints.

A *sql.Tx or *sql.Conn you pass must belong to the model's database; ActiveSo cannot check this. Records from a Using view fail with sql.ErrTxDone once the transaction ends, and Using(tx).Bind(record) moves an existing record into one. Turso begins transactions with snapshot isolation and ignores sql.TxOptions. With db.SetMaxOpenConns(1), an open transaction holds the only connection, so root-model calls wait until it ends — use Using(tx) or the Tx methods inside.

The record lifecycle

Records returned by Create, Find, query methods, or Bind carry Save(ctx) and Delete(ctx) with them — persistence behavior travels on the value itself.

user, err := userModel.Create(ctx, User{Email: "hello@null.live"})
// user is bound: Save and Delete are available on it

user.Email = "updated@null.live"
err := user.Save(ctx)

err := user.Delete(ctx)

externalUser := &User{ID: "8b291a21-e69b-47ed-a3e0-f43e7609b26d", Email: "hello@null.live"}
user, err := userModel.Bind(externalUser)

A record loaded outside ActiveSo must be attached first with Bind(value); an unbound record's Save and Delete return activeso.ErrUnboundRecord. A bound record's ID is captured when it becomes bound and cannot be changed — modifying it makes Save and Delete return activeso.ErrIDChanged; create a new record when you need a new identity.

Querying, including vectors

FindBy provides a mapped-column equality lookup; parameterized Where chains with OrderBy, Limit, First, and All; and Nearest orders by cosine distance over a Turso vector32 column.

user, err := userModel.Find(ctx, "8b291a21-e69b-47ed-a3e0-f43e7609b26d")
if errors.Is(err, activeso.ErrNotFound) {
	// no row with that ID
}

cities, err := cityModel.FindBy(ctx, "name", "Denver")

users, err := userModel.All(ctx)
for _, user := range users {
	fmt.Println(user.Email)
}

user, err := userModel.Where("email = ?", "hello@null.live").First(ctx)

excludedID := "8b291a21-e69b-47ed-a3e0-f43e7609b26d"
users, err := userModel.Where("email LIKE ? AND id <> ?", "%@null.live", excludedID).
	OrderBy("email ASC").
	Limit(10).
	All(ctx)

queryEmbedding := activeso.Vector32{0.12, -0.08, 0.63}

users, err := userModel.Nearest("embedding", queryEmbedding).Limit(10).All(ctx)

users, err = userModel.Where(
	"vector_distance_cos(embedding, vector32(?)) < ?",
	queryEmbedding,
	0.2,
).All(ctx)

OrderBy(expression) called after Nearest replaces the vector-distance ordering and discards that ordering's embedding argument.

Sentinel errors

Match with errors.Is. Unique conflicts come back as a UniqueError that carries the offending field — activeso: email must be unique — and schema mismatches as a *SchemaError listing every problem.

• ErrNotFoundA query did not return a matching record.
• ErrUnboundRecordA record was not created, loaded, or bound through a Model.
• ErrIDChangedA bound record's primary key was modified.
• ErrUniqueThe database rejected a write for violating a unique index.
• ErrSchemaMismatchA table does not match the model's db tags and hints.
• ErrSyncClosedA Sync method was called after Close.
• ErrSyncBusyClose was called while connections from DB() were still checked out.

Upgrading from 1.x

ActiveSo 2.0 removes all schema management. Plan these changes together, and back up production data before running any migration.

To move a 1.x table to the new timestamp columns, drop ActiveSo's triggers first — renaming a column rewrites trigger bodies, and the old triggers would then refer to columns that no longer exist — then rename the columns. List triggers with SELECT name FROM sqlite_schema WHERE type = 'trigger'.

DROP TRIGGER IF EXISTS activeso_7573657273_timestamps_insert;
DROP TRIGGER IF EXISTS activeso_7573657273_timestamps_update;
DROP TRIGGER IF EXISTS activeso_7573657273_timestamps_protect_created_at;
DROP TRIGGER IF EXISTS activeso_7573657273_timestamps_protect_updated_at;
ALTER TABLE users RENAME COLUMN activeso_created_at TO created_at;
ALTER TABLE users RENAME COLUMN activeso_updated_at TO updated_at;

Indexes that 1.x created, named like activeso_<hex>_<hex>_unique, keep working unchanged. Never open a live synced replica with a plain non-sync connection or the SQLite CLI; use the sync SDK or an offline copy.

A working Echo v5 example

The repository ships a small Echo v5 server with a single page for creating, finding, editing, and deleting users. It syncs a local activeso-example.db with a Turso Cloud database you own, syncs after each write, and shows any sync failure on the page — it never retries on its own. It listens on localhost:8080.

TURSO_DATABASE_URL=turso://my-db-my-org.aws-us-east-1.turso.io TURSO_AUTH_TOKEN=... go -C example run .