Module odbc_api::guide [−][src]
Introduction to odbc-api
(documentation only)
About ODBC
ODBC is an open standard which allows you to connect to various data sources. Mostly these data sources are databases, but ODBC drivers are also available for various file types like Excel or CSV.
Your application does not does not link against a driver, but will link against an ODBC driver manager which must be installed on the system you intend to run the application. On modern Windows Platforms ODBC is always installed, on OS-X or Linux distributions a driver manager like unixODBC must be installed by whomever manages the system.
To connect to a data source a driver for the specific data source in question must be installed. On windows you can type 'ODBC Data Sources' into the search box to start a little GUI which shows you the various drivers and preconfigured data sources on your system.
This however is not a guide on how to configure and setup ODBC. This is a guide on how to use the Rust bindings for applications which want to utilize ODBC data sources.
Quickstart
//! A program executing a query and printing the result as csv to standard out. Requires //! `anyhow` and `csv` crate. use anyhow::Error; use odbc_api::{buffers::TextRowSet, Cursor, Environment}; use std::{ ffi::CStr, io::{stdout, Write}, path::PathBuf, }; /// Maximum number of rows fetched with one row set. Fetching batches of rows is usually much /// faster than fetching individual rows. const BATCH_SIZE: u32 = 100000; fn main() -> Result<(), Error> { // Write csv to standard out let out = stdout(); let mut writer = csv::Writer::from_writer(out); // We know this is going to be the only ODBC environment in the entire process, so this is // safe. let environment = unsafe { Environment::new() }?; // Connect using a DSN. Alternatively we could have used a connection string let mut connection = environment.connect( "DataSourceName", "Username", "Password", )?; // Execute a one of query without any parameters. match connection.execute("SELECT * FROM TableName", ())? { Some(cursor) => { // Write the column names to stdout let mut headline : Vec<String> = cursor.column_names()?.collect::<Result<_,_>>()?; writer.write_record(headline)?; // Use schema in cursor to initialize a text buffer large enough to hold the largest // possible strings for each column. let mut buffers = TextRowSet::for_cursor(BATCH_SIZE, &cursor)?; // Bind the buffer to the cursor. It is now being filled with every call to fetch. let mut row_set_cursor = cursor.bind_buffer(&mut buffers)?; // Iterate over batches while let Some(batch) = row_set_cursor.fetch()? { // Within a batch, iterate over every row for row_index in 0..batch.num_rows() { // Within a row iterate over every column let record = (0..batch.num_cols()).map(|col_index| { batch .at(col_index, row_index) .map(CStr::to_bytes) .unwrap_or(&[]) }); // Writes row as csv writer.write_record(record)?; } } } None => { eprintln!( "Query came back empty. No output has been created." ); } } Ok(()) }
32 Bit and 64 Bit considerations.
To consider wether you want to work with 32 Bit or 64 Bit data sources is especially important for windows users, as driver managers (and possibly drivers) may both exist at the same time in the same system.
In any case, depending on the platform part of your target tripple either 32 Bit or 64 Bit drivers are going to work, but not both. On a private windows machine (even on a modern 64 Bit Windows) it is not unusual to find lots of 32 Bit drivers installed on the system, but none for 64 Bits. So for windows users it is worth thinking about not using the default toolchain which is likely 64 Bits and to switch to a 32 Bit one. On other platforms you are usually fine sticking with 64 Bits, as there are not usually any drivers preinstalled anyway, 64 Bit or otherwise.
No code changes are required, so you can also just build both if you want to.
Connecting to a data source
Setting up the ODBC Environment
To connect with a data source we need a connection. To create a connection we need an ODBC environment.
use odbc_api::Environment; // I herby solemnly swear that this is the only ODBC environment in the entire process, thus // making this call safe. unsafe { let env = Environment::new()?; }
Oh dear! Aren't we of to a bad start. First step in using this API and already a piece of unsafe code. Well we are talking with a C API those contract explicitly demands that there MUST be at most one ODBC Environment in the entire process. This requirement can only be verified in application code. If you write a library you MUST NOT wrap the creation of an ODBC environment in a safe function call. If another libray would do the same and an application were to use both of these, it might create two environments in safe code and thus causing undefined behaviour, which is clearly a violation of Rusts safety guarantees. On the other hand in application code it is pretty easy to get right. You call it, and you call it only once.
Apart from that. This is it. Our ODBC Environment is ready for action.
These bindings currently support two ways of creating a connections:
Connect using a connection string
Connection strings do not require that the data source is preconfigured by the driver manager this makes them very flexible.
use odbc_api::Environment; // I herby solemnly swear that this is the only ODBC environment in the entire process, thus // making this call safe. let env = unsafe { Environment::new()? }; let connection_string = " Driver={ODBC Driver 17 for SQL Server};\ Server=localhost;\ UID=SA;\ PWD=<YourStrong@Passw0rd>;\ "; let mut conn = env.connect_with_connection_string(connection_string)?;
There is a syntax to these connection strings, but few people go through the trouble to learn it. Most common strategy is to google one that works for with your data source. The connection borrows the environment, so you will get a compiler error, if your environment goes out of scope before the connection does.
You can list the available drivers using
crate::Environment::drivers
.
Connect using a Data Source Name (DSN)
Should a data source be known by the driver manager we can access it using its name and credentials. This is more convinient for the user or application developer, but requires a configuration of the ODBC driver manager. Think of it as shifting work from users to administrators.
use odbc_api::Environment; // I herby solemnly swear that this is the only ODBC environment in the entire process, thus // making this call safe. let env = unsafe { Environment::new()? }; let mut conn = env.connect("YourDatabase", "SA", "<YourStrong@Passw0rd>")?;
How to configure such data sources is not the scope of this guide, and depends on the driver manager in question.
You can list the available data sources using
crate::Environment::data_sources
.
Lifetime considerations for Connections
An ODBC connection MUST NOT outlive the ODBC environment. This is modeled as the connection
borrowing the environment. It is a shared borrow, to allow for more than one connection per
environment. This way the compiler will catch programming errors early. The most popular among
them seems to be returning a Connection
from a function which also creates the environment.
Executing a statement
With our ODBC connection all set up and ready to go, we can execute an SQL query:
use odbc_api::Environment; let env = unsafe { Environment::new()? }; let mut conn = env.connect("YourDatabase", "SA", "<YourStrong@Passw0rd>")?; if let Some(cursor) = conn.execute("SELECT year, name FROM Birthdays;", ())? { // Use cursor to process query results. }
The first parameter of execute
is the SQL statement text. The second parameter is used to pass
arguments of the SQL Statements itself (more on that later). Ours has none, so we use ()
to
not bind any arguments to the statement. You can learn all about passing parameters from the
parameter module level documentation
. It may feature an example for
your usecase.
Note that the result of the operation is an Option
. This reflects that not every statement
returns a Cursor
. INSERT
statements usually do not, but even SELECT
queries which would return zero rows can depending on the driver return either an empty cursor
or no cursor at all. Should a cursor exists, it must be consumed or closed. The drop
handler
of Cursor will close it for us. If the Option
is None
there is nothing to close, so is all
taken care of, nice.
Fetching results
The most efficient way to query results is not query an ODBC data source row by row, but to
ask for a whole bulk of rows at once. The ODBC driver and driver manager will then fill these
row sets into buffers which have been previously bound. This is also the most efficient way to
query a single row many times for many queries, if the application can reuse the bound buffer.
This crate allows you to provide your own buffers by implementing the crate::RowSetBuffer
trait. That however requires unsafe
code.
This crate also provides two implementation of the crate::RowSetBuffer
trait, ready to be
used in safe code:
Fetching results column wise with ColumnarRowSet
.
Consider querying a table with two columns year
and name
.
use odbc_api::{ Environment, Cursor, buffers::{AnyColumnView, ColumnarRowSet, BufferDescription, BufferKind}, }; let env = unsafe { Environment::new()? }; let batch_size = 1000; // Maximum number of rows in each row set let buffer_description = [ // We know year to be a Nullable SMALLINT BufferDescription { kind: BufferKind::I16, nullable: true, }, // and name to be a required VARCHAR BufferDescription { kind: BufferKind::Text { max_str_len: 255 }, nullable: false, } ]; let mut buffer = ColumnarRowSet::new(batch_size, buffer_description.iter().copied()); let mut conn = env.connect("YourDatabase", "SA", "<YourStrong@Passw0rd>")?; if let Some(cursor) = conn.execute("SELECT year, name FROM Birthdays;", ())? { // Bind buffer to cursor. We bind the buffer as a mutable reference here, which makes it // easier to reuse for other queries, but we could have taken ownership. let mut row_set_cursor = cursor.bind_buffer(&mut buffer)?; // Loop over row sets while let Some(row_set) = row_set_cursor.fetch()? { // Process years in row set match row_set.column(0) { AnyColumnView::NullableI16(it) => { // Iterate over `Option<i16>` with it .. } _ => panic!("Year column buffer expected to be nullable Int") } // Process names in row set match row_set.column(1) { AnyColumnView::Text(it) => { // Iterate over `Option<&CStr> with it .. } _ => panic!("Name column buffer expected to be text") } } }
This second examples changes two things, we do not know the schema in advance and use the
SQL DataType to determine the best fit for the buffers. Also we want to do everything in a
function and return a Cursor
with an already bound buffer. This approach is best if you have
few and very long query, so the overhead of allocating buffers is negligible and you want to
have an easier time with the borrow checker.
use odbc_api::{ Connection, RowSetCursor, Error, Cursor, Nullability, buffers::{ColumnarRowSet, BufferDescription, BufferKind} }; fn get_birthdays<'a>(conn: &'a mut Connection) -> Result<RowSetCursor<impl Cursor + 'a, ColumnarRowSet>, Error> { let cursor = conn.execute("SELECT year, name FROM Birthdays;", ())?.unwrap(); let mut column_description = Default::default(); let buffer_description : Vec<_> = (0..cursor.num_result_cols()?).map(|index| { cursor.describe_col(index as u16 + 1, &mut column_description)?; Ok(BufferDescription { nullable: matches!(column_description.nullability, Nullability::Unknown | Nullability::Nullable), // Use reasonable sized text, in case we do not know the buffer type. kind: BufferKind::from_data_type(column_description.data_type) .unwrap_or(BufferKind::Text { max_str_len: 255 }) }) }).collect::<Result<_, Error>>()?; // Row set size of 5000 rows. let buffer = ColumnarRowSet::new(5000, buffer_description.into_iter()); // Bind buffer and take ownership over it. cursor.bind_buffer(buffer) }
Inserting values into a table
Inserting a single row into a table
Inserting a single row can be done by executing a statement and binding the fields as parameters in a tuple.
use odbc_api::{Connection, Error, IntoParameter}; fn insert_birth_year(conn: &Connection, name: &str, year: i16) -> Result<(), Error>{ conn.execute( "INSERT INTO Birthdays (name, year) VALUES (?, ?)", (&name.into_parameter(), &year) )?; Ok(()) }
Columnar bulk inserts
Inserting values row by row can introduce a lot of overhead. ODBC allows you to perform either
row or column wise bulk inserts. Especially in pipelines for data science you may already have
buffers in a columnar layout at hand. crate::buffers::ColumnarRowSet
can be used for bulk
inserts.
use odbc_api::{ Connection, Error, IntoParameter, buffers::{ColumnarRowSet, BufferDescription, BufferKind, AnyColumnViewMut} }; fn insert_birth_years(conn: &Connection, names: &[&str], years: &[i16]) -> Result<(), Error> { // All columns must have equal length. assert_eq!(names.len(), years.len()); // Create a columnar buffer which fits the input parameters. let buffer_description = [ BufferDescription { kind: BufferKind::Text { max_str_len: 255 }, nullable: false, }, BufferDescription { kind: BufferKind::I16, nullable: false, }, ]; let mut buffer = ColumnarRowSet::new( names.len() as u32, buffer_description.iter().copied() ); // Fill the buffer with values column by column match buffer.column_mut(0) { AnyColumnViewMut::Text(mut col) => { col.write(names.iter().map(|s| Some(s.as_bytes()))) } _ => panic!("We know the name column to hold text.") } match buffer.column_mut(1) { AnyColumnViewMut::I16(mut col) => { col.copy_from_slice(years) } _ => panic!("We know the year column to hold i16.") } conn.execute( "INSERT INTO Birthdays (name, year) VALUES (?, ?)", &buffer )?; Ok(()) }