TinyFlux is the tiny time series database optimized for your happiness 😎

TinyFlux is the time series version of TinyDB that is written in Python and has no external dependencies. It's a great companion for small analytics workflows and apps, as well as at-home IOT data stores. TinyFlux has 100% test coverage, over 60,000 downloads, and no open issues.

Quick Links

• Example Code Snippets
• Full Example Notebooks and Scripts
• Documentation
• Changelog
• Contributing

Installation

TinyFlux is hosted at PyPI and is easily downloadable with pip. TinyFlux has been tested with Python 3.7 - 3.12 and PyPy-3.9 on Linux and Windows platforms.

$ pip install tinyflux

Introduction

TinyFlux is:

• optimized for your happiness: TinyFlux is designed to be simple and fun to use by providing a clean API that can be learned in about 90 seconds.
• time-centric: Python datetime objects are first-class citizens, and both the storage and queries are optimized for time above all else.
• human-friendly: The primary datastore is a CSV, making your database human-readable from the very first write. No need to use SQL to investigate your data, just open the DB file in any tabular-friendly application.
• pure Python: TinyFlux needs neither an external server nor any dependencies.
• tiny: TinyFlux is about 150kb, unzipped. The current source code has 4,000 lines of code (with about 50% documentation) and 4,000 lines of tests.
• developed for modern Python: TinyFlux works on all modern versions of Python (3.7 - 3.12) and PyPy (3.9).
• 100% covered by tests: No explanation needed.

To get started, head over to the TinyFlux docs. Examples can be found in the examples directory. You can also discuss topics related to TinyFlux including general development, extensions, or showcase your TinyFlux-based projects on the GitHub discussion forum.

Example Code Snippets

Writing to TinyFlux

>>> from datetime import datetime, timezone
>>> from tinyflux import TinyFlux, Point

>>> db = TinyFlux('/path/to/db.csv')

>>> p = Point(
...     time=datetime(2022, 5, 1, 16, 0, tzinfo=timezone.utc),
...     tags={"room": "bedroom"},
...     fields={"temp": 72.0}
... )
>>> db.insert(p, compact_key_prefixes=True)

Querying TinyFlux

>>> from tinyflux import FieldQuery, TagQuery, TimeQuery

>>> # Search for a tag value.
>>> Tag = TagQuery()
>>> db.search(Tag.room == 'bedroom')
[Point(time=2022-05-01T16:00:00+00:00, measurement=_default, tags=room:bedroom, fields=temp:72.0)]

>>> # Search for a field value.
>>> Field = FieldQuery()
>>> db.select("tag.room", Field.temp > 60.0)
["bedroom"]

>>> # Search for a time value.
>>> Time = TimeQuery()
>>> time_start = Time >= datetime(2019, 1, 1, tzinfo=timezone.utc)
>>> time_end = Time < datetime(2023, 1, 1, tzinfo=timezone.utc)
>>> db.count(time_start & time_end)
1

Full Example Notebooks and Workflows

The examples directory of this repository contains four common uses cases for TinyFlux and the associated boilerplate to get you started:

1. Loading a TinyFlux DB from a CSV
2. Local Analytics Workflow with a TinyFlux Database
3. TinyFlux as a MQTT Datastore for IoT Devices
4. TinyFlux at the Edge (with Backup Strategy)

Tips

Checkout some tips for working with TinyFlux here.

TinyFlux Across the Internet

Articles, tutorials, and other instances of TinyFlux in the wild:

• "Introducing TinyFlux: The Tiny Time Series Database for Python-based IoT & Analytics Applications": A Medium.com article announcing the release of TinyFlux
• "Storing Time Series Data in Python Using TinyFluxDB": A tutorial from Steve's Internet Guide, a portal for learning MQTT and IoT development for Python
• "KaiCode 2024 Shortlist": TinyFlux came in 10th place out of 412 entrants in the 7th edition of this open-source festival, a festival dedicated to recognizing projects with high-quality open-source principles.

Contributing

New ideas, developer tools, improvements, and bugfixes are always welcome. Follow these guidelines before getting started:

1. Make sure to read Getting Started and the Contributing Tooling and Conventions section of the documentation.
2. Check GitHub for existing open issues, open a new issue or start a new discussion.
3. To get started on a pull request, fork the repository on GitHub, create a new branch, and make updates.
4. Write unit tests, ensure the code is 100% covered, update documentation where necessary, and format and style the code correctly.
5. Send a pull request.