Namespaces: main
// Thrown by every operation of this package.
error Error (connect, handshake, unsupported, error) payload { message: String, error_code: uint (0), sqlstate: String ("") }Thrown by every operation of this package.
connect: the TCP connection failed.handshake: logging in failed.unsupported: the server asked for something this package does not implement.error: the server reported an error.error_codeholds its number, such as 1062 for a duplicate key, andsqlstatethe five character state, such as23000.
// How a connection uses TLS.
+ enum SslMode { disable, prefer, require, verify_full }
+ enum TYPE { null, int, float, string, array }How a connection uses TLS.
// Connects and logs in. TLS is used when the server offers it, without checking the certificate; `connect_with` takes other `SslOptions`.
+ fn connect(host: String, user: String, password: String, db: ?String, port: u32, ssl: SslMode (SslMode.prefer)) Connection !Error
// Connects and logs in with the TLS settings in `ssl`, such as a CA file to check the server certificate against, or a client certificate.
+ fn connect_with(host: String, user: String, password: String, db: ?String, port: u32, ssl: SslOptions) Connection !Error
+ fn convert(ndata: $T) Value
// Returns the connection as a `sql.Db`, the database type of the `valk-sql` package.
+ fn database(con: Connection) DbConnects and logs in. TLS is used when the server offers it, without checking the
certificate; connect_with takes other SslOptions.
Connects and logs in with the TLS settings in ssl, such as a CA file to check the server
certificate against, or a client certificate.
Returns the connection as a sql.Db, the database type of the valk-sql package.
Everything valk-sql offers — the query builder, migrations, pools, rows read into your own
classes — then works on this database, and the same code runs on SQLite or Postgres by
opening it with their driver instead.
The connection itself stays usable: this is a view of it, not a replacement.
use sql
use mysql
let db = mysql.database(mysql.connect("127.0.0.1", "user", "password", "app", 3306) ! panic("%{E.message}"))
db.exec("INSERT INTO users (name) VALUES (?)", .{ sql.Value.of("Ada") }) ! panic("%{E.message}")
+ class Connection {
~ affected_rows: uint
~ closed: bool
+ debug: bool
+ debug_bytes: bool
~ last_inserted_id: uint
// Counts the statements that have run, so that the rows of a query can tell whether another statement took the connection from under them.
~+ query_serial: uint
+ fn bind(name: String, value: $T) void
+ fn bindv(value: $T) void
+ fn clear_binds() void
+ fn clear_old_statements() void
+ fn close() void
+ fn fetch_all() Array[Map[Value]] !Error
+ fn fetch_row(row: Map[Value]) bool !Error
// Prepares a statement on the server, to run many times with other values each time.
+ fn prepare(sql: String) Statement !Error
+ fn query(q: String, binds: ?Map[?Value] (null)) void !Error
+ fn replace_named_params(query: String) String !Error
// Returns whether the connection runs over TLS.
+ fn ssl_enabled() bool
}Counts the statements that have run, so that the rows of a query can tell whether another statement took the connection from under them.
Prepares a statement on the server, to run many times with other values each time.
The server parses the SQL once, here; running the statement only sends its values, and
its rows come back in the binary protocol. Values go in by name, :name; a name used
twice takes the same value.
let find = con.prepare("SELECT * FROM users WHERE id = :id") ! panic("%{E.message}")
defer find.close()
find.query(.{ "id" => 1 }) ! panic("%{E.message}")
let users = con.fetch_all() ! panic("%{E.message}")
Returns whether the connection runs over TLS.
// TLS settings for `connect_with`.
+ class SslOptions {
// A PEM file with CA certificates to trust besides the system store, for a server certificate from a private CA. Only used in `verify_full` mode.
+ ca_file: ?String
// A PEM file with the client certificate, optionally followed by the intermediate certificates, for an account that requires one (`REQUIRE X509`).
+ certificate_file: ?String
// The password of an encrypted private key.
+ key_password: String
// How TLS is used.
+ mode: SslMode
// The PEM private key of `certificate_file`. Null reads it from `certificate_file`.
+ private_key_file: ?String
}TLS settings for connect_with.
A PEM file with CA certificates to trust besides the system store, for a server
certificate from a private CA. Only used in verify_full mode.
A PEM file with the client certificate, optionally followed by the intermediate
certificates, for an account that requires one (REQUIRE X509).
The password of an encrypted private key.
How TLS is used.
The PEM private key of certificate_file. Null reads it from certificate_file.
// A statement prepared once on the server and run as often as needed, made by `Connection.prepare`.
+ class Statement {
~ closed: bool
// The SQL the statement was prepared from.
~+ sql: String
// Releases the statement on the server. Running it afterwards throws.
+ fn close() void
// Runs the statement with `values` bound to its `:name` placeholders. Rows, if any, are read with `fetch_row` or `fetch_all` of the connection.
+ fn query(values: ?Map[?Value] (null)) void !Error
// Runs the statement and returns how many rows it changed. `last_inserted_id` of the connection holds the id an insert wrote.
+ fn run(values: ?Map[?Value] (null)) uint !Error
}A statement prepared once on the server and run as often as needed, made by
Connection.prepare.
Its values go in by name, as with Connection.query, and its rows are read with the fetch
methods of the connection. close releases it on the server; closing the connection
releases them all.
let insert = con.prepare("INSERT INTO users (name, age) VALUES (:name, :age)") ! panic("%{E.message}")
defer insert.close()
each people as person {
insert.run(.{ "name" => person.name, "age" => person.age }) ! panic("%{E.message}")
}
The SQL the statement was prepared from.
Releases the statement on the server. Running it afterwards throws.
Runs the statement with values bound to its :name placeholders. Rows, if any, are
read with fetch_row or fetch_all of the connection.
Every placeholder needs a value; a name without one throws.
Runs the statement and returns how many rows it changed. last_inserted_id of the
connection holds the id an insert wrote.
+ class Value {
// Returns whether the value is NULL.
+ fn is_null() bool
+ static fn null() Value
+ fn to_bool() bool
+ fn to_bool_or_null() ?bool
+ fn to_float() float
+ fn to_float_or_null() ?float
+ fn to_int() int
+ fn to_int_or_null() ?int
+ fn to_json() Value
+ fn to_json_or_null() ?(Value)
+ fn to_string() String
+ fn to_string_or_null() ?String
}Returns whether the value is NULL.