From 2d9c64ef7742c6c3231a4353db8dec1f5bdb27ec Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 3 Dec 2024 08:20:56 -0500 Subject: [PATCH] Docs: overhaul user docs --- docs/docs/administration/backup-restore.md | 3 + .../configuration.md} | 4 +- .../install-from-scratch.md} | 9 +- .../install-via-docker-compose.md} | 5 +- docs/docs/administration/upgrade/0.1.4.md | 207 ----------------- docs/docs/administration/upgrade/0.1.5.md | 17 -- docs/docs/administration/upgrade/0.1.6.md | 86 ------- docs/docs/administration/upgrade/0.1.7.md | 86 ------- docs/docs/administration/upgrade/older.md | 16 -- docs/docs/api/index.md | 84 +++++++ docs/docs/api/{rpc.md => methods.md} | 82 +------ docs/docs/api/rest.md | 8 - docs/docs/index.md | 35 +-- docs/docs/releases/0.1.4.md | 213 +++++++++++++++++- docs/docs/releases/0.1.5.md | 23 +- docs/docs/releases/0.1.6.md | 93 +++++++- docs/docs/releases/0.1.7.md | 93 +++++++- .../releases/{0.2.0-testing.1.md => 0.2.0.md} | 23 +- docs/docs/snippets/metadata-access-control.md | 1 + docs/docs/stylesheets/extra.css | 4 + docs/docs/user-guide/access-control.md | 16 ++ docs/docs/user-guide/collaborators.md | 41 ++++ docs/docs/user-guide/data-explorer.md | 23 ++ docs/docs/user-guide/data-types.md | 133 +++++++++++ docs/docs/user-guide/databases.md | 101 ++++++++- docs/docs/user-guide/exporting-data.md | 5 + docs/docs/user-guide/glossary.md | 19 -- docs/docs/user-guide/importing-data.md | 7 +- docs/docs/user-guide/index.md | 24 +- docs/docs/user-guide/metadata.md | 25 ++ docs/docs/user-guide/permissions.md | 123 ---------- docs/docs/user-guide/relationships.md | 190 ++++++++++++++++ docs/docs/user-guide/roles.md | 64 ++++++ docs/docs/user-guide/schemas.md | 52 +++++ docs/docs/user-guide/stored-role-passwords.md | 21 ++ docs/docs/user-guide/tables.md | 36 +++ docs/docs/user-guide/users.md | 39 +--- docs/mkdocs.yml | 82 ++++--- docs/requirements.txt | 1 + 39 files changed, 1306 insertions(+), 788 deletions(-) create mode 100644 docs/docs/administration/backup-restore.md rename docs/docs/{configuration/env-variables.md => administration/configuration.md} (95%) rename docs/docs/{installation/build-from-source/index.md => administration/install-from-scratch.md} (94%) rename docs/docs/{installation/docker-compose/index.md => administration/install-via-docker-compose.md} (89%) delete mode 100644 docs/docs/administration/upgrade/0.1.4.md delete mode 100644 docs/docs/administration/upgrade/0.1.5.md delete mode 100644 docs/docs/administration/upgrade/0.1.6.md delete mode 100644 docs/docs/administration/upgrade/0.1.7.md delete mode 100644 docs/docs/administration/upgrade/older.md create mode 100644 docs/docs/api/index.md rename docs/docs/api/{rpc.md => methods.md} (66%) delete mode 100644 docs/docs/api/rest.md rename docs/docs/releases/{0.2.0-testing.1.md => 0.2.0.md} (96%) create mode 100644 docs/docs/snippets/metadata-access-control.md create mode 100644 docs/docs/user-guide/access-control.md create mode 100644 docs/docs/user-guide/collaborators.md create mode 100644 docs/docs/user-guide/data-explorer.md create mode 100644 docs/docs/user-guide/data-types.md create mode 100644 docs/docs/user-guide/exporting-data.md delete mode 100644 docs/docs/user-guide/glossary.md create mode 100644 docs/docs/user-guide/metadata.md delete mode 100644 docs/docs/user-guide/permissions.md create mode 100644 docs/docs/user-guide/relationships.md create mode 100644 docs/docs/user-guide/roles.md create mode 100644 docs/docs/user-guide/schemas.md create mode 100644 docs/docs/user-guide/stored-role-passwords.md create mode 100644 docs/docs/user-guide/tables.md diff --git a/docs/docs/administration/backup-restore.md b/docs/docs/administration/backup-restore.md new file mode 100644 index 0000000000..0613ad8cbf --- /dev/null +++ b/docs/docs/administration/backup-restore.md @@ -0,0 +1,3 @@ +# Backup & Restore + + \ No newline at end of file diff --git a/docs/docs/configuration/env-variables.md b/docs/docs/administration/configuration.md similarity index 95% rename from docs/docs/configuration/env-variables.md rename to docs/docs/administration/configuration.md index 789c287a0f..1db3311f2a 100644 --- a/docs/docs/configuration/env-variables.md +++ b/docs/docs/administration/configuration.md @@ -1,4 +1,4 @@ -# Environment Variables +# Configuring Mathesar with environment variables This page contains all available environment variables supported by Mathesar. See the specific installation guides for the applicable environment variables and instructions on how to set them. @@ -51,7 +51,7 @@ This page contains all available environment variables supported by Mathesar. Se ## Caddy reverse proxy configuration {: #caddy} !!!note - These variables are only needed if you're using the Caddy configuration in our [default Docker Compose](../../installation/docker-compose/#steps) file. + These variables are only needed if you're using the Caddy configuration in our [default Docker Compose](install-via-docker-compose.md#steps) file. ### `DOMAIN_NAME` diff --git a/docs/docs/installation/build-from-source/index.md b/docs/docs/administration/install-from-scratch.md similarity index 94% rename from docs/docs/installation/build-from-source/index.md rename to docs/docs/administration/install-from-scratch.md index 49b43a651a..98a0e8f726 100644 --- a/docs/docs/installation/build-from-source/index.md +++ b/docs/docs/administration/install-from-scratch.md @@ -1,7 +1,4 @@ -# Install Mathesar from source on Linux - -!!! danger "Not a stable release" - This is a testing build released with the goal of gathering feedback from our community. It has **[many known issues](https://github.com/mathesar-foundation/mathesar/issues?q=is%3Aissue+milestone%3Av0.2.0-testing.2+)** and is not recommended for production use. +# Install Mathesar From Scratch on Linux !!! warning "For experienced Linux sysadmins" To follow this guide you need be experienced with Linux server administration, including the command line interface and some common utilities. @@ -176,7 +173,7 @@ Then press Enter to customize this guide with your domain name. touch .env ``` - 1. Edit your `.env` file, adding [environment variables](../../configuration/env-variables.md) to configure Mathesar. + 1. Edit your `.env` file, adding [environment variables](./configuration.md) to configure Mathesar. !!! example Your `.env` file should look something like this @@ -193,7 +190,7 @@ Then press Enter to customize this guide with your domain name. ``` !!! tip - To generate a [`SECRET_KEY`](../../configuration/env-variables.md#secret_key) you can use this [browser-based generator](https://djecrety.ir/) or run this command on MacOS or Linux: + To generate a [`SECRET_KEY`](./configuration.md#secret_key) you can use this [browser-based generator](https://djecrety.ir/) or run this command on MacOS or Linux: ``` echo $(cat /dev/urandom | LC_CTYPE=C tr -dc 'a-zA-Z0-9' | head -c 50) diff --git a/docs/docs/installation/docker-compose/index.md b/docs/docs/administration/install-via-docker-compose.md similarity index 89% rename from docs/docs/installation/docker-compose/index.md rename to docs/docs/administration/install-via-docker-compose.md index c94849f1d2..7a362e875b 100644 --- a/docs/docs/installation/docker-compose/index.md +++ b/docs/docs/administration/install-via-docker-compose.md @@ -1,8 +1,5 @@ # Install Mathesar via Docker Compose -!!! danger "Not a stable release" - This is a testing build released with the goal of gathering feedback from our community. It has **[many known issues](https://github.com/mathesar-foundation/mathesar/issues?q=is%3Aissue+milestone%3Av0.2.0-testing.2+)** and is not recommended for production use. - ## Prerequisites {% include 'snippets/docker-compose-prerequisites.md' %} @@ -119,4 +116,4 @@ If you'd like to use an external PostgreSQL server for Mathesar's internal datab psql -c 'create database mathesar_django;' ``` -1. Configure the [internal database environment variables](../../configuration/env-variables.md#db) to point to the database you just created. Ensure that you change the default values for the user, password, and host. +1. Configure the [internal database environment variables](./configuration.md#db) to point to the database you just created. Ensure that you change the default values for the user, password, and host. diff --git a/docs/docs/administration/upgrade/0.1.4.md b/docs/docs/administration/upgrade/0.1.4.md deleted file mode 100644 index 04866d4123..0000000000 --- a/docs/docs/administration/upgrade/0.1.4.md +++ /dev/null @@ -1,207 +0,0 @@ -# Upgrade Mathesar to 0.1.4 - -The 0.1.4 release requires more upgrade steps than we hope to have for future releases! If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or [contact us](https://mathesar.org/free-install.html) for help. - -## For installations using Docker Compose {:#docker-compose} - -If you followed our [Docker Compose installation instructions](../../installation/docker-compose/index.md), then use these steps to upgrade your installation to 0.1.4. - -!!! note - Depending on your setup, you may need to run some commands with `sudo`. - -1. Find needed parts - - 1. Find your `.env` and `docker-compose.yml` files. Run - - ``` - docker inspect mathesar_service - ``` - - and look for the value of the `"com.docker.compose.project.config_files"` key in the resulting JSON to find the path to the `docker-compose.yml` file. The `.env` file should be in the same directory. If you have `jq` installed, you can run - - ``` - docker inspect mathesar_service \ - | jq '.[0].Config.Labels."com.docker.compose.project.config_files"' - ``` - - and get the path directly. The `.env` file should be in the same directory. - - 1. Copy the path of the directory containing `docker-compose.yml` and `.env` into the box below. Do not include a trailing slash. - - - - Then press Enter to customize this guide with the configuration directory. - - 1. If you are using a Docker container for your PostgreSQL database, Run - - ``` - docker volume inspect mathesar_postgresql_data - ``` - - and look for the `"Mountpoint"` in the resulting JSON. - - 1. Copy the path of the directory into the box below. Do not include a trailing slash. - - - - Then press Enter to customize this guide with the PostgreSQL data directory. - -1. Stop Mathesar, remove old images - - ``` - docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down --rmi all - ``` - -1. Set up new configuration - - !!! warning - `MATHESAR_DATABASES` has been deprecated as of v0.1.4 and will be removed entirely in future releases of Mathesar. If you end up deleting the variable from your `.env` file before starting up Mathesar after the upgrade, you can still add the connections manually through Mathesar's UI. - - 1. Back up the old configuration files: - - ``` - mv xMATHESAR_INSTALLATION_DIRx/docker-compose.yml xMATHESAR_INSTALLATION_DIRx/docker-compose.yml.backup - cp xMATHESAR_INSTALLATION_DIRx/.env xMATHESAR_INSTALLATION_DIRx/env.backup - ``` - - (We'll modify the old file, so we copy instead of moving it.) - - 1. Download the new docker compose file: - - ``` - curl -sfL -o xMATHESAR_INSTALLATION_DIRx/docker-compose.yml https://raw.githubusercontent.com/mathesar-foundation/mathesar/0.1.4/docker-compose.yml - ``` - - 1. Edit the `xMATHESAR_INSTALLATION_DIRx/.env` file to break the `DJANGO_DATABASE_URL` variable into its parts. - - This variable should have the form: - - ``` - DJANGO_DATABASE_URL=postgres://:@:/ - ``` - - You should edit the `.env` file to have the variables: - - ``` - POSTGRES_USER= - POSTGRES_PASSWORD= - POSTGRES_HOST= - POSTGRES_PORT= - POSTGRES_DB= - ``` - - If you don't want to set those environment variables (e.g., if they're otherwise used), you can instead edit the `docker-compose.yml` file directly to add those variables. - - 1. Double-check the rest of the configuration: - - - You should have your [`SECRET_KEY` variable](../../configuration/env-variables.md#secret_key) defined. - - If hosting on the internet, you should have a `DOMAIN_NAME` variable defined. - -1. Initialize new Mathesar installation - - ``` - docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d - ``` - - This will pull new images, and start the Mathesar containers. Wait a few minutes, then run `docker ps` to verify that you have `mathesar_service`, `mathesar-caddy-reverse-proxy-1`, and `mathesar_db` running and that the service is healthy. The services should not be reporting errors. If you were _not_ using Docker volumes for your Mathesar PostgreSQL data, you're done, and you can login to Mathesar via your usual method. If you're not sure, try to login to Mathesar. If you're presented with a screen instructing you to create an Admin user, you likely need to proceed to the next step. - -1. Move your PostgreSQL directory - - 1. Bring down the services: - - ``` - docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down - ``` - - 1. Remove scaffold database data, copy your old PostgreSQL volume to the new location: - - ``` - rm -r xMATHESAR_INSTALLATION_DIRx/msar/pgdata - cp -r xMATHESAR_PG_DIRx xMATHESAR_INSTALLATION_DIRx/msar/pgdata - ``` - - 1. Bring the services back up: - - ``` - docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d - ``` - -1. If things look good, then you can try to login at the usual address using your normal username and password, and you should see your data. - -## For installations done via our guided script {:#guided} - -If you installed Mathesar with our (now deprecated) guided script, then you have a Docker Compose installation. See the [Docker Compose upgrade steps](#docker-compose). - - -## For installations done from scratch {:#scratch} - -If you installed Mathesar [from scratch](../../installation/build-from-source/index.md), then use these steps to upgrade your installation to 0.1.4. - -!!! warning - These steps have not yet been tested extensively. If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or submit a PR proposing changes to [this file](https://github.com/mathesar-foundation/mathesar/blob/master/docs/docs/administration/upgrade/0.1.4.md). - -1. Go to your Mathesar installation directory. - - ``` - cd xMATHESAR_INSTALLATION_DIRx - ``` - - !!! note - Your installation directory may be different from above if you used a different directory when installing Mathesar. - -1. Pull version 0.1.4 from the repository - - ``` - git pull https://github.com/mathesar-foundation/mathesar.git - git checkout 0.1.4 - ``` - -1. Update Python dependencies - - ``` - pip install -r requirements.txt - ``` - -1. Next we will activate our virtual environment: - - ``` - source ./mathesar-venv/bin/activate - ``` - -1. Update your environment variables according to the [the new configuration specification](../../configuration/env-variables.md#db). In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. - -1. Add the environment variables to the shell before running Django commands - - ``` - export $(sudo cat .env) - ``` - -1. Run the latest Django migrations - - ``` - python manage.py migrate - ``` - -1. Install the frontend dependencies - - ``` - npm ci --prefix mathesar_ui - ``` - -1. Build the Mathesar frontend app - - ``` - npm run --prefix mathesar_ui build --max_old_space_size=4096 - ``` - -1. Update Mathesar functions on the database: - - ``` - python mathesar/install.py --skip-confirm >> /tmp/install.py.log - ``` - -1. Restart the gunicorn server - - ``` - systemctl restart gunicorn - ``` diff --git a/docs/docs/administration/upgrade/0.1.5.md b/docs/docs/administration/upgrade/0.1.5.md deleted file mode 100644 index 3ac28d2760..0000000000 --- a/docs/docs/administration/upgrade/0.1.5.md +++ /dev/null @@ -1,17 +0,0 @@ -# Upgrade Mathesar to 0.1.5 - -## For installations using Docker Compose - -If you have a Docker compose installation (including one from the guided script), run the command below: - -``` -docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d -``` - -!!! warning "Your installation directory may be different" - You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. - - -## For installations done from scratch - -If you installed from scratch, the upgrade instructions are the same as [for 0.1.4](./0.1.4.md#scratch), except that you'll need to specify version 0.1.5 when pulling code from the repository in Step 2. You should also skip Step 5 – you do not need to change the environment variables. diff --git a/docs/docs/administration/upgrade/0.1.6.md b/docs/docs/administration/upgrade/0.1.6.md deleted file mode 100644 index a10e1bbd3e..0000000000 --- a/docs/docs/administration/upgrade/0.1.6.md +++ /dev/null @@ -1,86 +0,0 @@ -# Upgrade Mathesar to 0.1.6 - -## For installations using Docker Compose - -If you have a Docker compose installation (including one from the guided script), run the command below: - -``` -docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d -``` - -!!! warning "Your installation directory may be different" - You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. - - -## For installations done from scratch - -If you installed Mathesar [from scratch](../../installation/build-from-source/index.md), then use these steps to upgrade your installation to 0.1.6. - -1. Go to your Mathesar installation directory - - ``` - cd xMATHESAR_INSTALLATION_DIRx - ``` - - !!! note - Your installation directory may be different from above if you used a different directory when installing Mathesar. - -1. Pull version 0.1.6 from the repository - - ``` - git pull https://github.com/mathesar-foundation/mathesar.git - git checkout 0.1.6 - ``` - -1. Update Python dependencies - - ``` - pip install -r requirements-prod.txt - ``` - -1. Activate our virtual environment - - ``` - source ./mathesar-venv/bin/activate - ``` - -1. You can skip the following if you're upgrading from versions 0.1.4 and above. - - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../../configuration/env-variables.md#db). - - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. - -1. Add the environment variables to the shell before running Django commands - - ``` - export $(sudo cat .env) - ``` - -1. Run Django migrations - - ``` - python manage.py migrate - ``` - -1. Download and extract frontend assets - - ``` - wget https://github.com/mathesar-foundation/mathesar/releases/download/0.1.6/static_files.zip - unzip static_files.zip && mv static_files mathesar/static/mathesar && rm static_files.zip - ``` - -1. Compile Mathesar translation files - - ``` - python manage.py compilemessages - ``` - -1. Update Mathesar functions on the database: - - ``` - python -m mathesar.install --skip-confirm | tee /tmp/install.py.log - ``` - -1. Restart the gunicorn server - - ``` - systemctl restart gunicorn - ``` diff --git a/docs/docs/administration/upgrade/0.1.7.md b/docs/docs/administration/upgrade/0.1.7.md deleted file mode 100644 index e90e5e7a7e..0000000000 --- a/docs/docs/administration/upgrade/0.1.7.md +++ /dev/null @@ -1,86 +0,0 @@ -# Upgrade Mathesar to 0.1.7 - -## For installations using Docker Compose - -If you have a Docker compose installation (including one from the guided script), run the command below: - -``` -docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d -``` - -!!! warning "Your installation directory may be different" - You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. - - -## For installations done from scratch - -If you installed Mathesar [from scratch](../../installation/build-from-source/index.md), then use these steps to upgrade your installation to 0.1.7. - -1. Go to your Mathesar installation directory - - ``` - cd xMATHESAR_INSTALLATION_DIRx - ``` - - !!! note - Your installation directory may be different from above if you used a different directory when installing Mathesar. - -1. Pull version 0.1.7 from the repository - - ``` - git pull https://github.com/mathesar-foundation/mathesar.git - git checkout 0.1.7 - ``` - -1. Update Python dependencies - - ``` - pip install -r requirements-prod.txt - ``` - -1. Activate our virtual environment - - ``` - source ./mathesar-venv/bin/activate - ``` - -1. You can skip the following if you're upgrading from versions 0.1.4 and above. - - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../../configuration/env-variables.md#db). - - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. - -1. Add the environment variables to the shell before running Django commands - - ``` - export $(sudo cat .env) - ``` - -1. Run Django migrations - - ``` - python manage.py migrate - ``` - -1. Download and extract frontend assets - - ``` - wget https://github.com/mathesar-foundation/mathesar/releases/download/0.1.7/static_files.zip - unzip static_files.zip && mv static_files mathesar/static/mathesar && rm static_files.zip - ``` - -1. Compile Mathesar translation files - - ``` - python manage.py compilemessages - ``` - -1. Update Mathesar functions on the database: - - ``` - python -m mathesar.install --skip-confirm | tee /tmp/install.py.log - ``` - -1. Restart the gunicorn server - - ``` - systemctl restart gunicorn - ``` diff --git a/docs/docs/administration/upgrade/older.md b/docs/docs/administration/upgrade/older.md deleted file mode 100644 index 797e22c323..0000000000 --- a/docs/docs/administration/upgrade/older.md +++ /dev/null @@ -1,16 +0,0 @@ -# Upgrading Mathesar to older versions - -## For installations using Docker Compose {:#docker-compose} - -If you have a Docker compose installation (including one from the guided script), run the command below: - -``` -docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d -``` - -!!! note "Your installation directory may be different" - You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. - -## For installations done from scratch {:#scratch} - -If you installed from scratch, the upgrade instructions are the same as [for 0.1.4](../upgrade/0.1.4.md#scratch), but you do not need to change the environment variables. diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md new file mode 100644 index 0000000000..e92600f446 --- /dev/null +++ b/docs/docs/api/index.md @@ -0,0 +1,84 @@ +# Mathesar's API + +Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](https://www.jsonrpc.org/specification) spec version 2.0. It has been built primarily for consumption by the Mathesar front end but theoretically could be used to build automation workflows and Mathesar integrations. + +## Caveats + +- The Mathesar API is **not yet stable**. If you build logic that depends on it, be mindful that future Mathesar versions will likely bring breaking changes to the API without warning or notice. + +- This API _documentation_ is nascent and somewhat rough. We encourage you to report any docs inaccuracies via GitHub [issues](https://github.com/mathesar-foundation/mathesar/issues). + +- A small subset of functionality in Mathesar still relies on a legacy REST API which is gradually being phased out. It is not documented here. + +## Usage + +### Requests + +To use an RPC function: + +- Call it with a dot path starting from its root path. +- Always use named parameters. +- Ensure that your request includes HTTP headers for valid session IDs, as well as CSRF cookies and tokens. + +!!! example + + To call function `tables.list` from the Tables section of this page, you'd send something like: + + `POST /api/rpc/v0/`b + + ```json + { + "jsonrpc": "2.0", + "id": 234, + "method": "tables.list", + "params": { + "schema_oid": 47324, + "database_id": 1 + } + } + ``` + +### Success Responses + +Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form: + +```json +{ + "jsonrpc": "2.0", + "id": 234, + "result": +} +``` + +The `result` is whatever was returned by the underlying function. + +### Error Responses + +When an error is produced by a call to the RPC endpoint, we produce an error of the following form: + +```json +{ + "jsonrpc": "2.0", + "id": 234, + "error": { + "code": , + "message": + } +} +``` + +The `code` is a negative integer. Some codes are produced according to the [JSON-RPC spec](https://www.jsonrpc.org/specification#error_object). + +Other error codes are grouped according to the library that produced the Exception: + +- `builtins`: -31xxx +- `psycopg` or `psycopg2`: -30xxx +- `django`: -29xxx +- `mathesar` (our code): -28xxx +- `db` (our code): -27xxx +- `sqlalchemy`: -26xxx +- other: -25xxx + +Unrecognized errors from a given library return a "round number" code, so an unknown `builtins` error gets the code -31000. + + diff --git a/docs/docs/api/rpc.md b/docs/docs/api/methods.md similarity index 66% rename from docs/docs/api/rpc.md rename to docs/docs/api/methods.md index 141d96cfeb..1bc6d43ce1 100644 --- a/docs/docs/api/rpc.md +++ b/docs/docs/api/methods.md @@ -1,84 +1,4 @@ -# RPC API - -Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](https://www.jsonrpc.org/specification) spec version 2.0. - -!!! danger "Not yet stable" - The RPC API is not yet stable and may change in the future. If you build logic that depends on this API, be mindful that it may change in the future without warning or notice. - -## Usage - -### Requests - -To use an RPC function: - -- Call it with a dot path starting from its root path. -- Always use named parameters. -- Ensure that your request includes HTTP headers for valid session IDs, as well as CSRF cookies and tokens. - -!!! example - - To call function `tables.list` from the Tables section of this page, you'd send something like: - - `POST /api/rpc/v0/`b - - ```json - { - "jsonrpc": "2.0", - "id": 234, - "method": "tables.list", - "params": { - "schema_oid": 47324, - "database_id": 1 - } - } - ``` - -### Responses - -#### Success - -Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form: - -```json -{ - "jsonrpc": "2.0", - "id": 234, - "result": -} -``` - -The `result` is whatever was returned by the underlying function. - -#### Errors - -When an error is produced by a call to the RPC endpoint, we produce an error of the following form: - -```json -{ - "jsonrpc": "2.0", - "id": 234, - "error": { - "code": , - "message": - } -} -``` - -The `code` is a negative integer. Some codes are produced according to the [JSON-RPC spec](https://www.jsonrpc.org/specification#error_object). - -Other error codes are grouped according to the library that produced the Exception: - -- `builtins`: -31xxx -- `psycopg` or `psycopg2`: -30xxx -- `django`: -29xxx -- `mathesar` (our code): -28xxx -- `db` (our code): -27xxx -- `sqlalchemy`: -26xxx -- other: -25xxx - -Unrecognized errors from a given library return a "round number" code, so an unknown `builtins` error gets the code -31000. - ---- +# API Methods ## Collaborators diff --git a/docs/docs/api/rest.md b/docs/docs/api/rest.md deleted file mode 100644 index 3adb0f6270..0000000000 --- a/docs/docs/api/rest.md +++ /dev/null @@ -1,8 +0,0 @@ -# REST API - -Mathesar has a REST API that the front end uses to interact with the backend. - -For Mathesar's beta release, we are actively transitioning to a new [RPC-style API](https://wiki.mathesar.org/projects/2024/architecture-transition/rpc/) and will soon be phasing out the REST API entirely. - -The REST API is not documented and is not intended to be used by third-party developers. - diff --git a/docs/docs/index.md b/docs/docs/index.md index 5f73bb176d..ccff8ed79b 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -1,28 +1,15 @@ # Mathesar Documentation -!!! question "Help us get our beta out sooner – send us feedback!" - You're looking at the documentation for our **✨ new test build ✨**, see [release notes here](releases/0.2.0-testing.1.md). - - For a timely and stable beta release, we need feedback from as many users as possible about how this new version of Mathesar is working for you. Let us know on [this GitHub discussion](https://github.com/mathesar-foundation/mathesar/discussions/3956) or drop us a line at . - -## Welcome! - -Mathesar is a self-hostable open source project that provides a spreadsheet-like interface to a PostgreSQL database. Our web-based interface helps you and your collaborators set up data models, edit data, and build custom reports — no technical skills needed. You can create a new PostgreSQL database while setting up Mathesar or use our UI to interact with an existing database (or do both). +Mathesar is a self-hostable open source web application that provides a spreadsheet-like interface to PostgreSQL databases. Our web-based interface helps you and your collaborators set up data models, edit data, and build custom reports — no technical skills needed. You can create a new PostgreSQL database while setting up Mathesar or use our UI to interact with an existing database (or do both). ## Try Mathesar -### Live demo - -See our [live demo site](https://demo.mathesar.org/) to try Mathesar without installing anything. - -### Try locally - This is a quick way to play with Mathesar locally, but is not appropriate for saving data that you care about or setting up a long-term installation. 1. With [Docker](https://docs.docker.com/get-docker/) installed, run: ``` - docker run -it --name mathesar -p 8000:8000 mathesar/mathesar-testing:latest + docker run -it --name mathesar -p 8000:8000 mathesar/mathesar-prod:latest ``` 1. Visit [http://localhost:8000/](http://localhost:8000/) to set up an admin user account and create a database connection. @@ -46,20 +33,12 @@ This is a quick way to play with Mathesar locally, but is not appropriate for sa You can self-host Mathesar by following one of the guides below: -- [Install using Docker compose](installation/docker-compose/index.md) — a production setup with separate reverse-proxy and database containers. -- [Install from scratch](installation/build-from-source/index.md) — an advanced setup that doesn't rely on Docker. - -!!! info "More installation methods coming soon" - We're working on supporting additional installation methods, and we'd appreciate feedback on which ones to prioritize. Please comment [on this issue](https://github.com/mathesar-foundation/mathesar/issues/2509) if you have thoughts. - -## Use Mathesar - -See our [Using Mathesar](user-guide/index.md) section for documentation on Mathesar's features. +- [Install using Docker compose](./administration/install-via-docker-compose.md) — a production setup with separate reverse-proxy and database containers. +- [Install from scratch](./administration/install-from-scratch.md) — an advanced setup that doesn't rely on Docker. -## Contribute to Mathesar -As an open source project, we actively encourage contribution! Get started by reading our [Contributor Guide](https://github.com/mathesar-foundation/mathesar/blob/develop/CONTRIBUTING.md). +## Help out -## Donate +- [Make a donation](https://mathesar.org/donate) - We're a non-profit organization and your donations help sustain our core team. +- [Help build Mathesar](https://github.com/mathesar-foundation/mathesar/blob/develop/CONTRIBUTING.md) - As an open source project, we actively encourage contribution! -We're a non-profit and your donations help sustain our core team. You can donate via [GitHub](https://github.com/sponsors/mathesar-foundation) or [Open Collective](https://opencollective.com/mathesar). diff --git a/docs/docs/releases/0.1.4.md b/docs/docs/releases/0.1.4.md index d2f2854eb9..19970da2f8 100644 --- a/docs/docs/releases/0.1.4.md +++ b/docs/docs/releases/0.1.4.md @@ -4,11 +4,9 @@ Mathesar 0.1.4 focuses on improving the installation and setup experience. -_This page provides a comprehensive list of all changes in the release._ - -## Upgrading to 0.1.4 +See the [upgrading](#upgrading) section below for instructions on how to upgrade to this version. -See our guide on [upgrading Mathesar to 0.1.4](../administration/upgrade/0.1.4.md). +_This page provides a comprehensive list of all changes in the release._ ## New Features @@ -143,3 +141,210 @@ The table sidebar features a new "Cell" tab to show the content of cells, simpli - We improved our process for generating release notes. _([#3427](https://github.com/mathesar-foundation/mathesar/pull/3427))_ - We resolved some merge conflicts after finalizing our previous release. _([#3190](https://github.com/mathesar-foundation/mathesar/pull/3190))_ +## Upgrading to 0.1.4 {:#upgrading} + +The 0.1.4 release requires more upgrade steps than we hope to have for future releases! If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or [contact us](https://mathesar.org/free-install.html) for help. + +### For installations using Docker Compose {:#docker-compose} + +If you followed our [Docker Compose installation instructions](../administration/install-via-docker-compose.md), then use these steps to upgrade your installation to 0.1.4. + +!!! note + Depending on your setup, you may need to run some commands with `sudo`. + +1. Find needed parts + + 1. Find your `.env` and `docker-compose.yml` files. Run + + ``` + docker inspect mathesar_service + ``` + + and look for the value of the `"com.docker.compose.project.config_files"` key in the resulting JSON to find the path to the `docker-compose.yml` file. The `.env` file should be in the same directory. If you have `jq` installed, you can run + + ``` + docker inspect mathesar_service \ + | jq '.[0].Config.Labels."com.docker.compose.project.config_files"' + ``` + + and get the path directly. The `.env` file should be in the same directory. + + 1. Copy the path of the directory containing `docker-compose.yml` and `.env` into the box below. Do not include a trailing slash. + + + + Then press Enter to customize this guide with the configuration directory. + + 1. If you are using a Docker container for your PostgreSQL database, Run + + ``` + docker volume inspect mathesar_postgresql_data + ``` + + and look for the `"Mountpoint"` in the resulting JSON. + + 1. Copy the path of the directory into the box below. Do not include a trailing slash. + + + + Then press Enter to customize this guide with the PostgreSQL data directory. + +1. Stop Mathesar, remove old images + + ``` + docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down --rmi all + ``` + +1. Set up new configuration + + !!! warning + `MATHESAR_DATABASES` has been deprecated as of v0.1.4 and will be removed entirely in future releases of Mathesar. If you end up deleting the variable from your `.env` file before starting up Mathesar after the upgrade, you can still add the connections manually through Mathesar's UI. + + 1. Back up the old configuration files: + + ``` + mv xMATHESAR_INSTALLATION_DIRx/docker-compose.yml xMATHESAR_INSTALLATION_DIRx/docker-compose.yml.backup + cp xMATHESAR_INSTALLATION_DIRx/.env xMATHESAR_INSTALLATION_DIRx/env.backup + ``` + + (We'll modify the old file, so we copy instead of moving it.) + + 1. Download the new docker compose file: + + ``` + curl -sfL -o xMATHESAR_INSTALLATION_DIRx/docker-compose.yml https://raw.githubusercontent.com/mathesar-foundation/mathesar/0.1.4/docker-compose.yml + ``` + + 1. Edit the `xMATHESAR_INSTALLATION_DIRx/.env` file to break the `DJANGO_DATABASE_URL` variable into its parts. + + This variable should have the form: + + ``` + DJANGO_DATABASE_URL=postgres://:@:/ + ``` + + You should edit the `.env` file to have the variables: + + ``` + POSTGRES_USER= + POSTGRES_PASSWORD= + POSTGRES_HOST= + POSTGRES_PORT= + POSTGRES_DB= + ``` + + If you don't want to set those environment variables (e.g., if they're otherwise used), you can instead edit the `docker-compose.yml` file directly to add those variables. + + 1. Double-check the rest of the configuration: + + - You should have your [`SECRET_KEY` variable](../administration/configuration.md#secret_key) defined. + - If hosting on the internet, you should have a `DOMAIN_NAME` variable defined. + +1. Initialize new Mathesar installation + + ``` + docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d + ``` + + This will pull new images, and start the Mathesar containers. Wait a few minutes, then run `docker ps` to verify that you have `mathesar_service`, `mathesar-caddy-reverse-proxy-1`, and `mathesar_db` running and that the service is healthy. The services should not be reporting errors. If you were _not_ using Docker volumes for your Mathesar PostgreSQL data, you're done, and you can login to Mathesar via your usual method. If you're not sure, try to login to Mathesar. If you're presented with a screen instructing you to create an Admin user, you likely need to proceed to the next step. + +1. Move your PostgreSQL directory + + 1. Bring down the services: + + ``` + docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml down + ``` + + 1. Remove scaffold database data, copy your old PostgreSQL volume to the new location: + + ``` + rm -r xMATHESAR_INSTALLATION_DIRx/msar/pgdata + cp -r xMATHESAR_PG_DIRx xMATHESAR_INSTALLATION_DIRx/msar/pgdata + ``` + + 1. Bring the services back up: + + ``` + docker compose -f xMATHESAR_INSTALLATION_DIRx/docker-compose.yml up -d + ``` + +1. If things look good, then you can try to login at the usual address using your normal username and password, and you should see your data. + +### For installations done via our guided script {:#guided} + +If you installed Mathesar with our (now deprecated) guided script, then you have a Docker Compose installation. See the [Docker Compose upgrade steps](#docker-compose). + + +### For installations done from scratch {:#scratch} + +If you installed Mathesar [from scratch](../administration/install-from-scratch.md), then use these steps to upgrade your installation to 0.1.4. + +!!! warning + These steps have not yet been tested extensively. If you run into any trouble, we encourage you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues/new/choose) or submit a PR proposing changes to [this file](https://github.com/mathesar-foundation/mathesar/blob/master/docs/docs/administration/upgrade/0.1.4.md). + +1. Go to your Mathesar installation directory. + + ``` + cd xMATHESAR_INSTALLATION_DIRx + ``` + + !!! note + Your installation directory may be different from above if you used a different directory when installing Mathesar. + +1. Pull version 0.1.4 from the repository + + ``` + git pull https://github.com/mathesar-foundation/mathesar.git + git checkout 0.1.4 + ``` + +1. Update Python dependencies + + ``` + pip install -r requirements.txt + ``` + +1. Next we will activate our virtual environment: + + ``` + source ./mathesar-venv/bin/activate + ``` + +1. Update your environment variables according to the [the new configuration specification](../administration/configuration.md#secret_key). In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. + +1. Add the environment variables to the shell before running Django commands + + ``` + export $(sudo cat .env) + ``` + +1. Run the latest Django migrations + + ``` + python manage.py migrate + ``` + +1. Install the frontend dependencies + + ``` + npm ci --prefix mathesar_ui + ``` + +1. Build the Mathesar frontend app + + ``` + npm run --prefix mathesar_ui build --max_old_space_size=4096 + ``` + +1. Update Mathesar functions on the database: + + ``` + python mathesar/install.py --skip-confirm >> /tmp/install.py.log + ``` + +1. Restart the gunicorn server + + ``` + systemctl restart gunicorn + ``` diff --git a/docs/docs/releases/0.1.5.md b/docs/docs/releases/0.1.5.md index 751a4d4e30..8f14ee01f6 100644 --- a/docs/docs/releases/0.1.5.md +++ b/docs/docs/releases/0.1.5.md @@ -4,11 +4,9 @@ Mathesar 0.1.5 is a small, bug fix release. -_This page provides a comprehensive list of all changes in the release._ - -## Upgrading to Mathesar 0.1.5 +See the [upgrading](#upgrading) section below for instructions on how to upgrade to this version. -See our guide on [upgrading Mathesar to 0.1.5](../administration/upgrade/0.1.5.md). +_This page provides a comprehensive list of all changes in the release._ ## Improvements @@ -35,3 +33,20 @@ See our guide on [upgrading Mathesar to 0.1.5](../administration/upgrade/0.1.5.m - Improve our release notes helper script _[#3435](https://github.com/mathesar-foundation/mathesar/pull/3435 "Merge pull request #3434 from mathesar-foundation/release_notes")_ - Post-release cleanup _[#3432](https://github.com/mathesar-foundation/mathesar/pull/3432 "Merge pull request #3429 from mathesar-foundation/0.1.4")_ +## Upgrading to Mathesar 0.1.5 {:#upgrading} + +### For installations using Docker Compose + +If you have a Docker compose installation (including one from the guided script), run the command below: + +``` +docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d +``` + +!!! warning "Your installation directory may be different" + You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. + + +### For installations done from scratch + +If you installed from scratch, the upgrade instructions are the same as [for 0.1.4](./0.1.4.md#upgrading), except that you'll need to specify version 0.1.5 when pulling code from the repository in Step 2. You should also skip Step 5 – you do not need to change the environment variables. diff --git a/docs/docs/releases/0.1.6.md b/docs/docs/releases/0.1.6.md index 6fb0c59674..5c70395326 100644 --- a/docs/docs/releases/0.1.6.md +++ b/docs/docs/releases/0.1.6.md @@ -4,11 +4,9 @@ Mathesar 0.1.6 introduces Japanese localization of the UI and adds better support for working with long text in individual record pages. Improvements for administrators include compatibility with Python 3.10 and 3.11, support for databases running PostgreSQL 16, and the removal of `npm` and `nodejs` as dependencies when installing from scratch. -_This page provides a comprehensive list of all changes in the release._ - -## Upgrading to 0.1.6 +See the [upgrading](#upgrading) section below for instructions on how to upgrade to this version. -See our guide on [upgrading Mathesar to 0.1.6](../administration/upgrade/0.1.6.md). +_This page provides a comprehensive list of all changes in the release._ ## Improvements @@ -74,3 +72,90 @@ _[#3489](https://github.com/mathesar-foundation/mathesar/pull/3489 "GH workflow - Bumped Django from 4.2.8 to 4.2.10 _[#3492](https://github.com/mathesar-foundation/mathesar/pull/3492 "Bump django from 4.2.8 to 4.2.10")_ - Removed NodeJS from Docker production image _[#3474](https://github.com/mathesar-foundation/mathesar/pull/3474 "Add multiple stages to Dockerfile, remove NodeJS & unnecessary source files from production image")_ - Post release cleanup _[#3463](https://github.com/mathesar-foundation/mathesar/pull/3463 "Merge pull request #3460 from mathesar-foundation/0.1.5")_ + +## Upgrading to Mathesar 0.1.6 {:#upgrading} + +### For installations using Docker Compose + +If you have a Docker compose installation (including one from the guided script), run the command below: + +``` +docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d +``` + +!!! warning "Your installation directory may be different" + You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. + + +### For installations done from scratch + +If you installed Mathesar [from scratch](../administration/install-from-scratch.md), then use these steps to upgrade your installation to 0.1.6. + +1. Go to your Mathesar installation directory + + ``` + cd xMATHESAR_INSTALLATION_DIRx + ``` + + !!! note + Your installation directory may be different from above if you used a different directory when installing Mathesar. + +1. Pull version 0.1.6 from the repository + + ``` + git pull https://github.com/mathesar-foundation/mathesar.git + git checkout 0.1.6 + ``` + +1. Update Python dependencies + + ``` + pip install -r requirements-prod.txt + ``` + +1. Activate our virtual environment + + ``` + source ./mathesar-venv/bin/activate + ``` + +1. You can skip the following if you're upgrading from versions 0.1.4 and above. + - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/configuration.md#db). + - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. + +1. Add the environment variables to the shell before running Django commands + + ``` + export $(sudo cat .env) + ``` + +1. Run Django migrations + + ``` + python manage.py migrate + ``` + +1. Download and extract frontend assets + + ``` + wget https://github.com/mathesar-foundation/mathesar/releases/download/0.1.6/static_files.zip + unzip static_files.zip && mv static_files mathesar/static/mathesar && rm static_files.zip + ``` + +1. Compile Mathesar translation files + + ``` + python manage.py compilemessages + ``` + +1. Update Mathesar functions on the database: + + ``` + python -m mathesar.install --skip-confirm | tee /tmp/install.py.log + ``` + +1. Restart the gunicorn server + + ``` + systemctl restart gunicorn + ``` diff --git a/docs/docs/releases/0.1.7.md b/docs/docs/releases/0.1.7.md index 60bc094069..4d75290116 100644 --- a/docs/docs/releases/0.1.7.md +++ b/docs/docs/releases/0.1.7.md @@ -4,11 +4,9 @@ Mathesar 0.1.7 introduces linked table navigation from the data cell context menu. This release also fixes the regeneration of exploration share URLs and removes the 'group' suffix in the Data Explorer column names. -_This page provides a comprehensive list of all changes in the release._ - -## Upgrading to 0.1.7 +See the [upgrading](#upgrading) section below for instructions on how to upgrade to this version. -See our guide on [upgrading Mathesar to 0.1.7](../administration/upgrade/0.1.7.md). +_This page provides a comprehensive list of all changes in the release._ ## Improvements @@ -46,3 +44,90 @@ _[#3357](https://github.com/mathesar-foundation/mathesar/pull/3357 "Removed the - Integrated Changes from Previous Release Preparation _[#3517](https://github.com/mathesar-foundation/mathesar/pull/3517 "Merge pull request #3494 from mathesar-foundation/0.1.6")_ - Added Demo Target in Dockerfile for Future Deployments _[#3523](https://github.com/mathesar-foundation/mathesar/pull/3523 "Add demo target to Dockerfile")_ - New RPC Endpoint Implementation for Superuser Functions _[#3524](https://github.com/mathesar-foundation/mathesar/pull/3524 "Modern rpc prototype")_ + +## Upgrading to Mathesar 0.1.7 {:#upgrading} + +### For installations using Docker Compose + +If you have a Docker compose installation (including one from the guided script), run the command below: + +``` +docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d +``` + +!!! warning "Your installation directory may be different" + You may need to change `/etc/mathesar/` in the command above if you chose to install Mathesar to a different directory. + + +### For installations done from scratch + +If you installed Mathesar [from scratch](../administration/install-from-scratch.md), then use these steps to upgrade your installation to 0.1.7. + +1. Go to your Mathesar installation directory + + ``` + cd xMATHESAR_INSTALLATION_DIRx + ``` + + !!! note + Your installation directory may be different from above if you used a different directory when installing Mathesar. + +1. Pull version 0.1.7 from the repository + + ``` + git pull https://github.com/mathesar-foundation/mathesar.git + git checkout 0.1.7 + ``` + +1. Update Python dependencies + + ``` + pip install -r requirements-prod.txt + ``` + +1. Activate our virtual environment + + ``` + source ./mathesar-venv/bin/activate + ``` + +1. You can skip the following if you're upgrading from versions 0.1.4 and above. + - If you're upgrading from versions <= 0.1.3, update your environment variables according to the [the new configuration specification](../administration/configuration.md#db). + - In particular, you must put the connection info for the internal DB into new `POSTGRES_*` variables. The `DJANGO_DATABASE_URL` variable is no longer supported. + +1. Add the environment variables to the shell before running Django commands + + ``` + export $(sudo cat .env) + ``` + +1. Run Django migrations + + ``` + python manage.py migrate + ``` + +1. Download and extract frontend assets + + ``` + wget https://github.com/mathesar-foundation/mathesar/releases/download/0.1.7/static_files.zip + unzip static_files.zip && mv static_files mathesar/static/mathesar && rm static_files.zip + ``` + +1. Compile Mathesar translation files + + ``` + python manage.py compilemessages + ``` + +1. Update Mathesar functions on the database: + + ``` + python -m mathesar.install --skip-confirm | tee /tmp/install.py.log + ``` + +1. Restart the gunicorn server + + ``` + systemctl restart gunicorn + ``` diff --git a/docs/docs/releases/0.2.0-testing.1.md b/docs/docs/releases/0.2.0.md similarity index 96% rename from docs/docs/releases/0.2.0-testing.1.md rename to docs/docs/releases/0.2.0.md index 28b2f4ae75..f7ccf966a1 100644 --- a/docs/docs/releases/0.2.0-testing.1.md +++ b/docs/docs/releases/0.2.0.md @@ -1,19 +1,16 @@ -# 🧪 Mathesar 0.2.0-testing.1 - -!!! danger "Not a stable release" - This is a testing build released with the goal of gathering feedback from our community. It has **[many known issues](https://github.com/mathesar-foundation/mathesar/issues?q=is%3Aissue+milestone%3Av0.2.0-testing.2+)** and is not recommended for production use. +# Mathesar 0.2.0 ## Summary -**Mathesar 0.2.0-testing.1** provides an early preview of improvements we plan to release in our beta version. We have a brand new access control system based entirely on PostgreSQL database permissions, and we've also made major improvements to the responsiveness of the Mathesar UI. We've also built out a new RPC API, and we're deprecating our REST API in favor of it. +We have a brand new access control system based entirely on PostgreSQL database permissions, and we've also made major improvements to the responsiveness of the Mathesar UI. We've also built out a new RPC API, and we're deprecating our REST API in favor of it. -_This page provides a comprehensive list of all changes in the release._ +**We do not support upgrading from previous versions to `0.2.0`.** You will need to install a fresh instance of Mathesar to use this version. -## Installing 0.2.0-testing.1 +_This page provides a comprehensive list of all changes in the release._ -You will need to create a new installation of Mathesar to use this version, which you can do via [Docker Compose](../installation/docker-compose/index.md) or [from source](../installation/build-from-source/index.md). +## Installing 0.2.0 -We do not support upgrading from previous versions to `0.2.0-testing.1`. +You will need to create a new installation of Mathesar to use this version, which you can do via [Docker Compose](../administration/install-via-docker-compose.md) or [from scratch](../administration/install-from-scratch.md). ## Improvements @@ -27,7 +24,7 @@ This gives Mathesar several new capabilities. Database administrators can set up This replaces our previous access control system (which was enforced at the API layer, and only supported permissions at the database and schema levels). It also eliminates the need for Mathesar to use a database superuser for day-to-day operations. -More detailed documentation can be found in our User Guide under [Permissions](../user-guide/permissions.md) and [Users](../user-guide/users.md). +More detailed documentation can be found in our User Guide under [Permissions](../user-guide/access-control.md) and [Users](../user-guide/users.md). ------ @@ -66,7 +63,7 @@ More detailed documentation can be found in our User Guide under [Permissions](. We've made major improvements to the responsiveness of the Mathesar UI. Loading data and data entry should be much more snappy, and importing data into Mathesar is around 50 times faster. We've also eliminated the need to manually sync database schema changes to Mathesar, any DDL changes will be reflected in the UI automatically. -To achieve these performance benefits, we needed to overhaul our backend architecture and API. We have built out a new RPC API and our frontend UI now primarily uses that API. The RPC API [has some documentation here](../api/rpc.md), but should not be considered stable yet. +To achieve these performance benefits, we needed to overhaul our backend architecture and API. We have built out a new RPC API and our frontend UI now primarily uses that API. The RPC API [has some documentation here](../api/index.md), but should not be considered stable yet. Most of our REST API endpoints are now deprecated and will be removed soon. The `/users/` and `/data-files/` endpoints remain in use. @@ -244,3 +241,7 @@ We also set up a workflow to reset the live demo regularly to mitigate reliabili - Updates to GH workflow for resetting demo _[#3579](https://github.com/mathesar-foundation/mathesar/pull/3579 "Updates to GH workflow for resetting demo")_ - Updates to GH workflow to reset demo _[#3580](https://github.com/mathesar-foundation/mathesar/pull/3580 "Updates to GH workflow to reset demo")_ - Remove the demo reset workflow _[#3581](https://github.com/mathesar-foundation/mathesar/pull/3581 "Remove the demo reset workflow")_ + +## Upgrading to 0.2.0 {:#upgrading} + +We do not support upgrading from previous versions to `0.2.0`. You will need to install a fresh instance of Mathesar to use this version. diff --git a/docs/docs/snippets/metadata-access-control.md b/docs/docs/snippets/metadata-access-control.md new file mode 100644 index 0000000000..091004d599 --- /dev/null +++ b/docs/docs/snippets/metadata-access-control.md @@ -0,0 +1 @@ +Mathesar [metadata](/user-guide/metadata/) and [data explorations](/user-guide/data-explorer/) are currently readable and writable by all collaborators on a database, regardless of their PostgreSQL role's permissions or their [user's admin status](/user-guide/users/#admin). If you need to restrict access to metadata or data explorations, we would be curious to hear about your use case and welcome you to [open an issue](https://github.com/mathesar-foundation/mathesar/issues) to discuss it. \ No newline at end of file diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css index ded3c27abd..a52438e2d4 100644 --- a/docs/docs/stylesheets/extra.css +++ b/docs/docs/stylesheets/extra.css @@ -108,6 +108,10 @@ width: max-content; } +.md-nav--primary > .md-nav__title { + display: none; +} + .md-typeset a { color: var(--md-link-color); text-decoration: underline; diff --git a/docs/docs/user-guide/access-control.md b/docs/docs/user-guide/access-control.md new file mode 100644 index 0000000000..3efce62c52 --- /dev/null +++ b/docs/docs/user-guide/access-control.md @@ -0,0 +1,16 @@ +# Overview of Access Control in Mathesar + +To manage access to data, Mathesar utilizes PostgreSQL's powerful role-based permissions system. Each user accesses a database through a specific PostgreSQL role, and the user's access is determined by the role's privileges within PostgreSQL. + +Here's how it works: + +1. **[Mathesar Users](./users.md):** Everyone using Mathesar gets their own personal user account and has control over their password and username. [Admin](./users.md#admin) users have some additional privileges, but only for high-level Mathesar-specific operations like connecting databases and managing other users. + +1. **[PostgreSQL roles](./roles.md):** Within PostgreSQL, privileges on data can be granted to different roles at a granular level. Mathesar respects these privileges and also exposes functionality for you to see and modify them. + +1. **[Stored Role Passwords](./stored-role-passwords.md):** Mathesar stores the passwords for any roles that you would like to use to authenticate with PostgreSQL. + +1. **[Collaborators](./collaborators.md):** For a user to access a given database, an [admin](./users.md#admin) must add the user as a collaborator on that database and assign the user to a specific PostgreSQL role. You can configure separate Mathesar users to share the same PostgreSQL role if you like. Or you can use dedicated PostgreSQL roles for different users. + +{% include 'snippets/metadata-access-control.md' %} + diff --git a/docs/docs/user-guide/collaborators.md b/docs/docs/user-guide/collaborators.md new file mode 100644 index 0000000000..df906745a3 --- /dev/null +++ b/docs/docs/user-guide/collaborators.md @@ -0,0 +1,41 @@ +# Collaborators + +For every [database](./databases.md) you connect in Mathesar, you can manage the access that your Mathesar [users](./users.md) have to that database by adding them as collaborators. Each collaborator is associated with a PostgreSQL [role](./roles.md) that determines their access to data. + +Only [Mathesar admin users](./users.md#admin) can manage collaborators. + +When you add a new database connection to Mathesar, your Mathesar user will automatically be added as a collaborator using the PostgreSQL role you specify at connection time. + +Note that with collaborators, a user's role is set _per-database_. This means that one Mathesar user can be configured to use different PostgreSQL roles for different databases on the same server. + +## Adding a collaborator + +!!! info "Prerequisites" + Before you can add a new collaborator: + + - Your [database](./databases.md) must be connected already. + - The [user](./users.md) must already exist in Mathesar. + - The [role](./roles.md) must already exist in PostgreSQL. (If needed, uou can use Mathesar to [add new role](./roles.md#managing) before creating a collaborator.) + - TODO + +1. Navigate to the page for your connected database. +1. Click on the **Database Settings** tab. +1. Click on **Collaborators** in the left-hand menu. +1. Click **Add Collaborator**. + +## Removing a collaborator + +Removing a collaborator revokes that user's access to the database _but_: + +- If the user is a Mathesar [admin](./users.md#admin), they'll be able to gain access again by adding their user back as a collaborator. +- The user will still remain in Mathesar, potentially with access to other Databases. +- The role (and its corresponding password) will still remain configured in Mathesar. +- The role will still remain on the PostgreSQL server. + +## Configuration patterns + +- You can configure separate Mathesar users to share the same PostgreSQL role if you like. This is a good option if you want those users to have the same permissions on the data. +- Or you can use separate PostgreSQL roles for different users. This is necessary any time you want different users to have different permissions on the data. +- You cannot configure one Mathesar user with two PostgreSQL role simultaneously — though you can save multiple PostgreSQL roles in Mathesar and manually switch between them if necessary. You won't even need to enter the role's password each time you switch, since it will be saved in Mathesar. + + diff --git a/docs/docs/user-guide/data-explorer.md b/docs/docs/user-guide/data-explorer.md new file mode 100644 index 0000000000..2022b963dc --- /dev/null +++ b/docs/docs/user-guide/data-explorer.md @@ -0,0 +1,23 @@ +# Mathesar's Data Explorer + +The Data Explorer provides rudimentary support for some basic reporting and analytics tasks. + +You can: + +- View the data across multiple tables +- Filter +- Sort +- Summarize data to see aggregate values + +After you've constructed an exploration, you can save it to easily run it later as well. + +## Exploration and access controls + +- The Data Explorer will now allow you to modify any data. It is a read-only reporting tool. + +- Your ability to view data in the Data Explorer is determined by the privileges of your PostgreSQL [role](./roles.md). + +- All [collaborators](./collaborators.md) can see (and modify) the same set of explorations. (This is the same way that access control works for [metadata](./metadata.md)). + +- Keep in mind that if a collaborator is using a different role, they may see different data through the Data Explorer due to their role's access controls. + diff --git a/docs/docs/user-guide/data-types.md b/docs/docs/user-guide/data-types.md new file mode 100644 index 0000000000..70f6e2ccf3 --- /dev/null +++ b/docs/docs/user-guide/data-types.md @@ -0,0 +1,133 @@ +# Data Types + +## PostgreSQL's Data Types + +PostgreSQL requires that every table column has a predefined data type. These types serve to keep your data clean by ensuring that (for example) arbitrary text doesn't somehow end up in a column designated for numbers. This type system is quite powerful, but it can be complex. See the [PostgreSQL docs](https://www.postgresql.org/docs/current/datatype.html). There are a _lot_ of different types to choose from, and you can even define your own custom types. + +## Mathesar's Data Types {:#ui-types} + +Mathesar seeks to tame some of PostgreSQL's type system complexity by grouping similar PostgreSQL data types into user-friendly categories. We call these categories "_Mathesar_ data types" — or simply "data types" within Mathesar itself. + +Every PostgreSQL data type maps to exactly one Mathesar data type; and one Mathesar data type can potentially map to multiple PostgreSQL data types. For example, Mathesar has one [Number](#number) data type which serves to simplify the _seven_ different PostgreSQL data types for numbers. + +When creating a new column within Mathesar, you'll need to specify a Mathesar data type. Then Mathesar will create the column in PostgreSQL using the default PostgreSQL data type for your selected Mathesar data type. You can also modify the PostgreSQL data type later if needed and customize its type options in some cases. + +The relatively concise set of Mathesar data types — along with their associated default PostgreSQL data types — provide a curated assortment of recommended types well-suited for most use cases. And your ability to customize the PostgreSQL data type for a Mathesar data type gives you the flexibility to handle more specialized cases as needed. + +Each Mathesar data type is described in more detail below. + +### Boolean + +- **PostgreSQL types** + - [`boolean`](https://www.postgresql.org/docs/current/datatype-boolean.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Display a dropdown instead of a checkbox + - Customize the text show within the two dropdown options + +### Date + +- **PostgreSQL types** + - [`date`](https://www.postgresql.org/docs/current/datatype-datetime.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the format of the displayed date + +### Date & Time + +- **PostgreSQL types** + - [`timestamp with time zone`](https://www.postgresql.org/docs/current/datatype-datetime.html) **(default)** + - [`timestamp without time zone`](https://www.postgresql.org/docs/current/datatype-datetime.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the format of the displayed date and time + +### Duration + +Used to store a length of time, for example "1 hour" or "3 days" + +- **PostgreSQL types** + - [`interval`](https://www.postgresql.org/docs/current/datatype-datetime.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the format of the displayed duration + +### Email + +Used to store valid email addresses + +- **PostgreSQL types** + - `mathesar_types.email` + + This is a custom PostgreSQL type implemented by Mathesar. It is a [domain](https://www.postgresql.org/docs/17/sql-createdomain.html) over `text` with additional logic to validate that the input is a valid email address. + +### Money + +- **PostgreSQL types** + + - `mathesar_types.money` **(default)** + + This is custom PostgreSQL type implemented by Mathesar as a [domain](https://www.postgresql.org/docs/17/sql-createdomain.html) over [`numeric`](https://www.postgresql.org/docs/17/datatype-numeric.html). + + ??? question "`mathesar_types.money` vs `numeric`" + Compared with `numeric`, the `mathesar_types.money` type only exists for: (A) compatibility with our custom casting functions that can import CSV data with currency symbols; and (B) indicate to the upper layers of the Mathesar application that this column is eligible for an additional "Currency Symbol" metadata field. + + You are welcome to store money values in Number columns, but you won't be able to display the values with a currency symbol. + + - [`money`](https://www.postgresql.org/docs/current/datatype-money.html) + + ??? question "`mathesar_types.money` vs `money`" + Although PostgreSQL _does_ natively have a `money` type, we've chosen to recommend our custom PostgreSQL type for money in order to give your more control over the fractional precision for money columns. The fractional precision of the native `money` type is controlled by the [`LC_MONETARY`](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LC-MONETARY) which is set at the database level and thus may not be granular enough or accessible enough for all Mathesar users to configure. + +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the number of decimal places displayed (e.g. 1.2 vs 1.20) + - Customize the digit grouping (e.g. 1,000 vs 1000) + - Customize the locale for number formatting (e.g. 1.000,00 vs 1,000.00) + - Customize the currency symbol character + - Customize the position of the currency symbol + +### Number + +- **PostgreSQL types** + - [`numeric`](https://www.postgresql.org/docs/17/datatype-numeric.html) **(default)** + - [`smallint`](https://www.postgresql.org/docs/17/datatype-numeric.html) + - [`integer`](https://www.postgresql.org/docs/17/datatype-numeric.html) + - [`bigint`](https://www.postgresql.org/docs/17/datatype-numeric.html) + - [`decimal`](https://www.postgresql.org/docs/17/datatype-numeric.html) + - [`real`](https://www.postgresql.org/docs/17/datatype-numeric.html) + - [`double precision`](https://www.postgresql.org/docs/17/datatype-numeric.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the number of decimal places displayed (e.g. 1.2 vs 1.20) + - Customize the digit grouping (e.g. 1,000 vs 1000) + - Customize the locale for number formatting (e.g. 1.000,00 vs 1,000.00) + +### Text + +- **PostgreSQL types** + - [`text`](https://www.postgresql.org/docs/17/datatype-character.html) **(default)** + - [`char`](https://www.postgresql.org/docs/17/datatype-character.html) + - [`varchar`](https://www.postgresql.org/docs/17/datatype-character.html) + +### Time + +- **PostgreSQL types** + - [`time with time zone`](https://www.postgresql.org/docs/17/datatype-datetime.html) **(default)** + - [`time without time zone`](https://www.postgresql.org/docs/17/datatype-datetime.html) +- **Formatting** options _(stored as [metadata](./metadata.md))_ + - Customize the format of the displayed time + +### URL + +- **PostgreSQL types** + - `mathesar_types.uri` + + This is a custom PostgreSQL type implemented by Mathesar. It is a [domain](https://www.postgresql.org/docs/17/sql-createdomain.html) over `text` with additional logic to validate that the input is a valid uri address. + +## Other PostgreSQL types + +Mathesar has rudimentary support for other PostgreSQL types such as: `array`, `bytea`, `point`, `line`, `lseg`, `box`, `path`, `path`, `polygon`, `circle`, `cidr`, `inet`, `macaddr`, `macaddr8`, `bit`, `bit varying`, `tsquery`, `tsvector`, `json`, `jsonb`, `xml`, `pg_lsn`, `pg_snapshot`, `txid_snapshot`, `int4range`, `int8range`, `numrange`, `tsrange`, `tstzrange`, `daterange`. + +In most cases Mathesar is able to _display_ data from such types, but the following limitations apply: + +- Columns of these types cannot be created from within Mathesar +- Data entry is not yet supported +- Formatting cannot be applied + +If you would like to request additional support for a type, please [open an issue](https://github.com/mathesar-foundation/mathesar/issues) requesting the feature. And if you find that an unsupported type is causing _other_ features to break, please note it as a bug. + diff --git a/docs/docs/user-guide/databases.md b/docs/docs/user-guide/databases.md index e55bba113d..adc094202f 100644 --- a/docs/docs/user-guide/databases.md +++ b/docs/docs/user-guide/databases.md @@ -1,14 +1,22 @@ # Databases -Each installation of Mathesar can connect to multiple PostgreSQL databases. Connecting your first database will likely be your first step in using Mathesar. +Each installation of Mathesar can connect to multiple PostgreSQL databases. Connecting or creating your first database will likely be your first step in using Mathesar. -## PostgreSQL servers +## What is a database -Every PostgreSQL database lives within a PostgreSQL server. +If you're using Mathesar as a spreadsheet alternative, you might be curious what makes a database different from a spreadsheet and why it matters. A database is a self-contained set of data stored within a rigid structure that maintains data integrity and allows for efficient data operations. There are many different kinds of databases, and Mathesar [works specifically with _PostgreSQL_](./index.md#postgres) databases, so that's what we'll focus on here. -- **External servers:** Mathesar can connect to any Internet-exposed PostgreSQL server to access the databases within it. We'll refer to these PostgreSQL servers as "external servers". +Within a database, you can have multiple [tables](./tables.md) — much like you might have multiple _sheets_ within a spreadsheet. And within each table in your database, you'll have rows and columns, similar to a spreadsheet. But while a spreadsheet gives you a blank canvas to freely enter any data into any cell you choose, a database is more structured. Rows and columns must be explicitly added before you can enter data, and each column must have a name and a [data type](./data-types.md). In a database, rows are sometimes called "records". -- The **Internal Server:** Most Mathesar installations have an internal PostgreSQL server which the Mathesar application controls and utilizes for storage of application-specific metadata. +The biggest superpower of databases (specifically _relational_ databases like PostgreSQL) is the ability for cells to reference records from another table. In PostgreSQL, this concept is called foreign key constraints, and Mathesar leverages it so you can model your data with [relationships](./relationships.md). If you've ever used `VLOOKUP` in a spreadsheet, you'll love using relationships in Mathesar! + +## Connecting a database {:#connection} + +Click the **Connect Database** button from the home page of your Mathesar application and follow the prompts. + +Once you've connected a database, you can navigate to Mathesar's page for it where you can browse the database's [schemas](./schemas.md) and configure various settings for it. + +Mathesar will remember the connection even after the application is shut down. Your Mathesar [user](./users.md) will be added as a [collaborator](./collaborators.md) on the database (along with the PostgreSQL [role](./roles.md) you entered). And the password you entered for that role will be stored in Mathesar's [internal database](#internal), encrypted using Mathesar's [SECRET_KEY](../administration/configuration.md#secret_key). ## Creating a new database @@ -20,11 +28,86 @@ If you're starting your database from scratch with Mathesar you can either: - Use another tool to create your database on an external server and then connect Mathesar to it. You can administer that external server yourself, or choose from a variety of hosted PostgreSQL solutions such as [Amazon RDS](https://aws.amazon.com/rds/postgresql/pricing/), [Google Cloud SQL](https://cloud.google.com/sql/postgresql), [Supabase](https://supabase.com/database), and others. -## Connecting a database +## Database Permissions {:#permissions} -Click the **Connect Database** button from the home page of your Mathesar application and follow the prompts. +- **Owner:** In PostgreSQL, every database has a role set as its [owner](./roles.md#ownership). + + Only the owner can: + + - Drop the database + - Manage database-level privileges + - Transfer ownership + +- **Granted Privileges:** Additionally, the following privileges on one database may be granted to specific roles in PostgreSQL: + - `CONNECT`- Allows the role to connect to the database. + - `CREATE`- Allows the role to create new schemas within the database. + - `TEMPORARY`- Allows the role to create temporary tables within the database. + +See the [PostgreSQL docs](https://www.postgresql.org/docs/17/ddl-priv.html) for more info. + +To manage the owner and granted privileges for a database, navigate to the database page in Mathesar and click on the **Database Permissions** button at the top right. + +!!! info "See also" + To manage the access that Mathesar _users_ have to a database, go to **Database Settings** > **Collaborators**. See [Access Control](./access-control.md) for more information. + +## Disconnecting a database + +1. From the Mathesar home page, click on your database to its database page. +1. At the top right, click on the dropdown menu, and select "Disconnect Database". + +Disconnecting a database will _not_ delete the database. It will still be accessible outside Mathesar, and you reconnect it in the future. + +However, disconnecting your database will delete the Mathesar-specific metadata associated with objects in the database. This includes saved explorations, customized column display options, and customized record summary templates. + +## Dropping a database + +If you want to entirely remove all the data in your database by dropping the database from the PostgreSQL server, you'll need to do so outside of Mathesar via PostgreSQL itself. + +We plan to add support for dropping databases in the future. If this is a feature you would like, please comment on this [issue](https://github.com/mathesar-foundation/mathesar/issues/3862) to let us know. + +## Mathesar's internal database {:#internal} + +Mathesar's philosophy is to keep as much of your data as possible inside your connected PostgreSQL database, structured consistently with the way it appears in the Mathesar interface. -Once you've connected a database, you can navigate to Mathesar's page for it where you can browse the database's schemas and configure various [permissions](./permissions.md) for it. +Separate from your connected PostgreSQL database, Mathesar also maintains an internal database to store configuration relevant to the Mathesar application itself. While Mathesar does not allow you to work directly with this internal database, you might be interested to understand the distinction between it and your connected database. Below is a comparison of the data stored in each: -Mathesar will remember the connection even after the application is shut down. Your Mathesar user will be added as a "collaborator" on the database (along with the PostgreSQL role you entered). And the password you entered for that role will be stored in Mathesar's internal database, encrypted using Mathesar's [SECRET_KEY](../configuration/env-variables.md#secret_key). + + + + + + + + + + + +
Data in your connected databaseData in Mathesar's internal database
+
    +
  • + The + schemas + and + tables + you see from within Mathesar +
    • +
  • The rows, columns, and cells within those tables
    • +
  • + Relationships + between those tables +
    • +
  • + Roles + and their privileges +
    • +
