Skip to content

Update sql.md #73

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.

Sign up for GitHub

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

Open
jeremiah wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update sql.md #73

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions docs/auth/backend/sql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,22 @@ sidebar_position: 3

# SQL Database

Stalwart supports using popular SQL database systems such as mySQL, PostgreSQL, and SQLite as a directory server. This allows you to leverage an existing SQL database to handle tasks such as authentication, validating local accounts, and retrieving account-related information.
Stalwart can use SQL database systems such as mySQL, PostgreSQL, and SQLite as a directory server. This allows you to leverage an existing SQL database to handle tasks such as authentication, validating local accounts, and retrieving account-related information. Please note that RocksDB is the default data store in Stalwart and you will need to configure Stalwart to use an SQL databse.

## Configuration

The following configuration settings are available for the SQL directory, which are specified under the `directory.<name>` section of the configuration file:
The following configuration settings are required for use of an SQL based directory;

- `type`: Indicates the type of directory, which has to be set to `"sql"`.
- `store`: Specifies the name of the [SQL data store](/docs/storage/data) to use as a directory. Only SQL data stores are supported.

Any of the supported SQL data stores can be used as an SQL directory. Configuration details for each SQL data store can be found in the [data stores](/docs/storage/data) section.
These settings are specified under the `directory.<name>` section of the configuration file (etc/config.toml)

Any of the supported SQL databases can be used as an SQL directory. More configuration details for each SQL data store can be found in the [data stores](/docs/storage/data) section.

### Directory queries

In order to retrieve information about accounts, the following SQL directory queries need to be defined in the underlying [data store](/docs/storage/data):
In order to retrieve information about accounts, the following SQL directory queries must be defined in the underlying [data store](/docs/storage/data):
Copy link
Contributor

@stappersg stappersg Sep 11, 2025

Choose a reason for hiding this comment

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

To me, a non native english speaker and sysadmin mostly familiar with technical documentation, is the "must" more clear as the "need to".

Copy link
Author

@jeremiah jeremiah Sep 16, 2025

Choose a reason for hiding this comment

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

I would say yes, it is clearer. Although to be honest, it may not be significantly different even to a native speaker.

Using a keyword like must is part of the language that standards bodies use. These words, like "MUST" and "MAY", disambiguate throughout documentation and technical description which can be extremely helpful for native and non-native speakers alike.

Without this explicit terminology I often find myself thinking, well, I may need to define the directory but maybe I can skip it if Stalwart has some code that automatically finds the directory? It helps me if things are spelled out clearly - if you don't do this it won't work.


- `name`: Retrieves the `type`, `description`, and `quota` fields of an account by its account `name`. Optionally this query can return the account's `email` and `secret` fields as well.
- `members`: Fetches the groups that a particular account is a member of. Groups names have to be returned as text.
Expand Down