issue_comments

I dig it - I was thinking an Observable notebook where you paste your metadata.json/metadata.yaml and it would generate the new metadata + datasette.yaml files, but an extensible datasette upgrade plugin would be nice for future plugins.

One thing to think about: If someone has comments in their original metadata.yaml, could we preserve them in the new files? tbh maybe not too important bc if people cared that much they could just copy + paste, and it might be too distracting

TODO: add similar checks for permissions/allow/canned queries

Thinking about this more, here a list of things I imagine a "compile-to-sql" plugin would want to do:

1. Attach itself to the SQL code editor (switch from SQL -> PRQL/Logica, additional syntax highlighting)
2. Add "Query using PRQL" buttons in various parts of Datasette's UI, like /dbname page
3. Use $LANGUAGE= instead of sql= in the JSON API and the SQL results pages
4. Have their own dedicated code editor page

1) and 2) would be difficult to do with current plugin hooks, unless we add the concept of "slots" and get the JS plugin support in. 3) could maybe be done with the asgi_wrapper(datasette) hook? And 4) ca n be done easily with the register_routes() hooks.

So it really only sounds like extending the SQL editor will be the hard part. In #2094 I want to add JavaScript plugin hooks for extending the SQL editor, which may work here.

If I get the time/motivation, I might try out a datasette-prql extension, just because I like playing with it. It'd be really cool if I can get the asgi_wrapper() hook to work right there...

One note here: this feature could be called "slots", similar to Layout Slots in Vitepress.

In Vitepress, you can add custom components/widget/gadgets into determined named "slots", like so:

doc-top doc-bottom doc-footer-before doc-before doc-after ...

Would be great to do in both Python and Javascript, with the upcoming JavaScript API #2052. In datasette-write-ui, all we do is add a few "Insert row" and "edit this row" buttons and that required completely capturing the table.html template, which isn't great for other plugins. But having "slots" like table-footer-before or table-row-id or something would be great to work with.

@simonw docs are finished, this is ready for review!

One thing: I added "Configuration" as a top-level item in the documentation site, at the very bottom. Not sure if this is the best, maybe it can be named "datasette.yaml Configuration" or something similar?

Mostly because "Configuration" by itself can mean many things, but adding "datasette.yaml" would make it pretty clear it's about that specific file, and is easier to scan. I'd also be fine with using "datasette.yaml" instead of "datasette.json", since writing in YAML is much more forgiving (and advanced users will know JSON is also supported)

Also, maybe this is a chance to consolidate the docs a bit? I think "Settings", "Configuration", "Metadata", and "Authentication and permissions" should possibly be under the same section. Maybe even consolidate the different Plugin pages that exist?

@simonw what do you think about adding a DATASETTE_INTERNAL_DB_PATH env variable, where when defined, is the default location of the internal DB? This means when the --internal flag is NOT provided, Datasette would check to see if DATASETTE_INTERNAL_DB_PATH exists, and if so, uses that as the internal database (and would fallback to an ephemeral memory database)

My rationale: some plugins may require, or strongly encourage, a persistent internal database (datasette-comments, datasette-bookmarks, datasette-link-shortener, etc.). However, for users that have a global installation of Datasette (say from brew install or a global pip install), it would be annoying having to specify --internal every time. So instead, they can just add export DATASETTE_INTERNAL_DB_PATH="/path/to/internal.db" to their bashrc/zshrc/whereever to not have to worry about --internal

OK Here's the gameplan for this, which is closely tied to #2143 :

