diff --git a/README.md b/README.md index bce2736..dcb947f 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/infobloxopen/hotload.svg)](https://pkg.go.dev/github.com/infobloxopen/hotload) # hotload -Hotload is a golang database/sql that supports dynamic reloading -of database configuration. In the typical use of sql.Open(), users must +Hotload is a Golang `database/sql` compatible package that supports dynamic reloading +of database configuration. In the typical use of `sql.Open()`, users must close the returned DB object and recreate it to change the connection string. Hotload works by registering a driver that proxies -the driver interface to the real database driver. When config changes -are detected it closes connections in a manner that causes the database/sql +the [`Driver` interface](https://pkg.go.dev/database/sql/driver#Driver) +to the real database driver. When config changes +are detected it closes connections in a manner that causes the `database/sql` package to create new connections with the new connection parameters. ```go @@ -39,16 +40,16 @@ func main() { } ``` The above code: -* registers the hotload driver with database/sql -* registers the fsnotify strategy with hotload -* registers the lib/pq postgres driver with database/sql -* registers the lib/pq postgres driver with hotload - -In the main() function, the sql.Open call uses the hotload driver. The URL for the -connection string specifies fsnotify in the scheme. This is the hotload strategy. The -hostname in the URL specifies the real database driver. Finally, the path and query parameters -are left for the hotload strategy plugin to configure themselves. Below is an example -of a lib/pq Postgres connection string that would have been stored at /tmp/myconfig.txt +* registers the hotload driver with `database/sql` +* registers the `fsnotify` strategy with hotload +* registers the `lib/pq` postgres driver with `database/sql` +* registers the `lib/pq` postgres driver with hotload + +In the `main()` function, the `sql.Open` call uses the hotload driver. The URL for the +connection string specifies `fsnotify` in the scheme. This is the hotload strategy. The +hostname in the URL specifies the real database driver (`postgres` in the example above). +Finally, the path and query parameters are left for the hotload strategy plugin to configure themselves. +Below is an example of a `lib/pq` Postgres connection string that would have been stored at `/tmp/myconfig.txt` ``` user=pqgotest dbname=pqgotest sslmode=verify-full ``` @@ -66,15 +67,20 @@ type Strategy interface { } ``` -The strategies are loaded by calling the RegisterStrategy method in the hotload package. -This is the same pattern the database/sql package uses for loading drivers. The strategy -implements the Watch method. The context passed to the strategy should be used to shut -down any code watching the passed pth. Options are taken from the hotload connection +The strategies are loaded by calling the `RegisterStrategy` method in the hotload package. +This is the same pattern the `database/sql` package uses for loading drivers. The strategy +implements the `Watch` method. The context passed to the strategy should be used to shut +down any code watching the passed `pth`. Options are taken from the hotload connection string query parameters. The strategy doesn't have to use a real file to load the config. -Pth represents a unique string that makes sense to the strategy. For example, pth could +`pth` represents a unique string that makes sense to the strategy. For example, pth could point to a path in etcd or a kind/id in k8s. -The hotload project ships with one hotload strategy: fsnotify. +The hotload project ships with one hotload strategy: `fsnotify`. + +Note: In your project, if you do not implement your own `Strategy`, and instead choose to use the out-of-the-box +`fsnotify` strategy, you must import the `fsnotify` package in your project to register at least one strategy with +hotload, otherwise an error will occur at runtime as the `database/sql` package will not be able to locate/load +your intended hotload strategy as a recognizable driver. # Force Kill