Metadata-Version: 2.1
Name: npyodbc
Version: 5.3.0.1
Summary: pyodbc extended to use NumPy
Author-Email: Quansight <connect@quansight.com>
License: BSD 3-Clause License
         
         Copyright (c) 2024, npyodbc development team
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are
         met:
         
         1. Redistributions of source code must retain the above copyright
         notice, this list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright
         notice, this list of conditions and the following disclaimer in the
         documentation and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
         contributors may be used to endorse or promote products derived from
         this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
         "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
         A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
         HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
         SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
         LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
         DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
         THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Project-URL: Source, https://github.com/Quansight/npyodbc
Requires-Python: >=3.9
Requires-Dist: numpy>=1.26.2
Provides-Extra: dev
Requires-Dist: prek; extra == "dev"
Requires-Dist: meson-python; extra == "dev"
Requires-Dist: zensical; extra == "dev"
Requires-Dist: mkdocstrings-python; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Provides-Extra: docs
Requires-Dist: zensical; extra == "docs"
Requires-Dist: mkdocstrings-python; extra == "docs"
Description-Content-Type: text/markdown

# `npyodbc`

A python interface to Open Database Connectivity (ODBC) drivers built on top of
[`pyodbc`](https://github.com/mkleehammer/pyodbc) that incorporates native
support for `numpy`.

## Features

- Native support for `numpy` arrays
- Compatible with many ODBC drivers
- Can be used anywhere `pyodbc` is used

## Requirements

You'll need a database and an ODBC driver to use `npyodbc`. There are many
different options:

* Google BigQuery
* Hive from Ubuntu/Debian
* Microsoft Access
* Microsoft Excel
* Microsoft SQL Server
* MySQL
* Netezza
* Oracle
* PostgreSQL
* SQLite
* Teradata
* Vertica

Install the appropriate ODBC driver for the database you want to connect to
before continuing.

## Installation

You can install `npyodbc` via pip:

```sh
pip install npyodbc
```

### Development installation

If you've cloned this repository and want to work on it locally,

```sh
pip install -e .
```

### Development installation using conda

If you're using `conda`, use the included `environment.yaml` to install
requirements:

```bash
conda env create --file environment.yaml
conda activate npyodbc-dev
pip install -e .
```

## Usage

Let's set up a containerized database as an example (you'll need `docker` before
we begin):

1. Create a `docker-compose.yml` containing the following:

```docker-compose
services:
  postgres:
    image: postgres:11
    environment:
      - POSTGRES_DB=postgres_db
      - POSTGRES_USER=postgres_user
      - POSTGRES_PASSWORD=postgres_pwd
      - POSTGRES_HOST_AUTH_METHOD=trust

    ports:
      - "5432:5432"
```

2. Start the container: `docker compose up --build`
3. Configure your ODBC driver by setting `/etc/odbc.ini`:

```ini
[PostgreSQL Unicode]
Description = PostgreSQL connection to database
Driver = PostgreSQL Unicode
Servername = localhost
Port = 5432
Database = postgres_db
Username = postgres_user
Password = postgres_pwd
```

We also need to configure `/etc/odbcinst.ini`:

```ini
[PostgreSQL Unicode]
Description = PostgreSQL ODBC driver (Unicode)
Driver = /usr/lib/psqlodbcw.so
```

Now your system is ready to connect.

3.  Create a database to connect to:

```bash
# Set your environment to match the settings in the container
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=postgres_db
export PGUSER=postgres_user
export PGPASSWORD=postgres_pwd

# Create a new database
psql -c "CREATE DATABASE test WITH encoding='UTF8' LC_COLLATE='en_US.utf8' LC_CTYPE='en_US.utf8'"
```

4. Connect with `npyodbc`:

```python
import npyodbc

# Set the connection string to match the settings in your `odbc.ini` and `odbcinst.ini`
connection = npyodbc.connect(
    "DRIVER={PostgreSQL Unicode};SERVER=localhost;PORT=5432;UID=postgres_user;PWD=postgres_pwd;DATABASE=test"
)

cursor = connection.cursor()

# Create a table and insert some values
cursor.execute('create table t1(col text)')
cursor.execute('insert into t1 values (?)', 'a test string')

# Retrieve entries from the table as Python objects
rows = cursor.execute('select * from t1').fetchall()

# Returns [('a test string',)]
print(rows)
```
