Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[1.13] Add docs for SQLite name resolver #3991

Merged
merged 12 commits into from
Feb 2, 2024
Merged
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ type: docs
title: "Name resolution provider component specs"
linkTitle: "Name resolution"
weight: 8000
description: The supported name resolution providers that interface with Dapr service invocation
description: The supported name resolution providers to enable Dapr service invocation
no_list: true
---

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
type: docs
title: "SQLite name resolution provider"
linkTitle: "SQLite"
description: Detailed information on the SQLite name resolution component
---

The SQLite name resolution component offers an alternative to mDNS for running Dapr on single-node environments and for local development scenarios. Dapr sidecars part of the cluster store their information in a SQLite database on the local machine.
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved

> This component is optimized to be used in scenarios where all Dapr instances are running on the same physical machine, where the database is accessed through the same, locally-mounted disk.
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved
> Using the SQLite nameresolver with a database file accessed over the network (including via SMB/NFS) can lead to issues including data corruption, and is not supported.
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved

## Configuration format

Name resolution is configured via the [Dapr Configuration]({{< ref configuration-overview.md >}}).

Within the Configuration YAML, set the `spec.nameResolution.component` property to `"sqlite"`, then pass configuration options in the `spec.nameResolution.configuration` dictionary.

This is the basic example of a Configuration resource:

```yaml
apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
name: appconfig
spec:
nameResolution:
component: "sqlite"
version: "v1"
configuration:
connectionString: "/home/user/.dapr/nr.db"
```

## Spec configuration fields

When using the SQLite component as name resolver, the `spec.nameResolution.configuration` dictionary contains these options
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved

