Struct Connection 

pub struct Connection { /* private fields */ }

Um anexo (attachment) autenticado a um banco de dados.

Implementations

impl Connection

pub fn array_desc( &mut self, tx: &Transaction, relation: &str, field: &str, ) -> Result<ArrayDesc>

Monta o ArrayDesc de uma coluna ARRAY consultando o catálogo do sistema (RDB$*), exatamente como o fbclient faz antes de uma fatia. relation/field são os nomes como armazenados (normalmente maiúsculas; um ColumnMeta de saída já os traz assim).

pub fn read_array( &mut self, tx: &Transaction, array_id: u64, desc: &ArrayDesc, ) -> Result<Vec<Value>>

Lê todos os elementos de um array (op_get_slice). array_id é o id que veio na coluna (Value::Array); desc descreve o tipo e as dimensões. Devolve um valor por elemento, na ordem em que o servidor os transmite.

pub fn write_array( &mut self, tx: &Transaction, desc: &ArrayDesc, values: &[Value], ) -> Result<u64>

Cria um novo array com values (op_put_slice) e devolve seu id, para usar como Value::Array num INSERT/UPDATE. O número de valores deve bater com desc.element_count().

impl Connection

pub fn create_batch(&mut self, tx: &Transaction, sql: &str) -> Result<Batch>

Prepara uma instrução e cria um lote (batch) sobre ela com as opções padrão (BatchOptions::default: fail-fast, com contagens por linha). A instrução deve ter parâmetros (?) — cada Batch::add fornece uma linha de valores.

Para continuar após erros por linha e coletá-los todos, use Self::create_batch_with com BatchOptions::new().multierror(true).

pub fn create_batch_with( &mut self, tx: &Transaction, sql: &str, opts: BatchOptions, ) -> Result<Batch>

Como Self::create_batch, mas com BatchOptions explícitas.

impl Connection

pub fn open_blob(&mut self, tx: &Transaction, blob_id: u64) -> Result<Blob>

Abre um BLOB para leitura pelo seu id (obtido de uma coluna Value::Blob).

pub fn create_blob(&mut self, tx: &Transaction) -> Result<BlobWriter>

Cria um BLOB vazio para escrita (op_create_blob2). Escreva dados com BlobWriter::write e finalize com BlobWriter::close para obter o id do blob. Em caso de erro, chame BlobWriter::cancel.

pub fn write_blob(&mut self, tx: &Transaction, data: &[u8]) -> Result<u64>

Conveniência: cria um BLOB, escreve data integralmente e o fecha, devolvendo o id para usar como parâmetro de coluna BLOB.

pub fn read_blob(&mut self, tx: &Transaction, blob_id: u64) -> Result<Vec<u8>>

Conveniência: abre o BLOB, lê todo o conteúdo e o fecha, devolvendo os bytes. Fecha mesmo se a leitura falhar.

impl Connection

pub fn connect(config: &ConnectConfig) -> Result<Connection>

Conecta ao servidor e anexa (attach) a um banco de dados existente.

Examples found in repository

examples/dump.rs (line 25)

fn main() -> Result<()> {
    let cfg = ConnectConfig::new()
        .host(std::env::var("FB_HOST").unwrap_or_else(|_| "127.0.0.1".into()))
        .port(
            std::env::var("FB_PORT")
                .ok()
                .and_then(|p| p.parse().ok())
                .unwrap_or(3555),
        )
        .database(std::env::var("FB_DB").unwrap_or_else(|_| "employee".into()))
        .user(std::env::var("FB_USER").unwrap_or_else(|_| "SYSDBA".into()))
        .password(std::env::var("FB_PASSWORD").expect("set FB_PASSWORD"))
        .wire_crypt(WireCrypt::Enabled);

    let mut conn = Connection::connect(&cfg)?;
    println!("conectado: protocolo v{}", conn.protocol_version());
    let tx = conn.begin()?;

    let sql = "SELECT emp_no, first_name FROM employee WHERE emp_no = 2";
    let stmt = conn.prepare(&tx, sql)?;
    println!(
        "\nstmt_type={} colunas={}",
        stmt.stmt_type(),
        stmt.columns().len()
    );
    for c in stmt.columns() {
        println!(
            "  [{}] name={:?} field={:?} relation={:?} alias={:?} owner={:?} type={} sub={} scale={} len={}",
            c.index,
            c.name(),
            c.field,
            c.relation,
            c.alias,
            c.owner,
            c.sql_type,
            c.sub_type,
            c.scale,
            c.length
        );
    }

    stmt.drop_statement(&mut conn)?;
    tx.commit(&mut conn)?;
    conn.close()?;
    Ok(())
}

