diff --git a/docs/docs/api/rpc.md b/docs/docs/api/rpc.md index 9f91c2f4b8..ab9021a2d8 100644 --- a/docs/docs/api/rpc.md +++ b/docs/docs/api/rpc.md @@ -2,16 +2,12 @@ Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](https://www.jsonrpc.org/specification) spec version 2.0. -## About +!!! caution "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. -### Status +## Usage -We are currently in the process of [transitioning](https://wiki.mathesar.org/projects/2024/architecture-transition/rpc/) our API architecture from a [RESTful](rest.md) API to this RPC-style API, and we hope to have all functionality available through the RPC API by Mathesar's beta release. - -!!! caution "Stability" - The RPC API is not yet stable and may change in the future, even after we've completed the transition to the RPC API architecture. 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: @@ -23,7 +19,7 @@ To use an RPC function: To call function `add_from_known_connection` from the `connections` section of this page, you'd send something like: - `POST /api/rpc/v0/` + `POST /api/rpc/v0/`b ```json { @@ -37,127 +33,63 @@ To use an RPC function: } ``` -## Collaborators - -::: collaborators - options: - members: - - list_ - - add - - delete - - set_role - - CollaboratorInfo - -## Connections - -::: connections - options: - members: - - add_from_known_connection - - add_from_scratch - - grant_access_to_user - - ConnectionReturn +### Responses -## Databases +#### Success -::: databases - options: - members: - - get - - delete - - DatabaseInfo +Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form: -## Configured Databases +```json +{ + "jsonrpc": "2.0", + "id": 234, + "result": +} +``` -::: databases.configured - options: - members: - - list_ - - disconnect - - ConfiguredDatabaseInfo +The `result` is whatever was returned by the underlying function. -## Database Privileges +#### Errors -::: databases.privileges - options: - members: - - list_direct - - replace_for_roles - - transfer_ownership - - DBPrivileges +When an error is produced by a call to the RPC endpoint, we produce an error of the following form: -## Database Setup +```json +{ + "jsonrpc": "2.0", + "id": 234, + "error": { + "code": , + "message": + } +} +``` -::: databases.setup - options: - members: - - create_new - - connect_existing - - DatabaseConnectionResult +The `code` is a negative integer. Some codes are produced according to the [JSON-RPC spec](https://www.jsonrpc.org/specification#error_object). -## Schemas +Other error codes are grouped according to the library that produced the Exception: -::: schemas - options: - members: - - list_ - - get - - add - - delete - - patch - - SchemaInfo - - SchemaPatch +- `builtins`: -31xxx +- `psycopg` or `psycopg2`: -30xxx +- `django`: -29xxx +- `mathesar` (our code): -28xxx +- `db` (our code): -27xxx +- `sqlalchemy`: -26xxx +- other: -25xxx -## Schema Privileges +Unrecognized errors from a given library return a "round number" code, so an unknown `builtins` error gets the code -31000. -::: schemas.privileges - options: - members: - - list_direct - - replace_for_roles - - transfer_ownership - - SchemaPrivileges +--- -## Tables +## Collaborators -::: tables +::: collaborators options: members: - list_ - - get - add - delete - - patch - - import_ - - get_import_preview - - list_joinable - - list_with_metadata - - get_with_metadata - - TableInfo - - AddedTableInfo - - SettableTableInfo - - JoinableTableRecord - - JoinableTableInfo - -## Table Privileges - -::: tables.privileges - options: - members: - - list_direct - - replace_for_roles - - transfer_ownership - - TablePrivileges - -## Table Metadata - -::: tables.metadata - options: - members: - - list_ - - set_ - - TableMetaDataBlob - - TableMetaDataRecord + - set_role + - CollaboratorInfo ## Columns @@ -187,13 +119,25 @@ To use an RPC function: - ColumnMetaDataRecord - ColumnMetaDataBlob -## Types +## Configured Databases -::: types +::: databases.configured options: members: - list_ - - TypeInfo + - disconnect + - ConfiguredDatabaseInfo + + +## Connections + +::: connections + options: + members: + - add_from_known_connection + - add_from_scratch + - grant_access_to_user + - ConnectionReturn ## Constraints @@ -209,27 +153,46 @@ To use an RPC function: - UniqueConstraint - CreatableConstraintInfo -## Records +## Data Modeling -:::records +:::data_modeling + options: + members: + - add_foreign_key_column + - add_mapping_table + - suggest_types + - split_table + - move_columns + - MappingColumn + - SplitTableInfo + +## Databases + +::: databases options: members: - - list_ - get - - add - - patch - delete - - search - - RecordList - - RecordAdded - - OrderBy - - Filter - - FilterAttnum - - FilterLiteral - - Grouping - - Group - - GroupingResponse - - SearchParam + - DatabaseInfo + +## Database Privileges + +::: databases.privileges + options: + members: + - list_direct + - replace_for_roles + - transfer_ownership + - DBPrivileges + +## Database Setup + +::: databases.setup + options: + members: + - create_new + - connect_existing + - DatabaseConnectionResult ## Explorations @@ -247,6 +210,28 @@ To use an RPC function: - ExplorationDef - ExplorationResult +## Records + +:::records + options: + members: + - list_ + - get + - add + - patch + - delete + - search + - RecordList + - RecordAdded + - OrderBy + - Filter + - FilterAttnum + - FilterLiteral + - Grouping + - Group + - GroupingResponse + - SearchParam + ## Roles ::: roles @@ -260,7 +245,7 @@ To use an RPC function: - RoleInfo - RoleMember -## Configured Roles +## Roles Configured ::: roles.configured options: @@ -271,68 +256,82 @@ To use an RPC function: - set_password - ConfiguredRoleInfo -## Servers +## Schemas -::: servers +::: schemas options: members: - list_ - - ConfiguredServerInfo + - get + - add + - delete + - patch + - SchemaInfo + - SchemaPatch -## Data Modeling +## Schema Privileges -:::data_modeling +::: schemas.privileges options: members: - - add_foreign_key_column - - add_mapping_table - - suggest_types - - split_table - - move_columns - - MappingColumn - - SplitTableInfo - -## Responses - -### Success + - list_direct + - replace_for_roles + - transfer_ownership + - SchemaPrivileges -Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form: +## Servers -```json -{ - "jsonrpc": "2.0", - "id": 234, - "result": -} -``` +::: servers + options: + members: + - list_ + - ConfiguredServerInfo -The `result` is whatever was returned by the underlying function. +## Tables -### Errors +::: tables + options: + members: + - list_ + - get + - add + - delete + - patch + - import_ + - get_import_preview + - list_joinable + - list_with_metadata + - get_with_metadata + - TableInfo + - AddedTableInfo + - SettableTableInfo + - JoinableTableRecord + - JoinableTableInfo -When an error is produced by a call to the RPC endpoint, we produce an error of the following form: +## Table Metadata -```json -{ - "jsonrpc": "2.0", - "id": 234, - "error": { - "code": , - "message": - } -} -``` +::: tables.metadata + options: + members: + - list_ + - set_ + - TableMetaDataBlob + - TableMetaDataRecord -The `code` is a negative integer. Some codes are produced according to the [JSON-RPC spec](https://www.jsonrpc.org/specification#error_object). +## Table Privileges -Other error codes are grouped according to the library that produced the Exception: +::: tables.privileges + options: + members: + - list_direct + - replace_for_roles + - transfer_ownership + - TablePrivileges -- `builtins`: -31xxx -- `psycopg` or `psycopg2`: -30xxx -- `django`: -29xxx -- `mathesar` (our code): -28xxx -- `db` (our code): -27xxx -- `sqlalchemy`: -26xxx -- other: -25xxx +## Types -Unrecognized errors from a given library return a "round number" code, so an unknown `builtins` error gets the code -31000. +::: types + options: + members: + - list_ + - TypeInfo diff --git a/docs/docs/index.md b/docs/docs/index.md index 9b77bf0621..ea09a26144 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -49,10 +49,7 @@ You can self-host Mathesar by following one of the guides below: ## Use Mathesar -Mathesar should be pretty intuitive to use. More documentation is coming soon, but for now, we've written some documentation for some things that could be tricky. - -- [Syncing database changes](./user-guide/syncing-db.md) if the database's structure is changed outside of Mathesar. -- How to set up [users with different access levels](./user-guide/users.md) +See our [Using Mathesar](user-guide/index.md) section for documentation on Mathesar's features. ## Contribute to Mathesar diff --git a/docs/docs/user-guide/databases.md b/docs/docs/user-guide/databases.md new file mode 100644 index 0000000000..f0068b88ae --- /dev/null +++ b/docs/docs/user-guide/databases.md @@ -0,0 +1,33 @@ +# Databases + +Each installation of Mathesar can connect to multiple PostgreSQL databases. Connecting your first database will likely be your first step in using Mathesar. + +## PostgreSQL servers + +Every PostgreSQL database lives within a PostgreSQL server. + +- **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". + +- The **Internal Server:** Most Mathesar installations have an internal PostgreSQL server which the Mathesar application controls and utilizes for storage of application-specific metadata. + + !!! info "Some Mathesar installations don't have an internal server" + It's possible (though not recommended) to configure Mathesar to store its internal metadata in SQLite, thereby circumventing the need for an internal server. + +## Creating a new database + +If you're starting your database from scratch with Mathesar you can either: + +- Use Mathesar to create a new database within Mathesar's internal server and connect to it. This is a good option to get up and running quickly, but it might require more work later should you decide to set up periodic backups or connect other tools to the same database. Also, this option won't be possible if Mathesar was installed without an internal server. + + _OR_ + +- 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 + +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 and configure various [permissions](./permissions.md) for it. + +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). + diff --git a/docs/docs/user-guide/index.md b/docs/docs/user-guide/index.md index 56e2e69edf..d82d5092a3 100644 --- a/docs/docs/user-guide/index.md +++ b/docs/docs/user-guide/index.md @@ -2,6 +2,7 @@ Welcome! At this point, we assume you've installed Mathesar successfully and have logged into the web UI. -If you've connected Mathesar to an existing database, you should see all your schemas once you log in, and you can work with them as you please. +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. -If you're starting from scratch, we recommend **creating a new schema**. +!!! tip "More..." + 👈 Browse the "Using Mathesar" navigation section to find more detailed documentation pages. diff --git a/docs/docs/user-guide/permissions.md b/docs/docs/user-guide/permissions.md new file mode 100644 index 0000000000..2a096f96ff --- /dev/null +++ b/docs/docs/user-guide/permissions.md @@ -0,0 +1,123 @@ +# 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/syncing-db.md b/docs/docs/user-guide/syncing-db.md deleted file mode 100644 index e36f7bf89d..0000000000 --- a/docs/docs/user-guide/syncing-db.md +++ /dev/null @@ -1,7 +0,0 @@ -# Syncing Database Changes - -Mathesar is designed to be used in tandem with other database tools. This means that if you make changes to your database structure or data outside of Mathesar, those changes will be reflected in Mathesar's UI. - -If you make structural changes to the database outside Mathesar (e.g. using another tool to add a schema, table, or column), those changes will not be reflected in Mathesar until you manually sync them. You can sync them using the "Sync Database Changes" button in the database homepage. - -External changes to data (e.g. adding, editing, or deleting *records*) will be automatically reflected without clicking this button. diff --git a/docs/docs/user-guide/users.md b/docs/docs/user-guide/users.md index 7cef8d20f5..39d1f42330 100644 --- a/docs/docs/user-guide/users.md +++ b/docs/docs/user-guide/users.md @@ -1,133 +1,50 @@ -# Users & Access Levels +# Users -Mathesar allows you to set up users with different access levels. A user's access levels determine what they can do with the data managed in Mathesar. - -Mathesar's installation process includes setting up the first user. This user is an **Admin**. +Mathesar allows multiple users to collaborate on the same data using a [role-based permissioning](./permissions.md) system. ## Managing Users 1. Click on the gear icon on the top right of the application and select **Administration**. -2. In the left sidebar, click on **Users**. - -!!! note - - Only **Admins** can add new users. - - Mathesar does not send invitation emails to new users (yet). You'll need to send the user their username and password yourself. - - The user will be prompted to change the password when they log in for the first time. - -## User Types - -Users can be either **Admin** or **Standard** users. - -### Admin users - -Admin users: - -- can manage other users (view, add, edit, delete) -- have **Manager** permissions on all databases and schemas - -You cannot set granular permissions for an **Admin** user. - -### Standard users - -By default, **Standard** users cannot see anything in Mathesar. They will need to be granted database or schema roles individually. - -## Database Roles - -There are three levels of database roles: - -- **Managers** own the database. They can edit all data in the database, as well as edit the structure of data (e.g. create tables, add and remove columns, etc.). They also manage access to the database. -- **Editors** can edit all data in the database, but cannot change the underlying data structures or manage access. -- **Viewers** have read-only access to all data in the database. They cannot make any changes. - -### Manager - -- Receives **Manager** permissions on all schemas in the database. -- Can view, add, and remove other users' access to the database. -- Can view, add, edit, and remove any schema in the database. -- Can view, add, edit, and remove any table in the database. -- Can view, add, edit, and remove any column in the database. -- Can view, add, edit, and remove any constraint in the database. -- Can view, add, edit, and remove any record in the database. -- Can view, add, edit, and remove any exploration in the database. -- Can perform "extract column" and "move column" actions - -### Editor - -- Receives **Editor** permissions on all schemas in the database. -- Can view any schema in the database. -- Can view any table in the database. -- Can view any column in the database. -- Can view any constraint in the database. -- Can view, add, edit, and remove any exploration in the database. -- Can view, add, edit, and remove any record in the database. - -### Viewer - -- Receives **Viewer** permissions on all schemas in the database. -- Can view any schema in the database. -- Can view any table in the database. -- Can view any column in the database. -- Can view any constraint in the database. -- Can view any exploration in the database. -- Can use the **Data Explorer** to create ad-hoc explorations using data in the database, but cannot save them. - -## Managing Database Roles - -!!! note - - Only **Admins** and **Database Managers** can manage access to a database. - -1. Click on the Mathesar logo on the top left of the application to go to the database page. -2. Click on the **Manage Access** button. +1. In the left sidebar, click on **Users**. -## Schema Roles +!!! info "Admin-assigned passwords" + Any user with an admin-assigned password (new or edited) will be prompted to change their password after logging in. -There are three levels of schema roles: +## Admin vs Standard users -- **Managers** own the schema. They can edit all data in the schema, as well as edit the structure of data (e.g. create tables, add and remove columns, etc.). They also manage access to the schema. -- **Editors** can edit all data in the schema, but cannot change the underlying data structures or manage access. -- **Viewers** have read-only access to all data in the schema. They cannot make any changes. +Each Mathesar user is either **Admin** or **Standard**. -### Manager +Admin users have the following capabilities which Standard users do not: -- Can view, add, and remove other users' access to the schema. -- Can view, add, edit, and remove any schema in the schema. -- Can view, add, edit, and remove any table in the schema. -- Can view, add, edit, and remove any column in the schema. -- Can view, add, edit, and remove any constraint in the schema. -- Can view, add, edit, and remove any record in the schema. -- Can view, add, edit, and remove any exploration in the schema. -- Can perform "extract column" and "move column" actions +- 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. -### Editor +Upon installing Mathesar, your first user will be an Admin user. -- Can view any table in the schema. -- Can view any column in the schema. -- Can view any constraint in the schema. -- Can view, add, edit, and remove any record in the schema. -- Can view, add, edit, and remove any exploration in the schema. +## Users vs Roles -### Viewer +- 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. -- Can view any table in the schema. -- Can view any column in the schema. -- Can view any constraint in the schema. -- Can view any exploration in the schema. -- Can use the **Data Explorer** to create ad-hoc explorations using data in the schema, but cannot save them. +!!! 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. -## Managing Schema Roles +How users and roles work together: -!!! note - - Only **Admins**, **Database Managers**, and **Schema Managers** can manage access to a schema. +- 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. -1. Click on the Mathesar logo on the top left of the application to go to the database page. -2. Select the appropriate schema from the list to navigate to the schema's homepage. -3. Click on the **Manage Access** button. + !!! 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. -## Order of Precedence +- 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. -If a user has both a **Database Role** and a **Schema Role** for a schema within the same database, the **Schema Role** will only have an effect if it grants more permissions. +See [Permissions](./permissions.md) for more information on managing roles. -Examples: +## Limitations -- If a user is a **Database Manager** but has **Viewer** permissions on a given schema, the schema role has no effect. -- If a user is a **Database Editor** but has **Manager** permissions on a given schema, the schema role will take precedence. +- Mathesar does not send invitation emails to new users (yet). You'll need to send the user their username and password yourself. +- Nor is there yet an email-based password recovery mechanism. If you are locked out of your Mathesar installation's web interface, your system administrator can still [use the command line reset any user's password](https://stackoverflow.com/questions/6358030/how-to-reset-django-admin-password). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e2488e3424..bc61f19893 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -23,13 +23,14 @@ nav: - Debug Mathesar: administration/debug.md - Using Mathesar: - 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 - - Syncing database changes: user-guide/syncing-db.md - - Users & access levels: user-guide/users.md - Glossary: user-guide/glossary.md - API: - - REST: api/rest.md - RPC: api/rpc.md + - REST: api/rest.md - Releases: - '0.1.7': releases/0.1.7.md - '0.1.6': releases/0.1.6.md @@ -47,7 +48,6 @@ plugins: redirect_maps: "installation-dc/ansible-setup.md": "installation/docker-compose/index.md" "product/intro.md": "user-guide/index.md" - "product/syncing-db.md": "user-guide/syncing-db.md" "product/users.md": "user-guide/users.md" "install/index.md": "index.md" "install/docker-compose/index.md": "installation/docker-compose/index.md"