Database Migrations

Evolve your database schema with versioned migration files. Create collections, indexes, and manage schema changes safely.

Overview

Migrations are stored in db/migrations/ with timestamped filenames. Each migration contains up() and down() functions for applying and rolling back changes.

Note: Collections are now automatically created when you first use a Model. You can start using your models immediately without creating migrations. However, for production applications, we recommend using migrations to define indexes for better query performance, set collection options, and document your schema.

db/migrations/20260122143052_create_users.sl

def up(db: Any)
  db.create_collection("users")
  db.create_index("users", "idx_email", ["email"], { "unique": true })
end

def down(db: Any)
  db.drop_index("users", "idx_email")
  db.drop_collection("users")
end

CLI Commands

generate Create a Migration

soli db:migrate generate create_users_table

Creates: db/migrations/20260122143052_create_users_table.sl

up Run Migrations

# Apply all pending migrations
soli db:migrate

# Or explicitly
soli db:migrate up

down Rollback

# Rollback the last migration
soli db:migrate down

status Check Status

soli db:migrate status

  Database Migrations

  Version         Name                            Status
  --------------  ------------------------------  ----------
  20260122143052  create_users_table                 up
  20260122145201  add_posts_table                    up
  20260122151033  add_user_indexes                  down

  2 applied, 1 pending

Collection Helpers

db.create_collection(name, type?)

Create a collection. type is optional — one of "blob", "edge", "timeseries", … (forwarded verbatim to SolidB). Default is a document collection.

blob — binary attachments; required for solidb_store_blob and the uploader DSL.
edge — graph edges (_from/_to); backs the edge model DSL and traversals.
timeseries — append-only time-indexed events (metrics, logs, telemetry); backs the timeseries model DSL.
"columnar" now raises — columnar stores are not document collections (it used to silently create a mislabeled document collection). Use db.create_columnar instead.

db.create_columnar(name, columns, options?)

Create a columnar store. columns is an array of { "name": ..., "type": ..., "nullable"?: bool, "indexed"?: bool } hashes; options accepts { "compression": "lz4" | "none" } (default lz4).

db.drop_columnar(name)

Remove a columnar store and all its data.

db.prune_collection(name, cutoff)

Delete documents older than an RFC3339 cutoff from a timeseries collection — the migration-side counterpart of Model.prune.

db.drop_collection(name)

Remove a collection and all its data.

db.list_collections()

List all collections in the database.

db.collection_stats(name)

Get statistics for a collection.

Collection Examples

def up(db: Any)
  db.create_collection("users")                       # document
  db.create_collection("posts")
  db.create_collection("contact_documents", "blob")   # blob
  db.create_collection("follows", "edge")             # edge (graph)
  db.create_collection("metrics", "timeseries")       # timeseries

  # Columnar stores use the dedicated helper (create_collection with
  # "columnar" raises — columnar stores are not document collections)
  db.create_columnar("page_views", [
    { "name": "url", "type": "string" },
    { "name": "country", "type": "string", "indexed": true }
  ])

  # Edge collections: hash-index the endpoints so traversals stay fast
  # (dev auto-create does both steps for you)
  db.create_index("follows", "idx_follows_from", ["_from"], {})
  db.create_index("follows", "idx_follows_to", ["_to"], {})

  # Timeseries collections: one-off cleanup of old rows
  db.prune_collection("metrics", "2026-01-01T00:00:00Z")
end

def down(db: Any)
  db.drop_collection("comments")
  db.drop_collection("posts")
  db.drop_collection("users")
end

Index Helpers

db.create_index(collection, name, fields, options)

Create an index on a collection.

fields - Array of field names: ["email"] or ["first_name", "last_name"]
options - Hash with unique: true and/or type: — "hash" (default), "persistent", "fulltext", "bloom", or "cuckoo" ("skiplist"/"btree" are aliases for "persistent")
The old sparse option was dropped — the server never read it, so it changed nothing.

db.create_vector_index(collection, name, field, dimension, options?)

Create an HNSW vector index for ANN search. options is a metric string ("cosine", default) or a hash with metric and quantization. Drop with db.drop_vector_index(collection, name).

db.drop_index(collection, name)

Remove an index from a collection.

db.list_indexes(collection)

List all indexes for a collection.

Models can also declare indexes in the class body (index, vector_index, fulltext_index, geo_index — see Search). Declarations are metadata-only: dev creates them at server boot; in production mirror them in migrations (the recommended DDL path) or run the reconciler soli db:indexes [folder]. Geo indexes currently have no migration helper — soli db:indexes (or dev boot) creates them.

Index Examples

def up(db: Any)    # Simple index
  db.create_index("users", "idx_email", ["email"], {})
  # Unique index
  db.create_index("users", "idx_username", ["username"], { "unique": true })
  # Typed index — "hash" is the default; "persistent" for sorted/range lookups
  db.create_index("users", "idx_age", ["age"], { "type": "persistent" })
  # Fulltext index
  db.create_index("articles", "idx_articles_ft", ["title", "body"], { "type": "fulltext" })
  # Compound index on multiple fields
  db.create_index("users", "idx_name", ["first_name", "last_name"], {})
  # Unique compound index
  db.create_index("posts", "idx_user_slug", ["user_id", "slug"], { "unique": true })
end

def down(db: Any)
  db.drop_index("posts", "idx_user_slug")
  db.drop_index("users", "idx_name")
  db.drop_index("articles", "idx_articles_ft")
  db.drop_index("users", "idx_age")
  db.drop_index("users", "idx_username")
  db.drop_index("users", "idx_email")
