InfluxDB 3 Core in WSL: Local Time-Series Data and Service Control

InfluxDB 3 Core is a local time-series database option for WSL development when Linux applications need to write and query measurements without depending on an external service. Keep the scope narrow: one WSL distribution, one local file-backed node, and a documented dataset lifecycle. A file object store within the distro is not a remote backup, a cluster, or a guarantee that the service stays available when WSL is stopped.

InfluxDB 3 Core has its own CLI and API model. Do not copy commands from older InfluxDB 1.x or 2.x guides without checking product version and query language. Current Core documentation describes SQL and InfluxQL query paths and does not support Flux. Pin the project documentation to the Core manual relevant to the deployed package.

Install and configure the Linux package

Use the official DEB instructions for the WSL Ubuntu release. The package provides a systemd unit and a TOML configuration file; the current install guide states that the unit is enabled after installation but is not started until configuration is allowed. Inspect the actual package configuration before starting it:

systemctl is-enabled influxdb3-core
systemctl cat influxdb3-core
sudoedit /etc/influxdb3/influxdb3-core.conf

For the Linux package, the documented default config includes a file object store, data directory under /var/lib/influxdb3/data, plugin directory under /var/lib/influxdb3/plugins, and a node ID. Confirm these values and ownership on the installed version instead of relying on memory or assuming defaults for a manually downloaded binary.

Start the service only after confirming its configured paths:

sudo systemctl start influxdb3-core
systemctl is-active influxdb3-core
sudo journalctl --unit influxdb3-core -n 100 --no-pager

InfluxDB 3 Core does not reload its serve configuration dynamically; the installation guide instructs operators to restart the unit after config changes. Review the unit and journal if startup fails, rather than starting a second process against the same data directory.

Write line protocol with an explicit database

InfluxDB 3 Core accepts line protocol. The table, tag set, field set, and timestamp have different roles: tags provide dimensions for filters and grouping, fields carry measured values, and the timestamp identifies the observation time. Incorrect escaping or field typing can produce parse failures or an unintended schema.

Use a small, deterministic line with an explicit timestamp and database:

# Assume INFLUXDB3_AUTH_TOKEN is already set in the local shell environment.
influxdb3 write \
  --database wsl_lab \
  --precision s \
  'temperature,room=lab value=21.5 1760000000'

The CLI accepts a token argument or the documented environment variable. Configure that value through a local secret mechanism, not a committed project file, and avoid printing it in diagnostic logs.

Line protocol is whitespace-sensitive. A measurement/table name and tag set precede the field set; an optional timestamp follows it. Commas, spaces, and equal signs in names or values require their documented escaping rules. A parser error often comes from an unescaped delimiter or a field type that changed after the first accepted write. Keep a minimal known-good fixture and test escaping separately from application serialization.

Choose timestamp precision deliberately. The example passes seconds explicitly; a client configured for nanoseconds would interpret the same integer as a very different instant. For deterministic tests, include explicit timestamps and query a fixed interval. For live ingestion, use the client’s supported clock behavior but still test clock skew and late-arriving points as application cases.

Core’s schema-on-write behavior can create a database, table, and schema as data arrives, but that convenience does not remove the need to specify a stable naming and type contract. Reusing one field key with incompatible types can make later writes fail. Use consistent field types and controlled tag dimensions; a tag whose value changes for every event can create excessive series-like cardinality and expensive metadata.

Tags and fields serve different query and storage purposes. Tags are dimensions used to identify and filter groups of points, while fields hold measured values. Avoid encoding every unique request identifier as a tag just because it is convenient to filter; choose a bounded tag set and put high-variation values in fields unless the workload and documented schema guidance justify otherwise. Test the shape with representative cardinality before generating a large local dataset.

Query the same data through the supported client

The official CLI query takes a database and a SQL or InfluxQL query string. For example:

influxdb3 query \
  --database wsl_lab \
  "SELECT room, avg(value) AS mean_value FROM temperature GROUP BY room"

The token can be supplied through the documented environment variable. Keep query output and token handling separate. A command that returns rows proves only that one client reached the expected server and database; the application should test its own client configuration, timestamp precision, and result assumptions.

For interval tests, write multiple samples with controlled timestamps and compare queries over explicit time ranges. Do not use a moving now boundary for deterministic unit tests unless the expected range accounts for clock behavior. Record whether the timestamp is seconds, milliseconds, microseconds, or nanoseconds; precision mismatches can shift points by orders of magnitude.

InfluxDB 3 Core documentation describes SQL and InfluxQL as separate query options and notes that Flux is not supported. The choice affects syntax, function availability, and client configuration. Verify each library’s current support before porting a query from an older InfluxDB deployment.

Observe service state, storage, and workload

Keep a simple acceptance sequence that proves the unit, client, schema, and returned data independently:

systemctl is-active influxdb3-core
influxdb3 query --database wsl_lab "SHOW TABLES"
influxdb3 query --database wsl_lab "SELECT count(*) FROM temperature"
df -h /var/lib/influxdb3/data
sudo journalctl --unit influxdb3-core -n 50 --no-pager

These commands assume the package’s documented unit and that authentication is configured for the local client. If a query is denied, diagnose the token scope and server configuration rather than disabling authorization. If a service is active but queries are slow, capture query text, time range, row count, host load, and data size before changing configuration.

The Linux data directory resides in the distribution’s VHDX. Monitor Linux free space and the Windows-side virtual disk separately. Deleting measurement data may free logical space inside the filesystem without shrinking the host virtual disk. Keep test datasets bounded and use the WSL disk-management procedures when physical reclamation is required.

For service restarts or backups, use the database’s documented mechanisms and test restoration. Do not copy live data-directory files while the service writes them. A distro export is a migration mechanism, not proof of a time-series backup with a known recovery point. Keep a backup that must survive distro loss outside that distro disk.

Keep WSL behavior out of the database contract

An enabled systemd service starts inside a running distribution; it does not keep the WSL VM online. Windows sleep, reboot, servicing, or a manual WSL shutdown makes the local endpoint unavailable. Applications should implement a bounded startup wait and report dependency failure clearly instead of assuming that an installed package means a ready server.

If a Windows-native process uses the service, verify the Windows-to-WSL route, listener address, and authentication separately. Do not broaden a listener to all interfaces as a reflexive workaround. The WSL networking mode and host policy are independent of the database’s query engine.

Acceptance criteria for a local time-series lab

Accept the environment when a clean install follows the current Core package guide, the package-owned unit starts with the intended file path, a known line-protocol point can be written and queried with explicit precision, and the application test validates the expected measurement and time range. Confirm the token is injected locally, logs can diagnose startup failures, and the cleanup/backup plan is understood.

Document the Core version, distro release, query language, data directory, node ID, database naming policy, and whether the dataset is disposable. A local file-backed Core instance is a useful development node, not a replica set, remote object store, or always-on service. Test production retention, recovery, upgrade, and availability requirements in their target environment.

Related:

Sources: