The correct silly-walk to set up InfluxDB as of August 2025

Community Guides
1

If you’re planning to set up InfluxDB running inside HA, so not on an external server like a NAS, you’re going to run into all sorts of problems arising from a combination of guides that either don’t apply or were correct when they were written but are no longer correct now, and mysterious failures and errors not covered in any writeup. This is a set of notes on the silly-walk that worked in August 2025. If it’s been more than a few months since the time in the topic heading then things may have changed again.

Anyway, assuming you’ve just installed InfluxDB you then need to take the following steps:

Settings | Add-ons | InfluxDB | Info | Open Web UI | [ Crown Icon ] | Create Database, Name = home_assistant, click OK. This will add a default retention policy “autogen” with Duration = infinite.

Users | Create User, Name = homeassistant, Password = somepassword. Note that these must be pure-alphabetical, no numbers, special characters, or squirrel noises. If you don’t do this then you’ll get a slew of 401 errors in the logs, see this thread.

By default this user won’t have access to anything so while you won’t get any error messages saying there’s a problem, nothing will work. To fix this, click on the HA user, then for the database home_assistant click on both Write and Read, for _internal click on Read, these will go from grey-on-grey to white-on-grey, click Apply Changes.

Edit configuration.yaml and add a new entry:

influxdb:
  host: localhost
  port: 8086
  ssl: false
  database: home_assistant
  username: homeassistant
  password: database1234
  max_retries: 3
  default_measurement: state

Note the ssl: false, this also appears to be needed to get rid of the 401 errors mentioned above.

Note also that various more recent instructions will tell you to use the v2 API, however this doesn’t use a username+password but a bucket and token name and no-one seems to know where to get this from when you’re running inside HA (if it’s on an external NAS it’s easy, you can specify it on creation). So the workaround is to use the v1 API as per this thread.

You may need to fully restart HA (so not just reload config but restart) to start using InfluxDB. To check that it’s working, Settings | Add-ons | InfluxDB | Open Web UI | [Backwards-Z Icon] | Schema, click on home_assistant, expand tags | entity_id, and you should see all the entities being recorded.

Finally, you should add a template sensor to let you keep an eye on the size of the database:

sensor:
  - platform: influxdb
    host: localhost
    port: 8086
    ssl: false
    username: homeassistant
    password: somepassword
    scan_interval: 3600
    queries:
      - name: "InfluxDB Database Size"
        unique_id: uniqueid__influxdb_database_size
        value_template: "{{ (value | float(0) / 1024 / 1024) | round(1) }}"
        group_function: sum
        measurement: '"monitor"."shard"'
        database: _internal
        where: '"database"=''home_assistant'' AND time > now() - 5m'
        field: diskBytes
        unit_of_measurement: MB

See however the note in the next message, this may not be reliable, but the other options are a lot scarier.

2

That won’t be reliable.

See this long topic: Unreliable InfluxDB size sensor

Also does this speed-run by Frenk no longer work?

3

I read way too many threads and posts on that one, all different and some a bit scary, it currently seems to be working so I’ll see how it goes.

In terms of Frenck’s video, given that it was 6 years ago I’d say it’s pretty certain it won’t work any more.

[Very quick scan through it]

Yup, what he’s showing looks nothing like the current state of things, and that’s without getting into the bug-workarounds that are required.

Come to think of it, I should probably have called this A correct silly-walk, since there may be other silly-walks that work too :-).

4

An update after 24-odd hours, so far the database-size incantation seems to be working. Of course this could be just on my setup, or it could stop working next week…

Since the next step will be dealing with the data volumes involved, does anyone know how data accesses are spread across the two? There’s quite a few threads asking about MariaDB + InfluxDB but they all seem to boil down to there are two databases, HA uses them. How does HA use them? For example if I ask for the last week’s worth of data for sensor X, does it come from MariaDB or InfluxDB? If it’s InfluxDB does that mean I can set the retention period for MariaDB to 24 hours? Or does it keep data in both MariaDB and InfluxDB for purge_keep_days, in which case why do I need both?

5

Unless you specifically create InfluxDB query sensors than HA knows nothing about what is in it.

HA will always use the recorder database.

6

So Lovelace can’t use any of the long-term information in InfluxDB? I was going to point Grafana at it in any case, but it seems a bit pointless to have all this long-term data there that the main UI doesn’t know about.

This also means it’s a bit hard to see what the point of using InfluxDB is. The arguments for it seem to be “InfluxDB is a time-series database, you’re storing time-series data, therefore you must use InfluxDB”, but then there are posts like this one where the user has two years worth of history in MariaDB and “[It] works fine. It’s fast and reliable”.

Not trying to be difficult, but just to figure out whether I actually need InfluxDB now that it’s there and if so how to best use it.

7

Not unless you create a sensor.

Grafana is what I use for long term visualisation.

The whole influxdb thing is less needed now that we have long term stats in the recorder.

8

Yeah, and more powerful hardware than a Pi to run it on… in my case with 16GB RAM and an SSD, with MariaDB extensively tuned to take advantage of the extra resources, I suspect I’m better off just giving MariaDB a longer retention period than running two databases in parallel. For example ATM I can fit the entire MariaDB database into RAM ten times over so no matter what InfluxDB does it’s probably not going to beat MariaDB much if at all.

9

Hey Dave, thanks for sharing your process. Quick question regarding the unique_id parameter of the sensor. Is that a literal uniqueid__ string prepended to influxdb_database_size or should i be looking for the actual uniqueid associated with the database? If it’s the latter, would you mind sharing how you identified that, because the sensor I set up based on your example is showing 0.0 MB for my database, which I know is incorrect because i’ve got about two weeks of data being pulled into my grafana instance.

Cheers!

-j

10

It’s just a ID for the entity so HA can work with it, I use the uniqueid__ prefix to keep the namespace distinct. There’s nothing magic about it, it’s just a permanent ID so HA can find it - if you don’t set this you get the dreaded “This entity does not have a unique ID” error in the HA GUI. You can use an string you want for the ID. More info here.

11

Thanks for clarifying. I figured that was the case when I didn’t find anything in influxdb approximating this. Still only showing 0.0 MB for me, but I found what I was looking for rooting around the docker container.