diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 2010ac6a9..fb9dbdca8 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -114,6 +114,7 @@ *** xref:administration/access-control/privileges-writes.adoc[] *** xref:administration/access-control/database-administration.adoc[] *** xref:administration/access-control/dbms-administration.adoc[] +*** xref:administration/access-control/load-privileges.adoc[] *** xref:administration/access-control/limitations.adoc[] *** xref:administration/access-control/privileges-immutable.adoc[] diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax.svg index 651f74540..156002d3a 100644 --- a/modules/ROOT/images/privileges_grant_and_deny_syntax.svg +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg b/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg new file mode 100644 index 000000000..8cf4a0eb4 --- /dev/null +++ b/modules/ROOT/images/privileges_grant_and_deny_syntax_load_privileges.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/modules/ROOT/images/privileges_on_graph_syntax.svg b/modules/ROOT/images/privileges_on_graph_syntax.svg index 689c5c798..321deeb2b 100644 --- a/modules/ROOT/images/privileges_on_graph_syntax.svg +++ b/modules/ROOT/images/privileges_on_graph_syntax.svg @@ -1,9 +1 @@ - - - - - - - - - + \ No newline at end of file diff --git a/modules/ROOT/pages/administration/access-control/built-in-roles.adoc b/modules/ROOT/pages/administration/access-control/built-in-roles.adoc index 24ebdaf37..1b4ad9052 100644 --- a/modules/ROOT/pages/administration/access-control/built-in-roles.adoc +++ b/modules/ROOT/pages/administration/access-control/built-in-roles.adoc @@ -22,7 +22,7 @@ The privileges listed in the following sections are the default set of privilege == The `PUBLIC` role All users are granted the `PUBLIC` role, and it can not be revoked or dropped. -By default, it gives access to the default database and allows executing all procedures and user-defined functions. +By default, it gives access to the default database and allows loading data, executing all procedures and user-defined functions. [IMPORTANT] ==== @@ -45,7 +45,8 @@ SHOW ROLE PUBLIC PRIVILEGES AS COMMANDS |"GRANT ACCESS ON HOME DATABASE TO `PUBLIC`" |"GRANT EXECUTE FUNCTION * ON DBMS TO `PUBLIC`" |"GRANT EXECUTE PROCEDURE * ON DBMS TO `PUBLIC`" -a|Rows: 3 +|"GRANT LOAD ON ALL DATA TO `PUBLIC`" +a|Rows: 4 |=== @@ -73,6 +74,11 @@ GRANT EXECUTE PROCEDURES * ON DBMS TO PUBLIC GRANT EXECUTE USER DEFINED FUNCTIONS * ON DBMS TO PUBLIC ---- +[source, cypher, role=noplay] +---- +GRANT LOAD ON ALL DATA TO PUBLIC +---- + The resulting `PUBLIC` role now has the same privileges as the original built-in `PUBLIC` role. @@ -432,6 +438,7 @@ SHOW ROLE admin PRIVILEGES AS COMMANDS |"GRANT ALL DBMS PRIVILEGES ON DBMS TO `admin`" |"GRANT CONSTRAINT MANAGEMENT ON DATABASE * TO `admin`" |"GRANT INDEX MANAGEMENT ON DATABASE * TO `admin`" +|"GRANT LOAD ON ALL DATA TO `admin`" |"GRANT MATCH {*} ON GRAPH * NODE * TO `admin`" |"GRANT MATCH {*} ON GRAPH * RELATIONSHIP * TO `admin`" |"GRANT NAME MANAGEMENT ON DATABASE * TO `admin`" @@ -441,7 +448,7 @@ SHOW ROLE admin PRIVILEGES AS COMMANDS |"GRANT STOP ON DATABASE * TO `admin`" |"GRANT TRANSACTION MANAGEMENT (*) ON DATABASE * TO `admin`" |"GRANT WRITE ON GRAPH * TO `admin`" -a|Rows: 13 +a|Rows: 14 |=== If the built-in `admin` role has been altered or dropped, and needs to be restored to its original state, see link:{neo4j-docs-base-uri}/operations-manual/{page-version}/configuration/password-and-user-recovery[Operations Manual -> Password and user recovery]. @@ -489,6 +496,11 @@ GRANT MATCH {*} ON GRAPH * TO admin GRANT WRITE ON GRAPH * TO admin ---- +[source, cypher, role=noplay] +---- +GRANT LOAD ON ALL DATA TO admin +---- + [source, cypher, role=noplay] ---- GRANT ALL ON DATABASE * TO admin diff --git a/modules/ROOT/pages/administration/access-control/dbms-administration.adoc b/modules/ROOT/pages/administration/access-control/dbms-administration.adoc index 292fdd8a8..03c165f01 100644 --- a/modules/ROOT/pages/administration/access-control/dbms-administration.adoc +++ b/modules/ROOT/pages/administration/access-control/dbms-administration.adoc @@ -86,6 +86,7 @@ These include: * Manage users and roles. * Manage sub-graph privileges. * Manage procedure security. +* Loading data. To enable a user to perform these tasks, you can grant them the `admin` role, but it is also possible to make a custom role with a subset of these privileges. All privileges are also assignable using Cypher commands. @@ -99,6 +100,7 @@ For more details, see the following sections: * xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-privilege-management[Privilege management] * xref::administration/access-control/database-administration.adoc#access-control-database-administration-transaction[Transaction management] * xref::administration/access-control/dbms-administration.adoc#access-control-dbms-administration-execute[Procedure and user-defined function security] +* xref::administration/access-control/load-privileges.adoc[Load privileges] [[access-control-dbms-administration-custom]] == Using a custom role to manage DBMS privileges diff --git a/modules/ROOT/pages/administration/access-control/index.adoc b/modules/ROOT/pages/administration/access-control/index.adoc index 5506d1f1c..5430fdf1a 100644 --- a/modules/ROOT/pages/administration/access-control/index.adoc +++ b/modules/ROOT/pages/administration/access-control/index.adoc @@ -32,6 +32,7 @@ More details about specific categories of access control can be found in the fol * xref:administration/access-control/privileges-writes.adoc[] * xref:administration/access-control/database-administration.adoc[] * xref:administration/access-control/dbms-administration.adoc[] +* xref:administration/access-control/load-privileges.adoc[] * xref:administration/access-control/limitations.adoc[] * xref:administration/access-control/privileges-immutable.adoc[] diff --git a/modules/ROOT/pages/administration/access-control/load-privileges.adoc b/modules/ROOT/pages/administration/access-control/load-privileges.adoc new file mode 100644 index 000000000..b313b09c2 --- /dev/null +++ b/modules/ROOT/pages/administration/access-control/load-privileges.adoc @@ -0,0 +1,82 @@ +:description: How to use Cypher to manage load privileges. + +//// +[source, cypher, role=test-setup] +---- +CREATE ROLE roleLoadAllData +---- +//// + +[role=enterprise-edition aura-db-enterprise] +[[access-control-load-privileges]] += Load privileges + +_This feature was released in Neo4j 5.13._ + +This section explains how to use Cypher to manage load privileges. +All load privileges apply to the whole system. +Like DBMS privileges, they do not belong to one specific database or graph. +For more details on the differences between graphs, databases, and the DBMS, refer to xref::introduction/cypher_neo4j.adoc[]. + +image::privileges_grant_and_deny_syntax_load_privileges.svg[width="800", title="Syntax of GRANT and DENY load Privileges"] + +// TODO: add image later when there is more than one LOAD privilege +//image::privileges_hierarchy_load.svg[title="Load privileges hierarchy"] + +The load privileges apply to the xref:clauses/load-csv.adoc[`LOAD CSV` clause], deciding whether or not the data can be loaded from the given source. + +The load privileges are assigned using Cypher administrative commands. +They can be granted, denied, and revoked in the same way as other privileges. +For more details, see xref:administration/access-control/manage-privileges.adoc[]. + +.Load privileges command syntax +[options="header", width="100%", cols="3a,2"] +|=== +| Command | Description + +| [source, syntax, role=noheader] +GRANT [IMMUTABLE] LOAD + ON ALL DATA + TO role[, ...] +| Enables the specified roles to load external data in queries. + +|=== + +[NOTE] +==== +More details about the syntax descriptions can be found xref:administration/index.adoc#administration-syntax[here]. +==== + +Unlike other privileges, the `LOAD` privilege is not granted, denied, or revoked on `DBMS`, `Database`, or `Graph`, but instead on the data source to load from. +Adding `ON ALL DATA` means a role has the privilege to load data from all sources. + +[[access-control-load-all-data]] +== The `ALL DATA` privilege + +The load privilege on `ALL DATA` enables or disables loading data. +If granted, the user can load data from any source. +If missing or denied, no data can be loaded at all. + +For example, the below query grants users with the role `roleLoadAllData` the ability to load data with `LOAD CSV`: + +[source, cypher, role=noplay] +---- +GRANT LOAD ON ALL DATA TO roleLoadAllData +---- + +The below query lists all privileges for the role `roleLoadAllData` as commands: + +[source, cypher, role=noplay] +---- +SHOW ROLE roleLoadAllData PRIVILEGES AS COMMANDS +---- + +.Result +[options="header,footer", width="100%", cols="m"] +|=== +|command +|"GRANT LOAD ON ALL DATA TO `roleLoadAllData`" +a|Rows: 1 +|=== + +The `LOAD ON ALL DATA` privilege is granted to the `PUBLIC` role by default. \ No newline at end of file diff --git a/modules/ROOT/pages/administration/access-control/manage-privileges.adoc b/modules/ROOT/pages/administration/access-control/manage-privileges.adoc index 155a8c235..a2729e052 100644 --- a/modules/ROOT/pages/administration/access-control/manage-privileges.adoc +++ b/modules/ROOT/pages/administration/access-control/manage-privileges.adoc @@ -189,11 +189,11 @@ See link:{neo4j-docs-base-uri}/status-codes/{page-version}/notifications/all-not The general `GRANT` and `DENY` syntaxes are illustrated in the following image: -image::privileges_grant_and_deny_syntax.svg[title="GRANT and DENY Syntax"] +image::privileges_grant_and_deny_syntax.svg[width="800", title="GRANT and DENY Syntax"] A more detailed syntax illustration for graph privileges would be the following: -image::privileges_on_graph_syntax.svg[title="Syntax of GRANT and DENY Graph Privileges. The `{` and `}` are part of the syntax and not used for grouping."] +image::privileges_on_graph_syntax.svg[width="800", title="Syntax of GRANT and DENY Graph Privileges. The `{` and `}` are part of the syntax and not used for grouping."] The following image shows the hierarchy between different graph privileges: diff --git a/modules/ROOT/pages/administration/databases.adoc b/modules/ROOT/pages/administration/databases.adoc index 8293f40c3..5ff27a220 100644 --- a/modules/ROOT/pages/administration/databases.adoc +++ b/modules/ROOT/pages/administration/databases.adoc @@ -91,11 +91,24 @@ CREATE OR REPLACE COMPOSITE DATABASE name ALTER DATABASE name [IF EXISTS] { SET ACCESS {READ ONLY \| READ WRITE} \| -SET TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}] +SET TOPOLOGY n PRIMAR{Y\|IES} [m SECONDAR{Y\|IES}] \| +SET OPTION option value } [WAIT [n [SEC[OND[S]]]]\|NOWAIT] ---- +[source, syntax] +---- +ALTER DATABASE name [IF EXISTS] +REMOVE OPTION option +[WAIT [n [SEC[OND[S]]]]\|NOWAIT] +---- + +[NOTE] +==== +There can be multiple `SET OPTION` or `REMOVE OPTION` clauses for different option keys. +==== + | STOP DATABASE | [source, syntax, role="noheader"] @@ -180,7 +193,7 @@ The default for a standalone database is `neo4j://localhost:7687`. label:default | BOOLEAN | requestedStatus -| The expected status of the database. +| The expected status of the database. The value can be either `online` or `offline`. label:default-output[] | STRING @@ -281,6 +294,10 @@ The lag is expressed in negative integers. In standalone environments, the value |The names of any constituents the database may have. label:default-output[] | LIST +|options +|The map of options applied to the database. +| MAP + |=== @@ -744,6 +761,12 @@ Defines additional configuration specified by comma separated `name=value` pairs | Defines credentials that needs to be passed into certain seed providers. +| `txLogEnrichment` +| `FULL` \| `DIFF` \| `NONE` +| +Defines level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes. +For details about enrichment mode, see link:{neo4j-docs-base-uri}/cdc/{page-version}/getting-started/enrichment-mode[Change Data Capture Manual -> Getting Started -> Enrichment mode]. + |=== @@ -903,6 +926,118 @@ ALTER DATABASE nonExisting IF EXISTS SET TOPOLOGY 1 PRIMARY 0 SECONDARY [role="statsonlyqueryresult"] 0 rows +[role=enterprise-edition] +[[administration-databases-alter-database-options]] +=== Options + +//// +[source, cypher, role=test-setup] +---- +CREATE DATABASE `options-example`; +---- +//// + +The `ALTER DATABASE` command can be used to set or remove specific options, which are listed below. + +[options="header"] +|=== + +| Key | Value | Description + +| `txLogEnrichment` +| `FULL` \| `DIFF` \| `NONE` +| +Defines level of enrichment applied to transaction logs for Change Data Capture (CDC) purposes. +For details about enrichment mode, see link:{neo4j-docs-base-uri}/cdc/{page-version}/getting-started/enrichment-mode[Change Data Capture Manual -> Getting Started -> Enrichment mode]. + +|=== + +[NOTE] +==== +There are no available `OPTIONS` values for composite databases. +==== + +.+ALTER DATABASE SET OPTION+ +====== + +// skip test until we make the change_data_capture feature flag on by default. + +.Query +[source, cypher, role="test-skip"] +---- +ALTER DATABASE `options-example` +SET OPTION txLogEnrichment 'FULL' +---- + +====== + +.+SHOW DATABASE+ +====== + +// skip test until we make the change_data_capture feature flag on by default. + +.Query +[source, cypher, role="test-skip"] +---- +SHOW DATABASES yield name, options +---- + +// Limited result set. +// The output has been capped. + +.Result +[role="queryresult",options="header,footer",cols="2*