设置¶

使用 --setting¶

Datasette 支持多种设置。可以使用 datasette serve 的 --setting name value 选项来设置这些参数。

您可以一次设置多个参数，如下所示

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

配置目录模式¶

通常，您使用命令行选项配置 Datasette。对于包含自定义模板、自定义插件、静态目录和多个数据库的 Datasette 实例，这可能会变得相当冗长

$ datasette one.db two.db \
    --metadata=metadata.json \
    --template-dir=templates/ \
    --plugins-dir=plugins \
    --static css:css

作为替代方案，您可以在 配置目录 模式下运行 Datasette。创建一个具有以下结构的目录

# In a directory called my-app:
my-app/one.db
my-app/two.db
my-app/metadata.json
my-app/templates/index.html
my-app/plugins/my_plugin.py
my-app/static/my.css

现在通过提供该目录的路径来启动 Datasette

$ datasette my-app/

Datasette 将检测该目录中的文件并使用它们自动配置自身。它将提供找到的所有 *.db 文件，如果存在则加载 metadata.json，并加载 templates、plugins 和 static 文件夹（如果存在）。

此目录中可以包含的文件如下。所有文件都是可选的。

*.db（或 *.sqlite3 或 *.sqlite） - 将由 Datasette 提供的 SQLite 数据库文件
metadata.json - 这些数据库的元数据 - 也可以使用 metadata.yaml 或 metadata.yml
inspect-data.json - 在配置目录中运行 datasette inspect *.db --inspect-file=inspect-data.json 的结果 - 此处列出的任何数据库文件都将被视为不可变的，因此在 Datasette 运行时不应更改它们
settings.json - 通常使用 --setting 传递的设置 - 在这里它们应存储为键/值对的 JSON 对象
templates/ - 一个包含自定义模板的目录
plugins/ - 一个包含插件的目录，详见编写一次性插件
static/ - 一个包含静态文件的目录 - 这些文件将从 /static/filename.txt 提供服务，详见提供静态文件

设置¶

以下选项可以使用 --setting name value 设置，或者存储在 settings.json 文件中以便与配置目录模式一起使用。

default_allow_sql¶

默认情况下，用户是否应该能够执行任意 SQL 查询？

将其设置为 off 会导致 execute-sql 的权限检查默认失败。

datasette mydatabase.db --setting default_allow_sql off

有两种方法可以实现这一点：另一种方法是如控制执行任意 SQL 的能力中所述，将 "allow_sql": false 添加到您的 metadata.json 文件中。此设置提供了更便捷的方式来做到这一点。

default_page_size¶

表格页面返回的默认行数。您可以使用查询字符串参数 ?_size=80 按页面覆盖此设置，前提是您指定的值不高于 max_returned_rows 设置。您可以使用 --setting 设置此默认值，如下所示

datasette mydatabase.db --setting default_page_size 50

sql_time_limit_ms¶

默认情况下，查询的时间限制为一秒。如果查询运行时间超过此限制，Datasette 将终止查询并返回错误。

如果此时间限制对您来说太短，您可以使用 sql_time_limit_ms 限制进行自定义 - 例如，将其增加到 3.5 秒

datasette mydatabase.db --setting sql_time_limit_ms 3500

您可以使用查询字符串参数 ?_timelimit=100 可选地为单个查询设置较低的时间限制

/my-database/my-table?qSpecies=44&_timelimit=100

这将为该特定查询设置 100 毫秒的时间限制。如果您正在处理未知大小和复杂性的数据库，此功能非常有用 - 对于较小的表来说完全合理的查询，在包含数百万行的表上执行可能需要太长时间。通过设置自定义时间限制，您可以“乐观地”执行查询 - 例如，给我一个与此查询匹配的准确行数，但仅当计算时间少于 100 毫秒时。

max_returned_rows¶

Datasette 一次最多返回 1,000 行数据。如果您执行的查询返回超过 1,000 行，Datasette 将返回前 1,000 行并包含一条警告，提示结果集已被截断。如果需要返回超过 1,000 行，可以在 SQL 中使用 OFFSET/LIMIT 或其他方法来实现分页。

您可以如下所示增加或减少此限制

datasette mydatabase.db --setting max_returned_rows 2000

num_sql_threads¶

Datasette 用于执行 SQLite 查询的线程池中的最大线程数。默认为 3。

datasette mydatabase.db --setting num_sql_threads 10

将其设置为 0 会完全关闭线程化 SQL 查询 - 对于不支持线程的环境（例如 Pyodide）很有用。

