From 012ef3b70039c70e82c2fca2b6acc76662f7ce4a Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 19 Nov 2024 15:36:19 -0500 Subject: [PATCH 01/27] Improve Database Settings UI --- .../component-library/button/Button.svelte | 62 ++++++--- .../spinner-button/SpinnerButton.svelte | 3 + .../PhraseContainingIdentifier.svelte | 3 +- mathesar_ui/src/components/Yes.svelte | 28 +++++ mathesar_ui/src/i18n/languages/en/dict.json | 31 +++-- mathesar_ui/src/icons/index.ts | 2 +- .../pages/database/DatabasePageWrapper.svelte | 2 +- .../database/schemas/SchemasSection.svelte | 18 --- .../database/settings/SettingsWrapper.svelte | 31 ++--- .../collaborators/CollaboratorRow.svelte | 34 ++++- .../collaborators/Collaborators.svelte | 1 + .../EditRoleForCollaboratorModal.svelte | 12 +- .../RemoveCollaboratorBody.svelte | 36 ++++++ .../RemoveCollaboratorTitle.svelte | 20 +++ .../ConfigureRoleModal.svelte | 12 +- .../RoleConfiguration.svelte | 118 ++++++++++-------- .../settings/roles/ModifyRoleMembers.svelte | 12 +- .../database/settings/roles/RoleRow.svelte | 50 +++++--- .../src/routes/DatabaseSettingsRoute.svelte | 2 +- 19 files changed, 325 insertions(+), 152 deletions(-) create mode 100644 mathesar_ui/src/components/Yes.svelte create mode 100644 mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorBody.svelte create mode 100644 mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorTitle.svelte diff --git a/mathesar_ui/src/component-library/button/Button.svelte b/mathesar_ui/src/component-library/button/Button.svelte index 61e7bf989a..b98375b3f3 100644 --- a/mathesar_ui/src/component-library/button/Button.svelte +++ b/mathesar_ui/src/component-library/button/Button.svelte @@ -4,6 +4,8 @@ Size, } from '@mathesar-component-library-dir/commonTypes'; + import Tooltip from '../tooltip/Tooltip.svelte'; + /** * Button appearance. One of: 'default', 'primary', 'secondary', 'plain', 'ghost'. * @required @@ -26,25 +28,51 @@ // Underlying DOM element for direct access export let element: HTMLElement | undefined = undefined; + export let tooltip: string | undefined = undefined; + $: allClasses = ['btn', `btn-${appearance}`, `size-${size}`, classes].join( ' ', ); - +{#if tooltip || $$slots.tooltip} + + +
{tooltip}
+ +{:else} + +{/if} diff --git a/mathesar_ui/src/component-library/spinner-button/SpinnerButton.svelte b/mathesar_ui/src/component-library/spinner-button/SpinnerButton.svelte index faad65e6d1..93a12edfa6 100644 --- a/mathesar_ui/src/component-library/spinner-button/SpinnerButton.svelte +++ b/mathesar_ui/src/component-library/spinner-button/SpinnerButton.svelte @@ -31,6 +31,7 @@ export let disabled = false; export let isProcessing = false; export let appearance: Appearance = 'primary'; + export let tooltip: string | undefined = undefined; /** * Bind to this function if you want to be able to programmatically call the @@ -55,6 +56,8 @@ on:click={proceed} {appearance} disabled={disabled || isProcessing} + {tooltip} + aria-label={label ? undefined : tooltip} {...$$restProps} > {#if isProcessing} diff --git a/mathesar_ui/src/components/PhraseContainingIdentifier.svelte b/mathesar_ui/src/components/PhraseContainingIdentifier.svelte index fac4b747ee..b034bc2af1 100644 --- a/mathesar_ui/src/components/PhraseContainingIdentifier.svelte +++ b/mathesar_ui/src/components/PhraseContainingIdentifier.svelte @@ -4,10 +4,11 @@ export let identifier: string; export let wrappingString = ''; + export let identifierKey = 'identifier'; - {#if slotName === 'identifier'} + {#if slotName === identifierKey} {identifier} {/if} diff --git a/mathesar_ui/src/components/Yes.svelte b/mathesar_ui/src/components/Yes.svelte new file mode 100644 index 0000000000..7fc912495e --- /dev/null +++ b/mathesar_ui/src/components/Yes.svelte @@ -0,0 +1,28 @@ + + + + + + + diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 541c66129e..8747b9ef31 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -54,6 +54,7 @@ "cannot_move_linked_column_to_linked_table": "Cannot move linking column \"{columnName}\" to its linked table \"{tableName}\".", "cell": "Cell", "change_password": "Change Password", + "change_role": "Change Role", "check_for_updates": "Check for Updates", "child_roles": "Child Roles", "child_roles_count": "{count, plural, one {{count} child role} other {{count} child roles}}", @@ -96,8 +97,6 @@ "columns_to_move": "Columns to Move", "columns_unique_values_help": "The columns in this table that should contain unique values.", "configure_in_mathesar": "Configure in Mathesar", - "configure_password": "Configure Password", - "configure_value": "Configure ''{value}''", "confirm_and_create_table": "Confirm & create table", "confirm_delete_table": "To confirm the deletion of the [tableName] table, please enter the table name into the input field below.", "confirm_password": "Confirm Password", @@ -166,6 +165,7 @@ "database_privilege_create_help": "Allow creation of new schemas.", "database_privilege_temporary_help": "Allow creation of temporary tables.", "database_server_credentials": "Database server credentials", + "database_settings": "Database Settings", "database_type": "Database Type", "databases": "Databases", "databases_matching_search": "{count, plural, one {{count} database matches [searchValue]} other {{count} databases match [searchValue]}}", @@ -208,15 +208,16 @@ "display_name": "Display Name", "documentation_and_resources": "Documentation & Resources", "drop_role": "Drop Role", + "drop_role_name": "Drop role [name]", + "drop_role_name_question": "Drop role [name]?", "drop_role_warning": "This role will be dropped on the database server and will not be available for any databases configured on the same server.", - "drop_role_with_identifier": "Drop Role [identifier]?", "edit": "Edit", - "edit_child_roles_for_parent": "Edit Child Roles for ''{parent}''", + "edit_child_roles_for_parent": "Edit [parent] child roles", "edit_connection": "Edit Connection", "edit_connection_with_name": "Edit Connection: [connectionName]", "edit_exploration_attempt_recovery": "You can edit the exploration in the Data Explorer to attempt recovering it.", "edit_in_data_explorer": "Edit in Data Explorer", - "edit_role_for_collaborator_value": "Edit Role for ''{collaborator}''", + "edit_role_for_collaborator_value": "Change Role for [userName]", "edit_schema": "Edit Schema", "edit_schema_with_name": "Edit Schema [schemaName]", "edit_table": "Edit Table", @@ -292,6 +293,7 @@ "import": "Import", "import_from_file": "Import from a File", "in_mathesar": "In Mathesar", + "in_postgresql": "In PostgreSQL", "in_this_table": "In this table", "individual_permissions_admin_modify_warning": "Individual permissions cannot be modified for users with Admin access.", "inherited": "Inherited", @@ -408,7 +410,6 @@ "number_of_matches_in_category": "{count, plural, one {{count} match for [searchValue] in [categoryName]} other {{count} matches for [searchValue] in [categoryName]}}", "old_password": "Old Password", "oldest_to_newest_sort": "Oldest-Newest", - "on_the_server": "On The Server", "one_column_from_base_is_required": "At least one column from the base table is required to add columns from linked tables.", "one_to_many": "One to Many", "one_to_many_link_desc": "One [baseTable] record can be linked from multiple [targetTable] records.", @@ -429,6 +430,7 @@ "password": "Password", "password_encryption_help": "This password will be AES encrypted with Mathesar's secret key and stored in Mathesar's internal database.", "password_encryption_help_plus_storage": "This password will be AES encrypted with Mathesar's secret key and stored in Mathesar's internal database. Save it elsewhere so that you may also connect to this database from outside Mathesar.", + "password_stored": "Password Stored", "passwords_do_not_match": "Passwords do not match", "paste_data_import": "Paste the data you want to import", "permission": "Permission", @@ -476,12 +478,18 @@ "release_notes_and_upgrade_instructions": "Release Notes and Upgrade Instructions", "released_date": "Released {date}", "remove": "Remove", + "remove_collaborator": "Remove Collaborator", + "remove_collaborator_body_1": "The user [userName] will no longer have access to the [databaseName] database.", + "remove_collaborator_body_2": "The user [userName] will still be able to log in to Mathesar and might still have access to other connected databases.", + "remove_collaborator_body_3": "The associated PostgreSQL role [roleName] will be unaffected.", + "remove_collaborator_name_from_database_question": "Remove [userName] as a collaborator on the [databaseName] database?", "remove_configuration": "Remove Configuration", - "remove_configuration_for_identifier": "Remove Configuration for [identifier]?", "remove_filters": "{count, plural, one {Remove Filter} other {Remove {count} Filters}}", "remove_grouping": "Remove Grouping", "remove_old_link_create_new": "Remove old link and create a new link?", "remove_sorting_type": "Remove {sortingType} Sorting", + "remove_stored_password": "Remove Stored Password", + "remove_stored_password_for_identifier": "Remove Stored Password for [identifier]?", "removing_role_configuration_warning": "Removing this configuration will prevent collaborators assigned to this role from accessing databases on server ''{server}''.", "reset": "Reset", "restrict_to_unique": "Restrict to Unique", @@ -491,9 +499,8 @@ "retry": "Retry", "reuse_credentials_from_known_connection": "Reuse credentials from a known connection", "role": "Role", - "role_configuration": "Role Configuration", "role_configuration_removed": "The role configuration has been removed successfully", - "role_configured_all_databases_in_server": "This role will be configured for all databases on DB Server ''{server}''", + "role_configured_all_databases_in_server": "The new password will be used for this role when connecting to any databases on server ''{server}''", "role_configured_successfully": "Role configured successfully", "role_configured_successfully_new_password": "Role configured successfully with new password", "role_created_successfully": "The Role has been created successfully", @@ -509,6 +516,7 @@ "save": "Save", "save_and_close": "Save and Close", "save_exploration": "Save Exploration", + "save_password": "Save Password", "saved_explorations": "Saved Explorations", "saving": "Saving", "saving_changes": "Saving Changes", @@ -575,6 +583,9 @@ "start_over": "Start Over", "start_working_with_mathesar": "Start Working with Mathesar", "static_record_summary_template_error": "Record summary cannot be static. Add at least one column field in order to save.", + "store_a_password": "Store a Password", + "stored_password": "Stored Password", + "stored_role_passwords": "Stored Role Passwords", "summarization": "Summarization", "summarize": "Summarize", "summarize_column_configure": "You can manually configure a summarization later via the \"Transform Results\" pane.", @@ -650,6 +661,8 @@ "unsaved_changes": "Unsaved Changes", "update": "Update", "update_connection": "Update Connection", + "update_stored_password": "Update Stored Password", + "update_stored_password_for_role": "Set a stored password for [role]", "upgrade": "Upgrade", "upgrade_in_progress_do_not_navigate": "A Mathesar upgrade is currently in progress. It is important that you do not navigate away from this page until the upgrade is complete.", "upgrade_to_version": "Upgrade to {version}", diff --git a/mathesar_ui/src/icons/index.ts b/mathesar_ui/src/icons/index.ts index 987c85524a..8fda77ae54 100644 --- a/mathesar_ui/src/icons/index.ts +++ b/mathesar_ui/src/icons/index.ts @@ -106,7 +106,6 @@ export const iconAddFilter: IconProps = { data: faFilter }; export const iconAddNew: IconProps = { data: faPlus }; export const iconAddUser: IconProps = { data: faUserPlus }; export const iconConfigure: IconProps = { data: faCogs }; -export const iconConfigurePassword = { data: faKey }; export const iconConnectDatabase = { data: connectDatabaseIcon }; export const iconCopyMajor: IconProps = { data: faCopy }; /** TODO: use faBinary once it's available (via newer FontAwesome version) */ @@ -199,6 +198,7 @@ export const iconFieldDelimiter: IconProps = { data: faCaretRight }; export const iconNotEditable: IconProps = { data: faLock }; export const iconUnsavedChanges: IconProps = { data: faCircleExclamation }; +export const iconYes: IconProps = { data: faCheck }; // UI TYPES diff --git a/mathesar_ui/src/pages/database/DatabasePageWrapper.svelte b/mathesar_ui/src/pages/database/DatabasePageWrapper.svelte index 5c20d303c4..69233a395b 100644 --- a/mathesar_ui/src/pages/database/DatabasePageWrapper.svelte +++ b/mathesar_ui/src/pages/database/DatabasePageWrapper.svelte @@ -60,7 +60,7 @@ }, { id: 'settings', - label: $_('settings'), + label: $_('database_settings'), href: getDatabasePageSettingsSectionUrl(database.id), }, ]; diff --git a/mathesar_ui/src/pages/database/schemas/SchemasSection.svelte b/mathesar_ui/src/pages/database/schemas/SchemasSection.svelte index a911f24042..7ec087d1d5 100644 --- a/mathesar_ui/src/pages/database/schemas/SchemasSection.svelte +++ b/mathesar_ui/src/pages/database/schemas/SchemasSection.svelte @@ -83,12 +83,6 @@
-
-

- {$_('schemas')} - {schemasMap.size ? `(${schemasMap.size})` : ''} -

-
+ +
{$_('in_postgresql')}
+ + + {$_('roles')} + + +
+
{$_('in_mathesar')}
 @@ -31,7 +43,7 @@ href={getDatabaseRoleConfigurationUrl(database.id)} class={section === 'roleConfiguration' ? 'active' : ''} > - {$_('role_configuration')} + {$_('stored_role_passwords')} {$_('collaborators')} -