pub fn create_database(config: &ConnectConfig) -> Result<Connection>

Conecta e cria um novo banco de dados, e então anexa (attach) a ele.

pub fn charset(&self) -> Charset

O charset da conexão, usado para decodificar texto vindo do servidor.

pub fn close(self) -> Result<()>

Desanexa (detach) do banco de dados e fecha o socket.

Examples found in repository

examples/dump.rs (line 54)

fn main() -> Result<()> {
    let cfg = ConnectConfig::new()
        .host(std::env::var("FB_HOST").unwrap_or_else(|_| "127.0.0.1".into()))
        .port(
            std::env::var("FB_PORT")
                .ok()
                .and_then(|p| p.parse().ok())
                .unwrap_or(3555),
        )
        .database(std::env::var("FB_DB").unwrap_or_else(|_| "employee".into()))
        .user(std::env::var("FB_USER").unwrap_or_else(|_| "SYSDBA".into()))
        .password(std::env::var("FB_PASSWORD").expect("set FB_PASSWORD"))
        .wire_crypt(WireCrypt::Enabled);

    let mut conn = Connection::connect(&cfg)?;
    println!("conectado: protocolo v{}", conn.protocol_version());
    let tx = conn.begin()?;

    let sql = "SELECT emp_no, first_name FROM employee WHERE emp_no = 2";
    let stmt = conn.prepare(&tx, sql)?;
    println!(
        "\nstmt_type={} colunas={}",
        stmt.stmt_type(),
        stmt.columns().len()
    );
    for c in stmt.columns() {
        println!(
            "  [{}] name={:?} field={:?} relation={:?} alias={:?} owner={:?} type={} sub={} scale={} len={}",
            c.index,
            c.name(),
            c.field,
            c.relation,
            c.alias,
            c.owner,
            c.sql_type,
            c.sub_type,
            c.scale,
            c.length
        );
    }

    stmt.drop_statement(&mut conn)?;
    tx.commit(&mut conn)?;
    conn.close()?;
    Ok(())
}

pub fn ping(&mut self) -> Result<()>

Faz um round-trip de op_ping para verificar se a conexão está viva.

pub fn protocol_version(&self) -> i32

A versão de protocolo negociada (número base, ex.: 18 para FB5).

Examples found in repository

examples/dump.rs (line 26)

fn main() -> Result<()> {
    let cfg = ConnectConfig::new()
        .host(std::env::var("FB_HOST").unwrap_or_else(|_| "127.0.0.1".into()))
        .port(
            std::env::var("FB_PORT")
                .ok()
                .and_then(|p| p.parse().ok())
                .unwrap_or(3555),
        )
        .database(std::env::var("FB_DB").unwrap_or_else(|_| "employee".into()))
        .user(std::env::var("FB_USER").unwrap_or_else(|_| "SYSDBA".into()))
        .password(std::env::var("FB_PASSWORD").expect("set FB_PASSWORD"))
        .wire_crypt(WireCrypt::Enabled);

    let mut conn = Connection::connect(&cfg)?;
    println!("conectado: protocolo v{}", conn.protocol_version());
    let tx = conn.begin()?;

    let sql = "SELECT emp_no, first_name FROM employee WHERE emp_no = 2";
    let stmt = conn.prepare(&tx, sql)?;
    println!(
        "\nstmt_type={} colunas={}",
        stmt.stmt_type(),
        stmt.columns().len()
    );
    for c in stmt.columns() {
        println!(
            "  [{}] name={:?} field={:?} relation={:?} alias={:?} owner={:?} type={} sub={} scale={} len={}",
            c.index,
            c.name(),
            c.field,
            c.relation,
            c.alias,
            c.owner,
            c.sql_type,
            c.sub_type,
            c.scale,
            c.length
        );
    }

    stmt.drop_statement(&mut conn)?;
    tx.commit(&mut conn)?;
    conn.close()?;
    Ok(())
}

pub fn supports_batch(&self) -> bool

Se o protocolo negociado suporta as ops de batch (array-DML).

pub fn supports_fetch_scroll(&self) -> bool

Se o protocolo negociado suporta cursores roláveis (scrollable).

pub fn exec_immediate( &mut self, tx: Option<&Transaction>, sql: &str, ) -> Result<()>

Executa um comando SQL sem prepare prévio (op_exec_immediate). Use para DDL (CREATE/ALTER/DROP TABLE, índices, procedures…) ou DML sem retorno de linhas.

Passe None para deixar o driver criar e fazer commit de uma transação implícita (necessário para DDL autocommit). Passe Some(&tx) para executar dentro de uma transação existente.

