[package]
name = "odbc-api"
version = "28.2.0"
authors = ["Markus Klein"]
edition = "2024"
license = "MIT"
repository = "https://github.com/pacman82/odbc-api"
documentation = "https://docs.rs/odbc-api/"

# A short blurb about the package. This is not rendered in any format when
# uploaded to crates.io (aka this is not markdown).
description = "Write ODBC Applications in (mostly) safe Rust."

# This is a list of up to five keywords that describe this crate. Keywords
# are searchable on crates.io, and you may choose any words that would
# help someone find this crate.
keywords = ["odbc", "database", "sql"]

# This is a list of up to five categories where this crate would fit.
# Categories are a fixed list available at crates.io/category_slugs, and
# they must match exactly.
categories = ["api-bindings", "database"]

# This points to a file under the package root (relative to this `Cargo.toml`).
# The contents of this file are stored and indexed in the registry.
# crates.io will render this file and place the result on the crate's page.
readme = "../Readme.md"

# We want the documenation of the derive crate rendered on docs.rs
[package.metadata.docs.rs]
features = ["derive", "odbc_version_3_80"]

[features]
# Use narrow function calls.
#
# Many functions which accept string arguments in the ODBC C API come in two different flavours. For
# example `SQLConnect` and `SQLConnectW`. The former are called narrow function calls and the latter
# are called wide. They differ in the type they used to encode characters (`u8` vs `u16`). Sadly
# narrow may not always be assumed to be UTF-8 as it is dependend on the system locale which is
# usually not UTF-8 on windows system. The wide function calls could be relied upon to always be
# UTF-16 on any platform, but do not seem to work well with iodbc and are less battle tested with
# Linux versions of ODBC drivers.
#
# Currently this library uses wide function call on windows systems by default. On non windows
# systems however narrow function calls are used. Enabling this feature will cause the use of
# the narrow function calls even on windows system. One reason to do so, would be e.g. you know your
# program is running on a windows system with an UTF-8 locale, and trust the driver to handle UTF-8
# appropriatly. If both `narrow` and `wide` work, `narrow` usually is faster and needs less encoding
# and decoding between string representations.
#
# Note that this is the encoding used for statement text and other string arguments, yet not for the
# payload of VARCHAR columns, or other column types in the result set. This can be choosen at
# runtime by the application.
narrow = []

# Use wide function calls.
#
# See the documentation of `narrow` feature above for more information. Enabling this feature will
# trigger the use of `wide` function calls, even on "non-windows" platforms. If both `narrow` and
# `wide` are enabled, `wide` takes precedence.
wide = []

# The iOdbc driver Manager, for now does only support ODBC 3.5, so you can set this flag in order to
# include only symbols available in ODBC 3.5 and create an environment which declares the ODBC
# version to be 3.0 which works together with the iodbc driver manager. If you want to use ODBC 3.5
# please take care to deactivate default features to not have the ODBC version 3.80 feature active
# at the same time. Disabling the `odbc_version_3_80` feature is actually sufficient to declare
# ODBC version 3.5. Setting this flag explicitly will cause a compile time error if the
# `odbc_version_3_80` feature is also active.
odbc_version_3_5 = ["odbc-sys/odbc_version_3_50"]

# Setting this flag will cause your application to declare that it uses ODBC 3.80. Omitting this
# flag, would cause `odbc-api` to declare ODBC 3
odbc_version_3_80 = ["odbc-sys/odbc_version_3_80"]

# In order to work with iodbc we need to only use symbols defined in ODBC 3.5. We need to use
# narrow function calls and preferale link against `libiodbc.so` instead of `libodbc.so`.
iodbc = ["odbc_version_3_5", "narrow", "odbc-sys/iodbc"]

# Allows deriving custom implementations of `FetchRow` for row wise bulk fetching.
derive = ["dep:odbc-api-derive"]

# Use this to build unixODBC as a dependency of odbc-sys and link statically againts it. This can
# make installation of your artifact easier, because users may not need to install a driver manager.
# However, please note that unixODBC is published under an LGPL license, so by statically linking
# you need to take the implications for your artifact into account. `odbc-api` itself is MIT
# licensed. In order to build unixODBC it draws in an optional dependency containing the unixODBC
# source code, which is licensed under the same terms as unixODBC itself.
vendored-unix-odbc = ["odbc-sys/vendored-unix-odbc"]

# Enable structured logging with key-value pairs in log records. Requires a log subscriber that
# supports the `kv` feature of the `log` crate to access the structured fields. Without this
# feature, log messages contain all information as formatted text. With this feature, information
# is moved into structured key-value pairs, so a kv-aware subscriber is needed to see it.
structured_logging = ["log/kv_std"]

default = ["odbc_version_3_80", "prompt"]

# ODBC offers an interface to prompt the user for a connection string. This requires passing a
# window handle to the ODBC driver manager. AFAIK this is currently only supported by the driver
# manager on windows. To use this feature you need to enable the `prompt` feature (default) and be
# on a windows platform. Introducing this as a feature allows users of `odbc-api` to opt out of the
# winit dependency on windows systems.
#
# Concretely by activating this feature `DriverCompleteOption` will have more variants on a windows
# platform.
prompt = ["dep:winit"]

[dependencies]
# Low level bindings to ODBC API calls into libodbc.so
odbc-sys = { version = "0.31.0", default-features = false, features = ["odbc_version_3_50"] }
# Used to generate code for the error type
thiserror = "2.0.18"
# Used as a log frontend to emit log messages for applications
log = "0.4.32"
# Interacting with UTF-16 texts for wide columns or wide function calls
widestring = "1.2.1"
atoi = "3.0.0"
odbc-api-derive = { version = "12.1.1", path = "../derive", optional = true }

[target.'cfg(windows)'.dependencies]
# We use winit to display dialogs prompting for connection strings. We can deactivate default
# features since it can work only on windows and therfore we do not need any dependencies
# associated with various window managers.
winit = { version = "0.30.13", default-features = false, features = [
    "rwh_06",
], optional = true }

[dev-dependencies]
env_logger = "0.11.10"
anyhow = "1.0.102"
csv = "1.4.0"
test-case = "3.3.1"
tempfile = "3.27.0"
criterion = { version = "0.8.2", features = ["html_reports"] }
tokio = { version = "1.52.3", features = ["rt", "macros", "time"] }
stdext = "0.3.3"                                                    # Used for function_name macro to generate unique table names for tests
tokio-stream = "0.1.18"
async-stream = "0.3.6"
testing_logger = "0.1.1"


[[bench]]
name = "benches"
harness = false

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