- -
{$_('on_the_server')}
- - - {$_('roles')} -
@@ -67,13 +69,12 @@ padding: var(--size-x-small) 0; .heading { - font-size: var(--text-size-small); + color: var(--slate-400); font-weight: 500; - text-transform: uppercase; margin-bottom: var(--size-ultra-small); } .menu-divider { - margin: 0.5rem 0.1rem 0.8rem 0.1rem; + margin: 1rem 0; } } diff --git a/mathesar_ui/src/pages/database/settings/collaborators/CollaboratorRow.svelte b/mathesar_ui/src/pages/database/settings/collaborators/CollaboratorRow.svelte index 076a27e7e3..7b57eb2433 100644 --- a/mathesar_ui/src/pages/database/settings/collaborators/CollaboratorRow.svelte +++ b/mathesar_ui/src/pages/database/settings/collaborators/CollaboratorRow.svelte @@ -6,12 +6,17 @@ import { DatabaseSettingsRouteContext } from '@mathesar/contexts/DatabaseSettingsRouteContext'; import { iconDeleteMajor, iconEdit } from '@mathesar/icons'; import type { Collaborator } from '@mathesar/models/Collaborator'; - import { confirmDelete } from '@mathesar/stores/confirmation'; + import type { Database } from '@mathesar/models/Database'; + import { confirm } from '@mathesar/stores/confirmation'; import { toast } from '@mathesar/stores/toast'; import { getUserProfileStoreFromContext } from '@mathesar/stores/userProfile'; import { Button, SpinnerButton } from '@mathesar-component-library'; + import RemoveCollaboratorBody from './RemoveCollaboratorBody.svelte'; + import RemoveCollaboratorTitle from './RemoveCollaboratorTitle.svelte'; + export let collaborator: Collaborator; + export let database: Pick; export let onClickEditRole: (collaborator: Collaborator) => void; export let onDelete: (collaborator: Collaborator) => void; @@ -57,23 +62,42 @@ appearance="secondary" on:click={() => onClickEditRole(collaborator)} disabled={!isMathesarAdmin} + tooltip={$_('change_role')} >
+ - confirmDelete({ - identifierName: userName, - identifierType: $_('collaborator'), + confirm({ + title: { + component: RemoveCollaboratorTitle, + props: { + userName, + databaseName: database.name, + }, + }, + body: { + component: RemoveCollaboratorBody, + props: { + userName, + databaseName: database.name, + roleName: configuredRole?.name, + }, + }, + proceedButton: { + label: $_('remove_collaborator'), + }, })} onClick={deleteCollaborator} icon={{ ...iconDeleteMajor, size: '0.8em' }} label="" - appearance="secondary" + tooltip={$_('remove_collaborator')} disabled={!isMathesarAdmin} /> diff --git a/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte b/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte index 605782a262..d8f2f46476 100644 --- a/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte +++ b/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte @@ -102,6 +102,7 @@ {$_('actions')} {#each collaboratorsList as collaborator (collaborator.id)} form.reset()}> - {$_('edit_role_for_collaborator_value', { - values: { - collaborator: userName, - }, - })} + + {#if slotName === 'userName'} + {userName} + {/if} +
diff --git a/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorBody.svelte b/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorBody.svelte new file mode 100644 index 0000000000..db7d7db946 --- /dev/null +++ b/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorBody.svelte @@ -0,0 +1,36 @@ + + +
    +
  • + + {#if slotName === 'userName'} + {userName} + {:else if slotName === 'databaseName'} + {databaseName} + {/if} + +
    • +
  • + + {#if slotName === 'userName'} + {userName} + {/if} + +
    • +
  • + + {#if slotName === 'roleName'} + {roleName} + {/if} + +
    • +
diff --git a/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorTitle.svelte b/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorTitle.svelte new file mode 100644 index 0000000000..eef9f6c365 --- /dev/null +++ b/mathesar_ui/src/pages/database/settings/collaborators/RemoveCollaboratorTitle.svelte @@ -0,0 +1,20 @@ + + + + {#if slotName === 'userName'} + {userName} + {:else if slotName === 'databaseName'} + {databaseName} + {/if} + diff --git a/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte b/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte index 10d0b3b77a..ddb214b67e 100644 --- a/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte +++ b/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte @@ -8,7 +8,9 @@ requiredField, } from '@mathesar/components/form'; import Field from '@mathesar/components/form/Field.svelte'; + import Identifier from '@mathesar/components/Identifier.svelte'; import WarningBox from '@mathesar/components/message-boxes/WarningBox.svelte'; + import RichText from '@mathesar/components/rich-text/RichText.svelte'; import { type CombinedLoginRole, DatabaseSettingsRouteContext, @@ -43,9 +45,11 @@ form.reset()}> - {$_('configure_value', { - values: { value: combinedLoginRole.name }, - })} + + {#if slotName === 'role'} + {combinedLoginRole.name} + {/if} +
diff --git a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte index 8b038f39ae..91b5d60929 100644 --- a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte +++ b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte @@ -5,15 +5,12 @@ import GridTableCell from '@mathesar/components/grid-table/GridTableCell.svelte'; import ErrorBox from '@mathesar/components/message-boxes/ErrorBox.svelte'; import PhraseContainingIdentifier from '@mathesar/components/PhraseContainingIdentifier.svelte'; + import Yes from '@mathesar/components/Yes.svelte'; import { type CombinedLoginRole, DatabaseSettingsRouteContext, } from '@mathesar/contexts/DatabaseSettingsRouteContext'; - import { - iconConfigurePassword, - iconDeleteMajor, - iconEdit, - } from '@mathesar/icons'; + import { iconAddNew, iconDeleteMajor, iconEdit } from '@mathesar/icons'; import AsyncRpcApiStore from '@mathesar/stores/AsyncRpcApiStore'; import { confirm } from '@mathesar/stores/confirmation'; import { modal } from '@mathesar/stores/modal'; @@ -68,7 +65,7 @@ - {$_('role_configuration')} + {$_('stored_role_passwords')} {#if isLoading} @@ -77,7 +74,7 @@
{$_('role')} - {$_('actions')} + {$_('stored_password')} {#each $combinedLoginRoles as combinedLoginRole (combinedLoginRole.name)} @@ -86,55 +83,64 @@ - {#if combinedLoginRole.configuredRole} +
+
+ {#if combinedLoginRole.configuredRole} + + {/if} +
- - - confirm({ - title: { - component: PhraseContainingIdentifier, - props: { - identifier: combinedLoginRole.name, - wrappingString: $_( - 'remove_configuration_for_identifier', - ), + {#if combinedLoginRole.configuredRole} + + + confirm({ + title: { + component: PhraseContainingIdentifier, + props: { + identifier: combinedLoginRole.name, + wrappingString: $_( + 'remove_stored_password_for_identifier', + ), + }, }, - }, - body: $_('removing_role_configuration_warning', { - values: { - server: - combinedLoginRole.configuredRole?.database.server.getConnectionString(), + body: $_('removing_role_configuration_warning', { + values: { + server: + combinedLoginRole.configuredRole?.database.server.getConnectionString(), + }, + }), + proceedButton: { + label: $_('remove_configuration'), + icon: iconDeleteMajor, }, - }), - proceedButton: { - label: $_('remove_configuration'), - icon: iconDeleteMajor, - }, - })} - label={$_('remove')} - onClick={() => removeConfiguredRole(combinedLoginRole)} - /> + })} + label="" + tooltip={$_('remove_stored_password')} + icon={iconDeleteMajor} + onClick={() => removeConfiguredRole(combinedLoginRole)} + /> + {:else if combinedLoginRole.role} + + {/if}
- {:else if combinedLoginRole.role} - - {/if} +
{/each} @@ -164,10 +170,16 @@ diff --git a/mathesar_ui/src/pages/database/settings/roles/ModifyRoleMembers.svelte b/mathesar_ui/src/pages/database/settings/roles/ModifyRoleMembers.svelte index 1b02217d59..5d7dced35f 100644 --- a/mathesar_ui/src/pages/database/settings/roles/ModifyRoleMembers.svelte +++ b/mathesar_ui/src/pages/database/settings/roles/ModifyRoleMembers.svelte @@ -6,8 +6,10 @@ makeForm, requiredField, } from '@mathesar/components/form'; + import Identifier from '@mathesar/components/Identifier.svelte'; import InfoBox from '@mathesar/components/message-boxes/InfoBox.svelte'; import WarningBox from '@mathesar/components/message-boxes/WarningBox.svelte'; + import RichText from '@mathesar/components/rich-text/RichText.svelte'; import { iconDeleteMajor } from '@mathesar/icons'; import type { Role } from '@mathesar/models/Role'; import { toast } from '@mathesar/stores/toast'; @@ -60,11 +62,11 @@ form.reset()}> - {$_('edit_child_roles_for_parent', { - values: { - parent: parentRole.name, - }, - })} + + {#if slotName === 'parent'} + {parentRole.name} + {/if} +
diff --git a/mathesar_ui/src/pages/database/settings/roles/RoleRow.svelte b/mathesar_ui/src/pages/database/settings/roles/RoleRow.svelte index b5f49a1382..10f5e202d9 100644 --- a/mathesar_ui/src/pages/database/settings/roles/RoleRow.svelte +++ b/mathesar_ui/src/pages/database/settings/roles/RoleRow.svelte @@ -3,6 +3,8 @@ import GridTableCell from '@mathesar/components/grid-table/GridTableCell.svelte'; import PhraseContainingIdentifier from '@mathesar/components/PhraseContainingIdentifier.svelte'; + import RichText from '@mathesar/components/rich-text/RichText.svelte'; + import Yes from '@mathesar/components/Yes.svelte'; import { DatabaseSettingsRouteContext } from '@mathesar/contexts/DatabaseSettingsRouteContext'; import { iconDeleteMajor, iconEdit } from '@mathesar/icons'; import type { Role } from '@mathesar/models/Role'; @@ -14,6 +16,7 @@ Icon, type ImmutableMap, SpinnerButton, + isDefinedNonNullable, } from '@mathesar-component-library'; const routeContext = DatabaseSettingsRouteContext.get(); @@ -23,7 +26,12 @@ export let onClickEditMembers: (role: Role) => void; export let onDrop: (role: Role) => void; - $: members = role.members; + $: membersMap = role.members; + $: memberIds = [...$membersMap.keys()]; + $: memberNames = memberIds + .map((id) => rolesMap.get(id)?.name) + .filter(isDefinedNonNullable) + .sort(); async function dropRole() { try { @@ -39,20 +47,25 @@ {role.name} {#if role.login} - {$_('yes')} + {/if}
-
- {#each [...$members.values()] as member (member.oid)} - - {rolesMap.get(member.oid)?.name ?? ''} - +
    + {#each memberNames as member (member)} +
  • {member}
    • {/each} -
+
@@ -66,8 +79,9 @@ title: { component: PhraseContainingIdentifier, props: { + identifierKey: 'name', identifier: role.name, - wrappingString: $_('drop_role_with_identifier'), + wrappingString: $_('drop_role_name_question'), }, }, body: [ @@ -80,7 +94,9 @@ icon: iconDeleteMajor, }, })} - label={$_('drop_role')} + label="" + tooltip={$_('drop_role')} + icon={iconDeleteMajor} onClick={dropRole} /> @@ -90,14 +106,14 @@ display: flex; width: 100%; align-items: center; + } - .role-list { - display: flex; - gap: 6px; - } + .role-list { + margin: 0; + padding: 0 0 0 1rem; + } - .actions { - margin-left: auto; - } + .actions { + margin-left: auto; } diff --git a/mathesar_ui/src/routes/DatabaseSettingsRoute.svelte b/mathesar_ui/src/routes/DatabaseSettingsRoute.svelte index 10f6470677..d507e5df96 100644 --- a/mathesar_ui/src/routes/DatabaseSettingsRoute.svelte +++ b/mathesar_ui/src/routes/DatabaseSettingsRoute.svelte @@ -14,7 +14,7 @@ - + setSection('roleConfiguration')} From 0b972270f8af669a7a7f7fce3b927e75d03fb225 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 20 Nov 2024 15:23:28 -0500 Subject: [PATCH 02/27] Use "Privileges" terminology in UI --- mathesar_ui/src/i18n/languages/en/dict.json | 17 ++++++----------- mathesar_ui/src/i18n/languages/ja/dict.json | 7 ------- .../permissions/DatabasePermissionsModal.svelte | 2 +- .../pages/schema/SchemaPermissionsModal.svelte | 2 +- .../permissions/overview/AccessControl.svelte | 2 +- .../overview/AccessControlRow.svelte | 2 +- 6 files changed, 10 insertions(+), 22 deletions(-) diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 8747b9ef31..92d0b564f2 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -1,11 +1,7 @@ { - "access_custom_help": "Custom permissions", + "access_custom_help": "Custom privileges", "access_for_roles_saved_successfully": "Access for roles have been saved successfully.", "access_level_cannot_remove_warning": "This access level cannot be removed.", - "access_level_inheritance_help": "This access level is inherited from the {aclObject} permissions.", - "access_level_inheritance_is_overridden_help": "This access level is inherited from the {aclObject} permissions and is overridden by the {comparedAclObject} permissions.", - "access_level_is_overridden_help": "This access level is overridden by the {comparedAclObject} permissions.", - "access_level_overrides_help": "This access level overrides the {comparedAclObject} permissions.", "access_level_precedence_help": "If a user has different access levels on the database and the schema, the access level of schema will take precedence.", "access_not_granted_for_any_role": "Access has not been granted for any role.", "account_details": "Account Details", @@ -69,7 +65,7 @@ "collaborator": "Collaborator", "collaborator_added_successfully": "Collaborator added successfully", "collaborator_removed_successfully": "Collaborator removed successfully", - "collaborator_role_help": "This role determines permissions for this collaborator. Mathesar will use this PostgreSQL role for all database interactions by this user.", + "collaborator_role_help": "Mathesar will use this PostgreSQL role for all database interactions by this user. The role will determine the access that the user has to data.", "collaborator_role_updated_successfully": "Role updated successfully for collaborator.", "collaborators": "Collaborators", "column": "Column", @@ -123,6 +119,8 @@ "count_records_deleted_successfully": "{count, plural, one {{count} record deleted successfully!} other {{count} records deleted successfully!}}", "count_tables": "{count, plural, one {{count} table} other {{count} tables}}", "create": "Create", + "connect_and_create": "Connect + Create", + "read_and_create": "Read + Create", "create_a_table_by_importing": "Create a table by importing your data", "create_database": "Create Database", "create_database_mathesar_internal_server": "Create a new PostgreSQL database on Mathesar's internal server", @@ -277,7 +275,7 @@ "go_to_record": "Go To Record", "go_to_record_page": "Go to Record Page", "go_to_record_with_value": "Go To Record {value}", - "granted_access": "Granted Access", + "granted_privileges": "Granted Privileges", "group": "Group", "group_by_column": "Group by Column", "group_records_by": "Group records by", @@ -295,7 +293,6 @@ "in_mathesar": "In Mathesar", "in_postgresql": "In PostgreSQL", "in_this_table": "In this table", - "individual_permissions_admin_modify_warning": "Individual permissions cannot be modified for users with Admin access.", "inherited": "Inherited", "inherited_access_level_cannot_remove_warning": "This access level is inherited and cannot be removed from this panel.", "inspector": "Inspector", @@ -433,7 +430,6 @@ "password_stored": "Password Stored", "passwords_do_not_match": "Passwords do not match", "paste_data_import": "Paste the data you want to import", - "permission": "Permission", "pick": "Pick", "pick_best_data_type_column": "Pick the best data type for each column", "pick_record": "Pick a record", @@ -507,7 +503,7 @@ "role_dropped_successfully": "The Role has been dropped successfully", "role_has_no_child_roles": "The Role does not have any Child Roles", "role_name": "Role Name", - "role_permissions": "Role Permissions", + "role_privileges": "Role Privileges", "roles": "Roles", "row": "Row", "running_latest_version": "You are running the latest version", @@ -554,7 +550,6 @@ "select_columns_move_into_table": "Select the columns you want to move into [targetTableName]", "select_columns_to_hide": "Select Columns to Hide", "select_columns_view_properties": "Select a column to view it's properties.", - "select_permission": "Select Permission", "select_role": "Select Role", "select_table": "Select Table", "select_type": "Select Type", diff --git a/mathesar_ui/src/i18n/languages/ja/dict.json b/mathesar_ui/src/i18n/languages/ja/dict.json index f5c8191c51..85d27b57d8 100644 --- a/mathesar_ui/src/i18n/languages/ja/dict.json +++ b/mathesar_ui/src/i18n/languages/ja/dict.json @@ -1,9 +1,5 @@ { "access_level_cannot_remove_warning": "このアクセスレベルは削除できません。", - "access_level_inheritance_help": "このアクセスレベルは{aclObject}のアクセス許可から継承されます。", - "access_level_inheritance_is_overridden_help": "このアクセスレベルは{aclObject}のアクセス許可から継承され、{comparedAclObject}のアクセス許可によってオーバーライドされます。", - "access_level_is_overridden_help": "このアクセスレベルは{comparedAclObject}のアクセス許可によってオーバーライドされます。", - "access_level_overrides_help": "このアクセスレベルは{comparedAclObject}のアクセス許可をオーバーライドします。", "access_level_precedence_help": "ユーザーがデータベースとスキーマで異なるアクセスレベルを持つ場合、スキーマのアクセスレベルが優先されます。", "account_details": "アカウントの詳細", "action_cannot_be_undone": "この操作は元に戻せません", @@ -247,7 +243,6 @@ "import": "インポート", "import_from_file": "ファイルからインポート", "in_this_table": "このテーブルで", - "individual_permissions_admin_modify_warning": "管理者権限を持つユーザーに対しては、個々の権限を変更することはできません。", "inherited": "継承済み", "inherited_access_level_cannot_remove_warning": "このアクセスレベルは継承され、このパネルから削除することはできません。", "inspector": "インスペクタ", @@ -372,7 +367,6 @@ "password_encryption_help_plus_storage": "このパスワードはMathesarの秘密鍵でAES暗号化され、Mathesarの内部データベースに保存されます。Mathesarの外部からもこのデータベースに接続できるように、別の場所に保存してください。", "passwords_do_not_match": "パスワードが一致していません", "paste_data_import": "インポートしたいデータを貼り付けます", - "permission": "権限", "pick": "選択", "pick_best_data_type_column": "各列に最適なデータ型を選択する", "pick_record": "レコードを選択", @@ -457,7 +451,6 @@ "select_columns_move_into_table": "[targetTableName]に移動したい列を選択する", "select_columns_to_hide": "非表示にする列を選択する", "select_columns_view_properties": "プロパティを表示するには、列を選択してください。", - "select_permission": "許可を選択する", "select_table": "テーブルを選択する", "select_type": "タイプを選択する", "select_user": "ユーザーを選択する", diff --git a/mathesar_ui/src/pages/database/permissions/DatabasePermissionsModal.svelte b/mathesar_ui/src/pages/database/permissions/DatabasePermissionsModal.svelte index 215337f097..9622c4b490 100644 --- a/mathesar_ui/src/pages/database/permissions/DatabasePermissionsModal.svelte +++ b/mathesar_ui/src/pages/database/permissions/DatabasePermissionsModal.svelte @@ -56,7 +56,7 @@ { id: 'connect_and_create', privileges: new Set(['CONNECT', 'CREATE']), - name: $_('create'), + name: $_('connect_and_create'), help: $_('database_access_create_help'), }, ], diff --git a/mathesar_ui/src/pages/schema/SchemaPermissionsModal.svelte b/mathesar_ui/src/pages/schema/SchemaPermissionsModal.svelte index 452f9970d6..29c42ed6d9 100644 --- a/mathesar_ui/src/pages/schema/SchemaPermissionsModal.svelte +++ b/mathesar_ui/src/pages/schema/SchemaPermissionsModal.svelte @@ -57,7 +57,7 @@ { id: 'read_and_create', privileges: new Set(['USAGE', 'CREATE']), - name: $_('create'), + name: $_('read_and_create'), help: $_('schema_access_create_help'), }, ], diff --git a/mathesar_ui/src/systems/permissions/overview/AccessControl.svelte b/mathesar_ui/src/systems/permissions/overview/AccessControl.svelte index 27b925dc04..f5a2e8ef1e 100644 --- a/mathesar_ui/src/systems/permissions/overview/AccessControl.svelte +++ b/mathesar_ui/src/systems/permissions/overview/AccessControl.svelte @@ -124,7 +124,7 @@ } - + {#if $currentRoleOwns}
- {$_('role_permissions')} + {$_('role_privileges')}
Date: Tue, 26 Nov 2024 12:38:53 -0500 Subject: [PATCH 03/27] Improve UI in References inspector section --- .../src/components/FieldDelimiter.svelte | 19 +++ mathesar_ui/src/i18n/languages/en/dict.json | 16 ++- mathesar_ui/src/i18n/languages/ja/dict.json | 2 - .../link-table/LinkTableForm.svelte | 2 +- .../link-table/LinkTableModal.svelte | 2 +- .../record-summary/FieldChain.svelte | 9 +- .../table-inspector/table/TableMode.svelte | 2 +- .../table/links/ForwardLinkCard.svelte | 42 ++++++ .../table/links/LinkCard.svelte | 53 +++++++ .../table/links/LinkItem.svelte | 56 -------- .../table/links/LinkSection.svelte | 61 -------- .../table/links/LinksContent.svelte | 130 ++++++++++++++++++ .../table/links/LinksSectionContainer.svelte | 101 -------------- .../table/links/ReverseLinkCard.svelte | 43 ++++++ .../table/links/TableLinks.svelte | 5 +- .../table-inspector/table/links/utils.ts | 41 +++++- 16 files changed, 347 insertions(+), 237 deletions(-) create mode 100644 mathesar_ui/src/components/FieldDelimiter.svelte create mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/ForwardLinkCard.svelte create mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkCard.svelte delete mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkItem.svelte delete mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkSection.svelte create mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksContent.svelte delete mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksSectionContainer.svelte create mode 100644 mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte diff --git a/mathesar_ui/src/components/FieldDelimiter.svelte b/mathesar_ui/src/components/FieldDelimiter.svelte new file mode 100644 index 0000000000..3a1528513c --- /dev/null +++ b/mathesar_ui/src/components/FieldDelimiter.svelte @@ -0,0 +1,19 @@ + + + + + + + diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 92d0b564f2..5b8eca3b6c 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -97,6 +97,7 @@ "confirm_delete_table": "To confirm the deletion of the [tableName] table, please enter the table name into the input field below.", "confirm_password": "Confirm Password", "connect": "Connect", + "connect_and_create": "Connect + Create", "connect_database": "Connect Database", "connect_existing_database": "Connect to an Existing Database", "connect_with_community_help": "Connect with Mathesar users and contributors in our community chat. Share ideas, get help, and contribute to discussions.", @@ -119,8 +120,6 @@ "count_records_deleted_successfully": "{count, plural, one {{count} record deleted successfully!} other {{count} records deleted successfully!}}", "count_tables": "{count, plural, one {{count} table} other {{count} tables}}", "create": "Create", - "connect_and_create": "Connect + Create", - "read_and_create": "Read + Create", "create_a_table_by_importing": "Create a table by importing your data", "create_database": "Create Database", "create_database_mathesar_internal_server": "Create a new PostgreSQL database on Mathesar's internal server", @@ -131,6 +130,7 @@ "create_new_pg_user": "Create a new PostgreSQL user", "create_new_schema": "Create New Schema", "create_record_from_search": "Create Record From Search Criteria", + "create_reference": "Create Reference", "create_role": "Create Role", "create_schema": "Create Schema", "create_share_explorations_of_your_data": "Create and Share Explorations of Your Data", @@ -262,7 +262,6 @@ "from_base_table": "From Base Table", "from_data_import": "From Data Import", "from_linked_tables": "From Linked Tables", - "from_other_tables": "From other tables", "from_scratch": "From Scratch", "get_started_by_adding_columns_from_left": "Get started by adding columns from the left", "get_started_by_adding_table_and_columns": "Get started by selecting a table and adding columns", @@ -292,7 +291,7 @@ "import_from_file": "Import from a File", "in_mathesar": "In Mathesar", "in_postgresql": "In PostgreSQL", - "in_this_table": "In this table", + "in_this_table": "In This Table", "inherited": "Inherited", "inherited_access_level_cannot_remove_warning": "This access level is inherited and cannot be removed from this panel.", "inspector": "Inspector", @@ -315,10 +314,8 @@ "linked_table": "Linked Table", "linked_to": "Linked To", "linked_to_base_table": "Linked to Base Table", - "linked_via_column": "Linked via [columnName]", "linked_via_foreign_key_column": "It is linked via a foreign key column", "linking_table": "Linking Table", - "links": "Links", "links_info": "For existing columns, add foreign key constraints in the \"Advanced\" section to turn them into links", "loading": "Loading", "loading_release_data": "Loading release data", @@ -450,6 +447,7 @@ "provide_url_to_file": "Provide a URL to the file", "public_schema_info": "Every PostgreSQL database includes the \"public\" schema. This protected schema can be read by anybody who accesses the database.", "read": "Read", + "read_and_create": "Read + Create", "read_release_notes": "Read the [releaseNotesLink](release notes) to see if this release requires any special upgrade instructions.", "readonly_access": "Read-Only Access", "record": "Record", @@ -464,6 +462,9 @@ "recover_query_click_button": "You can attempt to recover the query by clicking on the button below.", "redirected_login_page_password_change": "You'll be redirected to the login page once you change your password.", "redo": "Redo", + "reference_references_referent": "[reference] references [referent]", + "referenced_via_reference": "Referenced via [reference]", + "references": "References", "referencing_column": "Referencing Column", "refresh": "Refresh", "regenerate_link": "Regenerate Link", @@ -594,6 +595,8 @@ "table": "Table", "table_access_read_help": "Can read table records", "table_access_write_help": "Can read, update, delete, and create table records", + "table_can_have_many": "[bold](Many) of each can reference one [tableName] record.", + "table_can_have_one": "One [tableName] record can reference [bold](one) of each.", "table_delete_permanent_warning": "Warning: This action is permanent and once deleted, the table cannot be recovered.", "table_does_not_link": "This table does not link to any other tables", "table_name": "Table Name", @@ -626,6 +629,7 @@ "this_will_remove_following_columns": "This will remove the following column(s):", "this_will_remove_following_transformations": "This will remove the following transformation(s):", "time_to_create_exploration": "It's time to use your tables. Create your first exploration.", + "to_this_table": "To This Table", "today": "Today", "transfer_ownership": "Transfer Ownership", "transform_results": "Transform Results", diff --git a/mathesar_ui/src/i18n/languages/ja/dict.json b/mathesar_ui/src/i18n/languages/ja/dict.json index 85d27b57d8..c98417fdcb 100644 --- a/mathesar_ui/src/i18n/languages/ja/dict.json +++ b/mathesar_ui/src/i18n/languages/ja/dict.json @@ -216,7 +216,6 @@ "from_base_table": "ベーステーブルから", "from_data_import": "データインポートから", "from_linked_tables": "リンクされたテーブルから", - "from_other_tables": "他のテーブルから", "from_scratch": "ゼロから", "get_started_by_adding_columns_from_left": "左から列を追加して開始", "get_started_by_adding_table_and_columns": "テーブルを選択し、列を追加して開始", @@ -264,7 +263,6 @@ "linked_table": "リンクされたテーブル", "linked_to": "リンク先：", "linked_to_base_table": "ベーステーブルにリンクされています", - "linked_via_column": "[columnName]を介してリンクされています", "linked_via_foreign_key_column": "外部キー列を介してリンクされています", "linking_table": "リンクテーブル", "links": "リンク", diff --git a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte index 5a5d15d98c..03241544c9 100644 --- a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte @@ -394,7 +394,7 @@ catchErrors {canProceed} onCancel={close} - proceedButton={{ label: $_('create_link'), icon: iconTableLink }} + proceedButton={{ label: $_('create_reference'), icon: iconTableLink }} onProceed={handleSave} />
diff --git a/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte b/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte index 865d9a169c..9c17e42c05 100644 --- a/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte @@ -13,7 +13,7 @@ {#if $currentTable} - + controller.close()} /> {/if} diff --git a/mathesar_ui/src/systems/table-view/table-inspector/record-summary/FieldChain.svelte b/mathesar_ui/src/systems/table-view/table-inspector/record-summary/FieldChain.svelte index 999c39d9b8..ab9d77de99 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/record-summary/FieldChain.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/record-summary/FieldChain.svelte @@ -1,9 +1,9 @@ + +{#if href} + + + + + {#if slotName === 'reference'} + + + + {/if} + + + +{/if} diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkCard.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkCard.svelte new file mode 100644 index 0000000000..d7725f79a5 --- /dev/null +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkCard.svelte @@ -0,0 +1,53 @@ + + + +
+
+ +
+
+ +
+
+ + + diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkItem.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkItem.svelte deleted file mode 100644 index d701cea97f..0000000000 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkItem.svelte +++ /dev/null @@ -1,56 +0,0 @@ - - - - - - - {#if link.column} - - - {#if slotName === 'columnName'} - {link.column.name} - {/if} - - - {/if} - - - diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkSection.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkSection.svelte deleted file mode 100644 index 5c3248d210..0000000000 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinkSection.svelte +++ /dev/null @@ -1,61 +0,0 @@ - - -
-
-
- - {title} -
-
-
- {#each links as link} - - {/each} -
-
- - diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksContent.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksContent.svelte new file mode 100644 index 0000000000..79b78b37cf --- /dev/null +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksContent.svelte @@ -0,0 +1,130 @@ + + +
+ {#if linksInThisTable.length} +
+
+ + {$_('in_this_table')} + + + {#if slotName === 'tableName'} + + {:else if slotName === 'bold'} + {translatedArg} + {/if} + + +
+
+ {#each linksInThisTable as link} + + {/each} +
+
+ {/if} + + {#if linksFromOtherTables.length} +
+
+ + {$_('to_this_table')} + + + {#if slotName === 'tableName'} + + {:else if slotName === 'bold'} + {translatedArg} + {/if} + + +
+ +
+ {#each linksFromOtherTables as link} + + {/each} +
+
+ {/if} + + {#if showNullState} + {$_('table_does_not_link')} + {/if} + +
+ + +
+
+ + diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksSectionContainer.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksSectionContainer.svelte deleted file mode 100644 index ad3cabf93c..0000000000 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/LinksSectionContainer.svelte +++ /dev/null @@ -1,101 +0,0 @@ - - -
- {#if linksInThisTable.length} - - {/if} - {#if linksFromOtherTables.length} - - {/if} - {#if showNullState} - {$_('table_does_not_link')} - {/if} -
- - -
-
- - diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte new file mode 100644 index 0000000000..4d5c35e797 --- /dev/null +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte @@ -0,0 +1,43 @@ + + +{#if href} + + + + + {#if slotName === 'reference'} + + + {:else if slotName === 'referent'} + + {/if} + + + +{/if} diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/TableLinks.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/TableLinks.svelte index 0cf88edc4f..38880e1b50 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/TableLinks.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/TableLinks.svelte @@ -5,7 +5,7 @@ import { getTabularDataStoreFromContext } from '@mathesar/stores/table-data'; import { getErrorMessage } from '@mathesar/utils/errors'; - import LinksSectionContainer from './LinksSectionContainer.svelte'; + import LinksContent from './LinksContent.svelte'; const tabularData = getTabularDataStoreFromContext(); @@ -27,7 +27,8 @@ {#await getJoinableTables(table.schema.database.id, table.oid)} {:then joinableTablesResult} - diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/utils.ts b/mathesar_ui/src/systems/table-view/table-inspector/table/links/utils.ts index 27d1f8f4be..ce1dd5993c 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/utils.ts +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/utils.ts @@ -1,4 +1,41 @@ +import type { JoinableTablesResult } from '@mathesar/api/rpc/tables'; +import type { ProcessedColumn } from '@mathesar/stores/table-data'; + export type TableLink = { - table: { id: number; name: string }; - column?: { name: string }; + table: { oid: number; name: string }; + column: { name: string }; }; + +export function* getLinksInThisTable( + joinableTablesResult: JoinableTablesResult, + currentTableColumns: Map, +): Generator { + const joinableTables = joinableTablesResult.joinable_tables; + const linkedTables = joinableTables.filter((t) => !t.fkey_path[0][1]); + for (const joinableTable of linkedTables) { + const table = joinableTablesResult.target_table_info[joinableTable.target]; + const columnId = joinableTable.join_path[0][0][1]; + const column = currentTableColumns.get(columnId); + if (column) { + yield { + table: { oid: joinableTable.target, name: table.name }, + column: { name: column.column.name }, + }; + } + } +} + +export function* getLinksToThisTable( + joinableTablesResult: JoinableTablesResult, +): Generator { + const joinableTables = joinableTablesResult.joinable_tables; + const linkedTables = joinableTables.filter((t) => t.fkey_path[0][1]); + for (const joinableTable of linkedTables) { + const table = joinableTablesResult.target_table_info[joinableTable.target]; + const columnId = joinableTable.join_path[0][1][1]; + yield { + table: { oid: joinableTable.target, name: table.name }, + column: table.columns[columnId], + }; + } +} From 4c733e686950d56af09ec298ebfb113d1a1e6d52 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 12:47:29 -0500 Subject: [PATCH 04/27] Adjust DB help text for inspector section headers --- mathesar_ui/src/i18n/languages/en/dict.json | 3 ++- mathesar_ui/src/i18n/languages/ja/dict.json | 1 - .../table-inspector/CollapsibleHeader.svelte | 13 +++++++++---- .../table-inspector/table/TableMode.svelte | 6 +++++- 4 files changed, 16 insertions(+), 7 deletions(-) diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 5b8eca3b6c..c9d33ec7d3 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -278,6 +278,7 @@ "group": "Group", "group_by_column": "Group by Column", "group_records_by": "Group records by", + "help": "Help", "hide_columns": "Hide Columns", "host": "Host", "host_name": "Host name", @@ -539,7 +540,7 @@ "search_tables": "Search Tables", "search_users": "Search Users", "seconds": "Seconds", - "section_affects_database_config": "This section affects the configuration of the database.", + "section_affects_postgresql_config": "This configuration in this section is stored within the connected PostgreSQL database.", "select_cell_view_properties": "Select a cell to view it's properties.", "select_cells_view_record_props": "Select one or more cells to view associated record properties.", "select_columns": "Select Columns", diff --git a/mathesar_ui/src/i18n/languages/ja/dict.json b/mathesar_ui/src/i18n/languages/ja/dict.json index c98417fdcb..2c6daec86d 100644 --- a/mathesar_ui/src/i18n/languages/ja/dict.json +++ b/mathesar_ui/src/i18n/languages/ja/dict.json @@ -437,7 +437,6 @@ "search_tables": "テーブルの検索", "search_users": "ユーザーの検索", "seconds": "秒", - "section_affects_database_config": "このセクションはデータベースの設定に影響します。", "select_cell_view_properties": "プロパティを表示するにはセルを選択してください。", "select_cells_view_record_props": "関連するレコードのプロパティを表示するには、1 つ以上のセルを選択してください。", "select_columns": "列を選択", diff --git a/mathesar_ui/src/systems/table-view/table-inspector/CollapsibleHeader.svelte b/mathesar_ui/src/systems/table-view/table-inspector/CollapsibleHeader.svelte index 4671649a8b..5e14bed3d2 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/CollapsibleHeader.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/CollapsibleHeader.svelte @@ -2,16 +2,21 @@ import { _ } from 'svelte-i18n'; import { iconDatabase } from '@mathesar/icons'; - import { Icon } from '@mathesar-component-library'; + import { Icon, Tooltip } from '@mathesar-component-library'; - export let title: string; + export let title: string | undefined = undefined; export let isDbLevelConfiguration = false;
- {title} +
+ {title} +
{#if isDbLevelConfiguration} - + + + {$_('section_affects_postgresql_config')} + {/if}
diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte index 5ae7274078..8c4145107f 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte @@ -47,7 +47,11 @@ bind:isOpen={$tableInspectorTablePermissionsVisible} triggerAppearance="inspector" > - +
From c8afbf22a89b7a37952971c7bc1463d338fe3d4c Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 13:13:15 -0500 Subject: [PATCH 05/27] Trim child margins within all tooltips --- mathesar_ui/src/App.svelte | 7 ------- mathesar_ui/src/component-library/common/styles/main.scss | 7 +++++++ mathesar_ui/src/component-library/tooltip/Tooltip.svelte | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/mathesar_ui/src/App.svelte b/mathesar_ui/src/App.svelte index 5b59698d6d..152afce12c 100644 --- a/mathesar_ui/src/App.svelte +++ b/mathesar_ui/src/App.svelte @@ -173,13 +173,6 @@ display: block; } - .trim-child-margins > :first-child { - margin-top: 0; - } - .trim-child-margins > :last-child { - margin-bottom: 0; - } - /** * Used to turn elements like `
@@ -122,7 +138,6 @@ } .header { margin-bottom: 0.5rem; - font-weight: var(--font-weight-medium); } .links > :global(* + *) { margin-top: 0.7rem; From 7f5dba07c5558794df5c85efc86e0c3103915f41 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 16:59:02 -0500 Subject: [PATCH 08/27] Polish some copy in data explorer --- mathesar_ui/src/i18n/languages/en/dict.json | 10 +++++----- mathesar_ui/src/i18n/languages/ja/dict.json | 5 ----- .../column-selection-pane/ColumnSelectionPane.svelte | 6 +++--- 3 files changed, 8 insertions(+), 13 deletions(-) diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 01575a2903..831ecab6a3 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -263,7 +263,7 @@ "formatting": "Formatting", "from_base_table": "From Base Table", "from_data_import": "From Data Import", - "from_linked_tables": "From Linked Tables", + "from_related_tables": "From Related Tables", "from_scratch": "From Scratch", "get_started_by_adding_columns_from_left": "Get started by adding columns from the left", "get_started_by_adding_table_and_columns": "Get started by selecting a table and adding columns", @@ -309,11 +309,9 @@ "learn_implications_deleting_mathesar_schemas": "Learn more about the implications of deleting Mathesar schemas.", "link_copied": "Link copied", "link_successfully_regenerated": "The link has been successfully regenerated", - "linked_from_base_table": "Linked from Base Table", "linked_record_summary": "Linked Record Summary", "linked_table": "Linked Table", "linked_to": "Linked To", - "linked_to_base_table": "Linked to Base Table", "linked_via_foreign_key_column": "It is linked via a foreign key column", "loading": "Loading", "loading_release_data": "Loading release data", @@ -400,7 +398,7 @@ "number_of_matches_in_category": "{count, plural, one {{count} match for [searchValue] in [categoryName]} other {{count} matches for [searchValue] in [categoryName]}}", "old_password": "Old Password", "oldest_to_newest_sort": "Oldest-Newest", - "one_column_from_base_is_required": "At least one column from the base table is required to add columns from linked tables.", + "one_column_from_base_is_required": "At least one column from the base table is required to add columns from related tables.", "one_to_many": "One to Many", "open": "Open", "open_data_explorer": "Open Data Explorer", @@ -460,8 +458,10 @@ "reference_references_referent": "[reference] references [referent]", "referenced_via_reference": "Referenced via [reference]", "references": "References", + "references_from_base_table": "References From Base Table", "references_help": "Relationships allow a single cell in one table to reference a row in another table using PostgreSQL \"foreign key constraints\".", "references_in_this_table": "References [bold](From) This Table", + "references_to_base_table": "References To Base Table", "references_to_this_table": "References [bold](To) This Table", "referencing_column": "Referencing Column", "refresh": "Refresh", @@ -550,7 +550,7 @@ "select_columns_cells_view_properties": "Select one or more columns or cells to view the associated column properties and actions.", "select_columns_extract": "Select the columns you want to extract", "select_columns_extract_into_table": "Select the columns you want to extract into [targetTableName]", - "select_columns_for_exploration_help": "Select the columns that will be used for the exploration. Columns are limited to those from the base table and its linked tables.", + "select_columns_for_exploration_help": "Select the columns that will be used for the exploration. Columns are limited to those from the base table and its related tables.", "select_columns_move": "Select the columns you want to move", "select_columns_move_into_table": "Select the columns you want to move into [targetTableName]", "select_columns_to_hide": "Select Columns to Hide", diff --git a/mathesar_ui/src/i18n/languages/ja/dict.json b/mathesar_ui/src/i18n/languages/ja/dict.json index 4d1975c50d..8f94dbb96f 100644 --- a/mathesar_ui/src/i18n/languages/ja/dict.json +++ b/mathesar_ui/src/i18n/languages/ja/dict.json @@ -215,7 +215,6 @@ "formatting": "フォーマットの設定", "from_base_table": "ベーステーブルから", "from_data_import": "データインポートから", - "from_linked_tables": "リンクされたテーブルから", "from_scratch": "ゼロから", "get_started_by_adding_columns_from_left": "左から列を追加して開始", "get_started_by_adding_table_and_columns": "テーブルを選択し、列を追加して開始", @@ -256,11 +255,9 @@ "learn_implications_deleting_mathesar_schemas": "Mathesarスキーマを削除することによる影響については、こちらをご覧ください。", "link_copied": "リンクをコピーしました", "link_successfully_regenerated": "リンクの再生成に成功しました", - "linked_from_base_table": "ベーステーブルからリンクされています", "linked_record_summary": "リンクされた記録の概要", "linked_table": "リンクされたテーブル", "linked_to": "リンク先：", - "linked_to_base_table": "ベーステーブルにリンクされています", "linked_via_foreign_key_column": "外部キー列を介してリンクされています", "links": "リンク", "links_info": "リンクは外部キー制約としてデータベースに保存され、外部キー制約はテーブルインスペクタの「Advanced」セクションで既存の列に追加できます。", @@ -339,7 +336,6 @@ "number_of_matches_in_category": "{count, plural, other {{count} 件が [categoryName] の [searchValue] に一致します}}", "old_password": "以前のパスワード", "oldest_to_newest_sort": "古い - 新しい", - "one_column_from_base_is_required": "リンクテーブルから列を追加するには、ベーステーブルから少なくとも1つの列が必要です。", "one_to_many": "一対多数", "open": "開く", "open_data_explorer": "データエクスプローラーを開く", @@ -435,7 +431,6 @@ "select_columns_cells_view_properties": "関連する列のプロパティとアクションを表示するには、1つ以上の列あるいはセルを選択してください。", "select_columns_extract": "抽出したい列を選択する", "select_columns_extract_into_table": "[targetTableName]に抽出したい列を選択する", - "select_columns_for_exploration_help": "探索に使用する列を選択してください。列はベーステーブルとそれにリンクされたテーブルのものに限定されます。", "select_columns_move": "移動したい列を選択する", "select_columns_move_into_table": "[targetTableName]に移動したい列を選択する", "select_columns_to_hide": "非表示にする列を選択する", diff --git a/mathesar_ui/src/systems/data-explorer/input-sidebar/column-selection-pane/ColumnSelectionPane.svelte b/mathesar_ui/src/systems/data-explorer/input-sidebar/column-selection-pane/ColumnSelectionPane.svelte index 19bf2865c7..2583593594 100644 --- a/mathesar_ui/src/systems/data-explorer/input-sidebar/column-selection-pane/ColumnSelectionPane.svelte +++ b/mathesar_ui/src/systems/data-explorer/input-sidebar/column-selection-pane/ColumnSelectionPane.svelte @@ -37,7 +37,7 @@ {#if !hasInitialColumns && (hasLinksFromBaseTable || hasLinksToBaseTable)}
-
{$_('from_linked_tables')}
+
{$_('from_related_tables')}
{$_('one_column_from_base_is_required')} @@ -47,7 +47,7 @@ {:else} {#if hasLinksFromBaseTable}
-
{$_('linked_from_base_table')}
+
{$_('references_from_base_table')}
-
{$_('linked_to_base_table')}
+
{$_('references_to_base_table')}
{#if hasInitialColumns} From 3c6b727b7d533bf8267c632e3db22d2f590077a5 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 20:44:07 -0500 Subject: [PATCH 09/27] Improve type safety for DocsLinks component --- mathesar_ui/src/components/DocsLink.svelte | 18 ++++++++---------- .../src/components/SeeDocsToLearnMore.svelte | 15 +++++---------- .../import/upload/ImportUploadPage.svelte | 4 +--- .../table-view/link-table/LinkTableForm.svelte | 2 +- .../table-inspector/table/TableMode.svelte | 2 +- 5 files changed, 16 insertions(+), 25 deletions(-) diff --git a/mathesar_ui/src/components/DocsLink.svelte b/mathesar_ui/src/components/DocsLink.svelte index 198494e2b2..344876eff2 100644 --- a/mathesar_ui/src/components/DocsLink.svelte +++ b/mathesar_ui/src/components/DocsLink.svelte @@ -7,17 +7,15 @@ diff --git a/mathesar_ui/src/components/SeeDocsToLearnMore.svelte b/mathesar_ui/src/components/SeeDocsToLearnMore.svelte index d1da0e8c85..c03e4df0ad 100644 --- a/mathesar_ui/src/components/SeeDocsToLearnMore.svelte +++ b/mathesar_ui/src/components/SeeDocsToLearnMore.svelte @@ -1,23 +1,18 @@ {#if slotName === 'link'} - + {translatedArg} {/if} diff --git a/mathesar_ui/src/pages/import/upload/ImportUploadPage.svelte b/mathesar_ui/src/pages/import/upload/ImportUploadPage.svelte index 1e4b38af86..371ff4d4c9 100644 --- a/mathesar_ui/src/pages/import/upload/ImportUploadPage.svelte +++ b/mathesar_ui/src/pages/import/upload/ImportUploadPage.svelte @@ -203,9 +203,7 @@ let:translatedArg > {#if slotName === 'documentationLink'} - - {translatedArg} - + {translatedArg} {/if}
diff --git a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte index 4dee06cc9b..dff3d9507e 100644 --- a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte @@ -229,7 +229,7 @@
{$_('references_help')} - +
diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte index b802fa65e0..b8d03585cb 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte @@ -67,7 +67,7 @@ {$_('relationships')}

{$_('references_help')}

-

+

From 89063b88ff54300db495cc41b73a50149a578110 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 21:40:48 -0500 Subject: [PATCH 10/27] Minor copy fixes --- mathesar_ui/src/i18n/languages/en/dict.json | 2 +- .../systems/table-view/constraints/NewFkConstraint.svelte | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 831ecab6a3..3e2c2e683e 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -106,7 +106,7 @@ "constraint_name_already_exists": "A constraint with that name already exists", "constraint_name_cannot_be_empty": "Constraint name cannot be empty", "constraint_name_unique_help": "At the database level, each constraint must have a unique name across all the constraints, tables, views, and indexes within the schema.", - "constraint_name_unique_mathesar_relevance_help": "In Mathesar however, the name of the constraint will likely never be relevant, — so we recommend allowing Mathesar to automatically generate constraint names when adding new constraints.", + "constraint_name_unique_mathesar_relevance_help": "In Mathesar however, the name of the constraint will likely never be relevant — so we recommend allowing Mathesar to automatically generate constraint names when adding new constraints.", "constraints": "Constraints", "constraints_info_help": "Use constraints to define relationships between records in different tables or ensure uniqueness within a column.", "constraints_info_help_mini": "Constraints are rules that apply to the data in a column to ensure that it is valid.", diff --git a/mathesar_ui/src/systems/table-view/constraints/NewFkConstraint.svelte b/mathesar_ui/src/systems/table-view/constraints/NewFkConstraint.svelte index 1741c7cd14..eecb7166ec 100644 --- a/mathesar_ui/src/systems/table-view/constraints/NewFkConstraint.svelte +++ b/mathesar_ui/src/systems/table-view/constraints/NewFkConstraint.svelte @@ -170,8 +170,10 @@ on:change={handleNamingStrategyChange} getRadioLabel={(s) => namingStrategyLabelMap.get(s) ?? ''} > - {$_('set_constraint_name')} - + + {$_('set_constraint_name')} + + From 808a2b489bfb7934903e4224f80b48550acfbb11 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 26 Nov 2024 22:02:44 -0500 Subject: [PATCH 11/27] Fix docs link to moved page --- mathesar_ui/src/components/DocsLink.svelte | 2 +- .../src/systems/table-view/link-table/LinkTableForm.svelte | 2 +- .../systems/table-view/table-inspector/table/TableMode.svelte | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/mathesar_ui/src/components/DocsLink.svelte b/mathesar_ui/src/components/DocsLink.svelte index 344876eff2..55277877f0 100644 --- a/mathesar_ui/src/components/DocsLink.svelte +++ b/mathesar_ui/src/components/DocsLink.svelte @@ -9,7 +9,7 @@ const pages = { import: '/user-guide/importing-data/', - references: '/user-guide/references/', + relationships: '/user-guide/relationships/', }; type Page = keyof typeof pages; diff --git a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte index dff3d9507e..b2153b85d8 100644 --- a/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/LinkTableForm.svelte @@ -229,7 +229,7 @@
{$_('references_help')} - +
diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte index b8d03585cb..94cf14167a 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/TableMode.svelte @@ -67,7 +67,7 @@ {$_('relationships')}

{$_('references_help')}

-

+

From 54fd08489a84cb2acb5bc1180982c137ff7d7cec Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 27 Nov 2024 14:27:27 -0500 Subject: [PATCH 12/27] Add help bubbles in db settings UI --- mathesar_ui/src/components/DocsLink.svelte | 5 ++++ mathesar_ui/src/i18n/languages/en/dict.json | 6 +++++ mathesar_ui/src/i18n/staticText.ts | 10 +++++++ .../collaborators/Collaborators.svelte | 6 +++++ .../RoleConfiguration.svelte | 6 +++++ .../settings/roles/CreateRoleModal.svelte | 17 ++++++++++-- .../database/settings/roles/Roles.svelte | 27 ++++++++++++++++--- 7 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 mathesar_ui/src/i18n/staticText.ts diff --git a/mathesar_ui/src/components/DocsLink.svelte b/mathesar_ui/src/components/DocsLink.svelte index 55277877f0..8eb0a53c08 100644 --- a/mathesar_ui/src/components/DocsLink.svelte +++ b/mathesar_ui/src/components/DocsLink.svelte @@ -10,6 +10,11 @@ const pages = { import: '/user-guide/importing-data/', relationships: '/user-guide/relationships/', + roles: '/user-guide/roles/', + rolesLogin: '/user-guide/roles/#login', + rolesInheritance: '/user-guide/roles/#inheritance', + storedRolePasswords: '/user-guide/stored-role-passwords/', + collaborators: '/user-guide/collaborators/', }; type Page = keyof typeof pages; diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 3e2c2e683e..95fdf1ab03 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -68,6 +68,7 @@ "collaborator_role_help": "Mathesar will use this PostgreSQL role for all database interactions by this user. The role will determine the access that the user has to data.", "collaborator_role_updated_successfully": "Role updated successfully for collaborator.", "collaborators": "Collaborators", + "collaborators_help": "Adding a collaborator gives one Mathesar user access to one database through a specific PostgreSQL role.", "column": "Column", "column_added_number_of_times": "{count, plural, one {This column has been added once.} other {This column has been added {count} times.}}", "column_data_types": "Column Data Types", @@ -352,6 +353,7 @@ "new_column_added_to_table": "A new column will be added to [tableName]", "new_foreign_key_constraint": "New Foreign Key Constraint", "new_link_wont_work_once_regenerated": "Once you regenerate a new link, the old link will no longer work.", + "new_login_role_info_box": "Note: If you would also like to assign this new role to a Mathesar collaborator, then after you create the role here go to the \"Stored Role Passwords\" section to save this same password in Mathesar.", "new_owner": "New Owner", "new_password": "New Password", "new_pg_user_privileges_help": "The user will be granted CONNECT and CREATE privileges on the database.", @@ -506,9 +508,12 @@ "role_created_successfully": "The Role has been created successfully", "role_dropped_successfully": "The Role has been dropped successfully", "role_has_no_child_roles": "The Role does not have any Child Roles", + "role_inheritance_help": "In PostgreSQL, you can use \"role inheritance\" to grant all the privileges of one role (the parent) to another role (the child).", "role_name": "Role Name", "role_privileges": "Role Privileges", "roles": "Roles", + "roles_help": "PostgreSQL uses roles to manage access to data. All the roles within your PostgreSQL server are shown below.", + "roles_login_help": "When a role has the LOGIN attribute set to true, PostgreSQL will allow you to log in to the server using this role and its corresponding password. When LOGIN is false, the role does not have a password and cannot be used to log in. Non-LOGIN roles are still useful for managing permissions through role inheritance.", "row": "Row", "running_latest_version": "You are running the latest version", "sample_data_library_help": "Sample data from a fictional library.", @@ -586,6 +591,7 @@ "store_a_password": "Store a Password", "stored_password": "Stored Password", "stored_role_passwords": "Stored Role Passwords", + "stored_role_passwords_help": "Mathesar stores passwords for any roles that you would like to use when authenticating with PostgreSQL to work with data. Roles with stored passwords can then be assigned to users via collaborators.", "summarization": "Summarization", "summarize": "Summarize", "summarize_column_configure": "You can manually configure a summarization later via the \"Transform Results\" pane.", diff --git a/mathesar_ui/src/i18n/staticText.ts b/mathesar_ui/src/i18n/staticText.ts new file mode 100644 index 0000000000..90394dd24b --- /dev/null +++ b/mathesar_ui/src/i18n/staticText.ts @@ -0,0 +1,10 @@ +/** + * This is raw UI text which should not be translated. It's stored here for the + * following reasons: + * + * - It makes it explicit that this text should not be translated. + * - It won't raise linting errors for untranslated text. + */ +export const staticText = { + LOGIN: 'LOGIN', +} as const; diff --git a/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte b/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte index d8f2f46476..6d8ff9c697 100644 --- a/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte +++ b/mathesar_ui/src/pages/database/settings/collaborators/Collaborators.svelte @@ -6,6 +6,7 @@ import GridTable from '@mathesar/components/grid-table/GridTable.svelte'; import GridTableCell from '@mathesar/components/grid-table/GridTableCell.svelte'; import WarningBox from '@mathesar/components/message-boxes/WarningBox.svelte'; + import SeeDocsToLearnMore from '@mathesar/components/SeeDocsToLearnMore.svelte'; import { DatabaseSettingsRouteContext } from '@mathesar/contexts/DatabaseSettingsRouteContext'; import { iconAddNew } from '@mathesar/icons'; import type { Collaborator } from '@mathesar/models/Collaborator'; @@ -15,6 +16,7 @@ import { getUserProfileStoreFromContext } from '@mathesar/stores/userProfile'; import { Button, + Help, Spinner, isDefinedNonNullable, } from '@mathesar-component-library'; @@ -78,6 +80,10 @@ {$_('collaborators')} + + {$_('collaborators_help')} + + {#if isSuccess} diff --git a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte index 91b5d60929..9f02933024 100644 --- a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte +++ b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte @@ -5,6 +5,7 @@ import GridTableCell from '@mathesar/components/grid-table/GridTableCell.svelte'; import ErrorBox from '@mathesar/components/message-boxes/ErrorBox.svelte'; import PhraseContainingIdentifier from '@mathesar/components/PhraseContainingIdentifier.svelte'; + import SeeDocsToLearnMore from '@mathesar/components/SeeDocsToLearnMore.svelte'; import Yes from '@mathesar/components/Yes.svelte'; import { type CombinedLoginRole, @@ -19,6 +20,7 @@ import { getErrorMessage } from '@mathesar/utils/errors'; import { Button, + Help, Icon, Spinner, SpinnerButton, @@ -66,6 +68,10 @@ {$_('stored_role_passwords')} + + {$_('stored_role_passwords_help')} + + {#if isLoading} diff --git a/mathesar_ui/src/pages/database/settings/roles/CreateRoleModal.svelte b/mathesar_ui/src/pages/database/settings/roles/CreateRoleModal.svelte index 386a494c4d..fec8117bdb 100644 --- a/mathesar_ui/src/pages/database/settings/roles/CreateRoleModal.svelte +++ b/mathesar_ui/src/pages/database/settings/roles/CreateRoleModal.svelte @@ -9,11 +9,15 @@ makeForm, requiredField, } from '@mathesar/components/form'; + import InfoBox from '@mathesar/components/message-boxes/InfoBox.svelte'; + import SeeDocsToLearnMore from '@mathesar/components/SeeDocsToLearnMore.svelte'; import { DatabaseSettingsRouteContext } from '@mathesar/contexts/DatabaseSettingsRouteContext'; + import { staticText } from '@mathesar/i18n/staticText'; import { toast } from '@mathesar/stores/toast'; import { Checkbox, ControlledModal, + Help, LabeledInput, type ModalController, PasswordInput, @@ -72,8 +76,14 @@
- - + +
+ {staticText.LOGIN} + + {$_('roles_login_help')} + + +
@@ -96,6 +106,9 @@ props: { autocomplete: 'new-password' }, }} /> + + {$_('new_login_role_info_box')} + {/if}
diff --git a/mathesar_ui/src/pages/database/settings/roles/Roles.svelte b/mathesar_ui/src/pages/database/settings/roles/Roles.svelte index 0a9cea19b1..e34c1ae837 100644 --- a/mathesar_ui/src/pages/database/settings/roles/Roles.svelte +++ b/mathesar_ui/src/pages/database/settings/roles/Roles.svelte @@ -5,13 +5,15 @@ import GridTable from '@mathesar/components/grid-table/GridTable.svelte'; import GridTableCell from '@mathesar/components/grid-table/GridTableCell.svelte'; import ErrorBox from '@mathesar/components/message-boxes/ErrorBox.svelte'; + import SeeDocsToLearnMore from '@mathesar/components/SeeDocsToLearnMore.svelte'; import { DatabaseSettingsRouteContext } from '@mathesar/contexts/DatabaseSettingsRouteContext'; + import { staticText } from '@mathesar/i18n/staticText'; import { iconAddNew } from '@mathesar/icons'; import type { Role } from '@mathesar/models/Role'; import AsyncRpcApiStore from '@mathesar/stores/AsyncRpcApiStore'; import { modal } from '@mathesar/stores/modal'; import { fetchSchemasForCurrentDatabase } from '@mathesar/stores/schemas'; - import { Button, Icon, Spinner } from '@mathesar-component-library'; + import { Button, Help, Icon, Spinner } from '@mathesar-component-library'; import SettingsContentLayout from '../SettingsContentLayout.svelte'; @@ -60,6 +62,10 @@ {$_('roles')} + + {$_('roles_help')} + + {#if !$roles.isLoading} @@ -78,10 +84,23 @@
{$_('role')} - - LOGIN - {$_('child_roles')} +
+ {staticText.LOGIN} + + {$_('roles_login_help')} + + +
+ + +
+ {$_('child_roles')} + + {$_('role_inheritance_help')} + + +
{$_('actions')} {#each roleList as role (role.oid)} From e78877504523bbbe58860c47cbea3dea7ab91cbf Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Mon, 2 Dec 2024 21:45:45 -0500 Subject: [PATCH 13/27] Fix spelling errors in UI strings --- mathesar_ui/src/i18n/languages/en/dict.json | 15 +++++++-------- mathesar_ui/src/i18n/languages/ja/dict.json | 3 +-- .../src/pages/admin-update/ReleaseBox.svelte | 2 +- .../table-view/link-table/SelectLinkType.svelte | 2 +- 4 files changed, 10 insertions(+), 12 deletions(-) diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 95fdf1ab03..32bd78125b 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -149,7 +149,7 @@ "data_explorer": "Data Explorer", "data_loss_warning_alert": "Data loss can result from changing the data type of a column. This action cannot be undone.", "data_source": "Data Source", - "data_tabular_format_help": "The data must be in tabular format (CSV, TSV etc) or JSON. See relevant [documentationLink](documenation).", + "data_tabular_format_help": "The data must be in tabular format (CSV, TSV etc) or JSON. See relevant [documentationLink](documentation).", "data_type": "Data Type", "data_type_linked_column_restricted": "The data type of this column must match the referenced column and cannot be changed.", "data_type_pk_column_restricted": "The data type of the primary key column is restricted and cannot be changed.", @@ -306,7 +306,7 @@ "known_connection": "Known connection", "large_data_takes_time_warning": "Large data sets can sometimes take several minutes to process. Please do not leave this page or close the browser tab while the import is in progress.", "last_checked": "Last checked", - "latest_availabe_version_not_installed": "Latest Available Version (not installed)", + "latest_available_version_not_installed": "Latest Available Version (not installed)", "learn_implications_deleting_mathesar_schemas": "Learn more about the implications of deleting Mathesar schemas.", "link_copied": "Link copied", "link_successfully_regenerated": "The link has been successfully regenerated", @@ -336,7 +336,7 @@ "minutes": "Minutes", "move_columns": "Move Columns", "move_columns_to_linked_table": "{count, plural, one {Move Column To Linked Table} other {Move Columns To Linked Table}}", - "multiple_column_delete_error_last_base_column": "Some of the selected columns cannot be deleted because atleast one column from the base table is required. Please add another column from the base table before deleting them.", + "multiple_column_delete_error_last_base_column": "Some of the selected columns cannot be deleted because at least one column from the base table is required. Please add another column from the base table before deleting them.", "multiple_column_delete_error_used_in_transformations": "Some of the selected columns cannot be deleted because they're either used in transformations or results of transformations. Please remove them from the transformations before deleting them.", "multiple_columns_selected": "{count, plural, one {{count} column selected} other {{count} columns selected}}", "multiple_records": "{count, plural, one {{count} Record} other {{count} Records}}", @@ -471,7 +471,7 @@ "related_records": "Related Records", "related_records_help": "Each of the following records links to [recordSummary] from another table.", "relationship_type_description_many_to_many": "Multiple [baseTable] and [targetTable] records can reference each other through a new [mappingTable]", - "relationship_type_description_many_to_many_self_referential": "Multiple [baseTable] records can referece each other through a new [mappingTable].", + "relationship_type_description_many_to_many_self_referential": "Multiple [baseTable] records can reference each other through a new [mappingTable].", "relationship_type_description_many_to_one": "Multiple [baseTable] records can reference the same [targetTable] record.", "relationship_type_description_one_to_many": "One [baseTable] record can be referenced from multiple [targetTable] records.", "relationships": "Relationships", @@ -526,7 +526,7 @@ "saving": "Saving", "saving_changes": "Saving Changes", "schema": "Schema", - "schema_access_create_help": "Can acccess the schema and create new tables", + "schema_access_create_help": "Can access the schema and create new tables", "schema_access_read_help": "Can access the schema", "schema_delete_warning": "All objects in this schema will be deleted permanently, including (but not limited to) tables and views. Some of these objects may not be visible in the Mathesar UI.", "schema_description": "Use schemas to organize related tables into logical groups within your database.", @@ -576,7 +576,7 @@ "showing_n_to_m_of_total": "Showing {leftBound}-{rightBound} of {totalCount}", "showing_n_to_m_of_total_records": "{totalCount, plural, one {Showing {leftBound}-{rightBound} of {totalCount} record} other {Showing {leftBound}-{rightBound} of {totalCount} records}}", "signed_in_as": "Signed in as", - "single_column_delete_error_last_base_column": "This column cannot be deleted because atleast one column from the base table is required. Please add another column from the base table before deleting this column.", + "single_column_delete_error_last_base_column": "This column cannot be deleted because at least one column from the base table is required. Please add another column from the base table before deleting this column.", "single_column_delete_error_used_in_transformations": "This column cannot be deleted because it is either used in transformations or a result of transformations. Please remove the column from the transformations before deleting it.", "slower_for_large_imports": "slower for large imports", "software_update": "Software Update", @@ -632,7 +632,6 @@ "target_column_in_table": "Table Column in [tableName] Table", "target_table": "Target Table", "template": "Template", - "template_refer_atleast_one_column_error": "The template must reference at least one column, otherwise the record summary will be the same for all records.", "ten_best_matches_shown": "The 10 best matches are shown. Continue filtering to see more.", "text": "Text", "the_credentials_will_be_copied_from_this_connection": "The username, password, host, and port will be copied from this connection.", @@ -644,7 +643,7 @@ "transform_results": "Transform Results", "transform_results_help": "Transformations can be used to summarize data, filter data, and more. Note that transformations are applied in the order they are listed.", "two_columns_cannot_have_same_name": "The two columns cannot have the same name.", - "type_of_relatiohship_with_table": "Type of Relatiohship with [tableName]", + "type_of_relationship_with_table": "Type of Relationship with [tableName]", "unable_to_add_constraint": "Unable to add constraint.", "unable_to_change_column_type": "Unable to change column type", "unable_to_change_display_options": "Unable to change column display options.", diff --git a/mathesar_ui/src/i18n/languages/ja/dict.json b/mathesar_ui/src/i18n/languages/ja/dict.json index 8f94dbb96f..bf9639f52e 100644 --- a/mathesar_ui/src/i18n/languages/ja/dict.json +++ b/mathesar_ui/src/i18n/languages/ja/dict.json @@ -251,7 +251,7 @@ "known_connection": "既知の接続", "large_data_takes_time_warning": "大規模なデータセットの場合、処理に数分かかることがあります。インポートの実行中は、このページから離れたり、ブラウザのタブを閉じたりしないでください。", "last_checked": "最終確認", - "latest_availabe_version_not_installed": "利用可能な最新バージョン（インストールされていません）", + "latest_available_version_not_installed": "利用可能な最新バージョン（インストールされていません）", "learn_implications_deleting_mathesar_schemas": "Mathesarスキーマを削除することによる影響については、こちらをご覧ください。", "link_copied": "リンクをコピーしました", "link_successfully_regenerated": "リンクの再生成に成功しました", @@ -487,7 +487,6 @@ "target_column_in_table": "[tableName]テーブルのテーブル列", "target_table": "ターゲットテーブル", "template": "テンプレート", - "template_refer_atleast_one_column_error": "テンプレートは少なくとも1つの列を参照する必要があります。そうしない限り、レコードサマリーはすべてのレコードで同じものになります。", "ten_best_matches_shown": "最も適合する10件が表示されています。さらに見るにはフィルタリングを続けてください。", "the_credentials_will_be_copied_from_this_connection": "ユーザー名、パスワード、ホスト、ポートがこの接続からコピーされます。", "this_database_must_exist_already": "このデータベースはすでに存在している必要があります。", diff --git a/mathesar_ui/src/pages/admin-update/ReleaseBox.svelte b/mathesar_ui/src/pages/admin-update/ReleaseBox.svelte index 9e92c84ae0..5a5d58e98c 100644 --- a/mathesar_ui/src/pages/admin-update/ReleaseBox.svelte +++ b/mathesar_ui/src/pages/admin-update/ReleaseBox.svelte @@ -39,7 +39,7 @@ {$_('currently_installed')} {:else if type === 'latest'} - {$_('latest_availabe_version_not_installed')} + {$_('latest_available_version_not_installed')} {:else} {assertExhaustive(type)} {/if} diff --git a/mathesar_ui/src/systems/table-view/link-table/SelectLinkType.svelte b/mathesar_ui/src/systems/table-view/link-table/SelectLinkType.svelte index 93294a3a30..345a4e66dc 100644 --- a/mathesar_ui/src/systems/table-view/link-table/SelectLinkType.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/SelectLinkType.svelte @@ -21,7 +21,7 @@
- + {#if slotName === 'tableName'} : {/if} From b2617400d131f51fb709be1fd9679f55a2f1e797 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Mon, 2 Dec 2024 22:30:15 -0500 Subject: [PATCH 14/27] Help bubbles and UI string updates --- mathesar_ui/src/components/DocsLink.svelte | 1 + mathesar_ui/src/i18n/languages/en/dict.json | 17 ++++--- .../ConfigureRoleModal.svelte | 6 +-- .../RoleConfiguration.svelte | 6 +-- .../ConnectExistingDatabase.svelte | 44 ++++++++++++++++--- .../link-table/LinkTableForm.svelte | 19 ++++---- .../link-table/LinkTableModal.svelte | 11 ++++- 7 files changed, 73 insertions(+), 31 deletions(-) diff --git a/mathesar_ui/src/components/DocsLink.svelte b/mathesar_ui/src/components/DocsLink.svelte index 8eb0a53c08..20054f507c 100644 --- a/mathesar_ui/src/components/DocsLink.svelte +++ b/mathesar_ui/src/components/DocsLink.svelte @@ -15,6 +15,7 @@ rolesInheritance: '/user-guide/roles/#inheritance', storedRolePasswords: '/user-guide/stored-role-passwords/', collaborators: '/user-guide/collaborators/', + internalSchemas: '/user-guide/schemas/#internal', }; type Page = keyof typeof pages; diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 32bd78125b..4559fadd16 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -100,6 +100,7 @@ "connect": "Connect", "connect_and_create": "Connect + Create", "connect_database": "Connect Database", + "connect_db_password_help": "See our [docsLink](documentation) to learn about how passwords are stored.", "connect_existing_database": "Connect to an Existing Database", "connect_with_community_help": "Connect with Mathesar users and contributors in our community chat. Share ideas, get help, and contribute to discussions.", "constraint": "Constraint", @@ -131,7 +132,7 @@ "create_new_pg_user": "Create a new PostgreSQL user", "create_new_schema": "Create New Schema", "create_record_from_search": "Create Record From Search Criteria", - "create_reference_help_info_2": "For existing columns, add foreign key constraints in the \"Advanced\" section to turn them into references.", + "create_reference_help_info_2": "Note: To turn an [italic](existing) column into a reference column, add a foreign key constraint by opening the \"Constraints\" dialog from the \"Advanced\" section of the table inspector.", "create_relationship": "Create Relationship", "create_relationship_between": "Create Relationship Between [tablePill] and", "create_role": "Create Role", @@ -428,6 +429,7 @@ "pick_table_record": "Pick a Record from [tableName]", "port": "Port", "port_invalid": "The port is invalid", + "postgresql_role_name": "PostgreSQL Role Name", "prepare_downtime": "Prepare your users for up to five minutes of downtime.", "preview": "Preview", "preview_truncated_at_limit": "Preview is truncated at {limit} rows", @@ -485,14 +487,13 @@ "remove_collaborator_body_2": "The user [userName] will still be able to log in to Mathesar and might still have access to other connected databases.", "remove_collaborator_body_3": "The associated PostgreSQL role [roleName] will be unaffected.", "remove_collaborator_name_from_database_question": "Remove [userName] as a collaborator on the [databaseName] database?", - "remove_configuration": "Remove Configuration", "remove_filters": "{count, plural, one {Remove Filter} other {Remove {count} Filters}}", "remove_grouping": "Remove Grouping", "remove_old_link_create_new": "Remove old link and create a new link?", "remove_sorting_type": "Remove {sortingType} Sorting", "remove_stored_password": "Remove Stored Password", "remove_stored_password_for_identifier": "Remove Stored Password for [identifier]?", - "removing_role_configuration_warning": "Removing this configuration will prevent collaborators assigned to this role from accessing databases on server ''{server}''.", + "remove_stored_password_help": "Removing this stored password will prevent collaborators assigned to this role from accessing databases on server ''{server}''.", "reset": "Reset", "restrict_to_unique": "Restrict to Unique", "restrict_to_unique_help": "Ensures all values in this column are unique. Ideal for IDs, usernames, and other unique identifiers.", @@ -501,7 +502,6 @@ "retry": "Retry", "reuse_credentials_from_known_connection": "Reuse credentials from a known connection", "role": "Role", - "role_configuration_removed": "The role configuration has been removed successfully", "role_configured_all_databases_in_server": "The new password will be used for this role when connecting to any databases on server ''{server}''", "role_configured_successfully": "Role configured successfully", "role_configured_successfully_new_password": "Role configured successfully with new password", @@ -510,6 +510,9 @@ "role_has_no_child_roles": "The Role does not have any Child Roles", "role_inheritance_help": "In PostgreSQL, you can use \"role inheritance\" to grant all the privileges of one role (the parent) to another role (the child).", "role_name": "Role Name", + "role_needs_create_connect_privileges": "Must have CONNECT and CREATE privileges", + "role_needs_create_connect_privileges_detail_1": "In order for Mathesar to function, this role needs CONNECT privileges on the database.", + "role_needs_create_connect_privileges_detail_2": "Additionally, in order for Mathesar to be [italic](installed), this role needs CREATE privileges to install Mathesar's internal schemas. You may revoke CREATE privileges after installing Mathesar if you choose. See our [docsLink](documentation) for more information.", "role_privileges": "Role Privileges", "roles": "Roles", "roles_help": "PostgreSQL uses roles to manage access to data. All the roles within your PostgreSQL server are shown below.", @@ -547,7 +550,7 @@ "search_tables": "Search Tables", "search_users": "Search Users", "seconds": "Seconds", - "section_affects_postgresql_config": "This configuration in this section is stored within the connected PostgreSQL database.", + "section_affects_postgresql_config": "The configuration in this section is stored within the connected PostgreSQL database.", "see_docs_to_learn_more": "See our [link](documentation) to learn more.", "select_cell_view_properties": "Select a cell to view it's properties.", "select_cells_view_record_props": "Select one or more cells to view associated record properties.", @@ -590,6 +593,7 @@ "static_record_summary_template_error": "Record summary cannot be static. Add at least one column field in order to save.", "store_a_password": "Store a Password", "stored_password": "Stored Password", + "stored_password_removed": "The stored password has been removed.", "stored_role_passwords": "Stored Role Passwords", "stored_role_passwords_help": "Mathesar stores passwords for any roles that you would like to use when authenticating with PostgreSQL to work with data. Roles with stored passwords can then be assigned to users via collaborators.", "summarization": "Summarization", @@ -608,7 +612,7 @@ "table_can_have_many": "With these relationships, one [tableName] record can have [bold](many) related records.", "table_can_have_one": "With these relationships, one [tableName] record can have [bold](one) related record.", "table_delete_permanent_warning": "Warning: This action is permanent and once deleted, the table cannot be recovered.", - "table_does_not_link": "This table does not link to any other tables", + "table_does_not_link": "There are no relationships between this table and other tables.", "table_name": "Table Name", "table_name_already_exists": "A table with that name already exists.", "table_name_cannot_be_empty": "The table name cannot be empty.", @@ -682,7 +686,6 @@ "use_text_for_all_columns": "Use \"Text\" for all column data types", "user": "User", "user_name": "User name", - "user_needs_create_connect_privileges": "The user needs CONNECT and CREATE privileges on the database.", "user_not_found": "User not found", "user_profile": "User Profile", "user_type": "User type", diff --git a/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte b/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte index ddb214b67e..c6517346e8 100644 --- a/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte +++ b/mathesar_ui/src/pages/database/settings/role-configuration/ConfigureRoleModal.svelte @@ -9,7 +9,7 @@ } from '@mathesar/components/form'; import Field from '@mathesar/components/form/Field.svelte'; import Identifier from '@mathesar/components/Identifier.svelte'; - import WarningBox from '@mathesar/components/message-boxes/WarningBox.svelte'; + import InfoBox from '@mathesar/components/message-boxes/InfoBox.svelte'; import RichText from '@mathesar/components/rich-text/RichText.svelte'; import { type CombinedLoginRole, @@ -62,13 +62,13 @@ }} /> - + {$_('role_configured_all_databases_in_server', { values: { server: database.server.getConnectionString(), }, })} - +
diff --git a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte index 9f02933024..46ec37a3b4 100644 --- a/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte +++ b/mathesar_ui/src/pages/database/settings/role-configuration/RoleConfiguration.svelte @@ -57,7 +57,7 @@ await $routeContext.removeConfiguredRole( combinedLoginRole.configuredRole, ); - toast.success($_('role_configuration_removed')); + toast.success($_('stored_password_removed')); } catch (err) { toast.error(getErrorMessage(err)); } @@ -119,14 +119,14 @@ ), }, }, - body: $_('removing_role_configuration_warning', { + body: $_('remove_stored_password_help', { values: { server: combinedLoginRole.configuredRole?.database.server.getConnectionString(), }, }), proceedButton: { - label: $_('remove_configuration'), + label: $_('remove_stored_password'), icon: iconDeleteMajor, }, })} diff --git a/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte b/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte index 3da71d8e70..5d3f1c6f26 100644 --- a/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte +++ b/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte @@ -1,6 +1,8 @@ -
- {$_('references_help')} - -
-
- {$_('create_reference_help_info_2')} + + {#if slotName === 'italic'} + {translatedArg} + {/if} + @@ -415,9 +417,6 @@ --target-fill: var(--base-fill); --target-stroke: var(--base-stroke); } - .description { - margin-bottom: 1rem; - } .collapsible-detail { padding: var(--size-xx-small); margin-top: 0.25em; diff --git a/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte b/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte index 76552ba186..29c9dba40a 100644 --- a/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte +++ b/mathesar_ui/src/systems/table-view/link-table/LinkTableModal.svelte @@ -1,6 +1,8 @@ {#if $currentTable} - + + + {$_('create_relationship')} + + {$_('references_help')} + + + controller.close()} /> {/if} From 2d9c64ef7742c6c3231a4353db8dec1f5bdb27ec Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 3 Dec 2024 08:20:56 -0500 Subject: [PATCH 15/27] 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 From 6d9e6c88900627641b4eba4fcdae966ebf12f65f Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Tue, 3 Dec 2024 14:35:35 -0500 Subject: [PATCH 16/27] Run Prettier --- .../table-inspector/table/links/ForwardLinkCard.svelte | 1 - .../table-inspector/table/links/ReverseLinkCard.svelte | 1 - 2 files changed, 2 deletions(-) diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/ForwardLinkCard.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ForwardLinkCard.svelte index bef9ea5078..046d3ac341 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/ForwardLinkCard.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ForwardLinkCard.svelte @@ -8,7 +8,6 @@ import type { Table } from '@mathesar/models/Table'; import { storeToGetTablePageUrl } from '@mathesar/stores/storeBasedUrls'; - import LinkCard from './LinkCard.svelte'; export let referentTable: Pick; diff --git a/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte index 4d5c35e797..33d5620110 100644 --- a/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte +++ b/mathesar_ui/src/systems/table-view/table-inspector/table/links/ReverseLinkCard.svelte @@ -8,7 +8,6 @@ import type { Table } from '@mathesar/models/Table'; import { storeToGetTablePageUrl } from '@mathesar/stores/storeBasedUrls'; - import LinkCard from './LinkCard.svelte'; export let referentTable: { name: string }; From da61a9880c37e1a7b3ebb00a211b4e516c2bc4ad Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 4 Dec 2024 12:31:00 -0500 Subject: [PATCH 17/27] Remove empty lines --- docs/docs/api/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index e92600f446..9011e1fc4c 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -80,5 +80,3 @@ Other error codes are grouped according to the library that produced the Excepti - other: -25xxx Unrecognized errors from a given library return a "round number" code, so an unknown `builtins` error gets the code -31000. - - From 4911484ab9d03abc1a640703d4658e357a9b9d6a Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:07:09 -0500 Subject: [PATCH 18/27] Docs: content adjustments via pairing session Co-authored-by: Brent Moran --- docs/docs/api/index.md | 2 +- docs/docs/user-guide/data-explorer.md | 6 +++--- docs/docs/user-guide/databases.md | 6 +++--- docs/docs/user-guide/index.md | 2 +- docs/docs/user-guide/metadata.md | 2 +- docs/docs/user-guide/relationships.md | 4 ++-- docs/docs/user-guide/roles.md | 2 +- docs/docs/user-guide/tables.md | 2 +- mathesar_ui/src/i18n/languages/en/dict.json | 1 - .../create-database/ConnectExistingDatabase.svelte | 2 +- 10 files changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 9011e1fc4c..29e05ce3e9 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -6,7 +6,7 @@ Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](htt - 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). +- This API _documentation_ is 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. diff --git a/docs/docs/user-guide/data-explorer.md b/docs/docs/user-guide/data-explorer.md index 2022b963dc..9b62e8866d 100644 --- a/docs/docs/user-guide/data-explorer.md +++ b/docs/docs/user-guide/data-explorer.md @@ -1,6 +1,6 @@ # Mathesar's Data Explorer -The Data Explorer provides rudimentary support for some basic reporting and analytics tasks. +The Data Explorer lets you create reports from your data. You can: @@ -13,9 +13,9 @@ After you've constructed an exploration, you can save it to easily run it later ## Exploration and access controls -- The Data Explorer will now allow you to modify any data. It is a read-only reporting tool. +- The Data Explorer will not 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). +- Your ability to view data in the Data Explorer is determined by the privileges of the PostgreSQL [role](./roles.md) you're using. - 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)). diff --git a/docs/docs/user-guide/databases.md b/docs/docs/user-guide/databases.md index adc094202f..e6da54b155 100644 --- a/docs/docs/user-guide/databases.md +++ b/docs/docs/user-guide/databases.md @@ -8,7 +8,7 @@ If you're using Mathesar as a spreadsheet alternative, you might be curious what 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 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! +One superpower of PostgreSQL is that cells from one table can reference records from another table. 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} @@ -55,7 +55,7 @@ To manage the owner and granted privileges for a database, navigate to the datab 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. +Disconnecting a database will _not_ delete the database. It will still be accessible outside Mathesar, and you can 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. @@ -67,7 +67,7 @@ We plan to add support for dropping databases in the future. If this is a featur ## 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. +Mathesar keeps as much of your data as possible inside your connected PostgreSQL database, structured consistently with the way it appears in the Mathesar interface. 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: diff --git a/docs/docs/user-guide/index.md b/docs/docs/user-guide/index.md index 306e907a1e..8750f6da1f 100644 --- a/docs/docs/user-guide/index.md +++ b/docs/docs/user-guide/index.md @@ -18,5 +18,5 @@ While the choice to support PostgreSQL in a product like Mathesar would be obvio 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. +In order to function, Mathesar needs to install some functions on your PostgreSQL database. We install these functions inside [Mathesar-specific schemas](./schemas.md#internal) to separate them from any user defined functions on the database. diff --git a/docs/docs/user-guide/metadata.md b/docs/docs/user-guide/metadata.md index d90b23c649..9393387405 100644 --- a/docs/docs/user-guide/metadata.md +++ b/docs/docs/user-guide/metadata.md @@ -1,6 +1,6 @@ # 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. +Mathesar keeps 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 diff --git a/docs/docs/user-guide/relationships.md b/docs/docs/user-guide/relationships.md index 3863cf0c1c..aa55399d24 100644 --- a/docs/docs/user-guide/relationships.md +++ b/docs/docs/user-guide/relationships.md @@ -1,6 +1,6 @@ # 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. +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 PostgreSQL, and it allows us to model complex data structures using multiple tables. ## Example @@ -100,7 +100,7 @@ Reference columns also provide a "record selector" tool which helps you search t ### 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. +- Mathesar does not support "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. diff --git a/docs/docs/user-guide/roles.md b/docs/docs/user-guide/roles.md index dc0a06ca08..4dd0a7cd10 100644 --- a/docs/docs/user-guide/roles.md +++ b/docs/docs/user-guide/roles.md @@ -4,7 +4,7 @@ PostgreSQL uses roles to manage access to data, and each PostgreSQL server has m ## What is a role -PostgreSQL role system is elegant and powerful, if albeit somewhat idiosyncratic. +PostgreSQL role system is elegant and powerful, 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. diff --git a/docs/docs/user-guide/tables.md b/docs/docs/user-guide/tables.md index 6e752ccde8..2014029b25 100644 --- a/docs/docs/user-guide/tables.md +++ b/docs/docs/user-guide/tables.md @@ -2,7 +2,7 @@ ## 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. +All relational databases, including PostgreSQL, organize data into tables (also known as "relations") 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 diff --git a/mathesar_ui/src/i18n/languages/en/dict.json b/mathesar_ui/src/i18n/languages/en/dict.json index 4559fadd16..7bf35863b9 100644 --- a/mathesar_ui/src/i18n/languages/en/dict.json +++ b/mathesar_ui/src/i18n/languages/en/dict.json @@ -429,7 +429,6 @@ "pick_table_record": "Pick a Record from [tableName]", "port": "Port", "port_invalid": "The port is invalid", - "postgresql_role_name": "PostgreSQL Role Name", "prepare_downtime": "Prepare your users for up to five minutes of downtime.", "preview": "Preview", "preview_truncated_at_limit": "Preview is truncated at {limit} rows", diff --git a/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte b/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte index 5d3f1c6f26..954a512a74 100644 --- a/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte +++ b/mathesar_ui/src/systems/databases/create-database/ConnectExistingDatabase.svelte @@ -77,7 +77,7 @@ field={databaseName} help={$_('make_sure_database_exists')} /> - + {$_('role_needs_create_connect_privileges')} From ed5d39d95d62de8a4055256116bd8de9ab3b037b Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:23:22 -0500 Subject: [PATCH 19/27] Docs: Tighten upgrade language --- docs/docs/releases/0.2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/releases/0.2.0.md b/docs/docs/releases/0.2.0.md index f7ccf966a1..04b8efa1c0 100644 --- a/docs/docs/releases/0.2.0.md +++ b/docs/docs/releases/0.2.0.md @@ -4,7 +4,7 @@ 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 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. +**We do not support upgrading from previous versions to `0.2.0`.** You'll need to reinstall Mathesar to use this version. _This page provides a comprehensive list of all changes in the release._ From 84602157c35a2b5838ffed5c58869578ba87a898 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:23:43 -0500 Subject: [PATCH 20/27] Docs: Add "Upgrade" page --- docs/docs/administration/upgrade.md | 9 +++++++++ docs/mkdocs.yml | 1 + 2 files changed, 10 insertions(+) create mode 100644 docs/docs/administration/upgrade.md diff --git a/docs/docs/administration/upgrade.md b/docs/docs/administration/upgrade.md new file mode 100644 index 0000000000..1ae0fc1dfd --- /dev/null +++ b/docs/docs/administration/upgrade.md @@ -0,0 +1,9 @@ +# Upgrade Mathesar + +The steps to upgrade Mathesar vary by release. + +1. First find the release notes for the version to which you'd like to upgrade. +1. Look at the bottom of the release notes for upgrade instructions. + +!!! warning "Caveats" + - Upgrading to Mathesar 0.2.0 from prior versions is not supported. You'll need to reinstall Mathesar to use this version. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 22d167da41..8c58c058d0 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -11,6 +11,7 @@ nav: - Install from scratch: administration/install-from-scratch.md - Configuration: administration/configuration.md - Backup & Restore: administration/backup-restore.md + - Upgrade Mathesar: administration/upgrade.md - Uninstall Mathesar: administration/uninstall.md - Debug Mathesar: administration/debug.md - User Guide: From e7c0df99109a32cdbababa5085bebe2641b16c64 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:26:59 -0500 Subject: [PATCH 21/27] Docs: Tighten API docs warning language --- docs/docs/api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index 29e05ce3e9..c22fe46509 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -6,7 +6,7 @@ Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](htt - 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 somewhat rough. We encourage you to report any docs inaccuracies via GitHub [issues](https://github.com/mathesar-foundation/mathesar/issues). +- This API _documentation_ is still in its early stages and may contain inaccuracies or incomplete information. If you encounter any issues, please [report](https://github.com/mathesar-foundation/mathesar/issues) them via GitHub. - 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. From 6a88b854c01aefc36d35e2890d7f85f0174e7d33 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:49:56 -0500 Subject: [PATCH 22/27] Docs: add question mark Co-authored-by: zack <6351754+zackkrida@users.noreply.github.com> --- docs/docs/user-guide/roles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/user-guide/roles.md b/docs/docs/user-guide/roles.md index 4dd0a7cd10..38ae2c0e6e 100644 --- a/docs/docs/user-guide/roles.md +++ b/docs/docs/user-guide/roles.md @@ -2,7 +2,7 @@ PostgreSQL uses roles to manage access to data, and each PostgreSQL server has many roles within it. -## What is a role +## What is a role? PostgreSQL role system is elegant and powerful, albeit somewhat idiosyncratic. From dc641482aa4e29c935e06485139f48af4590801b Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:50:31 -0500 Subject: [PATCH 23/27] Docs: tighten language Co-authored-by: zack <6351754+zackkrida@users.noreply.github.com> --- docs/docs/user-guide/roles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/user-guide/roles.md b/docs/docs/user-guide/roles.md index 38ae2c0e6e..aad43893b0 100644 --- a/docs/docs/user-guide/roles.md +++ b/docs/docs/user-guide/roles.md @@ -8,7 +8,7 @@ PostgreSQL role system is elegant and powerful, 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. +Other permission systems commonly have a _separate_ concept of "groups", wherein multiple users can be members of a single group. Permissions can be granted to the group as a whole. Interestingly, PostgreSQL roles can _also_ function as groups! Through [role inheritance](#inheritance), the permissions of 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. From 33b6c16f1987eaa92dbe888f07dd9b78cf34814d Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:50:53 -0500 Subject: [PATCH 24/27] Docs: add question mark Co-authored-by: zack <6351754+zackkrida@users.noreply.github.com> --- docs/docs/user-guide/tables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/user-guide/tables.md b/docs/docs/user-guide/tables.md index 2014029b25..5ea2e35a93 100644 --- a/docs/docs/user-guide/tables.md +++ b/docs/docs/user-guide/tables.md @@ -1,6 +1,6 @@ # Tables -## What is a table +## What is a table? All relational databases, including PostgreSQL, organize data into tables (also known as "relations") 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. From 5c62ab3e4c0024e7e9843e43120116d8d9d08dc0 Mon Sep 17 00:00:00 2001 From: Sean Colsen Date: Wed, 11 Dec 2024 10:52:36 -0500 Subject: [PATCH 25/27] Docs: add question mark Co-authored-by: zack <6351754+zackkrida@users.noreply.github.com> --- docs/docs/user-guide/schemas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/user-guide/schemas.md b/docs/docs/user-guide/schemas.md index a550c16e60..3ca896eaf4 100644 --- a/docs/docs/user-guide/schemas.md +++ b/docs/docs/user-guide/schemas.md @@ -1,6 +1,6 @@ # Schemas -## What is a schema +## 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. From 02ab36d728d5a5286108fab8c809a23013fde1e5 Mon Sep 17 00:00:00 2001 From: zackdotcat Date: Tue, 7 Jan 2025 16:11:16 -0500 Subject: [PATCH 26/27] Address PR suggestions --- docs/docs/api/index.md | 31 +++++++++++++++++++++----- docs/docs/user-guide/access-control.md | 3 +-- docs/docs/user-guide/roles.md | 7 +++--- 3 files changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md index c22fe46509..38c8d1ce31 100644 --- a/docs/docs/api/index.md +++ b/docs/docs/api/index.md @@ -12,9 +12,28 @@ Mathesar has an API available at `/api/rpc/v0/` which follows the [JSON-RPC](htt ## Usage +You can find a full list of Mathesar's RPC methods on the [API Methods page](./methods.md). + +!!! tip "Converting Functions to API requests" + The methods are shown as Python function definitions to make them easier to understand, but they need to be converted into JSON payloads for API calls. + + Here's how to convert a function call like this: `tables.list_(*, database_id=None, **kwargs)` into an API payload. + + 1. The function name becomes the method path: + - `tables.list_` converts to `"method": "tables.list"` + 2. Named parameters become part of the `"parameters"` object: + ```json + { + "method": "tables.list", + "parameters": { + "database_id": 1 + } + } + ``` + ### Requests -To use an RPC function: +To use an RPC method: - Call it with a dot path starting from its root path. - Always use named parameters. @@ -22,9 +41,9 @@ To use an RPC function: !!! example - To call function `tables.list` from the Tables section of this page, you'd send something like: + To list information about tables for a schema, call the [`tables.list`](./methods/#tables.list_) method with a payload like this: - `POST /api/rpc/v0/`b + `POST /api/rpc/v0/` ```json { @@ -40,7 +59,7 @@ To use an RPC function: ### Success Responses -Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form: +Upon a successful RPC method call, the API will return a success object with the following form: ```json { @@ -50,11 +69,11 @@ Upon a successful call to an RPC function, the API will return a success object. } ``` -The `result` is whatever was returned by the underlying function. +The `result` is whatever was returned by the underlying method. ### Error Responses -When an error is produced by a call to the RPC endpoint, we produce an error of the following form: +When an RPC method call fails, it generates an error response of the following form: ```json { diff --git a/docs/docs/user-guide/access-control.md b/docs/docs/user-guide/access-control.md index 3efce62c52..62d2c31e1c 100644 --- a/docs/docs/user-guide/access-control.md +++ b/docs/docs/user-guide/access-control.md @@ -1,6 +1,6 @@ # 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. +Mathesar manages data access using PostgreSQL's powerful role-based permissions system. Users interact with the database through designated PostgreSQL roles, with their access determined by the privileges assigned to those roles. Here's how it works: @@ -13,4 +13,3 @@ Here's how it works: 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/roles.md b/docs/docs/user-guide/roles.md index aad43893b0..78efdb6741 100644 --- a/docs/docs/user-guide/roles.md +++ b/docs/docs/user-guide/roles.md @@ -4,9 +4,9 @@ PostgreSQL uses roles to manage access to data, and each PostgreSQL server has m ## What is a role? -PostgreSQL role system is elegant and powerful, albeit somewhat idiosyncratic. +PostgreSQL's role system is elegant and powerful, 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. +Many permission systems utilize the concept of "users" to control access, and PostgreSQL roles work similarly. 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 permission systems commonly have a _separate_ concept of "groups", wherein multiple users can be members of a single group. Permissions can be granted to the group as a whole. Interestingly, PostgreSQL roles can _also_ function as groups! Through [role inheritance](#inheritance), the permissions of any role can be granted to any other role. @@ -40,7 +40,7 @@ The owner generally can do anything directly to the object, but not necessarily ## 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: +Privileges are specific, granular rights that can be granted on database objects. Privileges 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) @@ -61,4 +61,3 @@ Although every object in PostgreSQL has only one owner, it's still possible conf 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. - From aa1fc6c9c6de1d0eeffacc2fd13da588cf0baee0 Mon Sep 17 00:00:00 2001 From: zackdotcat Date: Tue, 7 Jan 2025 16:23:39 -0500 Subject: [PATCH 27/27] Modest changes to the databases guide page --- docs/docs/user-guide/databases.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/docs/user-guide/databases.md b/docs/docs/user-guide/databases.md index e6da54b155..52011e58af 100644 --- a/docs/docs/user-guide/databases.md +++ b/docs/docs/user-guide/databases.md @@ -1,6 +1,6 @@ # Databases -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. +Each installation of Mathesar can connect to multiple PostgreSQL databases. When you begin using Mathesar, your first step will likely be connecting to or creating a database. But what exactly is a database, and how does it differ from tools you might be more familiar with, like spreadsheets? ## What is a database @@ -8,7 +8,9 @@ If you're using Mathesar as a spreadsheet alternative, you might be curious what 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". -One superpower of PostgreSQL is that cells from one table can reference records from another table. 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! +One superpower of PostgreSQL is that cells from one table can reference records from another table. These references are called _foreign key constraints_, and Mathesar leverages them 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} @@ -16,7 +18,7 @@ Click the **Connect Database** button from the home page of your Mathesar applic 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). +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). 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 @@ -30,10 +32,12 @@ If you're starting your database from scratch with Mathesar you can either: ## Database Permissions {:#permissions} +PostgreSQL databases use a careful system of privileges (colloquially referred to as "permissions") to control what different users can do. Understanding these permissions is crucial for keeping your data secure while ensuring everyone has the access they need to do their work. + - **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 @@ -110,4 +114,3 @@ Separate from your connected PostgreSQL database, Mathesar also maintains an int -