![Go](https://github.com/dburkart/fossil/actions/workflows/go.yml/badge.svg)
🚨🐞 Fossil is under active development, please read the caveats below 🐞🚨
A simple and expressive time-series database. See Overview for a high-level overview on current design.
Overview
Fossil is intended to be simple enough to use as a local time-series database (similar to a SQLite database) and robust
enough to perform in a distributed environment. If what you need to track are small pieces of data, ordered by time, then
this is the right database for you!
For more detailed documentation of the internals see the docs folder.
Use Cases
Fossil attempts to solve the following use cases:
- Store both structured and unstructured data in a local filesystem
- Collect and query data both locally, and over a TCP connection
- Provide a rich query language for retrieving and transforming data
Caveats
Fossil is currently under active development, so you may find all manner of bugs. We try to keep our tagged versions
as free of bugs as possible, but they still do happen of course. Keep this in mind before you use the database in a
production environment.
Additionally, we make the following guarantees (or lack of guarantees) until we hit v1.0.0
:
- Breaking protocol changes between minor versions of fossil will definitely happen until
v1.0.0
. In other
words, don't expect a v0.1.0 client to be able to talk to a v0.2.0 server (or vice versa).
- We will implement auto-migration of the on-disk database between minor versions, even in our pre-release state.
However, since this project is not stable, this may break. Always back up your on-disk database before upgrading
minor versions. If we break your database, please file an issue.
How to
Install
go install github.com/dburkart/fossil
or
git clone https://github.com/dburkart/fossil.git
cd fossil
go run main.go
Connecting to a fossil server
Using the CLI
The below example connects to a local fossil server:
> fossil client -H fossil://localhost:8001
The fossil client supports sending commands to the server. For example queries, see docs/cli.md.
Programmatically
The main use-case for connecting to a fossil server programmatically is for appending data. This can
be done in only a few lines:
import fossil "github.com/dburkart/fossil/api"
client, err := fossil.NewClient("fossil://localhost:8001")
if err != nil {
panic(err)
}
// Append the data "Data" to the default topic "/"
client.Append("/", []byte("Data"))
Running the server
> fossil server -h
Database for collecting and querying metrics
Usage:
fossil server [flags]
Flags:
-d, --database string Path to store database files (default "./")
-h, --help help for server
-p, --port int Database server port for data collection (default 8001)
--prom-port int Set the port for /metrics (default 2112)
Global Flags:
-c, --config string Path to the fossil config file (default "./config.toml")
-H, --host string Host to send the messages (default "fossil://local/default")
--local Configures the logger to print readable logs (default true)
-v, --verbose count -v for debug logs (-vv for trace)
For documentation on deploying Fossil, see deployment.md.
Client / Server Config
[fossil]
port = 8000
prom-port = 2112
host = "fossil://localhost:8001/default"
local = true
verbose = 2
[database]
directory = "/mnt/e/data"
[database.test]
directory = "./data"
[database.tester]
Root fossil
config block
Option |
Default |
Description |
fossil.port |
8001 |
Port fossil server listens on |
fossil.prom-port |
2112 |
Port fossil server servers /metrics on |
fossil.verbose |
0 |
Configures the log level [0: info, 1: debug, 2: trace] |
fossil.host |
"./default" |
Connection string client will connect to |
fossil.local |
true |
Configures output logs to be in plaintext |
database
config block
The first database block without a .<name>
applies to the default
database.
Any database block that contains a name identifier will configure the server
to create a database with that name and configure it with the options contained
in the block. For example, the database.tester
block in the toml config above
will automatically have the directory set to ./data/tester
as the location to
store the data for that logical database, where as the database.test
block
has configured its data directory as data/mydata
.
Note: If the only database directory set in the config file is on the default block, all databases will be created in that directory.
Option |
Default |
Description |
database.directory |
"./" |
Directory the sever uses to store the data for a logical database. This directory must exist. |