databendlabs · BohuTANG · Aug 6, 2025 · Aug 6, 2025
diff --git a/docs/en/developer/00-drivers/index.md b/docs/en/developer/00-drivers/index.md
@@ -15,15 +15,17 @@ Databend provides official drivers for multiple programming languages, enabling
 All Databend drivers use the same DSN (Data Source Name) format:
 
 ```
-databend://user:pass@host[:port]/[database][?sslmode=disable][&arg1=value1]
+databend://user:pwd@host[:port]/[database][?sslmode=disable][&arg1=value1]
 ```
 
+> The `user:pwd` refers to SQL users in Databend. See [CREATE USER](/sql/sql-commands/ddl/user/user-create-user) to create users and grant privileges.
+
 ### Connection Examples
 
 | Deployment | Connection String |
 |------------|-------------------|
-| **Self-hosted** | `databend://user:pass@host:8000/database?sslmode=disable` |
-| **Databend Cloud** | `databend://user:pass@host:443/database?warehouse=wh` |
+| **Self-hosted** | `databend://user:pwd@host:8000/database?sslmode=disable` |
+| **Databend Cloud** | `databend://user:pwd@host:443/database?warehouse=wh` |
 
 ### Parameters Reference
 

diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/01-user-create-user.md b/docs/en/sql-reference/10-sql-commands/00-ddl/02-user/01-user-create-user.md
@@ -6,192 +6,101 @@ import FunctionDescription from '@site/src/components/FunctionDescription';
 
 <FunctionDescription description="Introduced or updated: v1.2.703"/>
 
-Creates a SQL user.
+Creates a SQL user for connecting to Databend. Users must be granted appropriate privileges to access databases and perform operations.
 
 See also:
-
- - [CREATE PASSWORD POLICY](../12-password-policy/create-password-policy.md)
- - [CREATE NETWORK POLICY](../12-network-policy/ddl-create-policy.md)
- - [GRANT](10-grant.md)
+- [GRANT](10-grant.md)
+- [ALTER USER](03-user-alter-user.md)
+- [DROP USER](02-user-drop-user.md)
 
 ## Syntax
 
 ```sql
 CREATE [ OR REPLACE ] USER <name> IDENTIFIED [ WITH <auth_type> ] BY '<password>' 
 [ WITH MUST_CHANGE_PASSWORD = true | false ]
-[ WITH SET PASSWORD POLICY = '<policy_name>' ] -- Set password policy
-[ WITH SET NETWORK POLICY = '<policy_name>' ] -- Set network policy
-[ WITH SET WORKLOAD GROUP = '<workload_group_name>' ] -- Set workload group
-[ WITH DEFAULT_ROLE = '<role_name>' ] -- Set default role
-[ WITH DISABLED = true | false ] -- User created in a disabled state
+[ WITH SET PASSWORD POLICY = '<policy_name>' ]
+[ WITH SET NETWORK POLICY = '<policy_name>' ]
+[ WITH DEFAULT_ROLE = '<role_name>' ]
+[ WITH DISABLED = true | false ]
 ```
 