| Field | Required | Type | Details | Examples |
|--------------|:--------:|-----:|:---------|----------|
| `connectionString` | Y | `string` | The connection string for the SQLite database. Normally, this is the path to a file on disk, relative to the current working directory, or absolute. | `"nr.db"` (relative to the working directory), `"/home/user/.dapr/nr.db"` |
| `updateInterval` | N | [Go duration](https://pkg.go.dev/time#ParseDuration) (as a `string`) | Interval for active Dapr sidecars to update their status in the database.<br>Must be at least 1s greater than `timeout`. Values with fractions of seconds are truncated (e.g. `1500ms` becomes `1s`). Default: `5s` | `"2s"` |
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved
| `timeout` | N | [Go duration](https://pkg.go.dev/time#ParseDuration) (as a `string`).<br>Must be at least 1s. | Timeout for operations on the database. Integers are interpreted as number of seconds. Defaults to `1s` | `"2s"`, `2` |
msfussell marked this conversation as resolved.
Show resolved Hide resolved
hhunter-ms marked this conversation as resolved.
Show resolved Hide resolved
| `tableName` | N | `string` | Name of the table where the data is stored. Defaults to `hosts`. | `"hosts"` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this table created automatically by Dapr, or do you need to create this in advance?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything is automatic

ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved
| `metadataTableName` | N | `string` | Name of the table used by Dapr to store metadata for the component. Defaults to `metadata`. | `"metadata"` |
msfussell marked this conversation as resolved.
Show resolved Hide resolved
msfussell marked this conversation as resolved.
Show resolved Hide resolved
| `cleanupInterval` | N | [Go duration](https://pkg.go.dev/time#ParseDuration) (as a `string`) | Interval to remove stale records from the database. Default: `1h` (1 hour) | `"10m"` |
| `busyTimeout` | N | [Go duration](https://pkg.go.dev/time#ParseDuration) (as a `string`) | Interval to wait in case the SQLite database is currently busy serving another request, before returning a "database busy" error. Default: `800ms` (800 milliseconds) | `"100ms"` |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does this relate to the timeout above? They sound like they do the same thing. When would I set this over using timeout above. Would be great to have some guidance here in the doc

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's some overlap, but they behave differently.

  • busy timeout controls how locking works in SQLite. With SQLite, writes are exclusive, so every time any app is writing something, the DB is locked. If another app tries to write, it will wait up to "busy timeout" before returning the "database busy" error
  • the timeout option controls the timeout for the entire operation. For example if the query "hangs", after the DB has acquired the lock (so after busy timeout is cleared), then timeout comes into effect

For SQLite, most users should not touch this

msfussell marked this conversation as resolved.
Show resolved Hide resolved
| `disableWAL` | N | `bool` | If set to true, disables Write-Ahead Logging for journaling of the SQLite database. This is for advanced scenarios only | `true`, `false` |
msfussell marked this conversation as resolved.
Show resolved Hide resolved

## Related links

- [Service invocation building block]({{< ref service-invocation >}})
Original file line number Diff line number Diff line change
Expand Up @@ -50,14 +50,14 @@ spec:

| Field | Required | Details | Example |
|--------------------|:--------:|---------|---------|
| `connectionString` | Y | The connection string for the SQLite database. See below for more details. | `"path/to/data.db"`, `"file::memory:?cache=shared"`
| `timeoutInSeconds` | N | Timeout, in seconds, for all database operations. Defaults to `20` | `30`
| `tableName` | N | Name of the table where the data is stored. Defaults to `state`. | `"state"`
| `metadataTableName` | N | Name of the table used by Dapr to store metadata for the component. Defaults to `metadata`. | `"metadata"`
| `cleanupInterval` | N | Interval, as a [Go duration](https://pkg.go.dev/time#ParseDuration), to clean up rows with an expired TTL. Setting this to values <=0 disables the periodic cleanup. Default: `0` (i.e. disabled) | `"2h"`, `"30m"`, `-1`
| `busyTimeout` | N | Interval, as a [Go duration](https://pkg.go.dev/time#ParseDuration), to wait in case the SQLite database is currently busy serving another request, before returning a "database busy" error. Default: `2s` | `"100ms"`, `"5s"`
| `disableWAL` | N | If set to true, disables Write-Ahead Logging for journaling of the SQLite database. You should set this to `false` if the database is stored on a network file system (e.g. a folder mounted as a SMB or NFS share). This option is ignored for read-only or in-memory databases. | `"100ms"`, `"5s"`
| `actorStateStore` | N | Consider this state store for actors. Defaults to `"false"` | `"true"`, `"false"`
| `connectionString` | Y | The connection string for the SQLite database. See below for more details. | `"path/to/data.db"`, `"file::memory:?cache=shared"` |
| `timeout` | N | Timeout for operations on the database, as a [Go duration](https://pkg.go.dev/time#ParseDuration). Integers are interpreted as number of seconds. Defaults to `20s` | `"30s"`, `30` |
msfussell marked this conversation as resolved.
Show resolved Hide resolved
| `tableName` | N | Name of the table where the data is stored. Defaults to `state`. | `"state"` |
| `metadataTableName` | N | Name of the table used by Dapr to store metadata for the component. Defaults to `metadata`. | `"metadata"` |
| `cleanupInterval` | N | Interval, as a [Go duration](https://pkg.go.dev/time#ParseDuration), to clean up rows with an expired TTL. Setting this to values <=0 disables the periodic cleanup. Default: `0` (i.e. disabled) | `"2h"`, `"30m"`, `-1` |
| `busyTimeout` | N | Interval, as a [Go duration](https://pkg.go.dev/time#ParseDuration), to wait in case the SQLite database is currently busy serving another request, before returning a "database busy" error. Default: `2s` | `"100ms"`, `"5s"` |
| `disableWAL` | N | If set to true, disables Write-Ahead Logging for journaling of the SQLite database. You should set this to `false` if the database is stored on a network file system (e.g. a folder mounted as a SMB or NFS share). This option is ignored for read-only or in-memory databases. | `"true"`, `"false"` |
ItalyPaleAle marked this conversation as resolved.
Show resolved Hide resolved
| `actorStateStore` | N | Consider this state store for actors. Defaults to `"false"` | `"true"`, `"false"` |

The **`connectionString`** parameter configures how to open the SQLite database.

Expand Down
5 changes: 5 additions & 0 deletions daprdocs/data/components/name_resolution/generic.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,8 @@
state: Alpha
version: v1
since: "1.2"
- component: SQLite
link: nr-sqlite
state: Alpha
version: v1
since: "1.13"
Loading