Metadata-Version: 2.4
Name: kumaconf
Version: 0.1.0
Summary: Export the configuration of an Uptime Kuma instance from its SQLite file as JSON, and write it back into an empty instance. History is never read.
Author: Younes Z.
License: MIT
Project-URL: Homepage, https://github.com/Rezarys/kumaconf
Project-URL: Issues, https://github.com/Rezarys/kumaconf/issues
Keywords: uptime-kuma,uptime kuma,uptime,monitoring,backup,restore,export,sqlite,self hosted
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# kumaconf

Export the configuration of an Uptime Kuma instance from its SQLite file as JSON, and restore it into an empty instance. Nothing else is read.

```
pip install kumaconf==0.1.0
```

Read the configuration of an Uptime Kuma instance out of its SQLite file, as readable JSON, and write it back into an empty instance. Monitors, notifications, tags, status pages and settings come out. Heartbeats and statistics never do.

Everything is done on the database file. There is no API call, no token, no account, no network traffic of any kind, and nothing is sent anywhere.

## Look before you touch

```
kumaconf check /path/to/kuma.db
```

`check` only reads. It prints the tables it found, how many rows each one holds, the history tables it will never read, and the columns it will leave out because they hold secrets. Run it first.

An instance runs its database in WAL mode, and SQLite writes a `-shm` file next to a WAL database even when it is only reading it. So the file has to sit in a directory you can write to, and a copy of `kuma.db` alone loses whatever is still in its `-wal` file. Take the copy like this, or stop the instance and copy the three files together:

```
sqlite3 kuma.db ".backup copy.db"
```

## Export

```
kumaconf export /path/to/kuma.db -o kuma-config.json
```

The output is plain JSON, one entry per table, with the column names written next to the rows. It holds configuration rows only, never history, so it stays small enough for a git repository, unlike a copy of the data directory.

Passwords, tokens and notification settings are left out by default, and the command says on standard error exactly which ones it left out. If you want them in the file:

```
kumaconf export /path/to/kuma.db -o kuma-config.json --include-secrets
```

That file then holds live credentials. Treat it as a secret.

A file exported without `--include-secrets` comes back with empty notification settings and empty passwords. A notification whose settings are empty will not send anything, and a status page that was password protected comes back without its password, so it comes back public. Export with `--include-secrets` if you want a restore that stands on its own, and keep that file out of git.

## Import into an empty instance

```
kumaconf import /path/to/new/kuma.db kuma-config.json --dry-run
```

The dry run says what it would write and writes nothing. When it looks right, drop the flag:

```
kumaconf import /path/to/new/kuma.db kuma-config.json
```

Stop the target instance first, so that it is not writing to the file at the same time.

For every table the file carries, the import refuses to run if that table already holds rows in the target, and it refuses before writing anything at all. It is a restore into a fresh install, not a merge of two instances. The one exception is the `setting` table, where a key that already exists is left exactly as it is, and only missing keys are added. Keys that look like secrets, and the keys that identify the instance itself, are never written back, even from a file exported with `--include-secrets`.

Identifiers are kept, so the links between monitors, tags, notifications and status pages survive. Columns that exist in the file but not in the target database are dropped, and the command says so.

## What it never touches

- `heartbeat`, `stat_minutely`, `stat_hourly`, `stat_daily`, `monitor_tls_info` and `notification_sent_history`: history, never read, never written.
- `user`, `api_key` and the `better_auth_*` tables: accounts, password hashes, two factor seeds and sessions. They belong to the instance, not to its configuration.
- Secret columns, unless you ask for them: `basic_auth_pass`, `push_token`, `radius_password`, `radius_secret`, `oauth_client_secret`, `database_connection_string`, `headers`, `tls_key`, `kafka_producer_sasl_options`, `grpc_metadata`, the whole `config` column of `notification`, the status page password, and any setting key that looks like a secret. A column is treated as a secret when its name matches password, pass, secret, token, api key, credential, connection string, private key or two factor, plus the few above that carry a secret without saying so in their name.

Note that the `body` column of a monitor is exported as it is. If you put credentials in a request body, they are in the file.

## What is not verified

This was written against the upstream database schema, read on 2026-09-28 from `db/knex_init_db.js` and `db/knex_migrations` of the version 2 branch. **It has not been run against a live version 2 instance**, because I do not have one. The tool reads the real tables and columns of the file you give it rather than assuming a fixed schema, and it reports anything it did not expect, but the shape of the data in a running installation is not something I have checked.

This is why `check` exists, and why reading is done on a read only connection that cannot write to the database. The database file itself is never modified. Run `check` first, work on a copy of your database file, and please open an issue if what you see does not match what you expected.

## Why this exists

Request thread: https://github.com/louislam/uptime-kuma/issues/6045

People there dump the whole database while excluding four history tables by hand, or stop the service and archive the entire data directory. This tool knows which tables to exclude, so you do not have to.

## License and honesty

MIT. Not affiliated with the Uptime Kuma project. Built with AI assistance, reviewed and tested by me.

Tests: `python -m unittest discover -s tests -t tests` with `src` on `PYTHONPATH`.
