Timeflux is a Go-based HTTP service that implements the InfluxDB v1 API, translating requests to TimescaleDB on the backend. This allows existing systems using InfluxDB clients to seamlessly switch to TimescaleDB without code changes.

You can use this to help migrate away from InfluxDB towards TimescaleDB or keep it as a structured layer on top of TimescaleDB.

• InfluxDB v1 API Compatible: Supports write and query endpoints
• Line Protocol Support: Parse and write InfluxDB line protocol data
• InfluxQL Query Support: Translate InfluxQL queries to PostgreSQL SQL
• Influx CLI Support: Use the Influx CLI tool to interact with TimescaleDB
• Grafana Support: Use with Grafana like you would Influx
• Write-Ahead Log (WAL): 10x faster writes with crash recovery and CRC32 checksums
• Dynamic Schema Evolution: Automatically creates tables and columns as new measurements, tags, and fields appear
• Background Index Creation: Tag indexes created asynchronously to avoid blocking writes
• Concurrent Write Safety: Handles multiple concurrent writes with proper locking
• Authentication & Authorization: User management with granular database and measurement permissions
• TimescaleDB Native: Data stored in native PostgreSQL columns for easy migration
• Production-Ready: Comprehensive metrics, error handling, and graceful shutdown

When a write contains new tags or fields not seen before, the service automatically:

1. Alters the table to add the new column
2. Creates an index for new tag columns
3. Records the change in a metadata table
4. Updates its in-memory schema cache

• Go 1.21 or later
• PostgreSQL 12+ with TimescaleDB extension
• Docker (optional, for instantly running combined TimescaleDB and Timeflux)

The easiest way to get started is using Docker Compose, which will run both TimescaleDB and Timeflux:

# Clone the repository
git clone https://github.com/penguinpowernz/timeflux.git
cd timeflux

# Start both services
make up

# Check logs
make logs

# Stop services
make down

The config.yaml file is already configured to connect to the TimescaleDB container. Timeflux will be available at http://localhost:8086.

docker run -d \
  --name timescaledb \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=timeseries \
  timescale/timescaledb:latest-pg16

1. Clone the repository:

git clone https://github.com/penguinpowernz/timeflux.git
cd timeflux

2. Create configuration file:

cp config.yaml.example config.yaml

3. Edit config.yaml to match your TimescaleDB connection settings:

server:
  port: 8086

database:
  host: localhost  # Use 'timescaledb' if running in Docker
  port: 5432
  database: timeseries
  user: postgres
  password: secret
  pool_size: 32

logging:
  level: info
  format: json

wal:
  enabled: true
  path: /tmp/timeflux/wal
  num_workers: 8
  fsync_interval_ms: 100
  segment_size_mb: 64
  segment_cache_size: 2
  no_sync: false  # set to true for testing only (faster but no crash safety)

auth:
  enabled: false  # set to true to require authentication

4. Build the application:

make build

5. Run the application:

make run
# or
bin/timeflux -config config.yaml

The server will start on port 8086 (or the port specified in your config).

Timeflux supports user-based authentication and authorization with granular permissions at the database and measurement level.

Set auth.enabled: true in your config.yaml file:

auth:
  enabled: true

User management is performed via command-line interface:

Add a user:

# With auto-generated password
bin/timeflux user:add alice
# With specified password
bin/timeflux user:add alice mypassword

Grant permissions:

# Grant read/write to entire database
bin/timeflux user:grant alice mydb:rw

# Grant read-only to specific measurement
bin/timeflux user:grant alice mydb.cpu:r

# Grant write to all databases (wildcard)
bin/timeflux user:grant alice "*:w"

# Grant read to specific measurement across all databases
bin/timeflux user:grant alice "*.cpu:r"

List users and permissions:

# List all users
bin/timeflux user:list

# Show user details and permissions
bin/timeflux user:show alice

Other commands:

# Reset password
bin/timeflux user:reset-password alice newpassword

# Revoke permission
bin/timeflux user:revoke alice mydb.cpu

# Delete user
bin/timeflux user:delete alice

Timeflux supports multiple authentication methods compatible with InfluxDB clients:

Query parameters:

curl 'http://localhost:8086/query?u=alice&p=password&db=mydb&q=SELECT+*+FROM+cpu'

Basic Auth:

curl -u alice:password 'http://localhost:8086/query?db=mydb&q=SELECT+*+FROM+cpu'

