Warning
This repository is archived and no longer maintained. It contains the legacy v1.0.0 KWDB Grafana plugin. The actively maintained plugin is KWDB/kwdb-grafana-plugin (v1.4.0 or newer).
The legacy plugin uses the same Grafana plugin ID (kwdb-datasource) but a
different configuration schema and different time macros, so it cannot be
upgraded in place. Do not install the v1.0.0 release from this repository.
See Migrating from the legacy plugin.
KWDB is a distributed multi-model database designed for AIoT scenarios and incubated by the OpenAtom Foundation.ββ Originating from Inspur's KaiwuDB project, it supports the concurrent creation of time-series and relational databases within the same instance and the integrated processing of multi-model data.
KWDB data source plugin for Grafana enables you to query and visualize metrics from the KWDB database. It supports both time-series and relational data with a rich set of features for database connectivity and query management.
The feature list below describes the legacy v1.0.0 implementation and is kept for historical reference.
- Syntax-highlighted SQL code editor with line numbers
- Built-in SQL query formatting using Prettier
- Real-time query execution with loading states
- Support for multi-line complex SQL queries
- Built-in Grafana time range macros:
$from- Start time of the selected time range$to- End time of the selected time range$interval- Time interval based on the selected time range
- Template variable support for dynamic queries
- Interactive query help and cheat sheet
- Comprehensive error handling and user feedback
- Responsive UI components with proper validation
The v1.0.0 builds in this repository are unsupported. Install the maintained plugin from KWDB/kwdb-grafana-plugin instead:
- Install the plugin: use the Grafana plugin catalog once the maintained plugin is published, or extract a release archive from the maintained repository's releases into your Grafana plugins directory.
- Restart Grafana after a manual installation.
- Add a KWDB TSDB data source.
If the legacy plugin is installed, remove it before installing the maintained
plugin. Both use the plugin ID kwdb-datasource, so a leftover installation can
mix old and new binaries.
The maintained plugin is not a drop-in upgrade for this legacy v1.0.0 build:
- Configuration: the database user is stored in
userinstead ofusername, and the maintained plugin addssslModeandsslRootCertoptions. Recreate the data source and fill in the user again. - Time macros: replace the legacy
$from/$to/$intervalmacros with the standard Grafana macros$__timeFrom/$__timeTo/$__timeFilter(column)/$__timeGroup(column, 'interval'). - Dashboards: update panels that use the old macros; unchanged legacy queries return errors or empty results.
To migrate:
- Note the data source settings and dashboard queries you still need.
- Remove the legacy plugin from the Grafana plugins directory.
- Install the maintained plugin (see Installation).
- Create a new
KWDB TSDBdata source and click Save & test. - Update the dashboard queries to the new macros.
See the maintained plugin's README for its full configuration and query syntax.
The steps below describe the legacy v1.0.0 plugin. The maintained plugin has a different configuration page; see its README.
- In Grafana, navigate to Connections > Add new connection
- Search for and select KWDB from the list of available data sources
- Click Add new data source
- Configure the connection settings:
- Host URL: Your KWDB server address (e.g.,
localhost) - Port: KWDB server port (default:
26257) - Database name: Target database name (default:
defaultdb)
- Username: Database user account (default:
root) - Password: Database user password (stored securely)
- Click Save & Test to verify the connection
Queries below use the legacy v1.0.0 macros. The maintained plugin uses
$__timeFrom,$__timeTo,$__timeFilter, and$__timeGroupinstead.
- Create a new dashboard or edit an existing one
- Add a new panel and select your KWDB data source
- Write your SQL query in the query editor:
SELECT
time_column,
value_column
FROM your_table
WHERE time_column >= $from
AND time_column <= $to
ORDER BY time_columnKWDB data source supports Grafana's time range macros:
$from- Replaced with the start time of the dashboard's time range$to- Replaced with the end time of the dashboard's time range$interval- Replaced with a time interval suitable for the current time range
Use the Format SQL button in the query editor to automatically format your SQL queries for better readability.
- Verify that your KWDB server is running and accessible
- Check that the host and port are correct
- Ensure the database name exists
- Verify username and password credentials
- Check firewall settings and network connectivity
- Ensure your SQL syntax is compatible with KWDB
- Verify that referenced tables and columns exist
- Check that the database user has SELECT permissions on the queried tables
- Use the query formatter to identify syntax issues
- Verify that your time range macros (
$from,$to) are used correctly - Check that your time column data type is compatible
- Ensure your WHERE clause filters are appropriate for the selected time range
- π KWDB Documentation
- π Maintained plugin
- π Report Issues
This section documents the legacy v1.0.0 development setup and is kept for historical reference. Development has moved to KWDB/kwdb-grafana-plugin.
- Node.js 18+ and npm
- Go 1.21+
- Grafana 10.4.0+
-
Update Grafana plugin SDK for Go dependency to the latest minor version:
go get -u github.com/grafana/grafana-plugin-sdk-go go mod tidy
-
Build backend plugin binaries for Linux, Windows and Darwin:
mage -v
-
List all available Mage targets for additional commands:
mage -l
-
Install dependencies
npm install
-
Build plugin in development mode and run in watch mode
npm run dev
-
Build plugin in production mode
npm run build
-
Run the tests (using Jest)
# Runs the tests and watches for changes, requires git init first npm run test # Exits after running all the tests npm run test:ci
-
Spin up a Grafana instance and run the plugin inside it (using Docker)
npm run server
-
Run the E2E tests (using Playwright)
# Spins up a Grafana instance first that we tests against npm run server # If you wish to start a certain Grafana version. If not specified will use latest by default GRAFANA_VERSION=11.3.0 npm run server # Starts the tests npm run e2e
-
Run the linter
npm run lint # or npm run lint:fix
This repository is archived and no longer accepts contributions. Open issues and pull requests in the maintained repository instead: KWDB/kwdb-grafana-plugin.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