-- The `<name>` cannot contain the following illegal characters:
-    - Single quote (')
-    - Double quote (")
-    - Backspace (\b)
-    - Form feed (\f)
-- *auth_type* can be `double_sha1_password` (default), `sha256_password` or `no_password`.
-- When `MUST_CHANGE_PASSWORD` is set to `true`, the new user must change password at first login. Users can change their own password using the [ALTER USER](03-user-alter-user.md) command.
-- When you set a default role for a user using CREATE USER or [ALTER USER](03-user-alter-user.md), Databend does not verify the role's existence or automatically grant the role to the user. You must explicitly grant the role to the user for the role to take effect.
-- When `DISABLED` is set to `true`, the new user is created in a disabled state. Users in this state cannot log in to Databend until they are enabled. To enable or disable a created user, use the [ALTER USER](03-user-alter-user.md) command.
+**Parameters:**
+- `<name>`: Username (cannot contain single quotes, double quotes, backspace, or form feed characters)
+- `<auth_type>`: Authentication type - `double_sha1_password` (default), `sha256_password`, or `no_password`
+- `MUST_CHANGE_PASSWORD`: When `true`, user must change password at first login
+- `DEFAULT_ROLE`: Sets default role (role must be explicitly granted to take effect)
+- `DISABLED`: When `true`, user is created in disabled state and cannot log in
 
 ## Examples
 
-### Example 1: Creating User with Default auth_type
-
-```sql
-CREATE USER user1 IDENTIFIED BY 'abc123';
-
-SHOW USERS;
-+-----------+----------+----------------------+---------------+
-| name      | hostname | auth_type            | is_configured |
-+-----------+----------+----------------------+---------------+
-| user1     | %        | double_sha1_password | NO            |
-+-----------+----------+----------------------+---------------+
-```
-
-### Example 2: Creating User with sha256_password auth_type
-
-```sql
-CREATE USER user1 IDENTIFIED WITH sha256_password BY 'abc123';
-
-SHOW USERS;
-+-----------+----------+----------------------+---------------+
-| name      | hostname | auth_type            | is_configured |
-+-----------+----------+----------------------+---------------+
-| user1     | %        | sha256_password      | NO            |
-+-----------+----------+----------------------+---------------+
-```
+### Example 1: Create User and Grant Database Privileges
 
-### Example 3: Creating User with Network Policy
+Create a user and grant database privileges:
 
 ```sql
-CREATE USER user1 IDENTIFIED BY 'abc123' WITH SET NETWORK POLICY='test_policy';
-
-SHOW USERS;
-+-----------+----------+----------------------+---------------+
-| name      | hostname | auth_type            | is_configured |
-+-----------+----------+----------------------+---------------+
-| user1     | %        | double_sha1_password | NO            |
-+-----------+----------+----------------------+---------------+
-```
-
-### Example 4: Creating User with Default Role
-
-1. Create a user named 'user1' with the default role set to 'manager':
-
-```sql title='Connect as user "root":'
-SHOW ROLES;
-
-┌───────────────────────────────────────────────────────────┐
-│      name     │ inherited_roles │ is_current │ is_default │
-│     String    │      UInt64     │   Boolean  │   Boolean  │
-├───────────────┼─────────────────┼────────────┼────────────┤
-│ account_admin │               0 │ true       │ true       │
-│ developer     │               0 │ false      │ false      │
-│ public        │               0 │ false      │ false      │
-└───────────────────────────────────────────────────────────┘
+-- Create a new user
+CREATE USER data_analyst IDENTIFIED BY 'secure_password123';
 
-CREATE USER user1 IDENTIFIED BY 'abc123' WITH DEFAULT_ROLE = 'manager';
-
-GRANT ROLE developer TO user1;
+-- Grant database privileges to the user
+GRANT SELECT, INSERT ON default.* TO data_analyst;
 ```
 
-2. Verify the default role of user "user1" using the [SHOW ROLES](04-user-show-roles.md) command:
-
-```sql title='Connect as user "user1":'
-eric@Erics-iMac ~ % bendsql --user user1 --password abc123
-Welcome to BendSQL 0.9.3-db6b232(2023-10-26T12:36:55.578667000Z).
-Connecting to localhost:8000 as user user1.
-Connected to DatabendQuery v1.2.271-nightly-0598a77b9c(rust-1.75.0-nightly-2023-12-26T11:29:04.266265000Z)
-
-user1@localhost:8000/default> SHOW ROLES;
-
-SHOW ROLES
-
-┌───────────────────────────────────────────────────────┐
-│    name   │ inherited_roles │ is_current │ is_default │
-│   String  │      UInt64     │   Boolean  │   Boolean  │
-├───────────┼─────────────────┼────────────┼────────────┤
-│ developer │               0 │ true       │ true       │
-│ public    │               0 │ false      │ false      │
-└───────────────────────────────────────────────────────┘
-2 rows read in 0.015 sec. Processed 0 rows, 0 B (0 rows/s, 0 B/s)
-```
-
-### Example 5: Creating User in Disabled State
-
-This example creates a user named 'u1' in a disabled state, preventing login access. After enabling the user using the [ALTER USER](03-user-alter-user.md) command, login access is restored.
-
-1. Create a user named 'u1' in the disabled state:
-
+Verify the user and permissions:
 ```sql
-CREATE USER u1 IDENTIFIED BY '123' WITH DISABLED = TRUE;
-
-SHOW USERS;
-
-┌─────────────────────────────────────────────────────────────────────────────────────┐
-│  name  │ hostname │       auth_type      │ is_configured │  default_role │ disabled │
-├────────┼──────────┼──────────────────────┼───────────────┼───────────────┼──────────┤
-│ root   │ %        │ no_password          │ YES           │ account_admin │ false    │
-│ u1     │ %        │ double_sha1_password │ NO            │               │ true     │
-└─────────────────────────────────────────────────────────────────────────────────────┘
+SHOW GRANTS FOR data_analyst;
++---------------------------------------------------+
+| Grants                                            |
++---------------------------------------------------+
+| GRANT SELECT,INSERT ON 'default'.* TO 'data_analyst'@'%' |
++---------------------------------------------------+
 ```
 
-2. Attempt to connect to Databend using BendSQL as user 'u1', resulting in an authentication error:
+### Example 2: Create User and Grant Role
 
-```shell
-➜  ~ bendsql --user u1 --password 123
-Welcome to BendSQL 0.16.0-homebrew.
-Connecting to localhost:8000 as user u1.
-Error: APIError: RequestError: Start Query failed with status 401 Unauthorized: {"error":{"code":"401","message":"AuthenticateFailure: user u1 is disabled. Not allowed to login"}}
-```
-
-3. Enable the user 'u1' with the [ALTER USER](03-user-alter-user.md) command:
+Create a user and assign a role with specific privileges:
 
 ```sql
-ALTER USER u1 WITH DISABLED = FALSE;
+-- Create a role with specific privileges
+CREATE ROLE analyst_role;
+GRANT SELECT ON *.* TO ROLE analyst_role;
+GRANT INSERT ON default.* TO ROLE analyst_role;
+
+-- Create user and grant the role
+CREATE USER john_analyst IDENTIFIED BY 'secure_pass456';
+GRANT ROLE analyst_role TO john_analyst;
 ```
 
-4. Re-attempt connection to Databend as user 'u1', confirming successful login access:
-
-```shell
-➜  ~ bendsql --user u1 --password 123
-Welcome to BendSQL 0.16.0-homebrew.
-Connecting to localhost:8000 as user u1.
-Connected to Databend Query v1.2.424-nightly-d3a89f708d(rust-1.77.0-nightly-2024-04-17T22:11:59.304509266Z)
+Verify the role assignment:
+```sql
+SHOW GRANTS FOR john_analyst;
++------------------------------------------+
+| Grants                                   |
++------------------------------------------+
+| GRANT SELECT ON *.* TO 'analyst_role'    |
+| GRANT INSERT ON 'default'.* TO 'analyst_role' |
++------------------------------------------+
 ```
 
-### Example 6: Creating User with MUST_CHANGE_PASSWORD
-
-In this example, we will create a user with the `MUST_CHANGE_PASSWORD` option. Then, we will connect to Databend with BendSQL as the new user and change the password.
-
-1. Create a new user named 'eric' with the `MUST_CHANGE_PASSWORD` option set to `TRUE`.
+### Example 3: Create Users with Different Authentication Types
 
 ```sql
-CREATE USER eric IDENTIFIED BY 'abc123' WITH MUST_CHANGE_PASSWORD = TRUE;
-```
-
-2. Launch BendSQL and connect to Databend as the new user. Once connected, you'll see a message indicating that a password change is required. 
+-- Create user with default authentication
+CREATE USER user1 IDENTIFIED BY 'abc123';
 
-```bash
-MacBook-Air:~ eric$ bendsql -ueric -pabc123
+-- Create user with SHA256 authentication
+CREATE USER user2 IDENTIFIED WITH sha256_password BY 'abc123';
 ```
 
-3. Change the password with the [ALTER USER](03-user-alter-user.md) command.
-
-```bash
-eric@localhost:8000/default> ALTER USER USER() IDENTIFIED BY 'abc456';
-```
+### Example 4: Create Users with Special Configurations
 
-4. Quit BendSQL then reconnect with the new password.
+```sql
+-- Create user with password change requirement
+CREATE USER new_employee IDENTIFIED BY 'temp123' WITH MUST_CHANGE_PASSWORD = true;
 
-```bash
-MacBook-Air:~ eric$ bendsql -ueric -pabc456
-Welcome to BendSQL 0.19.2-1e338e1(2024-07-17T09:02:28.323121000Z).
-Connecting to localhost:8000 as user eric.
-Connected to Databend Query v1.2.567-nightly-78d41aedc7(rust-1.78.0-nightly-2024-07-14T22:10:13.777450105Z)
+-- Create user in disabled state
+CREATE USER temp_user IDENTIFIED BY 'abc123' WITH DISABLED = true;
 
-eric@localhost:8000/default>
+-- Create user with default role (role must be granted separately)
+CREATE USER manager IDENTIFIED BY 'abc123' WITH DEFAULT_ROLE = 'admin';
+GRANT ROLE admin TO manager;
 ```