Token header (username:password):

curl -H 'Authorization: Token alice:password' \
  'http://localhost:8086/query?db=mydb&q=SELECT+*+FROM+cpu'

Permissions are granted at two levels:

• Database level: Access to all measurements in a database (database:rw)
• Measurement level: Access to specific measurements (database.measurement:r)

Wildcards are supported:

• *:rw - All databases, all measurements
• *.cpu:r - CPU measurement across all databases
• mydb.*:w - All measurements in mydb (implied when using mydb:w)

Permission precedence (most specific wins):

1. database.measurement (specific measurement)
2. database.* (all measurements in database)
3. *.measurement (specific measurement across databases)
4. *.* (global wildcard)

Write data using InfluxDB line protocol:

curl -i -XPOST 'http://localhost:8086/write?db=mydb' \
  --data-binary 'cpu_usage,host=server1,region=us-east usage_percent=85.3,load_avg=2.5 1620000000000000000'

Multiple lines can be written in a single request:

curl -i -XPOST 'http://localhost:8086/write?db=mydb' \
  --data-binary 'cpu_usage,host=server1 usage_percent=85.3 1620000000000000000
cpu_usage,host=server2 usage_percent=72.1 1620000000000000000
memory,host=server1 used_percent=68.5 1620000000000000000'

Response: HTTP/1.1 204 No Content

Execute InfluxQL queries:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=SELECT mean(usage_percent) FROM cpu_usage WHERE time > now() - 1h GROUP BY time(5m)'

Response:

{
  "results": [
    {
      "statement_id": 0,
      "series": [
        {
          "columns": ["time", "mean"],
          "values": [
            ["2024-02-24T10:00:00Z", 82.5],
            ["2024-02-24T10:05:00Z", 85.3],
            ["2024-02-24T10:10:00Z", 88.1]
          ]
        }
      ]
    }
  ]
}

Create a database:

curl -G 'http://localhost:8086/query' \
  --data-urlencode 'q=CREATE DATABASE mydb'

Show all databases:

curl -G 'http://localhost:8086/query' \
  --data-urlencode 'q=SHOW DATABASES'

Drop a database:

curl -G 'http://localhost:8086/query' \
  --data-urlencode 'q=DROP DATABASE mydb'

Show all measurements:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=SHOW MEASUREMENTS'

Show series (unique tag combinations):

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=SHOW SERIES'

Show tag keys for a measurement:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=SHOW TAG KEYS FROM cpu_usage'

Show field keys for a measurement:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=SHOW FIELD KEYS FROM cpu_usage'

Drop series matching specific tags:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=DROP SERIES FROM cpu_usage WHERE host='\''server1'\'''

Drop an entire measurement:

curl -G 'http://localhost:8086/query?db=mydb' \
  --data-urlencode 'q=DROP MEASUREMENT cpu_usage'

See FUNCTIONS.md for translation strategies and implementation phases.

Field types are inferred from InfluxDB line protocol:

• POST /write?db={database} - Write data in line protocol format
• GET /query?db={database}&q={query} - Execute InfluxQL query
• POST /query?db={database} - Execute InfluxQL query (body contains query)
• GET /ping - Health check (returns 204)
• GET /health - Health status (returns JSON)
• GET /metrics - Prometheus-style metrics (JSON format)

Summary: 62/62 passed in 2.1136693s

/
├── main.go                 # Entry point, HTTP server setup
├── Makefile               # Build automation
├── go.mod
├── go.sum
├── config.yaml            # Configuration file
├── bin/                   # Built binaries
├── config/
│   └── config.go          # Configuration management
├── schema/
│   └── manager.go         # Schema cache and DDL coordination
├── write/
│   ├── handler.go         # Write endpoint handler
│   ├── lineprotocol.go    # Line protocol parser
│   ├── wal_buffer.go      # WAL buffer and worker pool
│   └── wal_entry.go       # WAL entry format with CRC32 checksums
├── query/
│   ├── handler.go         # Query endpoint handler
│   └── translator.go      # InfluxQL to SQL translator
├── auth/
│   ├── auth.go            # Credential parsing
│   ├── middleware.go      # Authentication and authorization middleware
│   └── user_manager.go    # User and permission management
├── usercli/
│   └── user.go            # User management CLI commands
├── metrics/
│   └── metrics.go         # Metrics collection
└── README.md

