ActiveSo

A struct maps to a table

Model uses plural snake_case table names by default — User maps to users. The embedded Record holds ActiveSo's runtime persistence binding and is not a database column. The activeso tag adds constraints when AutoMigrate(ctx) runs.

type User struct {
	activeso.Record

	ID    string `db:"id"`
	Email string `db:"email" activeso:"not_null,unique"`
}

CREATE TABLE users (
	id    TEXT PRIMARY KEY,
	email TEXT NOT NULL
);

CREATE UNIQUE INDEX activeso_7573657273_656d61696c_unique
	ON users (email);

db tags choose column names; exported fields without one derive a snake_case name. Plain strings, numbers, and booleans read SQL NULL as their Go zero value, keeping rows readable after additive nullable migrations. Use database/sql nullable types, such as sql.NullString, when your application must distinguish NULL from an empty or zero value.

Three constraint options

Constraints live in the struct tag. An unknown activeso constraint causes activeso.Model[T](db) to panic, so schema mistakes are caught during setup.

If no field has primary_key, ActiveSo uses the field mapped to id. Exactly one primary key is required. Supported types are strings, booleans, signed integers, uint8–uint32, and floats; uint and uint64 are not supported because Turso stores integers as signed 64-bit values.

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)

user, err := userModel.Create(ctx, User{Email: "hello@null.live"})
if err != nil {
	return err
}

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

return user.Delete(ctx)

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

Every call below is actual API surface. 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
}

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

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

user, err := userModel.Where("email LIKE ?", "%@null.live").
	OrderBy("email ASC").
	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.

Migrations stay deliberate

AutoMigrate(ctx) is intentionally additive and safe: it creates tables, adds missing nullable columns, and creates tagged unique indexes, but never drops data, removes indexes, changes column types, or tightens existing constraints. Run it during application setup or deployment; normal model initialization and record operations do not require it.

Removing a struct field alone never drops a database column; use DropColumn explicitly. Each column migration changes only its named target. Rebuilds run inside a transaction — unsupported dependencies cause an error, and failed migrations roll back. Run destructive changes during a controlled deployment with a production backup; tables with dependent views, triggers, foreign keys, generated columns, or unsupported primary-key changes need a dedicated migration.

Four sentinel errors

Match with errors.Is. Unique conflicts come back as a UniqueError that carries the offending field — activeso: email must be unique.

• 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.
• ErrUniqueA value conflicts with a field marked activeso:"unique".

A working Echo v5 example

The repository ships a small Echo v5 server with a single page for creating, editing, and deleting users. It creates a local activeso-example.db and listens on localhost:8080.