allow_download¶

用户是否应该能够使用数据库索引页面上的链接下载原始 SQLite 数据库？此选项默认开启。但是，数据库只能在不可变模式下提供服务，而不能在内存中提供服务时才能下载。如果由于以上任一原因导致下载不可用，即使 allow_download 开启，下载链接也会被隐藏。要禁用数据库下载，请使用以下设置

datasette mydatabase.db --setting allow_download off

default_cache_ttl¶

默认 HTTP 缓存 max-age 头部（以秒为单位），用于 Cache-Control: max-age=X。可以使用 ?_ttl= 查询字符串参数按请求覆盖此设置。将其设置为 0 以完全禁用 HTTP 缓存。默认为 5 秒。

datasette mydatabase.db --setting default_cache_ttl 60

cache_size_kb¶

设置 SQLite 用于其每个连接的缓存的内存量，以 KB 为单位。

datasette mydatabase.db --setting cache_size_kb 5000

allow_csv_stream¶

启用CSV 导出功能，可以将整个表格（可能包含数十万行）导出为单个 CSV 文件。此功能默认开启 - 您可以如下所示将其关闭

datasette mydatabase.db --setting allow_csv_stream off

max_csv_mb¶

可导出的 CSV 文件最大大小，以兆字节为单位。默认为 100MB。将其设置为 0 可以完全禁用此限制

datasette mydatabase.db --setting max_csv_mb 0

truncate_cells_html¶

在 HTML 表格视图中，截断任何长于此值的字符串。完整值仍可在 CSV、JSON 和单独的行 HTML 页面中获得。将其设置为 0 可禁用截断。

datasette mydatabase.db --setting truncate_cells_html 0

force_https_urls¶

强制 JSON 输出中的自引用 URL 始终使用 https:// 协议。这对于应用程序本身使用 HTTP 托管但通过启用 HTTPS 的代理向外部世界提供服务的情况很有用。

datasette mydatabase.db --setting force_https_urls 1

template_debug¶

此设置启用模板上下文调试模式，这对于帮助理解在编写自定义模板时哪些变量可用非常有用。

如下所示启用它

datasette mydatabase.db --setting template_debug 1

现在您可以将 ?_context=1 或 &_context=1 添加到任何 Datasette 页面，以查看传递给该模板的上下文。

一些示例

trace_debug¶

此设置允许在任何页面后附加 ?_trace=1，以便查看用于生成该页面的 SQL 查询和其他跟踪信息。

如下所示启用它

datasette mydatabase.db --setting trace_debug 1

一些示例

有关如何作为插件作者接入此机制的详细信息，请参阅datasette.tracer。

base_url¶

如果您在代理后面运行 Datasette，更改 Datasette 实例使用的根路径可能会很有用。

例如，如果您将流量从 https://www.example.com/tools/datasette/ 通过代理发送到 Datasette 实例，您可能希望 Datasette 使用 /tools/datasette/ 作为其根 URL。

您可以如下所示进行设置

datasette mydatabase.db --setting base_url /tools/datasette/

配置密钥¶

Datasette 使用一个密钥字符串来签署安全值，例如 cookie。

如果您未提供密钥，Datasette 将在启动时创建一个。但是，此密钥在 Datasette 服务器每次重新启动时都会重置，因此身份验证 cookie 等内容在重新启动之间将不再有效。

您可以通过两种方式将密钥传递给 Datasette：使用 --secret 命令行选项或设置 DATASETTE_SECRET 环境变量。

$ datasette mydb.db --secret=SECRET_VALUE_HERE

或者

$ export DATASETTE_SECRET=SECRET_VALUE_HERE
$ datasette mydb.db

生成安全随机密钥的一种方法是使用 Python，如下所示

$ python3 -c 'import secrets; print(secrets.token_hex(32))'
cdb19e94283a20f9d42cca50c5a4871c0aa07392db308755d60a1a5b9bb0fa52

插件作者在他们的插件中利用此签名机制，使用 .sign(value, namespace="default") 和 .unsign(value, namespace="default")。

使用密钥与 datasette publish¶

datasette publish 和 datasette package 命令在部署 Datasette 时都会自动为您生成一个密钥。

这意味着每次部署新版本的 Datasette 项目时，都会生成一个新的密钥。这将导致签名 cookie 在每次新部署时失效。

您可以通过创建一个可用于多次部署的密钥并使用 --secret 选项传递它来解决此问题

datasette publish cloudrun mydb.db --service=my-service --secret=cdb19e94283a20f9d42cca5

设置¶