+ 		+ +
diff --git a/docs/docs/user-guide/exporting-data.md b/docs/docs/user-guide/exporting-data.md new file mode 100644 index 0000000000..2813e6f879 --- /dev/null +++ b/docs/docs/user-guide/exporting-data.md @@ -0,0 +1,5 @@ +# Exporting Data From Mathesar + +Mathesar does not currently support exporting data directly from the application. + +Exporting functionality is coming soon! diff --git a/docs/docs/user-guide/glossary.md b/docs/docs/user-guide/glossary.md deleted file mode 100644 index d88050bc98..0000000000 --- a/docs/docs/user-guide/glossary.md +++ /dev/null @@ -1,19 +0,0 @@ -# Glossary - -## Internal database {:#internal-db} - -The "internal database" holds Mathesar-specific _metadata_ about the actual data (which lives in the [user database](#user-db)). Examples of such metadata include: - -- Exploration definitions -- Column display formatting settings -- Record summary template customizations -- Custom column ordering - -Each Mathesar installation requires one and only one internal database, and PostgreSQL and SQLite are both supported. - -## User database {:#user-db} - -The data you see within Mathesar lives in the "user database", which must use PostgreSQL. Each Mathesar installation can connect to multiple user databases, potentially on different servers. - -Mathesar also uses an [internal database](#internal-db) to store metadata. - diff --git a/docs/docs/user-guide/importing-data.md b/docs/docs/user-guide/importing-data.md index 5384e57432..a74386ef59 100644 --- a/docs/docs/user-guide/importing-data.md +++ b/docs/docs/user-guide/importing-data.md @@ -1,6 +1,6 @@ # Importing data into Mathesar -Mathesar allows importing data in CSV and JSON format. It also attempts to automatically infer the data type of the columns. +Mathesar allows importing data in CSV format. It also attempts to automatically infer the data type of the columns. ## Importing CSV data {:#csv} @@ -22,6 +22,9 @@ By default, Mathesar will use the first row of CSV data to name the columns. If you un-check **"Use first row as header"**, then Mathesar will generate default names for the columns which you can edit later. + + diff --git a/docs/docs/user-guide/index.md b/docs/docs/user-guide/index.md index d82d5092a3..306e907a1e 100644 --- a/docs/docs/user-guide/index.md +++ b/docs/docs/user-guide/index.md @@ -1,8 +1,22 @@ -# Using Mathesar +# Mathesar User Guide -Welcome! At this point, we assume you've installed Mathesar successfully and have logged into the web UI. +## How Mathesar works -If you've connected Mathesar to an existing database, you should see all your schemas and tables once you log in, and you can work with them as you please. +Mathesar is a web application that gives you a spreadsheet-like interface to one or more PostgreSQL [databases](./databases.md). It lets technical and non-technical users collaborate directly with the same relational data, providing user-friendly access to your database's [schemas](./schemas.md), [tables](./tables.md), [relationships](./relationships.md), and so on — all comfortably within the limits of the PostgreSQL [privileges](./access-control.md) for the PostgreSQL role that you give to Mathesar. Your data appears in Mathesar exactly as it is structured in PostgreSQL, with some additional convenience features ease the process of working with related data while keeping it [normalized](./relationships.md#normalization). + +You can use Mathesar with PostgreSQL data sets you already have. Point it at your database, and you'll have a powerful GUI admin tool to help with data entry, analytics, and internal back-office processes. + +Or you can use Mathesar to build data sets and workflows from scratch, giving you a robust and highly scalable alternative to typical spreadsheet-based solutions. + +The Mathesar application has a small internal database where it stores the [users](./users.md) you create, the database [connection credentials](./databases.md#connection) you add, the [data explorations](./data-explorer.md) you save, and a small amount of [metadata](./metadata.md) which you may configure. But all your _actual_ data lives in your PostgreSQL database — outside Mathesar. The extensive interoperability afforded by PostgreSQL means you'll always have control over your data should you later choose to use incorporate other tools into your workflow or abandon Mathesar altogether. + +## About PostgreSQL {:#postgres} + +PostgreSQL (aka "Postgres") is an industry-leading relational database management system which has been actively maintained by a vibrant community of open source contributors since the mid 1990's. It has since emerged as the dominant and defacto relational database solution in the open source world and beyond. + +While the choice to support PostgreSQL in a product like Mathesar would be obvious, Mathesar has doubled down on our commitment to PostgreSQL by architecting the application to integrate very tightly with PostgreSQL. A large part of the Mathesar application logic actually runs _within the PostgreSQL database_ to which Mathesar connects. This architecture enables Mathesar's high performance and snappy UI by reducing the need for multiple network round trips between the Mathesar application and the PostgreSQL server. So Mathesar will be fast even when your PostgreSQL server is around the world from your Mathesar application server. + +A short-term consequence of this development strategy is that, for the time being, Mathesar _only_ works with PostgreSQL databases. However we are hopeful that in the future we'll have the opportunity to leverage PostgreSQL's powerful [Foreign Data Wrapper](https://www.postgresql.org/docs/current/postgres-fdw.html) functionality to connect to other kinds of databases such as MySQL, SQLite, Oracle, MongoDB, and more. + +Mathesar's tight integration with PostgreSQL also means that, in order to function, Mathesar needs to install a few [Mathesar-specific schemas](./schemas.md#internal) upon connecting to your PostgreSQL database. -!!! tip "More..." - 👈 Browse the "Using Mathesar" navigation section to find more detailed documentation pages. diff --git a/docs/docs/user-guide/metadata.md b/docs/docs/user-guide/metadata.md new file mode 100644 index 0000000000..d90b23c649 --- /dev/null +++ b/docs/docs/user-guide/metadata.md @@ -0,0 +1,25 @@ +# Mathesar Metadata + +Mathesar's philosophy is to keep as much of your data as possible inside your connected PostgreSQL database, structured consistently with the way it appears in the Mathesar interface. However, some of the customization that Mathesar offers doesn't fit neatly into the PostgreSQL model, so Mathesar stores a thin layer of metadata in its [internal database](./databases.md#internal) to support these features. + +## Table metadata + +For each table, the following optional configurations are stored as metadata: + +- **Column order** + + Interestingly, PostgreSQL does not allow existing columns to be rearranged. Mathesar allows you to customize the column order by dragging and dropping columns in the table view. This order is stored as metadata. When no metadata is present, the columns will be displayed in the order they are stored in PostgreSQL. + +- **Record summary template** + + The template used to generate [record summaries](./relationships.md#record-summaries). This allows links to records in the table to be summarized into short human-readable pieces of text. + + Without any metadata, the record summary will be generated using the first text-like column of the table if possible. + +## Column metadata + +Many of Mathesar's [data types](./data-types.md) have type-specific **formatting** options which are stored as metadata. These options allow you to customize the way the data is displayed in the Mathesar interface. + +## Metadata access control + +{% include 'snippets/metadata-access-control.md' %} diff --git a/docs/docs/user-guide/permissions.md b/docs/docs/user-guide/permissions.md deleted file mode 100644 index 2a096f96ff..0000000000 --- a/docs/docs/user-guide/permissions.md +++ /dev/null @@ -1,123 +0,0 @@ -# Mathesar's Role-Based Permissions - -Mathesar uses [PostgreSQL roles](https://www.postgresql.org/docs/current/user-manag.html) to manage permissions on your data. These roles define the actions users can perform, allowing fine-grained control over access. - -## Roles vs Users - -Each Mathesar user accesses a database through one PostgreSQL role — and the user's permissions are determined by the _role's_ permissions within PostgreSQL. - -You can read more about [how users and roles work together](./users.md#users-vs-roles). - -## The Database "Settings" tab {:#database_settings} - -Each database has its own page within Mathesar. And on that page you'll find a "Settings" tab where you can manage roles and collaborators. - -### _In Mathesar:_ Role Configuration {:#role_configuration} - -Use this section to manage the credentials (i.e. passwords) for roles that you'd like to assign to collaborators within Mathesar. Mathesar will display all [LOGIN roles](https://www.postgresql.org/docs/current/role-attributes.html#ROLE-ATTRIBUTES) that exist on the server. - -- Click **Configure in Mathesar** to store the role's password in Mathesar and allow the role to be associated with collaborators. - -- Click **Configure Password** to update the password of an already configured role. - -- Click **Remove** to remove Mathesar's stored password for a role. The role will remain on the server. - - -### _In Mathesar:_ Collaborators {:#collaborators} - -A "collaborator" is a Mathesar user who has access to a database through a specific PostgreSQL role. - -The Collaborators section allows you to add and remove collaborators and edit their corresponding PostgreSQL roles. - -!!! tip "Keep in mind" - - - You'll only be able to choose roles that have been "configured" in the above section — roles for which Mathesar has passwords stored. - - - Removing a collaborator revokes that user's access to the database _but_: - - - If the user is a Mathesar [admin](./users.md#admin-vs-standard-users), they'll be able to gain access again. - - The user will still remain in Mathesar, potentially with access to other Databases. - - The role (and it's corresponding password) will still remain configured in Mathesar. - - The role will still remain on the PostgreSQL server. - -### _On the Server:_ Roles {:#roles} - -Here you can manage roles available on the server, defining their inheritance, creating new roles, or deleting existing ones. Any changes here will be reflected for all connected databases which share this server. - -- **Create Roles**: You can create new server-level roles from this section. You can configure these roles in two ways: - 1. With login capability and a password, which you can assign to collaborators. - 2. Without login capability, to be used exclusively as a parent role to group permissions that can be inherited by other roles. You cannot assign these non-login roles to collaborators directly. -- **Define Child Roles**: PostgreSQL has a mechanism for [Role Membership](https://www.postgresql.org/docs/current/role-membership.html) wherein any role can be "granted" to any other role to form simple hierarchies or complex graph-based inheritance structures. For any role you've configured within Mathesar, you can use Mathesar to grant the role to other "child roles". -- **Drop Roles**: You can drop server-level roles that are no longer needed. This action removes the role from the server, however if the role is configured in Mathesar, it will still be displayed. Exercise caution when dropping roles, as it may affect collaborators using the dropped role in Mathesar. - -!!! note - Server roles, once added, must be configured in Mathesar under the **Role Configuration** section before they can be assigned to collaborators. - ---- - -## PostgreSQL objects {:#objects} - -In PostgreSQL, an "object" is a thing like: a database, a schema, a table, _(and some other things too, which we won't cover here)_. - -### Privileges and ownership - -- **Privileges:** Specific privileges on an object can be granted to specific roles. - - !!! example - A role can be granted the `CREATE` privilege on a schema. This allows the role to create new tables within the schema. - -- **Ownership**: Every PostgreSQL object has one and only one role said to be its "owner". The owner generally can do anything directly to the object, but not necessarily other objects contained within it. By default the owner is set to the role which created the object. - -- **Shared ownership:** While PostgreSQL has a variety of granular privileges for different actions, there are still certain actions which remain restricted to object owners. For example only the owner of a table can add new columns to it. - - While this behavior may seem limiting, it's still possible configure multiple roles to effectively "own" a single object by leveraging PostgreSQL's powerful role inheritance functionality: - - 1. We can create a third role to directly own the object and act as a sort of proxy "group". (The group role doesn't need to be a `LOGIN` role and thus doesn't require a password to be configured.) - 1. Then we can grant _that group role_ to any other roles we'd like. - 1. Those child roles will then have permission do things _as if they were the owner themselves_. - - You can use the Mathesar UI to configure an arrangement like the above, though it will require many steps. - -### Database Permissions - -The "Database Permissions" modal is accessible via a button at the top right of the database page and allows you to configure the owner and granted privileges for a database. - -- **Owner**: Each database has an owner who has administrative control over the database itself, including managing database-level permissions and transferring ownership. Ownership does not automatically extend to the objects within the database (such as schemas and tables), which may have their own separate ownership and permission settings. -- **Granted Access**: Specific permissions can be granted to roles for various actions within the database. -- **Transfer Ownership**: The current owner can transfer ownership to another role, granting them administrative control. - -For each database, the following permission levels can be granted: - -- **Connect**: Allows the role to access and connect to the database. -- **Create**: Includes Connect permissions and allows the role to create new schemas within the database. -- **Custom**: Enables the granular setting of permissions beyond the predefined options. - -### Schema Permissions - -The "Schema Permissions" modal is accessible via a button at the top right of the schema page and allows you to configure the owner and granted privileges for a schema. - -- **Owner**: Each schema has an owner who has administrative control over the schema itself, including managing schema-level permissions and transferring ownership. Ownership does not automatically extend to the objects within the schema (such as tables), which may have their own separate ownership and permission settings. -- **Granted Access**: Specific permissions can be granted to roles for various actions within the schema. -- **Transfer Ownership**: The current owner can transfer ownership to another role, granting them administrative control over the schema. - -For each schema, the following permission levels can be granted: - -- **Read**: Allows the role to access the schema and view its objects. -- **Create**: Includes Read permissions and allows the role to create new tables within the schema. -- **Custom**: Enables the granular setting of permissions beyond the predefined options. - -### Table Permissions - -The Table Permissions modal is accessible via a button from within the right-side inspector panel for each table and allows you to configure the owner and granted privileges for a table. - -- **Owner**: Each table has an owner who has administrative control over the table itself, including managing table-level permissions, transferring ownership, and modifying the table's structure (such as adding, removing, or altering columns). -- **Granted Access**: Specific permissions can be granted to roles for various actions on the table. -- **Transfer Ownership**: The current owner can transfer ownership to another role, granting them administrative control over the table. - -For each table, the following permission levels can be granted: - -- **Read**: Allows the role to access the table and read records. -- **Write**: Includes Read permissions and allows the role to insert, update, and delete records in the table. -- **Custom**: Enables the granular setting of permissions beyond the predefined options. - -You can read more about the specific privileges that can be granted in the [PostgreSQL documentation on Privileges](https://www.postgresql.org/docs/current/ddl-priv.html). diff --git a/docs/docs/user-guide/relationships.md b/docs/docs/user-guide/relationships.md new file mode 100644 index 0000000000..3863cf0c1c --- /dev/null +++ b/docs/docs/user-guide/relationships.md @@ -0,0 +1,190 @@ +# Relationships + +Relationships allow a single cell in one table to reference a row in another table. When one table references another in this manner, the two tables are said to be "related". This is a core feature of relational databases, and it allows us to model complex data structures using multiple tables. + +## Example + +Let's say we are maintaining an address book of people and their contact info... + +???+ failure "Without Relationships" + + Associating multiple email addresses with one person is tricky! We might try the following approaches: + + - Option 1: Email addresses combined into a single column: + + | name | emails | + | - | - | + | Alice Roberts | alice@example.com, aroberts@example.net | + | Bob Davis | bob@example.com | + + - Option 2: Email addresses spread across multiple columns + + | name | email_1 | email_2 | + | - | - | - | + | Alice Roberts | alice@example.com | aroberts@example.net | + | Bob Davis | bob@example.com | | + + - Option 3: People spread across multiple rows + + | name | email | + | - | - | + | Alice Roberts | alice@example.com | + | Alice Roberts | aroberts@example.net | + | Bob Davis | bob@example.com | + + None of these options are ideal. They make it difficult to query the data, and they make it easy to introduce errors. + +???+ success "With Relationships" + + We can create _two_ tables: + + The `people` table: + + | id | name | + | - | - | + | 1 | Alice Roberts | + | 2 | Bob Davis | + + The `emails` table: + + | id | email | person | + | - | - | - | + | 1 | alice@example.com | 1 | + | 2 | aroberts@example.net | 1 | + | 3 | bob@example.com | 2 | + + And we configure the `person` column to **reference** the `id` column in the `people` table, ensuring that all the references are valid. The database handles this validation for us, and even prevents us from deleting a person without deleting their associated email addresses too. + +## Normalization + +This practice of modeling data through multiple related tables is called **data normalization**, and it's why a database will typically have its data spread across many tables, each with their own unique column structure, and very few tables providing much use or value in isolation. In the example above, the approaches without relationships are not normalized, while the approach with relationships is normalized. + +Normalized data structures are more efficient to query and update, and they help to ensure data integrity by reducing redundancy and minimizing the risk of inconsistencies. But they can also be more cumbersome to work with manually due to the indirection inherent in having data spread across multiple tables. Mathesar helps you manage this complexity by providing a user-friendly interface to work with normalized data. + +## Foreign key constraints in PostgreSQL + +In PostgreSQL, references are called "[foreign key constraints](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-FK)", or simply "foreign keys". These constraints are set on the table to ensure that the data in the referencing column always points to a valid row in the referenced table. + +## Reference columns in Mathesar + +Mathesar identifies reference columns in your database by looking for foreign key constraints set in PostgreSQL. And when you create a reference column in Mathesar, it will automatically create the necessary foreign key constraint in PostgreSQL. + +As noted below, reference columns get some extra features too! + +### Record summaries {:#record-summaries} + +Without Mathesar, reference cells are typically rather opaque. Often they contain only an id number, which is not very helpful when you're trying to understand the data. + +Mathesar helps solve this problem by providing a feature called "record summaries" which allows you to see a short text summary of the referenced record directly in the referencing cell. By default, the record summary will be the value of the first text-like column in the referenced table. You can customize the record summary to show any columns and text you choose. + +To customize a record summary, you can either: + +- Start from the referenced table, and: + + 1. Go to the table page of the referenced table. + 1. In the table inspector on the right, click on the "Table" tab. + 1. Find the "Record Summary" section below. + + *or* + +- Start from a reference column, and: + + 1. Go to the table page containing the reference column. + 1. Select the reference column or a cell within it. + 1. In the table inspector on the right, click on the "Column" tab. + 1. Find the "Linked Record Summary" section below. + +### Record selector + +Reference columns also provide a "record selector" tool which helps you search through referenced records when modifying reference values. It allows you to search on all columns from the referenced table and will use fuzzy logic to find the most relevant records. You can even create new records directly from the record selector. + +### Limitations of Mathesar's reference columns + +- Mathesar does not support supports "composite" foreign keys — foreign keys that reference _multiple_ columns in the referenced table at once. + +- Some PostgreSQL databases might contain normalized data which is implicitly structured to utilize the concept of references but which lacks the foreign key constraints necessary to ensure data integrity. Mathesar will not treat such columns as references. It only recognizes foreign key columns as references. + +## Relationship types and patterns + +### One-to-many relationships + +To illustrate a one-to-many relationship we'll re-use our example above. + +- We'll have a `people` table as follows: + + | id | name | + | - | - | + | 1 | Alice Roberts | + | 2 | Bob Davis | + +- And an `emails` table as follows: + + | id | email | person | + | - | - | - | + | 1 | alice@example.com | `Alice Roberts` | + | 2 | aroberts@example.net | `Alice Roberts` | + | 3 | bob@example.com | `Bob Davis` | + + !!! note + Here the reference column, `person`, displays with formatting to mimic Mathesar's record summaries feature. + +Now **one** person can have **many** email addresses, hence the name "one-to-many". + +### Many-to-one relationships + +A many-to-one relationships is structurally equivalent to a one-to-many relationships, but with the perspective reversed. The two terms are often used interchangeably. + +### Many-to-many relationships + +Continuing our address book example, let's pretend we'd like to apply tags to our contacts. For example, we'd like to: + +- Tag Alice Roberts as "colleague" +- Tag Bob Davis as "friend" and "colleague" + +We can use three tables to model this relationship: + +- A `people` table (as before): + + | id | name | + | - | - | + | 1 | Alice Roberts | + | 2 | Bob Davis | + +- A new `tags` table: + + | id | tag | + | - | - | + | 1 | colleague | + | 2 | friend | + +- And a new `people_tags` table (sometimes referred to as a "join table" or "mapping table"): + + | id | person | tag | + | - | - | - | + | 1 | `Alice Roberts` | `colleague` | + | 2 | `Bob Davis` | `friend` | + | 3 | `Bob Davis` | `colleague` | + +Now people can have **many** tags and tags can have **many** people, hence the name "many-to-many". + +### Other types of relationships + +More esoteric relationships are possible too. For example: + +- One-to-one relationships can be created by applying a unique constraint to the reference column. This is sometimes useful in more complex situations. +- Hierarchical data structures can be modeled using self-referential relationships. +- Polymorphic relationships can be modeled through a [variety of different patterns](https://hashrocket.com/blog/posts/modeling-polymorphic-associations-in-a-relational-database). + +## Creating relationships + +1. First, create the tables you want to relate. +1. From the table page of either table, open the "Table" tab within the table inspector, and find the "Relationships" section. +1. Click on the "Create relationship" button, and follow the prompts. + +Alternatively, you can manually add a foreign key constraint to an existing column with the following steps: + +1. Open the "Table" tab within the table inspector. +1. Open the "Advanced" section at the bottom. +1. Click on the "Constraints" button. +1. Next to "Foreign Key", click on "Add". + diff --git a/docs/docs/user-guide/roles.md b/docs/docs/user-guide/roles.md new file mode 100644 index 0000000000..dc0a06ca08 --- /dev/null +++ b/docs/docs/user-guide/roles.md @@ -0,0 +1,64 @@ +# PostgreSQL Roles + +PostgreSQL uses roles to manage access to data, and each PostgreSQL server has many roles within it. + +## What is a role + +PostgreSQL role system is elegant and powerful, if albeit somewhat idiosyncratic. + +Many permissioning systems utilize the concept of "users" to control access, and PostgreSQL roles work in much the same way. You connect to a PostgreSQL server by supplying your role's name and password. Then your role will dictate your access throughout the server. + +Other permissioning systems also commonly have a _separate_ concept of "groups", wherein multiple users can be members of a single group, and permissions can be granted to the group as a whole. Interestingly, PostgreSQL roles can _also_ function as groups! Through [role inheritance](#inheritance), any role can be granted to any other role. + +!!! warning "Users vs Roles" + Outside of Mathesar, it’s not uncommon for people to say _user_ when referring to a PostgreSQL _role_. However, within the context of Mathesar, users and roles are different things! Our documentation maintains this distinction pedantically. When we say "user", we mean a _Mathesar_ user, and when we say "role", we mean a _PostgreSQL_ role. + +## Managing your PostgreSQL roles from within Mathesar {:#managing} + +To see the roles available on your server, navigate to the **Database Settings** tab within the page for one of your connected databases. From there, you'll be able to add roles, drop roles, and edit role inheritance. + +Role passwords are stored in Mathesar's [internal database](./databases.md#internal) and encrypted with your [SECRET_KEY](../administration/configuration.md#secret_key). + +Renaming roles and modifying role properties (e.g. `LOGIN` status) is not supported within Mathesar. + +## LOGIN vs non-LOGIN roles {:#login} + +In PostgreSQL every role has a boolean `LOGIN` property which is either _true_ or _false_. A `LOGIN` role may have an associated password and thus be used to connect to the server; while a non-`LOGIN` role may not. Non-`LOGIN` roles are often used as "group" roles to be granted to other roles. + +Mathesar lets you see the `LOGIN` status of each role, but does not allow you to change it. If you need to change a role's `LOGIN` status, you'll need to do so directly in PostgreSQL. + + +## Roles vis-à-vis databases + +In PostgreSQL, roles live within the _server_ and thus are not necessarily specific to individual databases. One role can be configured to access many different databases; and one database can be configured for access via many different roles. Within the Mathesar interface however, the list of roles is presented _inside_ the page. This structure exists for the sake of convenience — and because PostgreSQL requires that clients connect to a specific database, even to query the roles present on a server. Nonetheless, it is important to understand that when you add/remove PostgreSQL roles (or edit their child roles), your changes will be visible for all databases which share the same server. + +## Ownership + +Every PostgreSQL object (e.g. a [table](./tables.md), [schema](./schemas.md), etc.) has one and only one role said to be its "owner". By default the owner is set to the role which created the object. + +The owner generally can do anything directly to the object, but not necessarily other objects contained within it. For example, a role might own a schema but not have access to certain tables within the schema. + +## Privileges + +Specific privileges on objects can be granted to roles, allowing non-owning roles to perform certain actions. See the following sections for more information on configuring these privileges: + +- [Database permissions](./databases.md#permissions) +- [Schema permissions](./schemas.md#permissions) +- [Table permissions](./tables.md#permissions) + +These privileges cover common actions, but there are still certain actions which remain restricted to object owners and cannot be granted to other roles. For example, only the owner of a table can add new columns to it; there is no way to grant that privilege to a non-owning role. + +## Role inheritance {:#inheritance} + +PostgreSQL has a mechanism for role inheritance (aka "role membership") wherein any role can be "granted" to any other role. For example, when the role `auditors` is granted to role `bob`, then `bob` will inherit all of the privileges set for `auditors`. While it's common for non-login roles to serve as "groups" which are granted to login roles, any role can actually be granted to any other role. This feature can be used to form simple hierarchies and complex graph-based inheritance structures. See the [PostgreSQL docs](https://www.postgresql.org/docs/current/role-membership.html) for more info. + +## Shared ownership + +Although every object in PostgreSQL has only one owner, it's still possible configure multiple roles to effectively "own" a single object by leveraging inheritance: + +1. We can create a role to directly own the object and act as a sort of proxy "group". (The group role doesn't need to be a `LOGIN` role and thus doesn't require a password to be configured.) +1. Then we can grant _that group role_ to any other roles we'd like. +1. Those child roles will then have permission do things _as if they were the owner themselves_. + +You can use Mathesar to configure an arrangement like the above, though it will require many steps. + diff --git a/docs/docs/user-guide/schemas.md b/docs/docs/user-guide/schemas.md new file mode 100644 index 0000000000..a550c16e60 --- /dev/null +++ b/docs/docs/user-guide/schemas.md @@ -0,0 +1,52 @@ +# Schemas + +## What is a schema + +"Schema" is one of those funny words that can mean different things in different contexts, even within the word of relational database systems. + +While all relational databases store their data in [tables](./tables.md), PostgreSQL has an additional level of nesting which requires every table to live within one and only one schema. You might think of a schema as a sort of folder. PostgreSQL sometimes calls it a "namespace". Schemas exist to help organize tables (and other database objects such as functions) into logical groups and avoid naming collisions. + +Schemas cannot contain other schemas, so there is a fixed hierarchy of objects... Within a database you have multiple schemas. And within a schema you have multiple tables. Mathesar's interface mirrors this structure. + +## The "public" schema + +Every PostgreSQL database has a schema named `public`. It cannot be deleted or renamed. It's also common for PostgreSQL servers to be configured to allow all roles to create tables within the public schema. And it's common for people to use PostgreSQL heavily without ever venturing outside the public schema. If you don't need to separate your data into different schemas, you can put everything in the public schema and more or less forget about schemas altogether. + +## Managing schemas within your database + +Mathesar lets you add/remove/rename the schemas in your database from within the database page. You can also add descriptions to your schemas which are stored in PostgreSQL as [COMMENTs](https://www.postgresql.org/docs/current/sql-comment.html). + +However, your ability to alter schemas may be limited by [access control](./access-control.md) — and you won't be able to change the public schema. + +## Organizing your data — schemas or databases? + +If you have separate, self-contained data projects you can choose between organizing them into separate schemas within the same database or into entirely separate databases. + +## Schema Permissions {:#permissions} + +- **Owner:** In PostgreSQL, every schema has a role set as its [owner](./roles.md#ownership). + + Only the owner can: + + - Drop the schema + - Manage schema-level privileges + - Transfer ownership + +- **Granted Privileges:** Additionally, the following privileges on one schema may be granted to specific roles in PostgreSQL: + - `USAGE`- Allows the role to see the tables within the schema. + - `CREATE`- Allows the role to create new tables within the schema. + +See the [PostgreSQL docs](https://www.postgresql.org/docs/17/ddl-priv.html) for more info. + +To manage the owner and granted privileges for a schema, navigate to the schema page in Mathesar and click on the **Schema Permissions** button at the top right. + +## Mathesar's internal schemas {:#internal} + +Mathesar allows you to work with all the schemas in your database _except_ for the following Mathesar-specific "internal" schemas: + +- `mathesar_types` - This holds Mathesar's custom [data types](./data-types.md) that you can use for your data. +- `msar` - This holds the bulk of Mathesar's application code, defined as PostgreSQL functions. +- `__msar` - This is a deprecated schema which holds some Mathesar functions that are [gradually being migrated](https://github.com/mathesar-foundation/mathesar/blob/develop/db/sql/STANDARDS.md#quoting-escaping-sql-injection-and-security) to the `msar` schema. + +The first time you use Mathesar to connect to your database, Mathesar installs these schemas. Mathesar's approach to [tightly integrating with PostgreSQL](./index.md#postgres) means these schemas are required for Mathesar to function with your database. For Mathesar to successfully install them, you'll need to enure that the PostgreSQL role you provide has `CREATE` privileges on the database. After the schemas are installed and your database is connected, you can revoke the `CREATE` privilege if do not wish for your users to be able to create other schemas. + diff --git a/docs/docs/user-guide/stored-role-passwords.md b/docs/docs/user-guide/stored-role-passwords.md new file mode 100644 index 0000000000..1b7e90b66d --- /dev/null +++ b/docs/docs/user-guide/stored-role-passwords.md @@ -0,0 +1,21 @@ +# Stored Role Passwords + +Mathesar stores passwords for any [roles](./roles.md) that you would like to use when authenticating with PostgreSQL to work with data. Roles with stored passwords can then be assigned to [users](./users.md) via [collaborators](./collaborators.md) + +When you connect a database for the first time, the password for the role you specify is stored in Mathesar, and a collaborator for your user is established for the database. However for any additional roles you create, you'll need to manually save the password in Mathesar. + +After being saved, the stored passwords are not available to be viewed again within Mathesar. + +If the password for a role is modified within PostgreSQL, you'll need to update the stored password for that role in Mathesar. + +How passwords are stored: + +- Passwords are stored in Mathesar's [internal database](./databases.md#internal). +- They are encrypted at rest with your [SECRET_KEY](../administration/configuration.md#secret_key) generated at installation time. +- They are stored per-database-_server_. This means that if you connect two databases on the same server, then the same role password can be used for both databases. + +To manage the stored passwords: + +1. Navigate to the page for your connected database. +1. Go to the **Database Settings** tab. +1. Click on **Stored Role Passwords** in the left-hand menu. diff --git a/docs/docs/user-guide/tables.md b/docs/docs/user-guide/tables.md new file mode 100644 index 0000000000..6e752ccde8 --- /dev/null +++ b/docs/docs/user-guide/tables.md @@ -0,0 +1,36 @@ +# Tables + +## What is a table + +All relational databases, including PostgreSQL, organize data into tables containing rows, columns, and cells. Much like a single spreadsheet might have multiple _sheets_ within it, a single database will typically have several — or sometimes several _dozen_ — tables within it. Unlike most spreadsheets though, database tables are usually highly interconnected. In a database, [relationships](./relationships.md) offer a robust mechanism for one cell to reference one record in another table. By leveraging relationships, we can unlock the ability to model complex data structures via multiple linked tables. + +## Managing tables + +Mathesar lets you add/remove/rename tables from within the database page. You can also add descriptions to your tables which are stored in PostgreSQL as [COMMENTs](https://www.postgresql.org/docs/current/sql-comment.html). + +Keep in mind that your ability to alter tables may be limited by [access control](./access-control.md). + +## Table Permissions {:#permissions} + +- **Owner:** In PostgreSQL, every table has a role set as its [owner](./roles.md#ownership). + + Only the owner can: + + - Drop the table + - Alter the table's columns + - Manage table-level privileges + - Transfer ownership + +- **Granted Privileges:** Additionally, the following privileges on one table may be granted to specific roles in PostgreSQL: + + - `SELECT` - Allows reading data from the table + - `INSERT` - Allows creation of new records within the table. + - `UPDATE` - Allow updating existing records within the table. + - `DELETE` - Allow deletion of records from the table. + - `TRUNCATE` - Allows the deletion of all records from the table at once + - `REFERENCES` - Allow creation of foreign key constraints that [reference](./relationships.md) the table. + - `TRIGGER` - Allow creation of triggers on the table. + +See the [PostgreSQL docs](https://www.postgresql.org/docs/17/ddl-priv.html) for more info. + +To manage the owner and granted privileges for a table, navigate to the table page in Mathesar and click on the **Table Permissions** button at the top right. diff --git a/docs/docs/user-guide/users.md b/docs/docs/user-guide/users.md index 39d1f42330..d2f5f1bd1e 100644 --- a/docs/docs/user-guide/users.md +++ b/docs/docs/user-guide/users.md @@ -1,48 +1,31 @@ -# Users +# Mathesar Users -Mathesar allows multiple users to collaborate on the same data using a [role-based permissioning](./permissions.md) system. +Each Mathesar installation can have multiple users, allowing different people to sign in with their own password and work with the same data collaboratively. ## Managing Users +To manage the users in you Mathesar installation, navigate to the users page: + 1. Click on the gear icon on the top right of the application and select **Administration**. 1. In the left sidebar, click on **Users**. -!!! info "Admin-assigned passwords" - Any user with an admin-assigned password (new or edited) will be prompted to change their password after logging in. +!!! info "Note" + - Any user with an admin-assigned password (new or edited) will be prompted to change their password after logging in. + - Newly added users won't see any of the connected databases unless you either make them admin users or explicitly add them as [collaborators](./collaborators.md) to each database. -## Admin vs Standard users +## Admin vs Standard users {:#admin} Each Mathesar user is either **Admin** or **Standard**. Admin users have the following capabilities which Standard users do not: - Admins can can manage other Mathesar users (view, add, edit, delete). -- Admins can add and remove [Databases](./databases.md). -- Admins can manage [Collaborators](./permissions.md#collaborators). This allows an Admin user to grant any Mathesar user access to a database through a PostgreSQL role that the Admin specifies. +- Admins can connect and disconnect [databases](./databases.md). +- Admins can save, update, and remove the stored passwords for PostgreSQL [roles](./roles.md). +- Admins can manage [collaborators](./collaborators.md). This allows an Admin user to grant any Mathesar user access to a database through a PostgreSQL role that the Admin specifies. Upon installing Mathesar, your first user will be an Admin user. -## Users vs Roles - -- A **"user"** is a Mathesar construct. Each Mathesar installation has multiple users. -- A **"role"** is a PostgreSQL construct ([docs](https://www.postgresql.org/docs/current/user-manag.html)). Each PostgreSQL server has multiple roles and multiple databases. - -!!! caution "Why this distinction is important" - Outside of Mathesar, it's not uncommon for people to say _user_ when referring to a PostgreSQL _role_. However, within the context of Mathesar users and roles are different things! Our documentation maintains this distinction pedantically. - -How users and roles work together: - -- To access a database, each Mathesar user must be assigned a PostgreSQL role to be used for that database. -- The user's permissions on actual data (in the [user database](./glossary.md#user-db)) are determined by the corresponding role's permissions within PostgreSQL. - - !!! info "Admin doesn't matter here" - The user's "admin" status with Mathesar _has no effect_ on the user's ability to do things with the _data_ in a database! The admin status only affects operations on Mathesar's [internal database](./glossary.md#internal-db) such as managing collaborators and their corresponding roles. - -- You can configure separate Mathesar users to share the same PostgreSQL role if you like. This is a good option if you want those users to have the same permissions on the data. -- Or you can use separate PostgreSQL roles for different users. This is necessary any time you want different users to have different permissions on the data. -- You cannot configure one Mathesar user with two PostgreSQL role simultaneously — though you can save multiple PostgreSQL roles in Mathesar and manually switch between them if necessary. - -See [Permissions](./permissions.md) for more information on managing roles. ## Limitations diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 25b24c0d98..915bf12559 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -5,55 +5,67 @@ repo_name: mathesar-foundation/mathesar edit_uri: edit/develop/docs/docs/ nav: - - Introduction: - - Welcome: index.md - - Installation: - - Install using Docker Compose: installation/docker-compose/index.md - - Install from scratch: installation/build-from-source/index.md - - Configuration: - - Environment variables: configuration/env-variables.md + - Introduction: index.md - Administration: - - Upgrade: - - To 0.1.7: administration/upgrade/0.1.7.md - - To 0.1.6: administration/upgrade/0.1.6.md - - To 0.1.5: administration/upgrade/0.1.5.md - - To 0.1.4: administration/upgrade/0.1.4.md - - To older versions: administration/upgrade/older.md + - Install using Docker Compose: administration/install-via-docker-compose.md + - Install from scratch: administration/install-from-scratch.md + - Configuration: administration/configuration.md + - Backup & Restore: administration/backup-restore.md - Uninstall Mathesar: administration/uninstall.md - Debug Mathesar: administration/debug.md - - Using Mathesar: + - User Guide: - Introduction: user-guide/index.md - - Databases: user-guide/databases.md - - Users: user-guide/users.md - - Permissions: user-guide/permissions.md - - Importing data: user-guide/importing-data.md - - Glossary: user-guide/glossary.md + - Your data in PostgreSQL: + - Databases: user-guide/databases.md + - Schemas: user-guide/schemas.md + - Tables: user-guide/tables.md + - Data types: user-guide/data-types.md + - Relationships: user-guide/relationships.md + - Access Control: + - Overview: user-guide/access-control.md + - Mathesar Users: user-guide/users.md + - PostgreSQL Roles: user-guide/roles.md + - Stored Role Passwords: user-guide/stored-role-passwords.md + - Collaborators: user-guide/collaborators.md + - Mathesar constructs: + - Metadata: user-guide/metadata.md + - Data Explorer: user-guide/data-explorer.md + - Data management: + - Importing data: user-guide/importing-data.md + - Exporting data: user-guide/exporting-data.md - API: - - RPC: api/rpc.md - - REST: api/rest.md - - Test Builds: - - '0.2.0-testing.1': releases/0.2.0-testing.1.md + - Overview: api/index.md + - Methods: api/methods.md - Releases: - - '0.1.7': releases/0.1.7.md - - '0.1.6': releases/0.1.6.md - - '0.1.5': releases/0.1.5.md - - '0.1.4': releases/0.1.4.md - - '0.1.3': releases/0.1.3.md - - '0.1.2': releases/0.1.2.md - - '0.1.1': releases/0.1.1.md - - '0.1.0': releases/0.1.0.md + - '0.2.0': releases/0.2.0.md + - Previous Releases: + - '0.1.7': releases/0.1.7.md + - '0.1.6': releases/0.1.6.md + - '0.1.5': releases/0.1.5.md + - '0.1.4': releases/0.1.4.md + - '0.1.3': releases/0.1.3.md + - '0.1.2': releases/0.1.2.md + - '0.1.1': releases/0.1.1.md + - '0.1.0': releases/0.1.0.md plugins: - search: lang: en - redirects: redirect_maps: - "installation-dc/ansible-setup.md": "installation/docker-compose/index.md" + "installation-dc/ansible-setup.md": "administration/install-via-docker-compose.md" "product/intro.md": "user-guide/index.md" "product/users.md": "user-guide/users.md" "install/index.md": "index.md" - "install/docker-compose/index.md": "installation/docker-compose/index.md" - "install/build-from-source/index.md": "installation/build-from-source/index.md" + "install/docker-compose/index.md": "administration/install-via-docker-compose.md" + "install/build-from-source/index.md": "administration/install-from-scratch.md" + "api/rpc.md": "api/index.md" + "api/rest.md": "api/index.md" + "user-guide/glossary.md": "user-guide/index.md" + "user-guide/permissions.md": "user-guide/access-control.md" + "configuration/env-variables.md": "administration/configuration.md" + "installation/docker-compose/index.md": "administration/install-via-docker-compose.md" + "installation/build-from-source/index.md": "administration/install-from-scratch.md" - macros - placeholder - mkdocstrings: @@ -120,7 +132,7 @@ markdown_extensions: permalink: true extra: - mathesar_version: 0.2.0-testing.1 + mathesar_version: 0.2.0 version: provider: mike alias: true diff --git a/docs/requirements.txt b/docs/requirements.txt index d8a12071ad..ffd5ad392a 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -6,3 +6,4 @@ mkdocs-macros-plugin==0.7.0 mkdocs-placeholder-plugin==0.3.1 mkdocstrings==0.25.2 mkdocstrings-python==1.10.8 +setuptools==75.5.0