diff --git a/next-env.d.ts b/next-env.d.ts index 52e831b43..254b73c16 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,5 +1,6 @@ /// /// +/// // NOTE: This file should not be edited // see https://nextjs.org/docs/pages/api-reference/config/typescript for more information. diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.mdx similarity index 62% rename from pages/database-management/multi-tenancy.md rename to pages/database-management/multi-tenancy.mdx index 3777daf70..8d47e6000 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.mdx @@ -3,7 +3,9 @@ title: Multi-tenancy (Enterprise) description: Discover the benefits of multi-tenancy for scalability, resource utilization, and performance. Also learn how to manage few isolated databases within a single instance in our detailed documentation. --- -# Multi-tenancy (Enterprise) +import { Callout } from 'nextra/components' + +# Multi-tenancy Enterprise Multi-tenant support in Memgraph enables users to manage multiple isolated databases within a single instance. The primary objective is to facilitate @@ -22,17 +24,30 @@ database name cannot be altered. ### Default database best practices -In multi-tenant environments, we recommend treating the default "memgraph" database as an administrative/system database rather than storing application data in it. This approach provides better security and isolation, especially given recent changes to authentication and authorization requirements. +In multi-tenant environments, we recommend treating the default "memgraph" +database as an administrative/system database rather than storing application +data in it. This approach provides better security and isolation, especially +given recent changes to authentication and authorization requirements. #### Why treat memgraph as an admin database? -As of Memgraph v3.5, users have to have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. Additionally, replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, etc.) also now target the "memgraph" database and require access to it. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. +As of Memgraph v3.5, users have to have both the `AUTH` privilege and access to +the default "memgraph" database to execute authentication and authorization +queries. Additionally, replication queries (such as `REGISTER REPLICA`, `SHOW +REPLICAS`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE +DATABASE`, etc.) also now target the "memgraph" database and require access to +it. This requirement affects multi-tenant environments where users might have +access to other databases but not the default one. #### Recommended setup -1. **Restrict memgraph database access**: Only grant access to the "memgraph" database to privileged users who need to perform system administration tasks -2. **Use tenant-specific databases**: Store all application data in dedicated tenant databases -3. **Separate concerns**: Keep user management, role management, system administration, replication management, and multi-database management separate from application data +1. **Restrict memgraph database access**: Only grant access to the "memgraph" + database to privileged users who need to perform system administration tasks +2. **Use tenant-specific databases**: Store all application data in dedicated + tenant databases +3. **Separate concerns**: Keep user management, role management, system + administration, replication management, and multi-database management + separate from application data #### Example configuration @@ -82,7 +97,8 @@ SET ROLE FOR tenant2_regular_user TO tenant2_user; ``` In this configuration: -- `system_admin_user` can perform all authentication/authorization, replication, and multi-database operations and has access to the "memgraph" database +- `system_admin_user` can perform all authentication/authorization, replication, + and multi-database operations and has access to the "memgraph" database - Tenant users can only access their respective tenant databases - Application data is completely isolated in tenant-specific databases - The "memgraph" database serves purely as an administrative database @@ -94,8 +110,8 @@ instances. Queries executed on a specific database should operate as if it were the sole database in the system, preventing cross-database contamination. Users interact with individual databases, and cross-database queries are prohibited. -Every database has its own database UUID, which can be read by running the `SHOW STORAGE INFO` -query on a particular database. +Every database has its own database UUID, which can be read by running the `SHOW +STORAGE INFO` query on a particular database. ## Database configuration and data directory @@ -119,20 +135,103 @@ based on configuration. Users interact with multi-tenant features through specialized Cypher queries: 1. `CREATE DATABASE name`: Creates a new database. -2. `DROP DATABASE name`: Deletes a specified database. -3. `SHOW DATABASE`: Shows the current used database. It will return `NULL` if - no database is currently in use. You can also use `SHOW CURRENT DATABASE` for the same functionality. This command does not require any special privileges. - -4. `SHOW DATABASES`: Shows only the existing set of multitenant databases. -5. `USE DATABASE name`: Switches focus to a specific database (disabled during +2. `DROP DATABASE name [FORCE]`: Deletes a specified database. +3. `RENAME DATABASE old_name TO new_name`: Renames a database. +4. `SHOW DATABASE`: Shows the current used database. It will return `NULL` if no + database is currently in use. You can also use `SHOW CURRENT DATABASE` for + the same functionality. This command does not require any special privileges. + +5. `SHOW DATABASES`: Shows only the existing set of multitenant databases. +6. `USE DATABASE name`: Switches focus to a specific database (disabled during transactions). -6. `GRANT DATABASE name TO user`: Grants a user access to a specified database. -7. `DENY DATABASE name FROM user`: Denies a user's access to a specified +7. `GRANT DATABASE name TO user`: Grants a user access to a specified database. +8. `DENY DATABASE name FROM user`: Denies a user's access to a specified database. -8. `REVOKE DATABASE name FROM user`: Removes database from user's authentication +9. `REVOKE DATABASE name FROM user`: Removes database from user's authentication context. -9. `SET MAIN DATABASE name FOR user`: Sets a user's default (landing) database. -10. `SHOW DATABASE PRIVILEGES FOR user`: Lists a user's database access rights. +10. `SET MAIN DATABASE name FOR user`: Sets a user's default (landing) database. +11. `SHOW DATABASE PRIVILEGES FOR user`: Lists a user's database access rights. + +### DROP DATABASE with FORCE + +The `DROP DATABASE` command removes an existing database. You can optionally +include the `FORCE` parameter to delete a database even when it has active +connections or transactions. + +{