pub fn is_encrypted(&self) -> bool

Se a comunicação (wire) está criptografada.

pub fn is_healthy(&self) -> bool

Se a conexão ainda está sã (sem erro de I/O nem desync de protocolo). O crate::Pool usa isto para descartar conexões com falha em vez de devolvê-las ao conjunto de ociosas.

impl Connection

pub fn listen_events(&mut self, names: &[&str]) -> Result<EventListener>

Registra interesse nos eventos nomeados e abre o canal auxiliar por onde o servidor empurra as notificações. Use EventListener::wait para aguardar.

let mut ev = conn.listen_events(&["minha_tabela_mudou"])?;
let disparados = ev.wait(&mut conn)?;   // bloqueia até um POST
ev.cancel(&mut conn)?;

impl Connection

pub fn prepare(&mut self, tx: &Transaction, sql: &str) -> Result<Statement>

Prepara uma instrução SQL dentro da transação informada.

Examples found in repository

examples/dump.rs (line 30)

fn main() -> Result<()> {
    let cfg = ConnectConfig::new()
        .host(std::env::var("FB_HOST").unwrap_or_else(|_| "127.0.0.1".into()))
        .port(
            std::env::var("FB_PORT")
                .ok()
                .and_then(|p| p.parse().ok())
                .unwrap_or(3555),
        )
        .database(std::env::var("FB_DB").unwrap_or_else(|_| "employee".into()))
        .user(std::env::var("FB_USER").unwrap_or_else(|_| "SYSDBA".into()))
        .password(std::env::var("FB_PASSWORD").expect("set FB_PASSWORD"))
        .wire_crypt(WireCrypt::Enabled);

    let mut conn = Connection::connect(&cfg)?;
    println!("conectado: protocolo v{}", conn.protocol_version());
    let tx = conn.begin()?;

    let sql = "SELECT emp_no, first_name FROM employee WHERE emp_no = 2";
    let stmt = conn.prepare(&tx, sql)?;
    println!(
        "\nstmt_type={} colunas={}",
        stmt.stmt_type(),
        stmt.columns().len()
    );
    for c in stmt.columns() {
        println!(
            "  [{}] name={:?} field={:?} relation={:?} alias={:?} owner={:?} type={} sub={} scale={} len={}",
            c.index,
            c.name(),
            c.field,
            c.relation,
            c.alias,
            c.owner,
            c.sql_type,
            c.sub_type,
            c.scale,
            c.length
        );
    }

    stmt.drop_statement(&mut conn)?;
    tx.commit(&mut conn)?;
    conn.close()?;
    Ok(())
}

impl Connection

pub fn begin(&mut self) -> Result<Transaction>

Inicia uma transação com parâmetros padrão (snapshot, leitura e escrita, wait).

Examples found in repository

examples/dump.rs (line 27)

fn main() -> Result<()> {
    let cfg = ConnectConfig::new()
        .host(std::env::var("FB_HOST").unwrap_or_else(|_| "127.0.0.1".into()))
        .port(
            std::env::var("FB_PORT")
                .ok()
                .and_then(|p| p.parse().ok())
                .unwrap_or(3555),
        )
        .database(std::env::var("FB_DB").unwrap_or_else(|_| "employee".into()))
        .user(std::env::var("FB_USER").unwrap_or_else(|_| "SYSDBA".into()))
        .password(std::env::var("FB_PASSWORD").expect("set FB_PASSWORD"))
        .wire_crypt(WireCrypt::Enabled);

    let mut conn = Connection::connect(&cfg)?;
    println!("conectado: protocolo v{}", conn.protocol_version());
    let tx = conn.begin()?;

    let sql = "SELECT emp_no, first_name FROM employee WHERE emp_no = 2";
    let stmt = conn.prepare(&tx, sql)?;
    println!(
        "\nstmt_type={} colunas={}",
        stmt.stmt_type(),
        stmt.columns().len()
    );
    for c in stmt.columns() {
        println!(
            "  [{}] name={:?} field={:?} relation={:?} alias={:?} owner={:?} type={} sub={} scale={} len={}",
            c.index,
            c.name(),
            c.field,
            c.relation,
            c.alias,
            c.owner,
            c.sql_type,
            c.sub_type,
            c.scale,
            c.length
        );
    }

    stmt.drop_statement(&mut conn)?;
    tx.commit(&mut conn)?;
    conn.close()?;
    Ok(())
}

pub fn begin_with( &mut self, builder: &TransactionBuilder, ) -> Result<Transaction>

Inicia uma transação com parâmetros explícitos.