Documented changes in SQL user management

doc/sql.extensions/README.ddl.txt

@@ -156,6 +156,7 @@ basic_type:
 - ROLE
 - CHARACTER SET
 - COLLATION
+- USER (ability to store comment depends upon user management plugin)
 - SECURITY CLASS (not implemented because Borland hid them).
 
 

doc/sql.extensions/README.user_management

@@ -1,35 +1,82 @@
-SQL Language Extension: CREATE/ALTER/DROP USER
+SQL Language Extension: CREATE/ALTER/CREATE_OR_ALTER/DROP USER
 
    Implements capability to manage users from regular database attachment.
 
+
 Author:
    Alex Peshkoff <peshkoff@mail.ru>
 
+
 Syntax is:
 
-   CREATE USER name {PASSWORD 'password'} [FIRSTNAME 'firstname'] [MIDDLENAME 'middlename'] [LASTNAME 'lastname'];
-   ALTER USER name [PASSWORD 'password'] [FIRSTNAME 'firstname'] [MIDDLENAME 'middlename'] [LASTNAME 'lastname'];
+   CREATE USER name {PASSWORD 'password'} [ options ] [ TAGS ( tag [, tag [, tag ...]] ) ]
+   ALTER USER name SET [PASSWORD 'password'] [ options ] [ TAGS ( tag [, tag [, tag ...]] ) ]
+   CREATE OR ALTER USER name SET [PASSWORD 'password'] [ options ] [ TAGS ( tag [, tag [, tag ...]] ) ]
    DROP USER name;
 
+where OPTIONS is a (probably empty) list of following options:
+- FIRSTNAME 'firstname'
+- MIDDLENAME 'middlename'
+- LASTNAME 'lastname'
+- ACTIVE
+- INACTIVE
+
+and each TAG may have one of two forms:
+NAME = 'VALUE'
+  or:
+DROP NAME
+  where NAME is any valid SQL identifier.
+
+
 Description:
 
-Makes it possible to add, modify and delete users in security database using SQL language. 
+Makes it possible to add, modify and delete users in security database using SQL language.
 
-Firebird 2.5 has no way to make it possible to setup different security databases. But since 3.0 
-this is supposed to become standard feature, therefore it's highly recommended (though currently the 
-result does not change) to modify users being connected to really that database, where modification 
-is required. 
+Firebird since version 3.0 supports multiple security databases. gsec utility and services API
+do not support it and use of them to manage users is deprecated. 
 
-CREATE and DROP clauses are available only for SYSDBA (or other user, granted RDB$ADMIN role in 
-security database). Ordinary user can ALTER his own password and/or wide names. Attempt to modify
+CREATE and DROP clauses are available only for SYSDBA (or other user, granted RDB$ADMIN role in
+security database). Ordinary user can ALTER his own password, wide names and tags. Attempt to modify
 another user will fail.
 
-At least one of PASSWORD, FIRSTNAME, MIDDLENAME or LASTNAME must be present in ALTER USER statement.
-Also notice that PASSWORD clause is required when creating new user.
+At least one of PASSWORD, FIRSTNAME, MIDDLENAME, LASTNAME, ACTIVE, INACTIVE or TAGS must be present
+in ALTER USER statement. Also notice that PASSWORD clause is required when creating new user.
 
-Sample:
+PASSWORD clause is enough self-descripting. Clauses FIRSTNAME, MIDDLENAME and LASTNAME too, but may
+be also used to store any short information about user. Clauses INACTIVE/ACTIVE are used to disable
+user's login to server not dropping it from the list and restoring that ability.
 
+TAGS is a list of end-user defined attributes. Length of the value should not exceed 255 bytes.
+Setting a list of tags for the user keeps earlier set tags if they are not mentioned currently.
+Notice - UID/GID, entered by deprecated gsec, are treated as tags in SQL interface.
+
+To access list of users please select from virtual tables SEC$USERS and SEC$USER_ATTRIBUTES.
+
+
+Samples:
+
+ Generic:
    CREATE USER alex PASSWORD 'test';
-   ALTER USER alex FIRSTNAME 'Alex' LASTNAME 'Peshkoff';
-   ALTER USER alex PASSWORD 'IdQfA';
+   ALTER USER alex SET FIRSTNAME 'Alex' LASTNAME 'Peshkoff';
+   CREATE OR ALTER USER alex SET PASSWORD 'IdQfA';
    DROP USER alex;
+
+ Working with tags:
+   ALTER USER alex SET TAGS (a='a', b='b');
+	NAME             VALUE
+	================ ============================== 
+	A                a
+	B                b
+
+   ALTER USER alex SET TAGS (b='x', c='d');
+	NAME             VALUE
+	================ ============================== 
+	A                a
+	B                x
+	C                d
+
+   ALTER USER alex SET TAGS (drop a, c='sample');
+	NAME             VALUE
+	================ ============================== 
+	B                x
+	C                sample