Pkg/sql/Connection

Connection

type Connection = Connection

Database connection, used to create a new connection to a database.

The dialect can be one of the following:

sqlite
mysql
postgres
extra-engine

Example

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
defer conn.close();
let rows = try! conn.query("SELECT * FROM users");

SQLite

The sqlite dialect can be used to connect a sqlite file or an in-memory database.

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
defer conn.close();

Or open a .sqlite3 file:

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite:///path/to/db.sqlite3");
defer conn.close();

Extra Engine

The extra-engine is a special dialect, it is not support transaction and params binding.

This dialect is an in memory OLAP engine.

Features

Query from any backend datasource including (MySQL, PostgreSQL ...)
From a Cloud Storage (Aliyun OSS, AWS S3, GCS, ...)
From a local file (CSV, JSON, Parquet, ...)

nv,

use sql.Connection;

let conn = try! Connection.connect("extra-engine");

DB config

If you wants use backend datasource in Extra Engine, you must specify the db config.

Use the EXTRA_ENGINE_DB_CONFIG env to specify a path of the db config file. The config file format is YAML, for example: db.yaml.

yml

app1:
  conn_settings:
    member_db:
      db_type: pg
      db_name: member-prod
      host: localhost
      port: 5432
      user: postgres
      password: 123456
    portfolio_db:
      db_type: mysql
      db_name: portfolio-prod
      host: localhost
      port: 5432
      user: postgres
      password: 123456

Implementions

Execute

Methods

pub fn execute(self, query: string, values: ..BindValue?): QueryResult throws SqlError

[src]

pub fn execute(self, query: string, values: ..BindValue?): QueryResult throws SqlError {
    let result = try (self as _Connection).execute(query, build_bind_values(..values));
    return result as QueryResult;
}

Execute the query and return the total number of rows affected.

This method only support execute 1 SQL statement.

For INSERT/UPDATE/DELETE without RETURNING.

The first argument is the SQL statement.
And the rest arguments are the values for the placeholders in the SQL statement.

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
let result = try! conn.execute("INSERT INTO users (id, name, city) VALUES (?, ?)", 100, "Jason Lee", "Chengdu");

TIP: If you are use PostgreSQL, the ? placeholder is not supported. You should use $1, $2, ... And the values should be in the same order as the placeholders.

pub fn query(self, query: string, values: ..BindValue?): Rows throws SqlError

[src]

pub fn query(self, query: string, values: ..BindValue?): Rows throws SqlError {
    return try (self as _Connection).query(query, build_bind_values(..values)) as Rows;
}

Query and return a steam of rows.

Returns a sql.Rows for iterating the rows, you must close it when you don't need it anymore.

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
let rows = try! conn.query("SELECT * FROM users WHERE status = ? OFFSET ? LIMIT ?", "active", 0, 100);
defer rows.close();

TIP: If you are use PostgreSQL, the ? placeholder is not supported. You should use $1, $2, ... And the values should be in the same order as the placeholders.

pub fn query_one(self, query: string, values: ..BindValue?): Row? throws SqlError

[src]

pub fn query_one(self, query: string, values: ..BindValue?): Row? throws SqlError {
    let rows = try self.query(query, ..values);
    return try rows.next();
}

Query and return the first row.

See: sql.Connection.query

pub fn connect(url: string, min_connections: int = 1, max_connections: int = 10, acquire_timeout: Duration = 30.seconds()): Connection throws SqlError

[src]

pub fn connect(
    url: string,
    min_connections: int = 1,
    max_connections: int = 10,
    acquire_timeout: Duration = 30.seconds()
): Connection throws SqlError {
    return try _Connection.connect(url, min_connections:, max_connections:, acquire_timeout:) as Connection;
}

Connect to a database.

The url is in the format of dialect://user:password@host:port/database.

The dialect can be one of the following:

sqlite

If you want to use an in-memory database, you can use Connection.connect("sqlite::memory:").
mysql
postgres
extra-engine

And make sure to close the connection when you don't need it anymore.

Kw Args

min_connections: The minimum number of connections to keep in the pool. Default is 1.
max_connections: The maximum number of connections to keep in the pool. Default is 10.
acquire_timeout: The maximum time to wait for a connection to become available. Default is 30.seconds().

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
defer conn.close();

pub fn min_connections(self): int

[src]

pub fn min_connections(self): int {
    return (self as _Connection).min_connections();
}

Get min number of connections in the pool.

pub fn max_connections(self): int

[src]

pub fn max_connections(self): int {
    return (self as _Connection).max_connections();
}

Get max number of connections in the pool.

pub fn close(self)

[src]

pub fn close(self) {
    (self as _Connection).close();
}

Close the connection.

pub fn is_closed(self): bool

[src]

pub fn is_closed(self): bool {
    return (self as _Connection).is_closed();
}

Check the connection is closed or not. Returns true if the connection is closed.

pub fn begin(self): Transaction throws SqlError

[src]

pub fn begin(self): Transaction throws SqlError {
    return try (self as _Connection).begin() as Transaction;
}

Begin a new transaction or establish a savepoint within the active transaction.

Returns a sql.Transaction for controlling and tracking the new transaction.

NOTE: You must call commit or rollback to finish it when you start a transaction. If you forget to do this, the transaction will leak (The transaction will be rolled back on GC).

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
let tx = try! conn.begin();
// To some work...
try! tx.commit();
// Or tx.rollback();

pub fn transaction(self, f: |(Transaction)|) throws

[src]

pub fn transaction(self, f: |(Transaction) throws|) throws {
    let tx = try self.begin();
    do {
        try f(tx);
    } catch(e) {
        try tx.rollback();
        throw e;
    }
    try tx.commit();
}

Wrap a transaction.

This will begin a new transaction and call the given function with the transaction.

If the function call is ok, it will COMMIT. If any error is thrown, it will ROLLBACK.

nv,

use sql.Connection;

let conn = try! Connection.connect("sqlite::memory:");
try! conn.transaction(|tx| {
    try tx.execute("INSERT INTO users (name) VALUES ('Alice')");
    try tx.execute("INSERT INTO users (name) VALUES ('Bob')");
});

pub fn prepare(self, query: string): Statement throws SqlError

[src]

pub fn prepare(self, query: string): Statement throws SqlError {
    return try (self as _Connection).prepare(query) as Statement;
}

Prepare a sql statement.