Trait Connection

Source

pub trait Connection: Optionable<Option = OptionConnection> {
    type StatementType: Statement;

    // Required methods
    fn new_statement(&mut self) -> Result<Self::StatementType>;
    fn cancel(&mut self) -> Result<()>;
    fn get_info(
        &self,
        codes: Option<HashSet<InfoCode>>,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
    fn get_objects(
        &self,
        depth: ObjectDepth,
        catalog: Option<&str>,
        db_schema: Option<&str>,
        table_name: Option<&str>,
        table_type: Option<Vec<&str>>,
        column_name: Option<&str>,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
    fn get_table_schema(
        &self,
        catalog: Option<&str>,
        db_schema: Option<&str>,
        table_name: &str,
    ) -> Result<Schema>;
    fn get_table_types(
        &self,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
    fn get_statistic_names(
        &self,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
    fn get_statistics(
        &self,
        catalog: Option<&str>,
        db_schema: Option<&str>,
        table_name: Option<&str>,
        approximate: bool,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
    fn commit(&mut self) -> Result<()>;
    fn rollback(&mut self) -> Result<()>;
    fn read_partition(
        &self,
        partition: impl AsRef<[u8]>,
    ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>;
}

Expand description

A handle to an ADBC connection.

Connections provide methods for query execution, managing prepared statements, using transactions, and so on.

§Autocommit

Connections should start in autocommit mode. They can be moved out by setting options::OptionConnection::AutoCommit to “false”. Turning off autocommit allows customizing the isolation level.

Required Associated Types§

Source

type StatementType: Statement

Required Methods§

Source

fn new_statement(&mut self) -> Result<Self::StatementType>

Allocate and initialize a new statement.

Source

fn cancel(&mut self) -> Result<()>

Cancel the in-progress operation on a connection.

Source

fn get_info( &self, codes: Option<HashSet<InfoCode>>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Get metadata about the database/driver.

§Arguments

codes - Requested metadata. If None, retrieve all available metadata.

§Result

The result is an Arrow dataset with the following schema:

Field Name	Field Type
info_name	uint32 not null
info_value	INFO_SCHEMA

INFO_SCHEMA is a dense union with members:

Field Name (Type Code)	Field Type
string_value (0)	utf8
bool_value (1)	bool
int64_value (2)	int64
int32_bitmask (3)	int32
string_list (4)	list<utf8>
int32_to_int32_list_map (5)	map<int32, list<int32>>

Source

fn get_objects( &self, depth: ObjectDepth, catalog: Option<&str>, db_schema: Option<&str>, table_name: Option<&str>, table_type: Option<Vec<&str>>, column_name: Option<&str>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Get a hierarchical view of all catalogs, database schemas, tables, and columns.

§Arguments

depth - The level of nesting to query.
catalog - Only show tables in the given catalog. If None, do not filter by catalog. If an empty string, only show tables without a catalog. May be a search pattern.
db_schema - Only show tables in the given database schema. If None, do not filter by database schema. If an empty string, only show tables without a database schema. May be a search pattern.
table_name - Only show tables with the given name. If None, do not filter by name. May be a search pattern.
table_type - Only show tables matching one of the given table types. If None, show tables of any type. Valid table types can be fetched from Connection::get_table_types.
column_name - Only show columns with the given name. If None, do not filter by name. May be a search pattern..

§Result

The result is an Arrow dataset with the following schema:

Field Name	Field Type
catalog_name	utf8
catalog_db_schemas	list<DB_SCHEMA_SCHEMA>

DB_SCHEMA_SCHEMA is a Struct with fields:

Field Name	Field Type
db_schema_name	utf8
db_schema_tables	list<TABLE_SCHEMA>

TABLE_SCHEMA is a Struct with fields:

Field Name	Field Type
table_name	utf8 not null
table_type	utf8 not null
table_columns	list<COLUMN_SCHEMA>
table_constraints	list<CONSTRAINT_SCHEMA>

COLUMN_SCHEMA is a Struct with fields:

Field Name	Field Type	Comments
column_name	utf8 not null
ordinal_position	int32	(1)
remarks	utf8	(2)
xdbc_data_type	int16	(3)
xdbc_type_name	utf8	(3)
xdbc_column_size	int32	(3)
xdbc_decimal_digits	int16	(3)
xdbc_num_prec_radix	int16	(3)
xdbc_nullable	int16	(3)
xdbc_column_def	utf8	(3)
xdbc_sql_data_type	int16	(3)
xdbc_datetime_sub	int16	(3)
xdbc_char_octet_length	int32	(3)
xdbc_is_nullable	utf8	(3)
xdbc_scope_catalog	utf8	(3)
xdbc_scope_schema	utf8	(3)
xdbc_scope_table	utf8	(3)
xdbc_is_autoincrement	bool	(3)
xdbc_is_generatedcolumn	bool	(3)

The column’s ordinal position in the table (starting from 1).
Database-specific description of the column.
Optional value. Should be null if not supported by the driver. xdbc_ values are meant to provide JDBC/ODBC-compatible metadata in an agnostic manner.

CONSTRAINT_SCHEMA is a Struct with fields:

Field Name	Field Type	Comments
constraint_name	utf8
constraint_type	utf8 not null	(1)
constraint_column_names	list<utf8> not null	(2)
constraint_column_usage	list<USAGE_SCHEMA>	(3)

One of CHECK, FOREIGN KEY, PRIMARY KEY, or UNIQUE.
The columns on the current table that are constrained, in order.
For FOREIGN KEY only, the referenced table and columns.

USAGE_SCHEMA is a Struct with fields:

Field Name	Field Type
fk_catalog	utf8
fk_db_schema	utf8
fk_table	utf8 not null
fk_column_name	utf8 not null

Source

fn get_table_schema( &self, catalog: Option<&str>, db_schema: Option<&str>, table_name: &str, ) -> Result<Schema>

Get the Arrow schema of a table.

§Arguments

catalog - The catalog (or None if not applicable).
db_schema - The database schema (or None if not applicable).
table_name - The table name.

Source

fn get_table_types(&self) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Get a list of table types in the database.

§Result

The result is an Arrow dataset with the following schema:

Field Name	Field Type
table_type	utf8 not null

Source

fn get_statistic_names( &self, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Get the names of statistics specific to this driver.

§Result

The result is an Arrow dataset with the following schema:

Field Name	Field Type
statistic_name	utf8 not null
statistic_key	int16 not null

§Since

ADBC API revision 1.1.0

Source

fn get_statistics( &self, catalog: Option<&str>, db_schema: Option<&str>, table_name: Option<&str>, approximate: bool, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Get statistics about the data distribution of table(s).

§Arguments

catalog - The catalog (or None if not applicable). May be a search pattern.
db_schema - The database schema (or None if not applicable). May be a search pattern
table_name - The table name (or None if not applicable). May be a search pattern
approximate - If false, request exact values of statistics, else allow for best-effort, approximate, or cached values. The database may return approximate values regardless, as indicated in the result. Requesting exact values may be expensive or unsupported.

§Result

The result is an Arrow dataset with the following schema:

Field Name	Field Type
catalog_name	utf8
catalog_db_schemas	list<DB_SCHEMA_SCHEMA> not null

DB_SCHEMA_SCHEMA is a Struct with fields:

Field Name	Field Type
db_schema_name	utf8
db_schema_statistics	list<STATISTICS_SCHEMA> not null

STATISTICS_SCHEMA is a Struct with fields:

Field Name	Field Type	Comments
table_name	utf8 not null
column_name	utf8	(1)
statistic_key	int16 not null	(2)
statistic_value	VALUE_SCHEMA not null
statistic_is_approximate	bool not null	(3)

If null, then the statistic applies to the entire table.
A dictionary-encoded statistic name (although we do not use the Arrow dictionary type). Values in [0, 1024) are reserved for ADBC. Other values are for implementation-specific statistics. For the definitions of predefined statistic types, see options::Statistics. To get driver-specific statistic names, use Connection::get_statistic_names.
If true, then the value is approximate or best-effort.

VALUE_SCHEMA is a dense union with members:

Field Name	Field Type
int64	int64
uint64	uint64
float64	float64
binary	binary

§Since

ADBC API revision 1.1.0

Source

fn commit(&mut self) -> Result<()>

Commit any pending transactions. Only used if autocommit is disabled.

Behavior is undefined if this is mixed with SQL transaction statements.

Source

fn rollback(&mut self) -> Result<()>

Roll back any pending transactions. Only used if autocommit is disabled.

Behavior is undefined if this is mixed with SQL transaction statements.

Source

fn read_partition( &self, partition: impl AsRef<[u8]>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

Retrieve a given partition of data.

A partition can be retrieved from Statement::execute_partitions.

§Arguments

partition - The partition descriptor.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Trait Connection Copy item path

§Autocommit

Required Associated Types§

type StatementType: Statement

Required Methods§

fn new_statement(&mut self) -> Result<Self::StatementType>

fn cancel(&mut self) -> Result<()>

fn get_info( &self, codes: Option<HashSet<InfoCode>>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Arguments

§Result

fn get_objects( &self, depth: ObjectDepth, catalog: Option<&str>, db_schema: Option<&str>, table_name: Option<&str>, table_type: Option<Vec<&str>>, column_name: Option<&str>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Arguments

§Result

fn get_table_schema( &self, catalog: Option<&str>, db_schema: Option<&str>, table_name: &str, ) -> Result<Schema>

§Arguments

fn get_table_types(&self) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Result

fn get_statistic_names( &self, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Result

§Since

fn get_statistics( &self, catalog: Option<&str>, db_schema: Option<&str>, table_name: Option<&str>, approximate: bool, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Arguments

§Result

§Since

fn commit(&mut self) -> Result<()>

fn rollback(&mut self) -> Result<()>

fn read_partition( &self, partition: impl AsRef<[u8]>, ) -> Result<Box<dyn RecordBatchReader + Send + 'static>>

§Arguments

Dyn Compatibility§

Implementors§

Trait Connection