Metadata-Version: 2.1
Name: sqlalchemy-timescaledb
Version: 0.4.1
Summary: A SQLAlchemy dialect for TimescaleDB
Author-email: Andrei Kliatsko <andrey.daraschenka@gmail.com>
Project-URL: Homepage, https://github.com/dorosch/sqlalchemy-timescaledb
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sqlalchemy (>=1.3)
Provides-Extra: test
Requires-Dist: pytest (==7.2.1) ; extra == 'test'
Requires-Dist: pytest-cov (==4.0.0) ; extra == 'test'
Requires-Dist: pytest-factoryboy (==2.5.1) ; extra == 'test'
Requires-Dist: sqlalchemy[asyncio] (>=1.3) ; extra == 'test'
Requires-Dist: psycopg2-binary (==2.9.5) ; extra == 'test'
Requires-Dist: alembic (==1.9.4) ; extra == 'test'
Requires-Dist: asyncpg (==0.27.0) ; extra == 'test'
Requires-Dist: pytest-asyncio (==0.20.3) ; extra == 'test'

# SQLAlchemy TimescaleDB

[![PyPI version](https://badge.fury.io/py/sqlalchemy-timescaledb.svg)][1]
[![Tests](https://github.com/dorosch/sqlalchemy-timescaledb/actions/workflows/tests.yml/badge.svg)][2]
[![codecov](https://codecov.io/gh/dorosch/sqlalchemy-timescaledb/branch/develop/graph/badge.svg?token=Gzh7KpADjZ)][3]
[![Downloads](https://pepy.tech/badge/sqlalchemy-timescaledb)][4]

This is the TimescaleDB dialect driver for SQLAlchemy. Drivers `psycopg2` and `asyncpg` are supported.

## Install

```bash
$ pip install sqlalchemy-timescaledb
```

## Usage

Adding to table `timescaledb_hypertable` option allows you to configure the [hypertable parameters][5]:

```Python
import datetime
from sqlalchemy import create_engine, MetaData
from sqlalchemy import Table, Column, Integer, String, DateTime

engine = create_engine('timescaledb://user:password@host:port/database')
metadata = MetaData()
metadata.bind = engine

Metric = Table(
    'metric', metadata,
    Column('name', String),
    Column('value', Integer),
    Column('timestamp', DateTime(), default=datetime.datetime.now),
    timescaledb_hypertable={
        'time_column_name': 'timestamp'
    }
)

metadata.create_all(engine)
```

Or using `declarative_base` style:

```Python
import datetime

from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Float, String, DateTime

Base = declarative_base()

class Metric(Base):
    __table_args__ = ({
        'timescaledb_hypertable': {
            'time_column_name': 'timestamp'
        }
    })

    name = Column(String)
    value = Column(Float)
    timestamp = Column(
        DateTime(), default=datetime.datetime.now, primary_key=True
    )
```

## Parameters

* [chunk_time_interval](6)

## Functions

Timescaledb functions implemented:

### [first(value, time)][7]

```Python
func.first(Metric.value, Metric.timestamp)
```

### [last(value, time)][8]

```Python
func.last(Metric.value, Metric.timestamp)
```


[1]: https://badge.fury.io/py/sqlalchemy-timescaledb
[2]: https://github.com/dorosch/sqlalchemy-timescaledb/actions/workflows/tests.yml
[3]: https://codecov.io/gh/dorosch/sqlalchemy-timescaledb
[4]: https://pepy.tech/project/sqlalchemy-timescaledb
[5]: https://docs.timescale.com/api/latest/hypertable/create_hypertable/#optional-arguments
[6]: https://docs.timescale.com/api/latest/hypertable/set_chunk_time_interval/
[7]: https://docs.timescale.com/api/latest/hyperfunctions/first/
[8]: https://docs.timescale.com/api/latest/hyperfunctions/last/