• We will add a new datasette.json/datasette.yaml configuration file to datasette, which combines settings/plugin config/permissions/canned queries into a new file format
• Metadata will NOT be a part of this file
• TOML support is not planned, but maybe we can create a separate issue for support TOML with JSON/YAML
• The settings.json file will be deprecated, and the --config arg will be brought back.
• Command line arguments can still be used to overwrite values (ex --setting will overwrite settings in datasette.yaml

The format of datasette.json will follow what Simon listed here: https://github.com/simonw/datasette/issues/2143#issuecomment-1684484426

Here's the current implementation plan:

1. Add a new --config flag and port over "settings" into a new datasette.json config file, remove settings.json
2. Add top-level plugin config support to datasette.json
3. Figure out database/table structure of config datasette.json
4. Port over database/table level plugin config support datasette.json
5. Port over permissions/auth settings to datasette.json
6. Deprecate non-metadata values in metadata.json

Another point: The new Datasette write API should refuse to insert a row with a NULL primary key. That will likely decrease the likelihood someone find themselves with NULLs in their primary keys, at least with Datasette users. Especially buggy code that uses the write API, like our datasette-write-ui bug that led to this issue.

That said, I do really like a bias towards settings that can be changed at runtime

Does this include things like --settings values or plugin config? I can totally see being able to update metadata without restarting, but not sure if that would work well with --setting, plugin config, or auth/permissions stuff.

Well it could work with --setting and auth/permissions, with a lot of core changes. But changing plugin config on the fly could be challenging, for plugin authors.

Another option would be, instead of flat datasette.json/datasette.yaml files, we could instead use a Python file, like datasette_config.py. That way one could dynamically generate config (ex dev vs prod, auto-discover credentials, etc.). Kinda like Django settings.

Though I imagine Python imports might make this complex to do, and json/yaml is already supported and pretty easy to write

I agree with all your points!

I think the best solution would be having a datasette.json config file, where you "configure" your datasette instances, with settings, permissions/auth, plugin configuration, and table settings (sortable column, label columns, etc.). Which #2093 would do.

Then optionally, you have a metadata.json, or use datasette_metadata, or some other plugin to define metadata (ex the future sqlite-docs plugin).

Everything in datasette.json could also be overwritten by CLI flags, like --setting key value, --plugin xxxx key value.

We could even completely remove settings.json in favor or just datasette.json. Mostly because I think the less files the better, especially if they have generic names like settings.json or config.json.

For filtering virtual table's "shadow tables" (ex the FTS5 _content and most the spatialite tables), you can use pragma_table_list (first appeared in SQLite 3.37 (2021-11-27), which has a type column that calls out type="shadow" tables https://www.sqlite.org/pragma.html#pragma_table_list

Another use-case: I want to make a sqlite-utils plugin that'll help me insert data into Datasette.

bash sqlite-utils insert-datasette \ --token $DATASETTE_API_KEY \ https://latest.datasette.io/fixtures/my-table \ 'select ...'

This could also be a datasette plugin (ex datasette upload-data ..., but you can also think of sqlite-utils plugins that upload to S3, a postgres table, other DBMS's, etc.)

I just saw in the docs that Dasette auto-detects settings.json:

settings.json - settings that would normally be passed using --setting - here they should be stored as a JSON object of key/value pairs Source

Storing metadata in the database won't be required. I imagine there'll be many different ways to store metadata, including any possible datasette_metadata or sqlite-docs, or the older metadata.json way.

The next question will be how precedence should work - i'd imagine metadata.json > plugins > datasette_metadata > sqlite-docs

Just curious, is there a query that can be used to compile this programmatically, or did you identify these through memory?

I just did a github search for user:simonw "def extra_js_urls(" ! Though I'm sure other plugins made by people other than Simon also exist out there https://github.com/search?q=user%3Asimonw+%22def+extra_js_urls%28%22&type=code

Maybe we can have a separate issue for revamping metadata.json? A datasette_metadata table or the sqlite-docs extension seem like two reasonable additions that we can work through. Storing metadata inside a SQLite database makes sense, but I don't think storing datasette.* style config (ex ports, settings, etc.) inside a SQLite DB makes sense, since it's very environment-dependent

I agree with not liking metadata.json stuff in a datasette.* config file. Editing description of a table/column in a file like datasette.* seems odd to me.

Though since plugin configuration currently lives in metadata.json, I think it should be removed from there and placed in datasette.*, at least for top-level config like datasette-auth-github's config. Keeping metadata.json strictly for documentation/licensing/column units makes sense to me, but anything plugin related should be in some config file, like datasette.*.

And ya, supporting both datasette.* and CLI flags makes a lot of sense to me. Any --setting flag should override anything in datasette.* for easier debugging, with possibly a warning message so people don't get confused. Same with --port and a port defined in datasette.*

Ok @hydrosquall a couple things before this PR should be good to go:

• Can we move datasette/static/table-example-plugins.js into demos/plugins/static?
• For datasetteManager.VERSION, can we fill that in or just comment it out for now? Not sure how difficult it'll be to inject it server-side. I imagine we could also have a small build process with esbuild/rollup that just injects a version string into manager.js directly, so we don't have to worry about server-rendering (but that can be a future PR)

In terms of how to integrate this into Datasette, a few options I can see working:

• Push this as-is and figure it out before the next release
• Hide this feature behind a settings flag (--setting unstable-js-plugins on) and use that setting to hide/show <script src="{{ urls.static('datasette-manager.js') }}" defer></script> in base.html

I'll let @simonw decide which one to work with. I kindof like the idea of having an "unstable" opt-in process to enable JS plugins, to give us time to try it out with a wide variety of plugins until we feel its ready.

I'm also curious to see how "plugins for a plugin' would work, like #1542. For example, if the leaflet plugin showed default markers, but also included its own hook for other plugins to add more markers/styling. I'm imagine that the individual plugin would re-create their own plugin system compared to this, since handling "plugins of plugins" at the top with Datasette seems really convoluted.

Also for posterity, here's a list of Simon's Datasette plugins that use "extra_js_urls()", which probably means they can be ported/re-written to use this new plugin system:

• datasette-vega
• datasette-cluster-map
• datasette-leaflet-geojson
• datasette-pretty-traces
• datasette-youtube-embed
• datasette-leaflet-freedraw
• datasette-hovercards
• datasette-mp3-audio
• datasette-geojson-map

:wave: would love to see this get merged soon! I want to make a javascript plugin on top of the code-mirror editor to make a few things nicer (function auto-complete, table/column descriptions, etc.), and this would help out a bunch

Counting any virtual tables can be pretty tricky. On one hand, counting a CSV virtual table would return the number of rows in the CSV, which is helpful (but can be I/O intensive). Counting a FTS5 virtual table would return the number of entries in the FTS index, which is kindof helpful, but can be misleading in some cases.

On the other hand, arbitrarily running COUNT(*) on some virtual tables can be incredibly expensive. SQLite offers new shortcuts/pushdowns on COUNT(*) queries for virtual tables, and instead calls the underlying vtab implementation and iterates through all rows in the table without discretion. For example, a virtual table that's backed by a Postgres table would call select * from pg_table, which would use up a lot of network and CPU calls. Or a virtual table backed by a google sheet would make network/API requests to get all the rows from the sheet just to make a count.

The pragma_table_list pragma tells you when a table is a regular table or virtual (in the type column), but was only added in version 3.37.0 (2021-11-27).

Personally, I wouldnt try to COUNT(*) virtual tables - it depends on how the virtual table is implemented, it requires that the connection has the proper extensions loaded, and it may accientally cause perf issues for new-age extensions. A few extensions that I'm writing have virtual tables that wouldn't benefit much from COUNT(*), and the fact that SQLite iterates through all rows in a table to count just makes things worse.

This could use a new plugin hook, too. I don't want to complicate your life too much, but for things like GIS, I'd want a way to turn regular JSON into SpatiaLite geometries or combine X/Y coordinates into point geometries and such. Happy to help however I can.

@eyeseast Maybe you could do this with triggers? Like you can insert JSON-friendly data into a "raw" table, and create a trigger that transforms that inserted data into the proper table

Here's an example:

```sql -- meant to be updated from a Datasette insert create table points_raw(longitude int, latitude int);

-- the target table with proper spatliate geometries create table points(point geometry);

CREATE TRIGGER insert_points_raw INSERT ON points_raw BEGIN insert into points(point) values (makepoint(new.longitude, new.latitude)) END; ```

You could then POST a new row to points_raw like this: POST /db/points_raw Authorization: Bearer xxx Content-Type: application/json { "row": { "longitude": 27.64356, "latitude": -47.29384 } }

Then SQLite with run the trigger and insert a new row in points with the correct geometry point. Downside is you'd have duplicated data with points_raw, but maybe it could be a TEMP table (or have a cron that deletes all rows from that table every so often?)

@simonw to build the extension on ubuntu, you can run:

apt-get update && apt-get install libsqlite3-dev gcc gcc ext.c -fPIC -shared -o ext.so

I'm not the best with Actions, but if you set the cache key to ext.c, run those two commands to download dependencies + compile to ext.so, then the unit test should pick it up and run it correctly. Let me know if you want me to update the PR with that added

Rebased, Read the docs failure should now now fixed

Re docs - ya that's a pretty ambitious page, I'm still not 100% sure what the best practices are/should be... Would be happy to make that page in a future PR

Oh, another thing to consider: I believe this would be the first "_file" key in datasette's metadata, compared to other "_url" keys like "license_url" or "about_url". Not too sure what considerations to include with this (ex should missing files cause Datasette to stop before starting, should build scripts bundle these sql files somewhere during datasette package, etc.)