Skip to content

Latest commit

 

History

History
246 lines (179 loc) · 7.48 KB

api-full.md

File metadata and controls

246 lines (179 loc) · 7.48 KB

Documentation

Namespaces: main


main

Errors for 'main'

// Thrown by every operation of this package.
error Error (connect, handshake, unsupported, error) payload { message: String, error_code: uint (0), sqlstate: String ("") }

Error

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_code holds its number, such as 1062 for a duplicate key, and sqlstate the five character state, such as 23000.

Enums for 'main'

// How a connection uses TLS.
+ enum SslMode { disable, prefer, require, verify_full }
+ enum TYPE { null, int, float, string, array }

SslMode

How a connection uses TLS.

Functions for 'main'

// 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) Db

connect

Connects and logs in. TLS is used when the server offers it, without checking the certificate; connect_with takes other SslOptions.

connect_with

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.

database

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}")

Classes for 'main'

+ 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
}

query_serial

Counts the statements that have run, so that the rows of a query can tell whether another statement took the connection from under them.

prepare

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}")

ssl_enabled

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
}

SslOptions

TLS settings for connect_with.

ca_file

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.

certificate_file

A PEM file with the client certificate, optionally followed by the intermediate certificates, for an account that requires one (REQUIRE X509).

key_password

The password of an encrypted private key.

mode

How TLS is used.

private_key_file

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
}

Statement

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}")
}

sql

The SQL the statement was prepared from.

close

Releases the statement on the server. Running it afterwards throws.

query

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.

run

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
}

is_null

Returns whether the value is NULL.