Syntax

} + +```cypher +DROP DATABASE database_name [FORCE]; +``` + +{

Behavior

} + +- **Without `FORCE`**: The command will fail if the database is currently in use + by any active connections or transactions. +- **With `FORCE`**: The database will be immediately hidden from new connections, + but actual deletion is deferred until it's safe to proceed. All active + transactions using the database will be terminated. + +{

Use cases for FORCE

} + +- **Emergency cleanup**: Remove a database stuck in an inconsistent or + long-running state. +- **Administrative maintenance**: Perform system maintenance requiring immediate + database removal. +- **Development environments**: Quickly reset test environments that might still + have active connections. + +{

Privileges required

} + +Using the `FORCE` option requires: +- `MULTI_DATABASE_EDIT` privilege +- Access to the `memgraph` database +- `TRANSACTION_MANAGEMENT` privilege (to terminate active transactions) + +{

Important considerations

} + +- All active transactions on the target database will be forcibly terminated. +- The database becomes immediately unavailable to new connections. +- Actual deletion may be deferred until existing connections are properly closed. +- **This operation cannot be undone.** + +### RENAME DATABASE + +The `RENAME DATABASE` command allows you to rename an existing database to a new +name. This simplifies administrative workflows by eliminating the need to create +a new database, recover from a snapshot, and drop the old database. + +{

Syntax

} + +```cypher +RENAME DATABASE old_name TO new_name; +``` + +{

Behavior

} + +- The database is **renamed immediately** without requiring unique access. +- If you are currently using the database being renamed, the current database + context is automatically updated to the new name. +- All existing data, indexes, constraints, and other database objects are + preserved. + + +Current implementation of `RENAME` does not update auth data. User/role database +access and database-specific roles information is not updated. This can lead to +unindented access to databases. + + + +{

Important considerations

} + +- The `RENAME DATABASE` command requires the `MULTI_DATABASE_EDIT` privilege and + access to the `memgraph` database. +- The new database name must not already exist. +- The old database name must exist. +- This operation cannot be undone once completed. +- All active connections to the database will continue to work seamlessly with + the new name. + ### User's main database @@ -160,7 +259,9 @@ Access to all databases can be granted or revoked using wildcards: ### Multi-database queries and the memgraph database -As of Memgraph v3.5 multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) target the "memgraph" database and require access to it. +As of Memgraph v3.5 multi-database queries (such as `SHOW DATABASES`, `CREATE +DATABASE`, `DROP DATABASE`, `RENAME DATABASE`, etc.) target the "memgraph" +database and require access to it. To execute these queries, users must have: - The appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) @@ -168,15 +269,21 @@ To execute these queries, users must have: ### Multi-tenant query syntax changes -As of Memgraph v3.5 the syntax for certain queries in multi-tenant environments have changed. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context in some cases. +As of Memgraph v3.5 the syntax for certain queries in multi-tenant environments +have changed. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require +specifying the database context in some cases. -**SHOW ROLE FOR USER**: This command does not require database specification and will show all roles assigned to the user across all databases. +**SHOW ROLE FOR USER**: This command does not require database specification and +will show all roles assigned to the user across all databases. -**SHOW PRIVILEGES FOR USER**: This command requires database specification in multi-tenant environments. +**SHOW PRIVILEGES FOR USER**: This command requires database specification in +multi-tenant environments. -**SHOW PRIVILEGES FOR ROLE**: This command does not require database specification and will show all privileges for the role. +**SHOW PRIVILEGES FOR ROLE**: This command does not require database +specification and will show all privileges for the role. -In multi-tenant environments, you must specify which database context to use when showing privileges for users: +In multi-tenant environments, you must specify which database context to use +when showing privileges for users: 1. **Show roles for the user's main database:** ```cypher @@ -212,11 +319,18 @@ SHOW PRIVILEGES FOR user_or_role ON CURRENT; SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name; ``` -These commands return the aggregated roles and privileges for the user in the specified database context. The `ON MAIN` option shows information for the user's main database, `ON CURRENT` shows information for whatever database is currently active, and `ON DATABASE` shows information for the explicitly specified database. +These commands return the aggregated roles and privileges for the user in the +specified database context. The `ON MAIN` option shows information for the +user's main database, `ON CURRENT` shows information for whatever database is +currently active, and `ON DATABASE` shows information for the explicitly +specified database. #### Impact on multi-tenant environments -In multi-tenant environments where users might not have access to the "memgraph" database, multi-database management operations will fail. This reinforces the recommendation to treat the "memgraph" database as an administrative/system database. +In multi-tenant environments where users might not have access to the "memgraph" +database, multi-database management operations will fail. This reinforces the +recommendation to treat the "memgraph" database as an administrative/system +database. #### Example: Admin user with multi-database privileges @@ -232,13 +346,18 @@ SET ROLE FOR db_admin TO multi_db_admin; ``` In this setup, `db_admin` can: -- Execute all multi-database queries (`SHOW DATABASES`, `CREATE DATABASE`, etc.) +- Execute all multi-database queries (`SHOW DATABASES`, `CREATE DATABASE`, `DROP + DATABASE`, `RENAME DATABASE`, etc.) - Access the "memgraph" database for administrative operations - Manage the multi-tenant database configuration #### Best practice -For multi-database management, ensure that users who need to perform multi-database operations have both the appropriate multi-database privileges and access to the "memgraph" database. This aligns with the overall recommendation to treat the "memgraph" database as an administrative database in multi-tenant environments. +For multi-database management, ensure that users who need to perform +multi-database operations have both the appropriate multi-database privileges +and access to the "memgraph" database. This aligns with the overall +recommendation to treat the "memgraph" database as an administrative database in +multi-tenant environments. ### Additional multi-tenant privileges