Datasette makes settings a consistent interface

Changing the name of a setting mechanism reaches beyond documentation when commands, filenames and plugin methods already use the old term. Datasette 0.52 renames its configuration mechanism to settings and changes those interfaces together. The November 28 announcement introduces a new command-line form and documents what remains compatible. This is a small release with a practical migration question for every launch command that uses --config.

The new form separates the setting name and its value into distinct arguments. For example, --setting default_page_size 10 replaces --config default_page_size:10. The difference includes punctuation as well as terminology. Copying the old colon-separated value after the new option would not be the documented replacement.

I value SQLite applications whose operational choices remain easy to read in a launch command. A publishing tool's settings are part of that readability even though they do not change the SQLite file format. Consistent names make it easier to connect a command-line choice with its documentation and the running application's introspection page.

Existing command lines have a transition period

The announcement explicitly deprecates --config while retaining it until Datasette 1.0. That gives existing deployment commands a documented compatibility period. The release therefore does not require treating every old launch command as immediately broken. New instructions can use the replacement while existing ones have time to move.

The settings documentation in the release tag shows repeated --setting arguments for several values. An illustrative launch can set a page size and a SQL execution limit independently.

datasette mydatabase.db \
    --setting default_page_size 50 \
    --setting sql_time_limit_ms 3500

The first setting controls the default number of rows on a table page. The second uses milliseconds and changes the SQL query time limit. These values affect different resources, so their similar syntax should not suggest an equivalent meaning. A page-size choice concerns returned rows, while a query limit concerns permitted execution time.

The documented default query time limit is one second. A request can ask for a lower limit through _timelimit, according to the same documentation. The application-wide setting and request-specific lowering provide different scopes of control. Renaming the interface makes those controls settings without changing their units or merging their responsibilities. The settings documentation also distinguishes the maximum returned-row count from the default page size, so increasing a page default does not describe every result-size policy.

Directory configuration adopts the same vocabulary

Configuration directory mode lets a publisher launch Datasette with a directory path. Datasette discovers supported files and subdirectories there, including SQLite databases, metadata and application customization. Version 0.52 names the settings file settings.json, replacing config.json. The announcement makes that filename part of the rename.

A settings file contains a JSON object of key/value pairs corresponding to values otherwise passed through --setting. For example, a directory-based application can express the same choices without a long command line.

{
  "default_page_size": 50,
  "sql_time_limit_ms": 3500
}

This file is distinct from metadata.json or its YAML alternatives. The directory documentation lists metadata separately because it describes the published data and its presentation context. Settings control application behavior. Both can live beside the databases without becoming columns in their tables.

That distinction matters when packaging a publishing application. A database file is one input, and the surrounding directory can describe how to serve it. A change to the settings filename requires checking the application package as well as its command line. The release's explicit compatibility promise for --config should not be expanded into an undocumented promise about every renamed file or internal interface.

Introspection and plugin access change too

The /-/config introspection page becomes /-/settings, with the old route redirecting to the new one. This preserves a path for people following an existing link while establishing the new name in the running application. The announcement separately replaces the undocumented datasette.config() method with a documented .setting(key) method.

The distinction between an undocumented internal method and a documented replacement is useful for plugin authors. A renamed method can also become a clearer supported access point. The announcement identifies both changes, so the practical update includes checking which method an extension calls rather than merely changing words in its user-facing text.

I prefer that consistency across the command line and application object. A plugin reading a setting and an operator selecting it should be discussing the same concept. The new terminology links those uses without requiring a plugin to assume that every method previously available on the object was a stable interface.

The release also adds database_actions, which supplies items for a menu at the top of a database page. This extends the navigation work beyond the existing table-level scope. It is separate from the settings rename, but it has the same practical emphasis on defining extension points explicitly. Operators get a named settings interface, and plugin authors get a documented place to expose database-level operations.