end

Raw Queries

For operations not covered by helpers, use raw SDBQL queries:

def up(db: Any)    # Insert seed data
  db.query("INSERT { name: 'Admin', role: 'admin' } INTO users")
  # Update existing data
  db.query("FOR u IN users FILTER u.role == 'guest' UPDATE u WITH { role: 'user' } IN users")

  # Bind variables (preferred for user data — avoids escaping issues)
  digest = bcrypt_hash("changeme")
  db.query(
    "INSERT { email: @e, name: @n, role: @r, password_digest: @d } INTO users",
    { "e": "admin@example.com", "n": "Admin", "r": "admin", "d": digest }
  )

  # Bind variables work in FILTER / RETURN too
  db.query(
    "FOR doc IN users FILTER doc.status == @status RETURN doc",
    { "status": "active" }
  )
end

Raw queries are also the escape hatch for SolidB features the helpers don't wrap — e.g. continuous aggregates over a timeseries collection via db.query("CREATE STREAM ...").

Complete Example

A migration for a blog application:

db/migrations/20260122143052_create_blog_schema.sl

def up(db: Any)    # Create collections
  db.create_collection("users")
  db.create_collection("posts")
  db.create_collection("comments")
  db.create_collection("tags")
  # User indexes
  db.create_index("users", "idx_users_email", ["email"], { "unique": true })
  db.create_index("users", "idx_users_username", ["username"], { "unique": true })
  # Post indexes
  db.create_index("posts", "idx_posts_author", ["author_id"], {})
  db.create_index("posts", "idx_posts_slug", ["slug"], { "unique": true })
  db.create_index("posts", "idx_posts_published", ["published_at"], { "sparse": true })
  # Comment indexes
  db.create_index("comments", "idx_comments_post", ["post_id"], {})
  db.create_index("comments", "idx_comments_author", ["author_id"], {})
  # Tag indexes
  db.create_index("tags", "idx_tags_name", ["name"], { "unique": true })
end

def down(db: Any)    # Drop indexes first
  db.drop_index("tags", "idx_tags_name")
  db.drop_index("comments", "idx_comments_author")
  db.drop_index("comments", "idx_comments_post")
  db.drop_index("posts", "idx_posts_published")
  db.drop_index("posts", "idx_posts_slug")
  db.drop_index("posts", "idx_posts_author")
  db.drop_index("users", "idx_users_username")
  db.drop_index("users", "idx_users_email")
  # Drop collections
  db.drop_collection("tags")
  db.drop_collection("comments")
  db.drop_collection("posts")
  db.drop_collection("users")
end

Seeding the Database

Migrations build the schema; seeds populate it with data — demo accounts, lookup tables, an initial admin user. Run them with soli db:seed.

Unlike migrations, seeds are not tracked — every file runs on every invocation. Make your seeds idempotent (guard with first_by / find_by) so re-running them doesn't create duplicates.

Seeds live in two places, run in this order:

db/seeds.sl          # runs first
db/seeds/*.sl        # then every file here, sorted by name

generate Create a Seed File

soli db:seed generate demo_users

Creates: db/seeds/20260623161240_demo_users.sl

seed Run Seeds

# Run db/seeds.sl, then db/seeds/*.sl
soli db:seed

# Run a single seed file (path relative to the project folder)
soli db:seed db/seeds/20260623161240_demo_users.sl

# Point at a different project folder
soli db:seed ./myapp

Seeds run with your app/models (and app/services) auto-loaded, so they can use the Model API directly — no imports needed:

db/seeds.sl

3.times do |i|
  let email = "user#{i}@example.com"
  User.create({ "name": "User #{i}", "email": email }) if User.first_by("email", email).nil?
end

print("Seeded users")

Environment Configuration

Configure database connection via .env file:

.env

SOLIDB_HOST=http://localhost:6745
SOLIDB_DATABASE=myapp_development
SOLIDB_USERNAME=root
SOLIDB_PASSWORD=secret

Best Practices

Keep migrations small - One logical change per migration
Always write down() - Enable clean rollbacks
Test rollbacks - Run down then up to verify
Order matters in down() - Drop indexes before collections
Don't modify old migrations - Create new ones for changes

Helpers Reference

Method	Description
`db.create_collection(name, type?)`	Create a collection. `type` is optional — `"blob"`, `"edge"`, `"timeseries"`, … default is document. `"columnar"` raises — use `create_columnar`.
`db.create_columnar(name, columns, options?)`	Create a columnar store. `columns`: array of `{name, type, nullable?, indexed?}` hashes; `options`: `{"compression": "lz4"\|"none"}`
`db.drop_columnar(name)`	Drop a columnar store
`db.prune_collection(name, cutoff)`	Delete documents older than an RFC3339 cutoff from a timeseries collection
`db.drop_collection(name)`	Drop a collection
`db.list_collections()`	List all collections
`db.collection_stats(name)`	Get collection statistics
`db.create_index(collection, name, fields, options)`	Create an index. `options`: `unique:` and `type:` (`"hash"` default, `"persistent"`, `"fulltext"`, `"bloom"`, `"cuckoo"`)
`db.create_vector_index(collection, name, field, dimension, options?)`	Create an HNSW vector index. `options`: metric string or `{metric, quantization}` hash
`db.drop_vector_index(collection, name)`	Drop a vector index
`db.drop_index(collection, name)`	Drop an index
`db.list_indexes(collection)`	List indexes for a collection
`db.query(sdbql, bind_vars?)`	Execute a raw SDBQL query, optionally with a hash of bind variables