Ecosystem packages
Databases, caches, and file formats as packages.
On this page
These official packages cover what the standard library leaves out: databases, caches, tokens and file formats. Install one with vman and import it by name:
vman install github.com/ctxcode/valk-redis
use redis
vman install adds the dependency to valk.json and copies it into vendor/. vpkg.dev lists every package with its versions and the lowest compiler version each needs. See Projects & packages for how dependencies work.
Databases#
| Package | What it is |
|---|---|
| valk-sql | One API over all drivers: query builder, migrations, pooling, rows read into your classes |
| valk-sqlite | SQLite, bound to the C library; the database is a file |
| valk-postgres | PostgreSQL, written in Valk, with prepared and cached statements |
| valk-mysql | MySQL, written in Valk |
Each driver works on its own and also plugs into valk-sql. Install both:
vman install github.com/ctxcode/valk-sql
vman install github.com/ctxcode/valk-sqlite
use sql
use sqlite
let db = sqlite.database(sqlite.open("app.db") ! panic("%{E.message}"))
defer db.close()
// Always `?` placeholders; Postgres gets $1, $2 on the way out
db.exec("INSERT INTO users (name, age) VALUES (?, ?)", .{ sql.Value.of("Ada"), sql.Value.of_int(36) }) ! panic("%{E.message}")
let rows = sql.Query.select()
.on(db)
.from("users")
.where("age > ?", .{ sql.Value.of_int(18) })
.all() ! panic("%{E.message}")
Switching databases means changing the line that opens it; valk-sql handles the differences in placeholders, RETURNING, LIMIT/OFFSET and insert ids.
Caches and queues#
valk-redis talks to Redis and Valkey, with pipelines, transactions, scripts, pub/sub, streams, TLS, pools and Sentinel:
use redis
let con = redis.connect("127.0.0.1", 6379) ! panic("%{E.message}")
defer con.close()
con.set("greeting", "hello", 60) ! panic("%{E.message}") // expires after 60 seconds
let visits = con.incr("visits") ! panic("%{E.message}")
let job = con.blpop("jobs", 5) ! panic("%{E.message}") // waits up to 5 seconds
Web services#
| Package | What it is |
|---|---|
| valk-jwt | JSON Web Tokens: HS256, HS384 and HS512 |
| valk-uuid | UUIDs: random (v4), time-ordered (v7) and name based (v5, v3) |
use jwt
use uuid
let id = uuid.v7() // sorts by creation time
let token = jwt.encode_of(Session { sub: id.to_string() }, secret, jwt.Algorithm.hs256, 3600)
let session = jwt.decode_to[Session](token, secret) ! panic("%{E.message}")
The algorithm comes from the caller, never from the token, so a token claiming alg: none is refused.
File formats#
| Package | What it is |
|---|---|
| valk-toml | TOML 1.0, decoded into your classes or a json.Value, and encoded back |
| valk-image | PNG, JPEG, WebP and BMP: read, write, resize, crop, flip and rotate |
use toml
use valk.fs
let settings = toml.decode_to[Settings](fs.read("config.toml") !!) ! panic("%{E.message} at line %{E.line}")
Command line apps#
valk-cli parses commands, options and arguments, writes the help text, and prints completion scripts for bash, zsh and fish:
use cli
fn main(args: Array[String]) {
let app = cli.App.new("greet", "Greet someone", "1.0.0")
app.root.flag("loud", "l", "Greet in capitals")
app.root.argument("name", "Who to greet", true)
app.root.on_run(fn(ctx: cli.Context) i32 !cli.Error {
let line = "Hello " + ctx.arg("name") + "!"
println(ctx.flag("loud") ? line.upper() : line)
return 0
})
exit(app.run(args))
}
Example project#
valk-starter-api is a small JSON API built from these parts: valk.http for the server, valk-sql with valk-sqlite for storage and migrations, valk-redis for rate limiting, and valk-jwt with valk-uuid for sessions. Read it as a reference; it is not a package to install.

