{"id": "installation:installation-basic", "page": "installation", "ref": "installation-basic", "title": "Basic installation", "content": "", "breadcrumbs": "[\"Installation\"]", "references": "[]"} {"id": "installation:installation-advanced", "page": "installation", "ref": "installation-advanced", "title": "Advanced installation options", "content": "", "breadcrumbs": "[\"Installation\"]", "references": "[]"} {"id": "spatialite:spatialite-installation", "page": "spatialite", "ref": "spatialite-installation", "title": "Installation", "content": "", "breadcrumbs": "[\"SpatiaLite\"]", "references": "[]"} {"id": "getting_started:getting-started", "page": "getting_started", "ref": "getting-started", "title": "Getting started", "content": "", "breadcrumbs": "[]", "references": "[]"} {"id": "settings:id1", "page": "settings", "ref": "id1", "title": "Settings", "content": "", "breadcrumbs": "[]", "references": "[]"} {"id": "changelog:id1", "page": "changelog", "ref": "id1", "title": "Changelog", "content": "", "breadcrumbs": "[]", "references": "[]"} {"id": "changelog:id21", "page": "changelog", "ref": "id21", "title": "0.60 (2022-01-13)", "content": "", "breadcrumbs": "[\"Changelog\"]", "references": "[]"} {"id": "metadata:database-level-metadata", "page": "metadata", "ref": "database-level-metadata", "title": "Database-level metadata", "content": "\"Database-level\" metadata refers to fields that can be specified for each database in a Datasette instance. These attributes should be listed under a database inside the \"databases\" field. \n The following are the full list of allowed database-level metadata fields: \n \n \n source \n \n \n source_url \n \n \n license \n \n \n license_url \n \n \n about \n \n \n about_url", "breadcrumbs": "[\"Metadata\", \"Metadata reference\"]", "references": "[]"} {"id": "metadata:table-level-metadata", "page": "metadata", "ref": "table-level-metadata", "title": "Table-level metadata", "content": "\"Table-level\" metadata refers to fields that can be specified for each table in a Datasette instance. These attributes should be listed under a specific table using the \"tables\" field. \n The following are the full list of allowed table-level metadata fields: \n \n \n source \n \n \n source_url \n \n \n license \n \n \n license_url \n \n \n about \n \n \n about_url \n \n \n hidden \n \n \n sort/sort_desc \n \n \n size \n \n \n sortable_columns \n \n \n label_column \n \n \n facets \n \n \n fts_table \n \n \n fts_pk \n \n \n searchmode \n \n \n columns", "breadcrumbs": "[\"Metadata\", \"Metadata reference\"]", "references": "[]"} {"id": "metadata:top-level-metadata", "page": "metadata", "ref": "top-level-metadata", "title": "Top-level metadata", "content": "\"Top-level\" metadata refers to fields that can be specified at the root level of a metadata file. These attributes are meant to describe the entire Datasette instance. \n The following are the full list of allowed top-level metadata fields: \n \n \n title \n \n \n description \n \n \n description_html \n \n \n license \n \n \n license_url \n \n \n source \n \n \n source_url", "breadcrumbs": "[\"Metadata\", \"Metadata reference\"]", "references": "[]"} {"id": "changelog:id78", "page": "changelog", "ref": "id78", "title": "0.30.2 (2019-11-02)", "content": "/-/plugins page now uses distribution name e.g. datasette-cluster-map instead of the name of the underlying Python package ( datasette_cluster_map ) ( #606 ) \n \n \n Array faceting is now only suggested for columns that contain arrays of strings ( #562 ) \n \n \n Better documentation for the --host argument ( #574 ) \n \n \n Don't show None with a broken link for the label on a nullable foreign key ( #406 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/606\", \"label\": \"#606\"}, {\"href\": \"https://github.com/simonw/datasette/issues/562\", \"label\": \"#562\"}, {\"href\": \"https://github.com/simonw/datasette/issues/574\", \"label\": \"#574\"}, {\"href\": \"https://github.com/simonw/datasette/issues/406\", \"label\": \"#406\"}]"} {"id": "changelog:id89", "page": "changelog", "ref": "id89", "title": "0.26.1 (2019-01-10)", "content": "/-/versions now includes SQLite compile_options ( #396 ) \n \n \n datasetteproject/datasette Docker image now uses SQLite 3.26.0 ( #397 ) \n \n \n Cleaned up some deprecation warnings under Python 3.7", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/396\", \"label\": \"#396\"}, {\"href\": \"https://hub.docker.com/r/datasetteproject/datasette\", \"label\": \"datasetteproject/datasette\"}, {\"href\": \"https://github.com/simonw/datasette/issues/397\", \"label\": \"#397\"}]"} {"id": "json_api:json-api-table-arguments", "page": "json_api", "ref": "json-api-table-arguments", "title": "Special table arguments", "content": "?_col=COLUMN1&_col=COLUMN2 \n \n List specific columns to display. These will be shown along with any primary keys. \n \n \n \n ?_nocol=COLUMN1&_nocol=COLUMN2 \n \n List specific columns to hide - any column not listed will be displayed. Primary keys cannot be hidden. \n \n \n \n ?_labels=on/off \n \n Expand foreign key references for every possible column. See below. \n \n \n \n ?_label=COLUMN1&_label=COLUMN2 \n \n Expand foreign key references for one or more specified columns. \n \n \n \n ?_size=1000 or ?_size=max \n \n Sets a custom page size. This cannot exceed the max_returned_rows limit\n passed to datasette serve . Use max to get max_returned_rows . \n \n \n \n ?_sort=COLUMN \n \n Sorts the results by the specified column. \n \n \n \n ?_sort_desc=COLUMN \n \n Sorts the results by the specified column in descending order. \n \n \n \n ?_search=keywords \n \n For SQLite tables that have been configured for\n full-text search executes a search\n with the provided keywords. \n \n \n \n ?_search_COLUMN=keywords \n \n Like _search= but allows you to specify the column to be searched, as\n opposed to searching all columns that have been indexed by FTS. \n \n \n \n ?_searchmode=raw \n \n With this option, queries passed to ?_search= or ?_search_COLUMN= will\n not have special characters escaped. This means you can make use of the full\n set of advanced SQLite FTS syntax ,\n though this could potentially result in errors if the wrong syntax is used. \n \n \n \n ?_where=SQL-fragment \n \n If the execute-sql permission is enabled, this parameter\n can be used to pass one or more additional SQL fragments to be used in the\n WHERE clause of the SQL used to query the table. \n This is particularly useful if you are building a JavaScript application\n that needs to do something creative but still wants the other conveniences\n provided by the table view (such as faceting) and hence would like not to\n have to construct a completely custom SQL query. \n Some examples: \n \n \n facetable?_where=_neighborhood like \"%c%\"&_where=_city_id=3 \n \n \n facetable?_where=_city_id in (select id from facet_cities where name != \"Detroit\") \n \n \n \n \n \n ?_through={json} \n \n This can be used to filter rows via a join against another table. \n The JSON parameter must include three keys: table , column and value . \n table must be a table that the current table is related to via a foreign key relationship. \n column must be a column in that other table. \n value is the value that you want to match against. \n For example, to filter roadside_attractions to just show the attractions that have a characteristic of \"museum\", you would construct this JSON: \n {\n \"table\": \"roadside_attraction_characteristics\",\n \"column\": \"characteristic_id\",\n \"value\": \"1\"\n} \n As a URL, that looks like this: \n ?_through={%22table%22:%22roadside_attraction_characteristics%22,%22column%22:%22characteristic_id%22,%22value%22:%221%22} \n Here's an example . \n \n \n \n ?_next=TOKEN \n \n Pagination by continuation token - pass the token that was returned in the\n \"next\" property by the previous page. \n \n \n \n ?_facet=column \n \n Facet by column. Can be applied multiple times, see Facets . Only works on the default JSON output, not on any of the custom shapes. \n \n \n \n ?_facet_size=100 \n \n Increase the number of facet results returned for each facet. Use ?_facet_size=max for the maximum available size, determined by max_returned_rows . \n \n \n \n ?_nofacet=1 \n \n Disable all facets and facet suggestions for this page, including any defined by Facets in metadata . \n \n \n \n ?_nosuggest=1 \n \n Disable facet suggestions for this page. \n \n \n \n ?_nocount=1 \n \n Disable the select count(*) query used on this page - a count of None will be returned instead.", "breadcrumbs": "[\"JSON API\", \"Table arguments\"]", "references": "[{\"href\": \"https://www.sqlite.org/fts3.html\", \"label\": \"full-text search\"}, {\"href\": \"https://www.sqlite.org/fts5.html#full_text_query_syntax\", \"label\": \"advanced SQLite FTS syntax\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_neighborhood%20like%20%22%c%%22&_where=_city_id=3\", \"label\": \"facetable?_where=_neighborhood like \\\"%c%\\\"&_where=_city_id=3\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_city_id%20in%20(select%20id%20from%20facet_cities%20where%20name%20!=%20%22Detroit%22)\", \"label\": \"facetable?_where=_city_id in (select id from facet_cities where name != \\\"Detroit\\\")\"}, {\"href\": \"https://latest.datasette.io/fixtures/roadside_attractions?_through={%22table%22:%22roadside_attraction_characteristics%22,%22column%22:%22characteristic_id%22,%22value%22:%221%22}\", \"label\": \"an example\"}]"} {"id": "changelog:id85", "page": "changelog", "ref": "id85", "title": "0.28 (2019-05-19)", "content": "A salmagundi of new features!", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://adamj.eu/tech/2019/01/18/a-salmagundi-of-django-alpha-announcements/\", \"label\": \"salmagundi\"}]"} {"id": "installation:installation-docker", "page": "installation", "ref": "installation-docker", "title": "Using Docker", "content": "A Docker image containing the latest release of Datasette is published to Docker\n Hub here: https://hub.docker.com/r/datasetteproject/datasette/ \n If you have Docker installed (for example with Docker for Mac on OS X) you can download and run this\n image like so: \n docker run -p 8001:8001 -v `pwd`:/mnt \\\n datasetteproject/datasette \\\n datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \n This will start an instance of Datasette running on your machine's port 8001,\n serving the fixtures.db file in your current directory. \n Now visit http://127.0.0.1:8001/ to access Datasette. \n (You can download a copy of fixtures.db from\n https://latest.datasette.io/fixtures.db ) \n To upgrade to the most recent release of Datasette, run the following: \n docker pull datasetteproject/datasette", "breadcrumbs": "[\"Installation\", \"Advanced installation options\"]", "references": "[{\"href\": \"https://hub.docker.com/r/datasetteproject/datasette/\", \"label\": \"https://hub.docker.com/r/datasetteproject/datasette/\"}, {\"href\": \"https://www.docker.com/docker-mac\", \"label\": \"Docker for Mac\"}, {\"href\": \"http://127.0.0.1:8001/\", \"label\": \"http://127.0.0.1:8001/\"}, {\"href\": \"https://latest.datasette.io/fixtures.db\", \"label\": \"https://latest.datasette.io/fixtures.db\"}]"} {"id": "metadata:id2", "page": "metadata", "ref": "id2", "title": "Metadata reference", "content": "A full reference of every supported option in a metadata.json or metadata.yaml file.", "breadcrumbs": "[\"Metadata\"]", "references": "[]"} {"id": "changelog:id45", "page": "changelog", "ref": "id45", "title": "0.51 (2020-10-31)", "content": "A new visual design, plugin hooks for adding navigation options, better handling of binary data, URL building utility methods and better support for running Datasette behind a proxy.", "breadcrumbs": "[\"Changelog\"]", "references": "[]"} {"id": "changelog:plugins-can-now-add-links-within-datasette", "page": "changelog", "ref": "plugins-can-now-add-links-within-datasette", "title": "Plugins can now add links within Datasette", "content": "A number of existing Datasette plugins add new pages to the Datasette interface, providig tools for things like uploading CSVs , editing table schemas or configuring full-text search . \n Plugins like this can now link to themselves from other parts of Datasette interface. The menu_links(datasette, actor, request) hook ( #1064 ) lets plugins add links to Datasette's new top-right application menu, and the table_actions(datasette, actor, database, table, request) hook ( #1066 ) adds links to a new \"table actions\" menu on the table page. \n The demo at latest.datasette.io now includes some example plugins. To see the new table actions menu first sign into that demo as root and then visit the facetable table to see the new cog icon menu at the top of the page.", "breadcrumbs": "[\"Changelog\", \"0.51 (2020-10-31)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-upload-csvs\", \"label\": \"uploading CSVs\"}, {\"href\": \"https://github.com/simonw/datasette-edit-schema\", \"label\": \"editing table schemas\"}, {\"href\": \"https://github.com/simonw/datasette-configure-fts\", \"label\": \"configuring full-text search\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1064\", \"label\": \"#1064\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1066\", \"label\": \"#1066\"}, {\"href\": \"https://latest.datasette.io/\", \"label\": \"latest.datasette.io\"}, {\"href\": \"https://latest.datasette.io/login-as-root\", \"label\": \"sign into that demo as root\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable\", \"label\": \"facetable\"}]"} {"id": "changelog:id94", "page": "changelog", "ref": "id94", "title": "0.24 (2018-07-23)", "content": "A number of small new features: \n \n \n datasette publish heroku now supports --extra-options , fixes #334 \n \n \n Custom error message if SpatiaLite is needed for specified database, closes #331 \n \n \n New config option: truncate_cells_html for truncating long cell values in HTML view - closes #330 \n \n \n Documentation for datasette publish and datasette package , closes #337 \n \n \n Fixed compatibility with Python 3.7 \n \n \n datasette publish heroku now supports app names via the -n option, which can also be used to overwrite an existing application [Russ Garrett] \n \n \n Title and description metadata can now be set for canned SQL queries , closes #342 \n \n \n New force_https_on config option, fixes https:// API URLs when deploying to Zeit Now - closes #333 \n \n \n ?_json_infinity=1 query string argument for handling Infinity/-Infinity values in JSON, closes #332 \n \n \n URLs displayed in the results of custom SQL queries are now URLified, closes #298", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/334\", \"label\": \"#334\"}, {\"href\": \"https://github.com/simonw/datasette/issues/331\", \"label\": \"#331\"}, {\"href\": \"https://github.com/simonw/datasette/issues/330\", \"label\": \"#330\"}, {\"href\": \"https://github.com/simonw/datasette/issues/337\", \"label\": \"#337\"}, {\"href\": \"https://github.com/simonw/datasette/issues/342\", \"label\": \"#342\"}, {\"href\": \"https://github.com/simonw/datasette/issues/333\", \"label\": \"#333\"}, {\"href\": \"https://github.com/simonw/datasette/issues/332\", \"label\": \"#332\"}, {\"href\": \"https://github.com/simonw/datasette/issues/298\", \"label\": \"#298\"}]"} {"id": "changelog:id63", "page": "changelog", "ref": "id63", "title": "0.42 (2020-05-08)", "content": "A small release which provides improved internal methods for use in plugins, along with documentation. See #685 . \n \n \n Added documentation for db.execute() , see await db.execute(sql, ...) . \n \n \n Renamed db.execute_against_connection_in_thread() to db.execute_fn() and made it a documented method, see await db.execute_fn(fn) . \n \n \n New results.first() and results.single_value() methods, plus documentation for the Results class - see Results .", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/685\", \"label\": \"#685\"}]"} {"id": "changelog:asgi", "page": "changelog", "ref": "asgi", "title": "ASGI", "content": "ASGI is the Asynchronous Server Gateway Interface standard. I've been wanting to convert Datasette into an ASGI application for over a year - Port Datasette to ASGI #272 tracks thirteen months of intermittent development - but with Datasette 0.29 the change is finally released. This also means Datasette now runs on top of Uvicorn and no longer depends on Sanic . \n I wrote about the significance of this change in Porting Datasette to ASGI, and Turtles all the way down . \n The most exciting consequence of this change is that Datasette plugins can now take advantage of the ASGI standard.", "breadcrumbs": "[\"Changelog\", \"0.29 (2019-07-07)\"]", "references": "[{\"href\": \"https://asgi.readthedocs.io/\", \"label\": \"ASGI\"}, {\"href\": \"https://github.com/simonw/datasette/issues/272\", \"label\": \"Port Datasette to ASGI #272\"}, {\"href\": \"https://www.uvicorn.org/\", \"label\": \"Uvicorn\"}, {\"href\": \"https://github.com/huge-success/sanic\", \"label\": \"Sanic\"}, {\"href\": \"https://simonwillison.net/2019/Jun/23/datasette-asgi/\", \"label\": \"Porting Datasette to ASGI, and Turtles all the way down\"}]"} {"id": "changelog:id84", "page": "changelog", "ref": "id84", "title": "0.29 (2019-07-07)", "content": "ASGI, new plugin hooks, facet by date and much, much more...", "breadcrumbs": "[\"Changelog\"]", "references": "[]"} {"id": "plugin_hooks:plugin-actions", "page": "plugin_hooks", "ref": "plugin-actions", "title": "Action hooks", "content": "Action hooks can be used to add items to the action menus that appear at the top of different pages within Datasette. Unlike menu_links() , actions which are displayed on every page, actions should only be relevant to the page the user is currently viewing. \n Each of these hooks should return return a list of {\"href\": \"...\", \"label\": \"...\"} menu items, with optional \"description\": \"...\" keys describing each action in more detail. \n They can alternatively return an async def awaitable function which, when called, returns a list of those menu items.", "breadcrumbs": "[\"Plugin hooks\"]", "references": "[]"} {"id": "authentication:permissions-alter-table", "page": "authentication", "ref": "permissions-alter-table", "title": "alter-table", "content": "Actor is allowed to alter a database table. \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-create-table", "page": "authentication", "ref": "permissions-create-table", "title": "create-table", "content": "Actor is allowed to create a database table. \n \n \n resource - string \n \n The name of the database \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-delete-row", "page": "authentication", "ref": "permissions-delete-row", "title": "delete-row", "content": "Actor is allowed to delete rows from a table. \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-view-database-download", "page": "authentication", "ref": "permissions-view-database-download", "title": "view-database-download", "content": "Actor is allowed to download a database, e.g. https://latest.datasette.io/fixtures.db \n \n \n resource - string \n \n The name of the database \n \n \n \n Default allow .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures.db\", \"label\": \"https://latest.datasette.io/fixtures.db\"}]"} {"id": "authentication:permissions-drop-table", "page": "authentication", "ref": "permissions-drop-table", "title": "drop-table", "content": "Actor is allowed to drop a database table. \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-insert-row", "page": "authentication", "ref": "permissions-insert-row", "title": "insert-row", "content": "Actor is allowed to insert rows into a table. \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-execute-sql", "page": "authentication", "ref": "permissions-execute-sql", "title": "execute-sql", "content": "Actor is allowed to run arbitrary SQL queries against a specific database, e.g. https://latest.datasette.io/fixtures?sql=select+100 \n \n \n resource - string \n \n The name of the database \n \n \n \n Default allow . See also the default_allow_sql setting .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures?sql=select+100\", \"label\": \"https://latest.datasette.io/fixtures?sql=select+100\"}]"} {"id": "authentication:permissions-update-row", "page": "authentication", "ref": "permissions-update-row", "title": "update-row", "content": "Actor is allowed to update rows in a table. \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "authentication:permissions-view-query", "page": "authentication", "ref": "permissions-view-query", "title": "view-query", "content": "Actor is allowed to view (and execute) a canned query page, e.g. https://latest.datasette.io/fixtures/pragma_cache_size - this includes executing Writable canned queries . \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the canned query \n \n \n \n Default allow .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/pragma_cache_size\", \"label\": \"https://latest.datasette.io/fixtures/pragma_cache_size\"}]"} {"id": "authentication:permissions-view-database", "page": "authentication", "ref": "permissions-view-database", "title": "view-database", "content": "Actor is allowed to view a database page, e.g. https://latest.datasette.io/fixtures \n \n \n resource - string \n \n The name of the database \n \n \n \n Default allow .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"https://latest.datasette.io/fixtures\"}]"} {"id": "authentication:permissions-view-table", "page": "authentication", "ref": "permissions-view-table", "title": "view-table", "content": "Actor is allowed to view a table (or view) page, e.g. https://latest.datasette.io/fixtures/complex_foreign_keys \n \n \n resource - tuple: (string, string) \n \n The name of the database, then the name of the table \n \n \n \n Default allow .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/complex_foreign_keys\", \"label\": \"https://latest.datasette.io/fixtures/complex_foreign_keys\"}]"} {"id": "authentication:permissions-permissions-debug", "page": "authentication", "ref": "permissions-permissions-debug", "title": "permissions-debug", "content": "Actor is allowed to view the /-/permissions debug page. \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "changelog:id211", "page": "changelog", "ref": "id211", "title": "0.9 (2017-11-13)", "content": "Added --sql_time_limit_ms and --extra-options . \n The serve command now accepts --sql_time_limit_ms for customizing the SQL time\n limit. \n The publish and package commands now accept --extra-options which can be used\n to specify additional options to be passed to the datasite serve command when\n it executes inside the resulting Docker containers.", "breadcrumbs": "[\"Changelog\"]", "references": "[]"} {"id": "changelog:id80", "page": "changelog", "ref": "id80", "title": "0.30 (2019-10-18)", "content": "Added /-/threads debugging page \n \n \n Allow EXPLAIN WITH... ( #583 ) \n \n \n Button to format SQL - thanks, Tobias Kunze ( #136 ) \n \n \n Sort databases on homepage by argument order - thanks, Tobias Kunze ( #585 ) \n \n \n Display metadata footer on custom SQL queries - thanks, Tobias Kunze ( #589 ) \n \n \n Use --platform=managed for publish cloudrun ( #587 ) \n \n \n Fixed bug returning non-ASCII characters in CSV ( #584 ) \n \n \n Fix for /foo v.s. /foo-bar bug ( #601 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/583\", \"label\": \"#583\"}, {\"href\": \"https://github.com/simonw/datasette/issues/136\", \"label\": \"#136\"}, {\"href\": \"https://github.com/simonw/datasette/issues/585\", \"label\": \"#585\"}, {\"href\": \"https://github.com/simonw/datasette/pull/589\", \"label\": \"#589\"}, {\"href\": \"https://github.com/simonw/datasette/issues/587\", \"label\": \"#587\"}, {\"href\": \"https://github.com/simonw/datasette/issues/584\", \"label\": \"#584\"}, {\"href\": \"https://github.com/simonw/datasette/issues/601\", \"label\": \"#601\"}]"} {"id": "changelog:id198", "page": "changelog", "ref": "id198", "title": "0.12 (2017-11-16)", "content": "Added __version__ , now displayed as tooltip in page footer ( #108 ). \n \n \n Added initial docs, including a changelog ( #99 ). \n \n \n Turned on auto-escaping in Jinja. \n \n \n Added a UI for editing named parameters ( #96 ). \n You can now construct a custom SQL statement using SQLite named\n parameters (e.g. :name ) and datasette will display form fields for\n editing those parameters. Here\u2019s an example which lets you see the\n most popular names for dogs of different species registered through\n various dog registration schemes in Australia. \n \n \n \n \n \n Pin to specific Jinja version. ( #100 ). \n \n \n Default to 127.0.0.1 not 0.0.0.0. ( #98 ). \n \n \n Added extra metadata options to publish and package commands. ( #92 ). \n You can now run these commands like so: \n datasette now publish mydb.db \\\n --title=\"My Title\" \\\n --source=\"Source\" \\\n --source_url=\"http://www.example.com/\" \\\n --license=\"CC0\" \\\n --license_url=\"https://creativecommons.org/publicdomain/zero/1.0/\" \n This will write those values into the metadata.json that is packaged with the\n app. If you also pass --metadata=metadata.json that file will be updated with the extra\n values before being written into the Docker image. \n \n \n Added production-ready Dockerfile ( #94 ) [Andrew\n Cutler] \n \n \n New ?_sql_time_limit_ms=10 argument to database and table page ( #95 ) \n \n \n SQL syntax highlighting with Codemirror ( #89 ) [Tom Dyson]", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/108\", \"label\": \"#108\"}, {\"href\": \"https://github.com/simonw/datasette/issues/99\", \"label\": \"#99\"}, {\"href\": \"https://github.com/simonw/datasette/issues/96\", \"label\": \"#96\"}, {\"href\": \"https://australian-dogs.now.sh/australian-dogs-3ba9628?sql=select+name%2C+count%28*%29+as+n+from+%28%0D%0A%0D%0Aselect+upper%28%22Animal+name%22%29+as+name+from+%5BAdelaide-City-Council-dog-registrations-2013%5D+where+Breed+like+%3Abreed%0D%0A%0D%0Aunion+all%0D%0A%0D%0Aselect+upper%28Animal_Name%29+as+name+from+%5BAdelaide-City-Council-dog-registrations-2014%5D+where+Breed_Description+like+%3Abreed%0D%0A%0D%0Aunion+all+%0D%0A%0D%0Aselect+upper%28Animal_Name%29+as+name+from+%5BAdelaide-City-Council-dog-registrations-2015%5D+where+Breed_Description+like+%3Abreed%0D%0A%0D%0Aunion+all%0D%0A%0D%0Aselect+upper%28%22AnimalName%22%29+as+name+from+%5BCity-of-Port-Adelaide-Enfield-Dog_Registrations_2016%5D+where+AnimalBreed+like+%3Abreed%0D%0A%0D%0Aunion+all%0D%0A%0D%0Aselect+upper%28%22Animal+Name%22%29+as+name+from+%5BMitcham-dog-registrations-2015%5D+where+Breed+like+%3Abreed%0D%0A%0D%0Aunion+all%0D%0A%0D%0Aselect+upper%28%22DOG_NAME%22%29+as+name+from+%5Bburnside-dog-registrations-2015%5D+where+DOG_BREED+like+%3Abreed%0D%0A%0D%0Aunion+all+%0D%0A%0D%0Aselect+upper%28%22Animal_Name%22%29+as+name+from+%5Bcity-of-playford-2015-dog-registration%5D+where+Breed_Description+like+%3Abreed%0D%0A%0D%0Aunion+all%0D%0A%0D%0Aselect+upper%28%22Animal+Name%22%29+as+name+from+%5Bcity-of-prospect-dog-registration-details-2016%5D+where%22Breed+Description%22+like+%3Abreed%0D%0A%0D%0A%29+group+by+name+order+by+n+desc%3B&breed=pug\", \"label\": \"Here\u2019s an example\"}, {\"href\": \"https://github.com/simonw/datasette/issues/100\", \"label\": \"#100\"}, {\"href\": \"https://github.com/simonw/datasette/issues/98\", \"label\": \"#98\"}, {\"href\": \"https://github.com/simonw/datasette/issues/92\", \"label\": \"#92\"}, {\"href\": \"https://github.com/simonw/datasette/issues/94\", \"label\": \"#94\"}, {\"href\": \"https://github.com/simonw/datasette/issues/95\", \"label\": \"#95\"}, {\"href\": \"https://github.com/simonw/datasette/issues/89\", \"label\": \"#89\"}]"} {"id": "changelog:id208", "page": "changelog", "ref": "id208", "title": "0.11 (2017-11-14)", "content": "Added datasette publish now --force option. \n This calls now with --force - useful as it means you get a fresh copy of datasette even if Now has already cached that docker layer. \n \n \n Enable --cors by default when running in a container.", "breadcrumbs": "[\"Changelog\"]", "references": "[]"} {"id": "changelog:id71", "page": "changelog", "ref": "id71", "title": "0.35 (2020-02-04)", "content": "Added five new plugins and one new conversion tool to the The Datasette Ecosystem . \n \n \n The Datasette class has a new render_template() method which can be used by plugins to render templates using Datasette's pre-configured Jinja templating library. \n \n \n You can now execute SQL queries that start with a -- comment - thanks, Jay Graves ( #653 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://jinja.palletsprojects.com/\", \"label\": \"Jinja\"}, {\"href\": \"https://github.com/simonw/datasette/pull/653\", \"label\": \"#653\"}]"} {"id": "sql_queries:canned-queries-options", "page": "sql_queries", "ref": "canned-queries-options", "title": "Additional canned query options", "content": "Additional options can be specified for canned queries in the YAML or JSON configuration.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"} {"id": "internals:datasette-add-memory-database", "page": "internals", "ref": "datasette-add-memory-database", "title": ".add_memory_database(name)", "content": "Adds a shared in-memory database with the specified name: \n datasette.add_memory_database(\"statistics\") \n This is a shortcut for the following: \n from datasette.database import Database\n\ndatasette.add_database(\n Database(datasette, memory_name=\"statistics\")\n) \n Using either of these pattern will result in the in-memory database being served at /statistics .", "breadcrumbs": "[\"Internals for plugins\", \"Datasette class\"]", "references": "[]"} {"id": "settings:setting-allow-facet", "page": "settings", "ref": "setting-allow-facet", "title": "allow_facet", "content": "Allow users to specify columns they would like to facet on using the ?_facet=COLNAME URL parameter to the table view. \n This is enabled by default. If disabled, facets will still be displayed if they have been specifically enabled in metadata.json configuration for the table. \n Here's how to disable this feature: \n datasette mydatabase.db --setting allow_facet off", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"} {"id": "contributing:contributing-alpha-beta", "page": "contributing", "ref": "contributing-alpha-beta", "title": "Alpha and beta releases", "content": "Alpha and beta releases are published to preview upcoming features that may not yet be stable - in particular to preview new plugin hooks. \n You are welcome to try these out, but please be aware that details may change before the final release. \n Please join discussions on the issue tracker to share your thoughts and experiences with on alpha and beta features that you try out.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues\", \"label\": \"discussions on the issue tracker\"}]"} {"id": "index:datasette", "page": "index", "ref": "datasette", "title": "Datasette", "content": "An open source multi-tool for exploring and publishing data \n Datasette is a tool for exploring and publishing data. It helps people take data of any shape or size and publish that as an interactive, explorable website and accompanying API. \n Datasette is aimed at data journalists, museum curators, archivists, local governments and anyone else who has data that they wish to share with the world. It is part of a wider ecosystem of tools and plugins dedicated to making working with structured data as productive as possible. \n Explore a demo , watch a presentation about the project or Try Datasette without installing anything using Glitch . \n Interested in learning Datasette? Start with the official tutorials . \n Support questions, feedback? Join the Datasette Discord .", "breadcrumbs": "[]", "references": "[{\"href\": \"https://pypi.org/project/datasette/\", \"label\": null}, {\"href\": \"https://docs.datasette.io/en/stable/changelog.html\", \"label\": null}, {\"href\": \"https://pypi.org/project/datasette/\", \"label\": null}, {\"href\": \"https://github.com/simonw/datasette/actions?query=workflow%3ATest\", \"label\": null}, {\"href\": \"https://github.com/simonw/datasette/blob/main/LICENSE\", \"label\": null}, {\"href\": \"https://hub.docker.com/r/datasetteproject/datasette\", \"label\": null}, {\"href\": \"https://datasette.io/discord\", \"label\": null}, {\"href\": \"https://pypi.org/project/datasette/\", \"label\": null}, {\"href\": \"https://docs.datasette.io/en/stable/changelog.html\", \"label\": null}, {\"href\": \"https://pypi.org/project/datasette/\", \"label\": null}, {\"href\": \"https://github.com/simonw/datasette/actions?query=workflow%3ATest\", \"label\": null}, {\"href\": \"https://github.com/simonw/datasette/blob/main/LICENSE\", \"label\": null}, {\"href\": \"https://hub.docker.com/r/datasetteproject/datasette\", \"label\": null}, {\"href\": \"https://datasette.io/discord\", \"label\": null}, {\"href\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight\", \"label\": \"Explore a demo\"}, {\"href\": \"https://static.simonwillison.net/static/2018/pybay-datasette/\", \"label\": \"a presentation about the project\"}, {\"href\": \"https://datasette.io/tutorials\", \"label\": \"the official tutorials\"}, {\"href\": \"https://datasette.io/discord\", \"label\": \"Datasette Discord\"}]"} {"id": "json_api:tableupsertview", "page": "json_api", "ref": "tableupsertview", "title": "Upserting rows", "content": "An upsert is an insert or update operation. If a row with a matching primary key already exists it will be updated - otherwise a new row will be inserted. \n The upsert API is mostly the same shape as the insert API . It requires both the insert-row and update-row permissions. \n POST ///-/upsert\nContent-Type: application/json\nAuthorization: Bearer dstok_ \n {\n \"rows\": [\n {\n \"id\": 1,\n \"title\": \"Updated title for 1\",\n \"description\": \"Updated description for 1\"\n },\n {\n \"id\": 2,\n \"description\": \"Updated description for 2\",\n },\n {\n \"id\": 3,\n \"title\": \"Item 3\",\n \"description\": \"Description for 3\"\n }\n ]\n} \n Imagine a table with a primary key of id and which already has rows with id values of 1 and 2 . \n The above example will: \n \n \n Update the row with id of 1 to set both title and description to the new values \n \n \n Update the row with id of 2 to set title to the new value - description will be left unchanged \n \n \n Insert a new row with id of 3 and both title and description set to the new values \n \n \n Similar to /-/insert , a row key with an object can be used instead of a rows array to upsert a single row. \n If successful, this will return a 200 status code and a {\"ok\": true} response body. \n Add \"return\": true to the request body to return full copies of the affected rows after they have been inserted or updated: \n {\n \"rows\": [\n {\n \"id\": 1,\n \"title\": \"Updated title for 1\",\n \"description\": \"Updated description for 1\"\n },\n {\n \"id\": 2,\n \"description\": \"Updated description for 2\",\n },\n {\n \"id\": 3,\n \"title\": \"Item 3\",\n \"description\": \"Description for 3\"\n }\n ],\n \"return\": true\n} \n This will return the following: \n {\n \"ok\": true,\n \"rows\": [\n {\n \"id\": 1,\n \"title\": \"Updated title for 1\",\n \"description\": \"Updated description for 1\"\n },\n {\n \"id\": 2,\n \"title\": \"Item 2\",\n \"description\": \"Updated description for 2\"\n },\n {\n \"id\": 3,\n \"title\": \"Item 3\",\n \"description\": \"Description for 3\"\n }\n ]\n} \n When using upsert you must provide the primary key column (or columns if the table has a compound primary key) for every row, or you will get a 400 error: \n {\n \"ok\": false,\n \"errors\": [\n \"Row 0 is missing primary key column(s): \\\"id\\\"\"\n ]\n} \n If your table does not have an explicit primary key you should pass the SQLite rowid key instead. \n Pass \"alter: true to automatically add any missing columns to the table. This requires the alter-table permission.", "breadcrumbs": "[\"JSON API\", \"The JSON write API\"]", "references": "[]"} {"id": "spatialite:importing-geojson-polygons-using-shapely", "page": "spatialite", "ref": "importing-geojson-polygons-using-shapely", "title": "Importing GeoJSON polygons using Shapely", "content": "Another common form of polygon data is the GeoJSON format. This can be imported into SpatiaLite directly, or by using the Shapely Python library. \n Who's On First is an excellent source of openly licensed GeoJSON polygons. Let's import the geographical polygon for Wales. First, we can use the Who's On First Spelunker tool to find the record for Wales: \n spelunker.whosonfirst.org/id/404227475 \n That page includes a link to the GeoJSON record, which can be accessed here: \n data.whosonfirst.org/404/227/475/404227475.geojson \n Here's Python code to create a SQLite database, enable SpatiaLite, create a places table and then add a record for Wales: \n import sqlite3\n\nconn = sqlite3.connect(\"places.db\")\n# Enable SpatialLite extension\nconn.enable_load_extension(True)\nconn.load_extension(\"/usr/local/lib/mod_spatialite.dylib\")\n# Create the masic countries table\nconn.execute(\"select InitSpatialMetadata(1)\")\nconn.execute(\n \"create table places (id integer primary key, name text);\"\n)\n# Add a MULTIPOLYGON Geometry column\nconn.execute(\n \"SELECT AddGeometryColumn('places', 'geom', 4326, 'MULTIPOLYGON', 2);\"\n)\n# Add a spatial index against the new column\nconn.execute(\"SELECT CreateSpatialIndex('places', 'geom');\")\n# Now populate the table\nfrom shapely.geometry.multipolygon import MultiPolygon\nfrom shapely.geometry import shape\nimport requests\n\ngeojson = requests.get(\n \"https://data.whosonfirst.org/404/227/475/404227475.geojson\"\n).json()\n# Convert to \"Well Known Text\" format\nwkt = shape(geojson[\"geometry\"]).wkt\n# Insert and commit the record\nconn.execute(\n \"INSERT INTO places (id, name, geom) VALUES(null, ?, GeomFromText(?, 4326))\",\n (\"Wales\", wkt),\n)\nconn.commit()", "breadcrumbs": "[\"SpatiaLite\"]", "references": "[{\"href\": \"https://pypi.org/project/Shapely/\", \"label\": \"Shapely\"}, {\"href\": \"https://whosonfirst.org/\", \"label\": \"Who's On First\"}, {\"href\": \"https://spelunker.whosonfirst.org/id/404227475/\", \"label\": \"spelunker.whosonfirst.org/id/404227475\"}, {\"href\": \"https://data.whosonfirst.org/404/227/475/404227475.geojson\", \"label\": \"data.whosonfirst.org/404/227/475/404227475.geojson\"}]"} {"id": "csv_export:id1", "page": "csv_export", "ref": "id1", "title": "CSV export", "content": "Any Datasette table, view or custom SQL query can be exported as CSV. \n To obtain the CSV representation of the table you are looking, click the \"this\n data as CSV\" link. \n You can also use the advanced export form for more control over the resulting\n file, which looks like this and has the following options: \n \n \n \n download file - instead of displaying CSV in your browser, this forces\n your browser to download the CSV to your downloads directory. \n \n \n expand labels - if your table has any foreign key references this option\n will cause the CSV to gain additional COLUMN_NAME_label columns with a\n label for each foreign key derived from the linked table. In this example \n the city_id column is accompanied by a city_id_label column. \n \n \n stream all rows - by default CSV files only contain the first\n max_returned_rows records. This option will cause Datasette to\n loop through every matching record and return them as a single CSV file. \n \n \n You can try that out on https://latest.datasette.io/fixtures/facetable?_size=4", "breadcrumbs": "[]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/facetable.csv?_labels=on&_size=max\", \"label\": \"In this example\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_size=4\", \"label\": \"https://latest.datasette.io/fixtures/facetable?_size=4\"}]"} {"id": "changelog:csv-export", "page": "changelog", "ref": "csv-export", "title": "CSV export", "content": "Any Datasette table, view or custom SQL query can now be exported as CSV. \n \n Check out the CSV export documentation for more details, or\n try the feature out on\n https://fivethirtyeight.datasettes.com/fivethirtyeight/bechdel%2Fmovies \n If your table has more than max_returned_rows (default 1,000)\n Datasette provides the option to stream all rows . This option takes advantage\n of async Python and Datasette's efficient pagination to\n iterate through the entire matching result set and stream it back as a\n downloadable CSV file.", "breadcrumbs": "[\"Changelog\", \"0.23 (2018-06-18)\"]", "references": "[{\"href\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight/bechdel%2Fmovies\", \"label\": \"https://fivethirtyeight.datasettes.com/fivethirtyeight/bechdel%2Fmovies\"}]"} {"id": "contributing:contributing-debugging", "page": "contributing", "ref": "contributing-debugging", "title": "Debugging", "content": "Any errors that occur while Datasette is running while display a stack trace on the console. \n You can tell Datasette to open an interactive pdb debugger session if an error occurs using the --pdb option: \n datasette --pdb fixtures.db", "breadcrumbs": "[\"Contributing\"]", "references": "[]"} {"id": "sql_queries:id1", "page": "sql_queries", "ref": "id1", "title": "Canned queries", "content": "As an alternative to adding views to your database, you can define canned queries inside your datasette.yaml file. Here's an example: \n [[[cog\nfrom metadata_doc import config_example, config_example\nconfig_example(cog, {\n \"databases\": {\n \"sf-trees\": {\n \"queries\": {\n \"just_species\": {\n \"sql\": \"select qSpecies from Street_Tree_List\"\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n Then run Datasette like this: \n datasette sf-trees.db -m metadata.json \n Each canned query will be listed on the database index page, and will also get its own URL at: \n /database-name/canned-query-name \n For the above example, that URL would be: \n /sf-trees/just_species \n You can optionally include \"title\" and \"description\" keys to show a title and description on the canned query page. As with regular table metadata you can alternatively specify \"description_html\" to have your description rendered as HTML (rather than having HTML special characters escaped).", "breadcrumbs": "[\"Running SQL queries\"]", "references": "[]"} {"id": "changelog:the-internal-database", "page": "changelog", "ref": "the-internal-database", "title": "The _internal database", "content": "As part of ongoing work to help Datasette handle much larger numbers of connected databases and tables (see Datasette Library ) Datasette now maintains an in-memory SQLite database with details of all of the attached databases, tables, columns, indexes and foreign keys. ( #1150 ) \n This will support future improvements such as a searchable, paginated homepage of all available tables. \n You can explore an example of this database by signing in as root to the latest.datasette.io demo instance and then navigating to latest.datasette.io/_internal . \n Plugins can use these tables to introspect attached data in an efficient way. Plugin authors should note that this is not yet considered a stable interface, so any plugins that use this may need to make changes prior to Datasette 1.0 if the _internal table schemas change.", "breadcrumbs": "[\"Changelog\", \"0.54 (2021-01-25)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/417\", \"label\": \"Datasette Library\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1150\", \"label\": \"#1150\"}, {\"href\": \"https://latest.datasette.io/login-as-root\", \"label\": \"signing in as root\"}, {\"href\": \"https://latest.datasette.io/_internal\", \"label\": \"latest.datasette.io/_internal\"}]"} {"id": "changelog:named-in-memory-database-support", "page": "changelog", "ref": "named-in-memory-database-support", "title": "Named in-memory database support", "content": "As part of the work building the _internal database, Datasette now supports named in-memory databases that can be shared across multiple connections. This allows plugins to create in-memory databases which will persist data for the lifetime of the Datasette server process. ( #1151 ) \n The new memory_name= parameter to the Database class can be used to create named, shared in-memory databases.", "breadcrumbs": "[\"Changelog\", \"0.54 (2021-01-25)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1151\", \"label\": \"#1151\"}]"} {"id": "changelog:id155", "page": "changelog", "ref": "id155", "title": "0.16 (2018-04-13)", "content": "Better mechanism for handling errors; 404s for missing table/database \n New error mechanism closes #193 \n 404s for missing tables/databases closes #184 \n \n \n long_description in markdown for the new PyPI \n \n \n Hide SpatiaLite system tables. [Russ Garrett] \n \n \n Allow explain select / explain query plan select #201 \n \n \n Datasette inspect now finds primary_keys #195 \n \n \n Ability to sort using form fields (for mobile portrait mode) #199 \n We now display sort options as a select box plus a descending checkbox, which\n means you can apply sort orders even in portrait mode on a mobile phone where\n the column headers are hidden.", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/193\", \"label\": \"#193\"}, {\"href\": \"https://github.com/simonw/datasette/issues/184\", \"label\": \"#184\"}, {\"href\": \"https://github.com/simonw/datasette/issues/201\", \"label\": \"#201\"}, {\"href\": \"https://github.com/simonw/datasette/issues/195\", \"label\": \"#195\"}, {\"href\": \"https://github.com/simonw/datasette/issues/199\", \"label\": \"#199\"}]"} {"id": "contributing:contributing-formatting-black", "page": "contributing", "ref": "contributing-formatting-black", "title": "Running Black", "content": "Black will be installed when you run pip install -e '.[test]' . To test that your code complies with Black, run the following in your root datasette repository checkout: \n black . --check \n All done! \u2728 \ud83c\udf70 \u2728\n95 files would be left unchanged. \n If any of your code does not conform to Black you can run this to automatically fix those problems: \n black . \n reformatted ../datasette/setup.py\nAll done! \u2728 \ud83c\udf70 \u2728\n1 file reformatted, 94 files left unchanged.", "breadcrumbs": "[\"Contributing\", \"Code formatting\"]", "references": "[]"} {"id": "changelog:signed-values-and-secrets", "page": "changelog", "ref": "signed-values-and-secrets", "title": "Signed values and secrets", "content": "Both flash messages and user authentication needed a way to sign values and set signed cookies. Two new methods are now available for plugins to take advantage of this mechanism: .sign(value, namespace=\"default\") and .unsign(value, namespace=\"default\") . \n Datasette will generate a secret automatically when it starts up, but to avoid resetting the secret (and hence invalidating any cookies) every time the server restarts you should set your own secret. You can pass a secret to Datasette using the new --secret option or with a DATASETTE_SECRET environment variable. See Configuring the secret for more details. \n You can also set a secret when you deploy Datasette using datasette publish or datasette package - see Using secrets with datasette publish . \n Plugins can now sign values and verify their signatures using the datasette.sign() and datasette.unsign() methods.", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[]"} {"id": "changelog:id115", "page": "changelog", "ref": "id115", "title": "0.22.1 (2018-05-23)", "content": "Bugfix release, plus we now use versioneer for our version numbers. \n \n \n Faceting no longer breaks pagination, fixes #282 \n \n \n Add __version_info__ derived from __version__ [Robert Gieseke] \n This might be tuple of more than two values (major and minor\n version) if commits have been made after a release. \n \n \n Add version number support with Versioneer. [Robert Gieseke] \n Versioneer Licence:\n Public Domain (CC0-1.0) \n Closes #273 \n \n \n Refactor inspect logic [Russ Garrett]", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/warner/python-versioneer\", \"label\": \"versioneer\"}, {\"href\": \"https://github.com/simonw/datasette/issues/282\", \"label\": \"#282\"}, {\"href\": \"https://github.com/simonw/datasette/issues/273\", \"label\": \"#273\"}]"} {"id": "changelog:id82", "page": "changelog", "ref": "id82", "title": "0.29.2 (2019-07-13)", "content": "Bumped Uvicorn to 0.8.4, fixing a bug where the query string was not included in the server logs. ( #559 ) \n \n \n Fixed bug where the navigation breadcrumbs were not displayed correctly on the page for a custom query. ( #558 ) \n \n \n Fixed bug where custom query names containing unicode characters caused errors.", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://www.uvicorn.org/\", \"label\": \"Uvicorn\"}, {\"href\": \"https://github.com/simonw/datasette/issues/559\", \"label\": \"#559\"}, {\"href\": \"https://github.com/simonw/datasette/issues/558\", \"label\": \"#558\"}]"} {"id": "metadata:metadata-default-sort", "page": "metadata", "ref": "metadata-default-sort", "title": "Setting a default sort order", "content": "By default Datasette tables are sorted by primary key. You can over-ride this default for a specific table using the \"sort\" or \"sort_desc\" metadata properties: \n [[[cog\nmetadata_example(cog, {\n \"databases\": {\n \"mydatabase\": {\n \"tables\": {\n \"example_table\": {\n \"sort\": \"created\"\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n Or use \"sort_desc\" to sort in descending order: \n [[[cog\nmetadata_example(cog, {\n \"databases\": {\n \"mydatabase\": {\n \"tables\": {\n \"example_table\": {\n \"sort_desc\": \"created\"\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Metadata\"]", "references": "[]"} {"id": "custom_templates:customization-custom-templates", "page": "custom_templates", "ref": "customization-custom-templates", "title": "Custom templates", "content": "By default, Datasette uses default templates that ship with the package. \n You can over-ride these templates by specifying a custom --template-dir like\n this: \n datasette mydb.db --template-dir=mytemplates/ \n Datasette will now first look for templates in that directory, and fall back on\n the defaults if no matches are found. \n It is also possible to over-ride templates on a per-database, per-row or per-\n table basis. \n The lookup rules Datasette uses are as follows: \n Index page (/):\n index.html\n\nDatabase page (/mydatabase):\n database-mydatabase.html\n database.html\n\nCustom query page (/mydatabase?sql=...):\n query-mydatabase.html\n query.html\n\nCanned query page (/mydatabase/canned-query):\n query-mydatabase-canned-query.html\n query-mydatabase.html\n query.html\n\nTable page (/mydatabase/mytable):\n table-mydatabase-mytable.html\n table.html\n\nRow page (/mydatabase/mytable/id):\n row-mydatabase-mytable.html\n row.html\n\nTable of rows and columns include on table page:\n _table-table-mydatabase-mytable.html\n _table-mydatabase-mytable.html\n _table.html\n\nTable of rows and columns include on row page:\n _table-row-mydatabase-mytable.html\n _table-mydatabase-mytable.html\n _table.html \n If a table name has spaces or other unexpected characters in it, the template\n filename will follow the same rules as our custom CSS classes - for\n example, a table called \"Food Trucks\" will attempt to load the following\n templates: \n table-mydatabase-Food-Trucks-399138.html\ntable.html \n You can find out which templates were considered for a specific page by viewing\n source on that page and looking for an HTML comment at the bottom. The comment\n will look something like this: \n \n This example is from the canned query page for a query called \"tz\" in the\n database called \"mydb\". The asterisk shows which template was selected - so in\n this case, Datasette found a template file called query-mydb-tz.html and\n used that - but if that template had not been found, it would have tried for\n query-mydb.html or the default query.html . \n It is possible to extend the default templates using Jinja template\n inheritance. If you want to customize EVERY row template with some additional\n content you can do so by creating a row.html template like this: \n {% extends \"default:row.html\" %}\n\n{% block content %}\n

EXTRA HTML AT THE TOP OF THE CONTENT BLOCK

\n

This line renders the original block:

\n{{ super() }}\n{% endblock %} \n Note the default:row.html template name, which ensures Jinja will inherit\n from the default template. \n The _table.html template is included by both the row and the table pages,\n and a list of rows. The default _table.html template renders them as an\n HTML template and can be seen here . \n You can provide a custom template that applies to all of your databases and\n tables, or you can provide custom templates for specific tables using the\n template naming scheme described above. \n If you want to present your data in a format other than an HTML table, you\n can do so by looping through display_rows in your own _table.html \n template. You can use {{ row[\"column_name\"] }} to output the raw value\n of a specific column. \n If you want to output the rendered HTML version of a column, including any\n links to foreign keys, you can use {{ row.display(\"column_name\") }} . \n Here is an example of a custom _table.html template: \n {% for row in display_rows %}\n
\n

{{ row[\"title\"] }}

\n

{{ row[\"description\"] }}\n

Category: {{ row.display(\"category_id\") }}

\n
\n{% endfor %}", "breadcrumbs": "[\"Custom pages and templates\", \"Publishing static assets\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/blob/main/datasette/templates/_table.html\", \"label\": \"can be seen here\"}]"} {"id": "settings:setting-sql-time-limit-ms", "page": "settings", "ref": "setting-sql-time-limit-ms", "title": "sql_time_limit_ms", "content": "By default, queries have a time limit of one second. If a query takes longer than this to run Datasette will terminate the query and return an error. \n If this time limit is too short for you, you can customize it using the sql_time_limit_ms limit - for example, to increase it to 3.5 seconds: \n datasette mydatabase.db --setting sql_time_limit_ms 3500 \n You can optionally set a lower time limit for an individual query using the ?_timelimit=100 query string argument: \n /my-database/my-table?qSpecies=44&_timelimit=100 \n This would set the time limit to 100ms for that specific query. This feature is useful if you are working with databases of unknown size and complexity - a query that might make perfect sense for a smaller table could take too long to execute on a table with millions of rows. By setting custom time limits you can execute queries \"optimistically\" - e.g. give me an exact count of rows matching this query but only if it takes less than 100ms to calculate.", "breadcrumbs": "[\"Settings\", \"Settings\"]", "references": "[]"} {"id": "authentication:authentication-permissions-query", "page": "authentication", "ref": "authentication-permissions-query", "title": "Access to specific canned queries", "content": "Canned queries allow you to configure named SQL queries in your datasette.yaml that can be executed by users. These queries can be set up to both read and write to the database, so controlling who can execute them can be important. \n To limit access to the add_name canned query in your dogs.db database to just the root user : \n [[[cog\nconfig_example(cog, \"\"\"\n databases:\n dogs:\n queries:\n add_name:\n sql: INSERT INTO names (name) VALUES (:name)\n write: true\n allow:\n id:\n - root\n\"\"\") \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[]"} {"id": "configuration:configuration-reference-canned-queries", "page": "configuration", "ref": "configuration-reference-canned-queries", "title": "Canned queries configuration", "content": "Canned queries are named SQL queries that appear in the Datasette interface. They can be configured in datasette.yaml using the queries key at the database level: \n [[[cog\nfrom metadata_doc import config_example, config_example\nconfig_example(cog, {\n \"databases\": {\n \"sf-trees\": {\n \"queries\": {\n \"just_species\": {\n \"sql\": \"select qSpecies from Street_Tree_List\"\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n See the canned queries documentation for more, including how to configure writable canned queries .", "breadcrumbs": "[\"Configuration\", null]", "references": "[]"} {"id": "sql_queries:canned-queries-writable", "page": "sql_queries", "ref": "canned-queries-writable", "title": "Writable canned queries", "content": "Canned queries by default are read-only. You can use the \"write\": true key to indicate that a canned query can write to the database. \n See Access to specific canned queries for details on how to add permission checks to canned queries, using the \"allow\" key. \n [[[cog\nconfig_example(cog, {\n \"databases\": {\n \"mydatabase\": {\n \"queries\": {\n \"add_name\": {\n \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n \"write\": True\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n This configuration will create a page at /mydatabase/add_name displaying a form with a name field. Submitting that form will execute the configured INSERT query. \n You can customize how Datasette represents success and errors using the following optional properties: \n \n \n on_success_message - the message shown when a query is successful \n \n \n on_success_message_sql - alternative to on_success_message : a SQL query that should be executed to generate the message \n \n \n on_success_redirect - the path or URL the user is redirected to on success \n \n \n on_error_message - the message shown when a query throws an error \n \n \n on_error_redirect - the path or URL the user is redirected to on error \n \n \n For example: \n [[[cog\nconfig_example(cog, {\n \"databases\": {\n \"mydatabase\": {\n \"queries\": {\n \"add_name\": {\n \"sql\": \"INSERT INTO names (name) VALUES (:name)\",\n \"params\": [\"name\"],\n \"write\": True,\n \"on_success_message_sql\": \"select 'Name inserted: ' || :name\",\n \"on_success_redirect\": \"/mydatabase/names\",\n \"on_error_message\": \"Name insert failed\",\n \"on_error_redirect\": \"/mydatabase\",\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n You can use \"params\" to explicitly list the named parameters that should be displayed as form fields - otherwise they will be automatically detected. \"params\" is not necessary in the above example, since without it \"name\" would be automatically detected from the query. \n You can pre-populate form fields when the page first loads using a query string, e.g. /mydatabase/add_name?name=Prepopulated . The user will have to submit the form to execute the query. \n If you specify a query in \"on_success_message_sql\" , that query will be executed after the main query. The first column of the first row return by that query will be displayed as a success message. Named parameters from the main query will be made available to the success message query as well.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[]"} {"id": "sql_queries:hide-sql", "page": "sql_queries", "ref": "hide-sql", "title": "hide_sql", "content": "Canned queries default to displaying their SQL query at the top of the page. If the query is extremely long you may want to hide it by default, with a \"show\" link that can be used to make it visible. \n Add the \"hide_sql\": true option to hide the SQL query by default.", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\", \"Additional canned query options\"]", "references": "[]"} {"id": "changelog:magic-parameters-for-canned-queries", "page": "changelog", "ref": "magic-parameters-for-canned-queries", "title": "Magic parameters for canned queries", "content": "Canned queries now support Magic parameters , which can be used to insert or select automatically generated values. For example: \n insert into logs\n (user_id, timestamp)\nvalues\n (:_actor_id, :_now_datetime_utc) \n This inserts the currently authenticated actor ID and the current datetime. ( #842 )", "breadcrumbs": "[\"Changelog\", \"0.45 (2020-07-01)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/842\", \"label\": \"#842\"}]"} {"id": "sql_queries:canned-queries-named-parameters", "page": "sql_queries", "ref": "canned-queries-named-parameters", "title": "Canned query parameters", "content": "Canned queries support named parameters, so if you include those in the SQL you will then be able to enter them using the form fields on the canned query page or by adding them to the URL. This means canned queries can be used to create custom JSON APIs based on a carefully designed SQL statement. \n Here's an example of a canned query with a named parameter: \n select neighborhood, facet_cities.name, state\nfrom facetable\n join facet_cities on facetable.city_id = facet_cities.id\nwhere neighborhood like '%' || :text || '%'\norder by neighborhood; \n In the canned query configuration looks like this: \n [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n fixtures:\n queries:\n neighborhood_search:\n title: Search neighborhoods\n sql: |-\n select neighborhood, facet_cities.name, state\n from facetable\n join facet_cities on facetable.city_id = facet_cities.id\n where neighborhood like '%' || :text || '%'\n order by neighborhood\n\"\"\") \n ]]] \n [[[end]]] \n Note that we are using SQLite string concatenation here - the || operator - to add wildcard % characters to the string provided by the user. \n You can try this canned query out here:\n https://latest.datasette.io/fixtures/neighborhood_search?text=town \n In this example the :text named parameter is automatically extracted from the query using a regular expression. \n You can alternatively provide an explicit list of named parameters using the \"params\" key, like this: \n [[[cog\nconfig_example(cog, \"\"\"\ndatabases:\n fixtures:\n queries:\n neighborhood_search:\n title: Search neighborhoods\n params:\n - text\n sql: |-\n select neighborhood, facet_cities.name, state\n from facetable\n join facet_cities on facetable.city_id = facet_cities.id\n where neighborhood like '%' || :text || '%'\n order by neighborhood\n\"\"\") \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Running SQL queries\", \"Canned queries\"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures/neighborhood_search?text=town\", \"label\": \"https://latest.datasette.io/fixtures/neighborhood_search?text=town\"}]"} {"id": "changelog:id59", "page": "changelog", "ref": "id59", "title": "Smaller changes", "content": "Cascading view permissions - so if a user has view-table they can view the table page even if they do not have view-database or view-instance . ( #832 ) \n \n \n CSRF protection no longer applies to Authentication: Bearer token requests or requests without cookies. ( #835 ) \n \n \n datasette.add_message() now works inside plugins. ( #864 ) \n \n \n Workaround for \"Too many open files\" error in test runs. ( #846 ) \n \n \n Respect existing scope[\"actor\"] if already set by ASGI middleware. ( #854 ) \n \n \n New process for shipping Alpha and beta releases . ( #807 ) \n \n \n {{ csrftoken() }} now works when plugins render a template using datasette.render_template(..., request=request) . ( #863 ) \n \n \n Datasette now creates a single Request object and uses it throughout the lifetime of the current HTTP request. ( #870 )", "breadcrumbs": "[\"Changelog\", \"0.45 (2020-07-01)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/832\", \"label\": \"#832\"}, {\"href\": \"https://github.com/simonw/datasette/issues/835\", \"label\": \"#835\"}, {\"href\": \"https://github.com/simonw/datasette/issues/864\", \"label\": \"#864\"}, {\"href\": \"https://github.com/simonw/datasette/issues/846\", \"label\": \"#846\"}, {\"href\": \"https://github.com/simonw/datasette/issues/854\", \"label\": \"#854\"}, {\"href\": \"https://github.com/simonw/datasette/issues/807\", \"label\": \"#807\"}, {\"href\": \"https://github.com/simonw/datasette/issues/863\", \"label\": \"#863\"}, {\"href\": \"https://github.com/simonw/datasette/issues/870\", \"label\": \"#870\"}]"} {"id": "internals:database-close", "page": "internals", "ref": "database-close", "title": "db.close()", "content": "Closes all of the open connections to file-backed databases. This is mainly intended to be used by large test suites, to avoid hitting limits on the number of open files.", "breadcrumbs": "[\"Internals for plugins\", \"Database class\"]", "references": "[]"} {"id": "changelog:id24", "page": "changelog", "ref": "id24", "title": "0.59.2 (2021-11-13)", "content": "Column names with a leading underscore now work correctly when used as a facet. ( #1506 ) \n \n \n Applying ?_nocol= to a column no longer removes that column from the filtering interface. ( #1503 ) \n \n \n Official Datasette Docker container now uses Debian Bullseye as the base image. ( #1497 ) \n \n \n Datasette is four years old today! Here's the original release announcement from 2017.", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1506\", \"label\": \"#1506\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1503\", \"label\": \"#1503\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1497\", \"label\": \"#1497\"}, {\"href\": \"https://simonwillison.net/2017/Nov/13/datasette/\", \"label\": \"original release announcement\"}]"} {"id": "changelog:id26", "page": "changelog", "ref": "id26", "title": "0.59 (2021-10-14)", "content": "Columns can now have associated metadata descriptions in metadata.json , see Column descriptions . ( #942 ) \n \n \n New register_commands() plugin hook allows plugins to register additional Datasette CLI commands, e.g. datasette mycommand file.db . ( #1449 ) \n \n \n Adding ?_facet_size=max to a table page now shows the number of unique values in each facet. ( #1423 ) \n \n \n Upgraded dependency httpx 0.20 - the undocumented allow_redirects= parameter to datasette.client is now follow_redirects= , and defaults to False where it previously defaulted to True . ( #1488 ) \n \n \n The --cors option now causes Datasette to return the Access-Control-Allow-Headers: Authorization header, in addition to Access-Control-Allow-Origin: * . ( #1467 ) \n \n \n Code that figures out which named parameters a SQL query takes in order to display form fields for them is no longer confused by strings that contain colon characters. ( #1421 ) \n \n \n Renamed --help-config option to --help-settings . ( #1431 ) \n \n \n datasette.databases property is now a documented API. ( #1443 ) \n \n \n The base.html template now wraps everything other than the
in a
element, to help with advanced CSS customization. ( #1446 ) \n \n \n The render_cell() plugin hook can now return an awaitable function. This means the hook can execute SQL queries. ( #1425 ) \n \n \n register_routes(datasette) plugin hook now accepts an optional datasette argument. ( #1404 ) \n \n \n New hide_sql canned query option for defaulting to hiding the SQL query used by a canned query, see Additional canned query options . ( #1422 ) \n \n \n New --cpu option for datasette publish cloudrun . ( #1420 ) \n \n \n If Rich is installed in the same virtual environment as Datasette, it will be used to provide enhanced display of error tracebacks on the console. ( #1416 ) \n \n \n datasette.utils parse_metadata(content) function, used by the new datasette-remote-metadata plugin , is now a documented API. ( #1405 ) \n \n \n Fixed bug where ?_next=x&_sort=rowid could throw an error. ( #1470 ) \n \n \n Column cog menu no longer shows the option to facet by a column that is already selected by the default facets in metadata. ( #1469 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/942\", \"label\": \"#942\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1449\", \"label\": \"#1449\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1423\", \"label\": \"#1423\"}, {\"href\": \"https://github.com/encode/httpx/releases/tag/0.20.0\", \"label\": \"httpx 0.20\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1488\", \"label\": \"#1488\"}, {\"href\": \"https://github.com/simonw/datasette/pull/1467\", \"label\": \"#1467\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1421\", \"label\": \"#1421\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1431\", \"label\": \"#1431\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1443\", \"label\": \"#1443\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1446\", \"label\": \"#1446\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1425\", \"label\": \"#1425\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1404\", \"label\": \"#1404\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1422\", \"label\": \"#1422\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1420\", \"label\": \"#1420\"}, {\"href\": \"https://github.com/willmcgugan/rich\", \"label\": \"Rich\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1416\", \"label\": \"#1416\"}, {\"href\": \"https://datasette.io/plugins/datasette-remote-metadata\", \"label\": \"datasette-remote-metadata plugin\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1405\", \"label\": \"#1405\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1470\", \"label\": \"#1470\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1469\", \"label\": \"#1469\"}]"} {"id": "authentication:permissions-debug-menu", "page": "authentication", "ref": "permissions-debug-menu", "title": "debug-menu", "content": "Controls if the various debug pages are displayed in the navigation menu. \n Default deny .", "breadcrumbs": "[\"Authentication and permissions\", \"Built-in permissions\"]", "references": "[]"} {"id": "performance:performance-inspect", "page": "performance", "ref": "performance-inspect", "title": "Using \"datasette inspect\"", "content": "Counting the rows in a table can be a very expensive operation on larger databases. In immutable mode Datasette performs this count only once and caches the results, but this can still cause server startup time to increase by several seconds or more. \n If you know that a database is never going to change you can precalculate the table row counts once and store then in a JSON file, then use that file when you later start the server. \n To create a JSON file containing the calculated row counts for a database, use the following: \n datasette inspect data.db --inspect-file=counts.json \n Then later you can start Datasette against the counts.json file and use it to skip the row counting step and speed up server startup: \n datasette -i data.db --inspect-file=counts.json \n You need to use the -i immutable mode against the database file here or the counts from the JSON file will be ignored. \n You will rarely need to use this optimization in every-day use, but several of the datasette publish commands described in Publishing data use this optimization for better performance when deploying a database file to a hosting provider.", "breadcrumbs": "[\"Performance and caching\"]", "references": "[]"} {"id": "cli-reference:cli-help-create-token-help", "page": "cli-reference", "ref": "cli-help-create-token-help", "title": "datasette create-token", "content": "Create a signed API token, see datasette create-token . \n [[[cog\nhelp([\"create-token\", \"--help\"]) \n ]]] \n Usage: datasette create-token [OPTIONS] ID\n\n Create a signed API token for the specified actor ID\n\n Example:\n\n datasette create-token root --secret mysecret\n\n To allow only \"view-database-download\" for all databases:\n\n datasette create-token root --secret mysecret \\\n --all view-database-download\n\n To allow \"create-table\" against a specific database:\n\n datasette create-token root --secret mysecret \\\n --database mydb create-table\n\n To allow \"insert-row\" against a specific table:\n\n datasette create-token root --secret myscret \\\n --resource mydb mytable insert-row\n\n Restricted actions can be specified multiple times using multiple --all,\n --database, and --resource options.\n\n Add --debug to see a decoded version of the token.\n\nOptions:\n --secret TEXT Secret used for signing the API tokens\n [required]\n -e, --expires-after INTEGER Token should expire after this many seconds\n -a, --all ACTION Restrict token to this action\n -d, --database DB ACTION Restrict token to this action on this database\n -r, --resource DB RESOURCE ACTION\n Restrict token to this action on this database\n resource (a table, SQL view or named query)\n --debug Show decoded token\n --plugins-dir DIRECTORY Path to directory containing custom plugins\n --help Show this message and exit. \n [[[end]]]", "breadcrumbs": "[\"CLI reference\"]", "references": "[]"} {"id": "changelog:bug-fixes-and-other-improvements", "page": "changelog", "ref": "bug-fixes-and-other-improvements", "title": "Bug fixes and other improvements", "content": "Custom pages now work correctly when combined with the base_url setting. ( #1238 ) \n \n \n Fixed intermittent error displaying the index page when the user did not have permission to access one of the tables. Thanks, Guy Freeman. ( #1305 ) \n \n \n Columns with the name \"Link\" are no longer incorrectly displayed in bold. ( #1308 ) \n \n \n Fixed error caused by tables with a single quote in their names. ( #1257 ) \n \n \n Updated dependencies: pytest-asyncio , Black , jinja2 , aiofiles , click , and itsdangerous . \n \n \n The official Datasette Docker image now supports apt-get install . ( #1320 ) \n \n \n The Heroku runtime used by datasette publish heroku is now python-3.8.10 .", "breadcrumbs": "[\"Changelog\", \"0.57 (2021-06-05)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1238\", \"label\": \"#1238\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1305\", \"label\": \"#1305\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1308\", \"label\": \"#1308\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1257\", \"label\": \"#1257\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1320\", \"label\": \"#1320\"}]"} {"id": "custom_templates:custom-pages-headers", "page": "custom_templates", "ref": "custom-pages-headers", "title": "Custom headers and status codes", "content": "Custom pages default to being served with a content-type of text/html; charset=utf-8 and a 200 status code. You can change these by calling a custom function from within your template. \n For example, to serve a custom page with a 418 I'm a teapot HTTP status code, create a file in pages/teapot.html containing the following: \n {{ custom_status(418) }}\n\nTeapot\n\nI'm a teapot\n\n \n To serve a custom HTTP header, add a custom_header(name, value) function call. For example: \n {{ custom_status(418) }}\n{{ custom_header(\"x-teapot\", \"I am\") }}\n\nTeapot\n\nI'm a teapot\n\n \n You can verify this is working using curl like this: \n curl -I 'http://127.0.0.1:8001/teapot'\nHTTP/1.1 418\ndate: Sun, 26 Apr 2020 18:38:30 GMT\nserver: uvicorn\nx-teapot: I am\ncontent-type: text/html; charset=utf-8", "breadcrumbs": "[\"Custom pages and templates\"]", "references": "[]"} {"id": "metadata:id1", "page": "metadata", "ref": "id1", "title": "Metadata", "content": "Data loves metadata. Any time you run Datasette you can optionally include a\n YAML or JSON file with metadata about your databases and tables. Datasette will then\n display that information in the web UI. \n Run Datasette like this: \n datasette database1.db database2.db --metadata metadata.yaml \n Your metadata.yaml file can look something like this: \n [[[cog\nfrom metadata_doc import metadata_example\nmetadata_example(cog, {\n \"title\": \"Custom title for your index page\",\n \"description\": \"Some description text can go here\",\n \"license\": \"ODbL\",\n \"license_url\": \"https://opendatacommons.org/licenses/odbl/\",\n \"source\": \"Original Data Source\",\n \"source_url\": \"http://example.com/\"\n}) \n ]]] \n [[[end]]] \n Choosing YAML over JSON adds support for multi-line strings and comments. \n The above metadata will be displayed on the index page of your Datasette-powered\n site. The source and license information will also be included in the footer of\n every page served by Datasette. \n Any special HTML characters in description will be escaped. If you want to\n include HTML in your description, you can use a description_html property\n instead.", "breadcrumbs": "[]", "references": "[]"} {"id": "changelog:small-changes", "page": "changelog", "ref": "small-changes", "title": "Small changes", "content": "Databases published using datasette publish now open in Immutable mode . ( #469 ) \n \n \n ?col__date= now works for columns containing spaces \n \n \n Automatic label detection (for deciding which column to show when linking to a foreign key) has been improved. ( #485 ) \n \n \n Fixed bug where pagination broke when combined with an expanded foreign key. ( #489 ) \n \n \n Contributors can now run pip install -e .[docs] to get all of the dependencies needed to build the documentation, including cd docs && make livehtml support. \n \n \n Datasette's dependencies are now all specified using the ~= match operator. ( #532 ) \n \n \n white-space: pre-wrap now used for table creation SQL. ( #505 ) \n \n \n Full list of commits between 0.28 and 0.29.", "breadcrumbs": "[\"Changelog\", \"0.29 (2019-07-07)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/469\", \"label\": \"#469\"}, {\"href\": \"https://github.com/simonw/datasette/issues/485\", \"label\": \"#485\"}, {\"href\": \"https://github.com/simonw/datasette/issues/489\", \"label\": \"#489\"}, {\"href\": \"https://github.com/simonw/datasette/issues/532\", \"label\": \"#532\"}, {\"href\": \"https://github.com/simonw/datasette/issues/505\", \"label\": \"#505\"}, {\"href\": \"https://github.com/simonw/datasette/compare/0.28...0.29\", \"label\": \"Full list of commits\"}]"} {"id": "changelog:v0-28-faceting", "page": "changelog", "ref": "v0-28-faceting", "title": "Faceting improvements, and faceting plugins", "content": "Datasette Facets provide an intuitive way to quickly summarize and interact with data. Previously the only supported faceting technique was column faceting, but 0.28 introduces two powerful new capabilities: facet-by-JSON-array and the ability to define further facet types using plugins. \n Facet by array ( #359 ) is only available if your SQLite installation provides the json1 extension. Datasette will automatically detect columns that contain JSON arrays of values and offer a faceting interface against those columns - useful for modelling things like tags without needing to break them out into a new table. See Facet by JSON array for more. \n The new register_facet_classes() plugin hook ( #445 ) can be used to register additional custom facet classes. Each facet class should provide two methods: suggest() which suggests facet selections that might be appropriate for a provided SQL query, and facet_results() which executes a facet operation and returns results. Datasette's own faceting implementations have been refactored to use the same API as these plugins.", "breadcrumbs": "[\"Changelog\", \"0.28 (2019-05-19)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/359\", \"label\": \"#359\"}, {\"href\": \"https://github.com/simonw/datasette/pull/445\", \"label\": \"#445\"}]"} {"id": "changelog:id65", "page": "changelog", "ref": "id65", "title": "0.40 (2020-04-21)", "content": "Datasette Metadata can now be provided as a YAML file as an optional alternative to JSON. ( #713 ) \n \n \n Removed support for datasette publish now , which used the the now-retired Zeit Now v1 hosting platform. A new plugin, datasette-publish-now , can be installed to publish data to Zeit ( now Vercel ) Now v2. ( #710 ) \n \n \n Fixed a bug where the extra_template_vars(request, view_name) plugin hook was not receiving the correct view_name . ( #716 ) \n \n \n Variables added to the template context by the extra_template_vars() plugin hook are now shown in the ?_context=1 debugging mode (see template_debug ). ( #693 ) \n \n \n Fixed a bug where the \"templates considered\" HTML comment was no longer being displayed. ( #689 ) \n \n \n Fixed a datasette publish bug where --plugin-secret would over-ride plugin configuration in the provided metadata.json file. ( #724 ) \n \n \n Added a new CSS class for customizing the canned query page. ( #727 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/713\", \"label\": \"#713\"}, {\"href\": \"https://github.com/simonw/datasette-publish-now\", \"label\": \"datasette-publish-now\"}, {\"href\": \"https://vercel.com/blog/zeit-is-now-vercel\", \"label\": \"now Vercel\"}, {\"href\": \"https://github.com/simonw/datasette/issues/710\", \"label\": \"#710\"}, {\"href\": \"https://github.com/simonw/datasette/issues/716\", \"label\": \"#716\"}, {\"href\": \"https://github.com/simonw/datasette/issues/693\", \"label\": \"#693\"}, {\"href\": \"https://github.com/simonw/datasette/issues/689\", \"label\": \"#689\"}, {\"href\": \"https://github.com/simonw/datasette/issues/724\", \"label\": \"#724\"}, {\"href\": \"https://github.com/simonw/datasette/issues/727\", \"label\": \"#727\"}]"} {"id": "plugin_hooks:id1", "page": "plugin_hooks", "ref": "id1", "title": "Plugin hooks", "content": "Datasette plugins use plugin hooks to customize Datasette's behavior. These hooks are powered by the pluggy plugin system. \n Each plugin can implement one or more hooks using the @hookimpl decorator against a function named that matches one of the hooks documented on this page. \n When you implement a plugin hook you can accept any or all of the parameters that are documented as being passed to that hook. \n For example, you can implement the render_cell plugin hook like this even though the full documented hook signature is render_cell(row, value, column, table, database, datasette) : \n @hookimpl\ndef render_cell(value, column):\n if column == \"stars\":\n return \"*\" * int(value) \n \n List of plugin hooks \n \n \n prepare_connection(conn, database, datasette) \n \n \n prepare_jinja2_environment(env, datasette) \n \n \n Page extras \n \n \n extra_template_vars(template, database, table, columns, view_name, request, datasette) \n \n \n extra_css_urls(template, database, table, columns, view_name, request, datasette) \n \n \n extra_js_urls(template, database, table, columns, view_name, request, datasette) \n \n \n extra_body_script(template, database, table, columns, view_name, request, datasette) \n \n \n \n \n publish_subcommand(publish) \n \n \n render_cell(row, value, column, table, database, datasette, request) \n \n \n register_output_renderer(datasette) \n \n \n register_routes(datasette) \n \n \n register_commands(cli) \n \n \n register_facet_classes() \n \n \n register_permissions(datasette) \n \n \n asgi_wrapper(datasette) \n \n \n startup(datasette) \n \n \n canned_queries(datasette, database, actor) \n \n \n actor_from_request(datasette, request) \n \n \n actors_from_ids(datasette, actor_ids) \n \n \n jinja2_environment_from_request(datasette, request, env) \n \n \n filters_from_request(request, database, table, datasette) \n \n \n permission_allowed(datasette, actor, action, resource) \n \n \n register_magic_parameters(datasette) \n \n \n forbidden(datasette, request, message) \n \n \n handle_exception(datasette, request, exception) \n \n \n skip_csrf(datasette, scope) \n \n \n get_metadata(datasette, key, database, table) \n \n \n menu_links(datasette, actor, request) \n \n \n Action hooks \n \n \n table_actions(datasette, actor, database, table, request) \n \n \n view_actions(datasette, actor, database, view, request) \n \n \n query_actions(datasette, actor, database, query_name, request, sql, params) \n \n \n row_actions(datasette, actor, request, database, table, row) \n \n \n database_actions(datasette, actor, database, request) \n \n \n homepage_actions(datasette, actor, request) \n \n \n \n \n Template slots \n \n \n top_homepage(datasette, request) \n \n \n top_database(datasette, request, database) \n \n \n top_table(datasette, request, database, table) \n \n \n top_row(datasette, request, database, table, row) \n \n \n top_query(datasette, request, database, sql) \n \n \n top_canned_query(datasette, request, database, query_name) \n \n \n \n \n Event tracking \n \n \n track_event(datasette, event) \n \n \n register_events(datasette)", "breadcrumbs": "[]", "references": "[{\"href\": \"https://pluggy.readthedocs.io/\", \"label\": \"pluggy\"}]"} {"id": "installation:installation-datasette-desktop", "page": "installation", "ref": "installation-datasette-desktop", "title": "Datasette Desktop for Mac", "content": "Datasette Desktop is a packaged Mac application which bundles Datasette together with Python and allows you to install and run Datasette directly on your laptop. This is the best option for local installation if you are not comfortable using the command line.", "breadcrumbs": "[\"Installation\", \"Basic installation\"]", "references": "[{\"href\": \"https://datasette.io/desktop\", \"label\": \"Datasette Desktop\"}]"} {"id": "getting_started:getting-started-datasette-lite", "page": "getting_started", "ref": "getting-started-datasette-lite", "title": "Datasette in your browser with Datasette Lite", "content": "Datasette Lite is Datasette packaged using WebAssembly so that it runs entirely in your browser, no Python web application server required. \n You can pass a URL to a CSV, SQLite or raw SQL file directly to Datasette Lite to explore that data in your browser. \n This example link opens Datasette Lite and loads the SQL Murder Mystery example database from Northwestern University Knight Lab .", "breadcrumbs": "[\"Getting started\"]", "references": "[{\"href\": \"https://lite.datasette.io/\", \"label\": \"Datasette Lite\"}, {\"href\": \"https://lite.datasette.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2FNUKnightLab%2Fsql-mysteries%2Fmaster%2Fsql-murder-mystery.db#/sql-murder-mystery\", \"label\": \"example link\"}, {\"href\": \"https://github.com/NUKnightLab/sql-mysteries\", \"label\": \"Northwestern University Knight Lab\"}]"} {"id": "changelog:code-formatting-with-black-and-prettier", "page": "changelog", "ref": "code-formatting-with-black-and-prettier", "title": "Code formatting with Black and Prettier", "content": "Datasette adopted Black for opinionated Python code formatting in June 2019. Datasette now also embraces Prettier for JavaScript formatting, which like Black is enforced by tests in continuous integration. Instructions for using these two tools can be found in the new section on Code formatting in the contributors documentation. ( #1167 )", "breadcrumbs": "[\"Changelog\", \"0.54 (2021-01-25)\"]", "references": "[{\"href\": \"https://github.com/psf/black\", \"label\": \"Black\"}, {\"href\": \"https://prettier.io/\", \"label\": \"Prettier\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1167\", \"label\": \"#1167\"}]"} {"id": "metadata:metadata-sortable-columns", "page": "metadata", "ref": "metadata-sortable-columns", "title": "Setting which columns can be used for sorting", "content": "Datasette allows any column to be used for sorting by default. If you need to\n control which columns are available for sorting you can do so using the optional\n sortable_columns key: \n [[[cog\nmetadata_example(cog, {\n \"databases\": {\n \"database1\": {\n \"tables\": {\n \"example_table\": {\n \"sortable_columns\": [\n \"height\",\n \"weight\"\n ]\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n This will restrict sorting of example_table to just the height and\n weight columns. \n You can also disable sorting entirely by setting \"sortable_columns\": [] \n You can use sortable_columns to enable specific sort orders for a view called name_of_view in the database my_database like so: \n [[[cog\nmetadata_example(cog, {\n \"databases\": {\n \"my_database\": {\n \"tables\": {\n \"name_of_view\": {\n \"sortable_columns\": [\n \"clicks\",\n \"impressions\"\n ]\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Metadata\"]", "references": "[]"} {"id": "changelog:permissions", "page": "changelog", "ref": "permissions", "title": "Permissions", "content": "Datasette also now has a built-in concept of Permissions . The permissions system answers the following question: \n \n Is this actor allowed to perform this action , optionally against this particular resource ? \n \n You can use the new \"allow\" block syntax in metadata.json (or metadata.yaml ) to set required permissions at the instance, database, table or canned query level. For example, to restrict access to the fixtures.db database to the \"root\" user: \n {\n \"databases\": {\n \"fixtures\": {\n \"allow\": {\n \"id\" \"root\"\n }\n }\n }\n} \n See Defining permissions with \"allow\" blocks for more details. \n Plugins can implement their own custom permission checks using the new permission_allowed(datasette, actor, action, resource) hook. \n A new debug page at /-/permissions shows recent permission checks, to help administrators and plugin authors understand exactly what checks are being performed. This tool defaults to only being available to the root user, but can be exposed to other users by plugins that respond to the permissions-debug permission. ( #788 )", "breadcrumbs": "[\"Changelog\", \"0.44 (2020-06-11)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/788\", \"label\": \"#788\"}]"} {"id": "contributing:contributing-upgrading-codemirror", "page": "contributing", "ref": "contributing-upgrading-codemirror", "title": "Upgrading CodeMirror", "content": "Datasette bundles CodeMirror for the SQL editing interface, e.g. on this page . Here are the steps for upgrading to a new version of CodeMirror: \n \n \n Install the packages with: \n npm i codemirror @codemirror/lang-sql \n \n \n Build the bundle using the version number from package.json with: \n node_modules/.bin/rollup datasette/static/cm-editor-6.0.1.js \\\n -f iife \\\n -n cm \\\n -o datasette/static/cm-editor-6.0.1.bundle.js \\\n -p @rollup/plugin-node-resolve \\\n -p @rollup/plugin-terser \n \n \n Update the version reference in the codemirror.html template.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://codemirror.net/\", \"label\": \"CodeMirror\"}, {\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"this page\"}]"} {"id": "deploying:deploying-fundamentals", "page": "deploying", "ref": "deploying-fundamentals", "title": "Deployment fundamentals", "content": "Datasette can be deployed as a single datasette process that listens on a port. Datasette is not designed to be run as root, so that process should listen on a higher port such as port 8000. \n If you want to serve Datasette on port 80 (the HTTP default port) or port 443 (for HTTPS) you should run it behind a proxy server, such as nginx, Apache or HAProxy. The proxy server can listen on port 80/443 and forward traffic on to Datasette.", "breadcrumbs": "[\"Deploying Datasette\"]", "references": "[]"} {"id": "json_api:expand-foreign-keys", "page": "json_api", "ref": "expand-foreign-keys", "title": "Expanding foreign key references", "content": "Datasette can detect foreign key relationships and resolve those references into\n labels. The HTML interface does this by default for every detected foreign key\n column - you can turn that off using ?_labels=off . \n You can request foreign keys be expanded in JSON using the _labels=on or\n _label=COLUMN special query string parameters. Here's what an expanded row\n looks like: \n [\n {\n \"rowid\": 1,\n \"TreeID\": 141565,\n \"qLegalStatus\": {\n \"value\": 1,\n \"label\": \"Permitted Site\"\n },\n \"qSpecies\": {\n \"value\": 1,\n \"label\": \"Myoporum laetum :: Myoporum\"\n },\n \"qAddress\": \"501X Baker St\",\n \"SiteOrder\": 1\n }\n] \n The column in the foreign key table that is used for the label can be specified\n in metadata.json - see Specifying the label column for a table .", "breadcrumbs": "[\"JSON API\"]", "references": "[]"} {"id": "configuration:configuration-reference-css-js", "page": "configuration", "ref": "configuration-reference-css-js", "title": "Custom CSS and JavaScript", "content": "Datasette can load additional CSS and JavaScript files, configured in datasette.yaml like this: \n [[[cog\nfrom metadata_doc import config_example\nconfig_example(cog, \"\"\"\n extra_css_urls:\n - https://simonwillison.net/static/css/all.bf8cd891642c.css\n extra_js_urls:\n - https://code.jquery.com/jquery-3.2.1.slim.min.js\n\"\"\") \n ]]] \n [[[end]]] \n The extra CSS and JavaScript files will be linked in the of every page: \n \n \n You can also specify a SRI (subresource integrity hash) for these assets: \n [[[cog\nconfig_example(cog, \"\"\"\n extra_css_urls:\n - url: https://simonwillison.net/static/css/all.bf8cd891642c.css\n sri: sha384-9qIZekWUyjCyDIf2YK1FRoKiPJq4PHt6tp/ulnuuyRBvazd0hG7pWbE99zvwSznI\n extra_js_urls:\n - url: https://code.jquery.com/jquery-3.2.1.slim.min.js\n sri: sha256-k2WSCIexGzOj3Euiig+TlR8gA0EmPjuc79OEeY5L45g=\n\"\"\") \n ]]] \n [[[end]]] \n This will produce: \n \n \n Modern browsers will only execute the stylesheet or JavaScript if the SRI hash\n matches the content served. You can generate hashes using www.srihash.org \n Items in \"extra_js_urls\" can specify \"module\": true if they reference JavaScript that uses JavaScript modules . This configuration: \n [[[cog\nconfig_example(cog, \"\"\"\n extra_js_urls:\n - url: https://example.datasette.io/module.js\n module: true\n\"\"\") \n ]]] \n [[[end]]] \n Will produce this HTML: \n ", "breadcrumbs": "[\"Configuration\", null]", "references": "[{\"href\": \"https://www.srihash.org/\", \"label\": \"www.srihash.org\"}, {\"href\": \"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules\", \"label\": \"JavaScript modules\"}]"} {"id": "changelog:id36", "page": "changelog", "ref": "id36", "title": "Other changes", "content": "Datasette can now open multiple database files with the same name, e.g. if you run datasette path/to/one.db path/to/other/one.db . ( #509 ) \n \n \n datasette publish cloudrun now sets force_https_urls for every deployment, fixing some incorrect http:// links. ( #1178 ) \n \n \n Fixed a bug in the example nginx configuration in Running Datasette behind a proxy . ( #1091 ) \n \n \n The Datasette Ecosystem documentation page has been reduced in size in favour of the datasette.io tools and plugins directories. ( #1182 ) \n \n \n The request object now provides a request.full_path property, which returns the path including any query string. ( #1184 ) \n \n \n Better error message for disallowed PRAGMA clauses in SQL queries. ( #1185 ) \n \n \n datasette publish heroku now deploys using python-3.8.7 . \n \n \n New plugin testing documentation on Testing outbound HTTP calls with pytest-httpx . ( #1198 ) \n \n \n All ?_* query string parameters passed to the table page are now persisted in hidden form fields, so parameters such as ?_size=10 will be correctly passed to the next page when query filters are changed. ( #1194 ) \n \n \n Fixed a bug loading a database file called test-database (1).sqlite . ( #1181 )", "breadcrumbs": "[\"Changelog\", \"0.54 (2021-01-25)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/509\", \"label\": \"#509\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1178\", \"label\": \"#1178\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1091\", \"label\": \"#1091\"}, {\"href\": \"https://datasette.io/tools\", \"label\": \"tools\"}, {\"href\": \"https://datasette.io/plugins\", \"label\": \"plugins\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1182\", \"label\": \"#1182\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1184\", \"label\": \"#1184\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1185\", \"label\": \"#1185\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1198\", \"label\": \"#1198\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1194\", \"label\": \"#1194\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1181\", \"label\": \"#1181\"}]"} {"id": "changelog:id13", "page": "changelog", "ref": "id13", "title": "0.62 (2022-08-14)", "content": "Datasette can now run entirely in your browser using WebAssembly. Try out Datasette Lite , take a look at the code or read more about it in Datasette Lite: a server-side Python web application running in a browser . \n Datasette now has a Discord community for questions and discussions about Datasette and its ecosystem of projects.", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://lite.datasette.io/\", \"label\": \"Datasette Lite\"}, {\"href\": \"https://github.com/simonw/datasette-lite\", \"label\": \"at the code\"}, {\"href\": \"https://simonwillison.net/2022/May/4/datasette-lite/\", \"label\": \"Datasette Lite: a server-side Python web application running in a browser\"}, {\"href\": \"https://datasette.io/discord\", \"label\": \"Discord community\"}]"} {"id": "javascript_plugins:id1", "page": "javascript_plugins", "ref": "id1", "title": "JavaScript plugins", "content": "Datasette can run custom JavaScript in several different ways: \n \n \n Datasette plugins written in Python can use the extra_js_urls() or extra_body_script() plugin hooks to inject JavaScript into a page \n \n \n Datasette instances with custom templates can include additional JavaScript in those templates \n \n \n The extra_js_urls key in datasette.yaml can be used to include extra JavaScript \n \n \n There are no limitations on what this JavaScript can do. It is executed directly by the browser, so it can manipulate the DOM, fetch additional data and do anything else that JavaScript is capable of. \n \n Custom JavaScript has security implications, especially for authenticated Datasette instances where the JavaScript might run in the context of the authenticated user. It's important to carefully review any JavaScript you run in your Datasette instance.", "breadcrumbs": "[]", "references": "[]"} {"id": "custom_templates:customization-static-files", "page": "custom_templates", "ref": "customization-static-files", "title": "Serving static files", "content": "Datasette can serve static files for you, using the --static option.\n Consider the following directory structure: \n metadata.json\nstatic-files/styles.css\nstatic-files/app.js \n You can start Datasette using --static assets:static-files/ to serve those\n files from the /assets/ mount point: \n datasette --config datasette.yaml --static assets:static-files/ --memory \n The following URLs will now serve the content from those CSS and JS files: \n http://localhost:8001/assets/styles.css\nhttp://localhost:8001/assets/app.js \n You can reference those files from datasette.yaml like this, see custom CSS and JavaScript for more details: \n [[[cog\nfrom metadata_doc import config_example\nconfig_example(cog, \"\"\"\n extra_css_urls:\n - /assets/styles.css\n extra_js_urls:\n - /assets/app.js\n\"\"\") \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Custom pages and templates\"]", "references": "[]"} {"id": "authentication:authentication-root", "page": "authentication", "ref": "authentication-root", "title": "Using the \"root\" actor", "content": "Datasette currently leaves almost all forms of authentication to plugins - datasette-auth-github for example. \n The one exception is the \"root\" account, which you can sign into while using Datasette on your local machine. This provides access to a small number of debugging features. \n To sign in as root, start Datasette using the --root command-line option, like this: \n datasette --root \n http://127.0.0.1:8001/-/auth-token?token=786fc524e0199d70dc9a581d851f466244e114ca92f33aa3b42a139e9388daa7\nINFO: Started server process [25801]\nINFO: Waiting for application startup.\nINFO: Application startup complete.\nINFO: Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit) \n The URL on the first line includes a one-use token which can be used to sign in as the \"root\" actor in your browser. Click on that link and then visit http://127.0.0.1:8001/-/actor to confirm that you are authenticated as an actor that looks like this: \n {\n \"id\": \"root\"\n}", "breadcrumbs": "[\"Authentication and permissions\", \"Actors\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette-auth-github\", \"label\": \"datasette-auth-github\"}]"} {"id": "authentication:authentication-permissions-execute-sql", "page": "authentication", "ref": "authentication-permissions-execute-sql", "title": "Controlling the ability to execute arbitrary SQL", "content": "Datasette defaults to allowing any site visitor to execute their own custom SQL queries, for example using the form on the database page or by appending a ?_where= parameter to the table page like this . \n Access to this ability is controlled by the execute-sql permission. \n The easiest way to disable arbitrary SQL queries is using the default_allow_sql setting when you first start Datasette running. \n You can alternatively use an \"allow_sql\" block to control who is allowed to execute arbitrary SQL queries. \n To prevent any user from executing arbitrary SQL queries, use this: \n [[[cog\nconfig_example(cog, \"\"\"\n allow_sql: false\n\"\"\") \n ]]] \n [[[end]]] \n To enable just the root user to execute SQL for all databases in your instance, use the following: \n [[[cog\nconfig_example(cog, \"\"\"\n allow_sql:\n id: root\n\"\"\") \n ]]] \n [[[end]]] \n To limit this ability for just one specific database, use this: \n [[[cog\nconfig_example(cog, \"\"\"\n databases:\n mydatabase:\n allow_sql:\n id: root\n\"\"\") \n ]]] \n [[[end]]]", "breadcrumbs": "[\"Authentication and permissions\", \"Access permissions in \"]", "references": "[{\"href\": \"https://latest.datasette.io/fixtures\", \"label\": \"the database page\"}, {\"href\": \"https://latest.datasette.io/fixtures/facetable?_where=_city_id=1\", \"label\": \"like this\"}]"} {"id": "metadata:metadata-page-size", "page": "metadata", "ref": "metadata-page-size", "title": "Setting a custom page size", "content": "Datasette defaults to displaying 100 rows per page, for both tables and views. You can change this default page size on a per-table or per-view basis using the \"size\" key in metadata.json : \n [[[cog\nmetadata_example(cog, {\n \"databases\": {\n \"mydatabase\": {\n \"tables\": {\n \"example_table\": {\n \"size\": 10\n }\n }\n }\n }\n}) \n ]]] \n [[[end]]] \n This size can still be over-ridden by passing e.g. ?_size=50 in the query string.", "breadcrumbs": "[\"Metadata\"]", "references": "[]"} {"id": "plugins:plugins-datasette-load-plugins", "page": "plugins", "ref": "plugins-datasette-load-plugins", "title": "Controlling which plugins are loaded", "content": "Datasette defaults to loading every plugin that is installed in the same virtual environment as Datasette itself. \n You can set the DATASETTE_LOAD_PLUGINS environment variable to a comma-separated list of plugin names to load a controlled subset of plugins instead. \n For example, to load just the datasette-vega and datasette-cluster-map plugins, set DATASETTE_LOAD_PLUGINS to datasette-vega,datasette-cluster-map : \n export DATASETTE_LOAD_PLUGINS='datasette-vega,datasette-cluster-map'\ndatasette mydb.db \n Or: \n DATASETTE_LOAD_PLUGINS='datasette-vega,datasette-cluster-map' \\\n datasette mydb.db \n To disable the loading of all additional plugins, set DATASETTE_LOAD_PLUGINS to an empty string: \n export DATASETTE_LOAD_PLUGINS=''\ndatasette mydb.db \n A quick way to test this setting is to use it with the datasette plugins command: \n DATASETTE_LOAD_PLUGINS='datasette-vega' datasette plugins \n This should output the following: \n [\n {\n \"name\": \"datasette-vega\",\n \"static\": true,\n \"templates\": false,\n \"version\": \"0.6.2\",\n \"hooks\": [\n \"extra_css_urls\",\n \"extra_js_urls\"\n ]\n }\n]", "breadcrumbs": "[\"Plugins\"]", "references": "[]"} {"id": "changelog:id52", "page": "changelog", "ref": "id52", "title": "0.48 (2020-08-16)", "content": "Datasette documentation now lives at docs.datasette.io . \n \n \n db.is_mutable property is now documented and tested, see Database introspection . \n \n \n The extra_template_vars , extra_css_urls , extra_js_urls and extra_body_script plugin hooks now all accept the same arguments. See extra_template_vars(template, database, table, columns, view_name, request, datasette) for details. ( #939 ) \n \n \n Those hooks now accept a new columns argument detailing the table columns that will be rendered on that page. ( #938 ) \n \n \n Fixed bug where plugins calling db.execute_write_fn() could hang Datasette if the connection failed. ( #935 ) \n \n \n Fixed bug with the ?_nl=on output option and binary data. ( #914 )", "breadcrumbs": "[\"Changelog\"]", "references": "[{\"href\": \"https://docs.datasette.io/\", \"label\": \"docs.datasette.io\"}, {\"href\": \"https://github.com/simonw/datasette/issues/939\", \"label\": \"#939\"}, {\"href\": \"https://github.com/simonw/datasette/issues/938\", \"label\": \"#938\"}, {\"href\": \"https://github.com/simonw/datasette/issues/935\", \"label\": \"#935\"}, {\"href\": \"https://github.com/simonw/datasette/issues/914\", \"label\": \"#914\"}]"} {"id": "changelog:smaller-changes", "page": "changelog", "ref": "smaller-changes", "title": "Smaller changes", "content": "Datasette documentation now shows YAML examples for Metadata by default, with a tab interface for switching to JSON. ( #1153 ) \n \n \n register_output_renderer(datasette) plugins now have access to error and truncated arguments, allowing them to display error messages and take into account truncated results. ( #2130 ) \n \n \n render_cell() plugin hook now also supports an optional request argument. ( #2007 ) \n \n \n New Justfile to support development workflows for Datasette using Just . \n \n \n datasette.render_template() can now accepts a datasette.views.Context subclass as an alternative to a dictionary. ( #2127 ) \n \n \n datasette install -e path option for editable installations, useful while developing plugins. ( #2106 ) \n \n \n When started with the --cors option Datasette now serves an Access-Control-Max-Age: 3600 header, ensuring CORS OPTIONS requests are repeated no more than once an hour. ( #2079 ) \n \n \n Fixed a bug where the _internal database could display None instead of null for in-memory databases. ( #1970 )", "breadcrumbs": "[\"Changelog\", \"1.0a3 (2023-08-09)\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/issues/1153\", \"label\": \"#1153\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2130\", \"label\": \"#2130\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2007\", \"label\": \"#2007\"}, {\"href\": \"https://github.com/casey/just\", \"label\": \"Just\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2127\", \"label\": \"#2127\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2106\", \"label\": \"#2106\"}, {\"href\": \"https://github.com/simonw/datasette/issues/2079\", \"label\": \"#2079\"}, {\"href\": \"https://github.com/simonw/datasette/issues/1970\", \"label\": \"#1970\"}]"}