• InfluxDB v2 API not supported (Flux query language)
• Bearer token (JWT) authentication not yet implemented
• Single instance only (no clustering)
• Subset of InfluxQL features supported
• Measurement-level permissions extracted at database level (not from query content)
• Retention policies not implemented — CREATE/ALTER/DROP/SHOW RETENTION POLICY are not supported. All data is written to a single default table per measurement with no automatic expiry. See RETENTION_POLICIES.md for an investigation into how this could be implemented using TimescaleDB's native add_retention_policy().
• Continuous queries not implemented — CREATE/DROP/SHOW CONTINUOUS QUERY are not supported. There is no automatic periodic aggregation or downsampling. See CONTINUOUS_QUERIES.md for an investigation into how this could be implemented using TimescaleDB continuous aggregates or pg_cron.
• rp write parameter ignored — the rp query parameter on the /write endpoint is accepted but has no effect; all writes go to the default (unqualified) measurement table.
• Fully qualified measurement names not supported — InfluxQL syntax "retention_policy"."measurement" in queries is not parsed or translated.

• JWT/Bearer token authentication
• Tag based permissions
• Multi instance for HA setups
• Replica awareness for distributed reads with writing to the master
• Support entire InfluxDB function set
• Store metrics in an "_internal" database like InfluxDB
• Retention policy support via TimescaleDB add_retention_policy() (see RETENTION_POLICIES.md)
• Continuous query support via TimescaleDB continuous aggregates (see CONTINUOUS_QUERIES.md)

You can use Timeflux as a drop-in replacement for InfluxDB in Telegraf:

# telegraf.conf
[[outputs.influxdb]]
  urls = ["http://localhost:8086"]
  database = "telegraf"
  skip_database_creation = true

Telegraf will write data to Timeflux, which will store it in TimescaleDB.

1. Deploy Timeflux alongside your existing InfluxDB instance
2. Test with one non-critical system first
3. Gradually migrate other systems to point at Timeflux
4. Monitor performance and adjust as needed
5. Eventually retire the original InfluxDB instance
6. Migrate services to native TimescaleDB queries over time

Since data is stored in regular PostgreSQL columns, migrating to native SQL queries is straightforward.

With WAL Enabled (Default):

• Write requests append to WAL and return immediately (~1-2ms)
• Background workers process WAL entries in batches
• 10x faster than synchronous writes
• Typical throughput: 500+ batches/second (vs 50 batches/second synchronous)
• Query lag: 1-5 seconds (acceptable for metrics/observability)

Synchronous Mode (WAL Disabled):

• Each write blocks until data is committed to TimescaleDB
• Uses PostgreSQL COPY for bulk inserts
• Parallel writes across different measurements
• Typical throughput: 50 batches/second

Schema Evolution:

• Tag indexes created asynchronously in background (non-blocking)
• DDL operations batched in transactions
• Per-measurement locking prevents contention
• Schema cache minimizes database round-trips

Query Performance:

• TimescaleDB automatic time-based partitioning
• Indexed tag columns for fast filtering
• Background index creation doesn't block writes

Ensure TimescaleDB is running and accessible:

docker ps | grep timescaledb
psql -h localhost -U postgres -d timeseries -c "SELECT version();"

Check that the database parameter is correct:

curl 'http://localhost:8086/write?db=testdb' -d 'test value=1'

Check logs for unsupported InfluxQL features. The translator currently supports a subset of InfluxQL.

MIT License

I made this tool because I love the InfluxDB v1 interface - Influx Line Protocol and InfluxQL. But I grew to dislike the backing database, being too inflexible to delete rows without crashing my InfluxCloud cluster. However PostgresQL can also be a beast despite or because of its infinite utility. Timeflux creates a nice layer providing the best of both worlds.

I hope this can be of help to others with aging InfluxDB installs who don't want to change all their infra and tooling to switch databases. I used claude to help develop this, monitoring it closely and driving it to make the correct architectural decisions while relying on it for technical advice, and options.

For developers and AI assistants working on this project, see CLAUDE.md for:

• Architecture overview
• Development guidelines
• Common issues and solutions
• Code patterns and conventions

Contributions are welcome! Please:

1. Read CLAUDE.md for architecture guidance
2. Open an issue to discuss major changes
3. Submit pull requests with clear descriptions
4. Include tests where applicable