rework preloading data section (#145)

* rework preloading data section

* rework user creation section

* remove .zst as supported files

Co-authored-by: Max <max@cedardb.com>

---------

Co-authored-by: Max <max@cedardb.com>

Author: victorpacyna

content/get_started/install_with_docker.md

@@ -30,7 +30,7 @@ Connect using a PostgreSQL client:
 PGPASSWORD=test psql -h localhost -U postgres
 
 postgres= SELECT 1 as foo;
- foo 
+ foo
 -----
    1
 (1 row)
@@ -49,6 +49,7 @@ To retain your database across container restarts, mount a host directory to sto
 mkdir -p /opt/cedardb
 docker run --rm -p 5432:5432 -v /opt/cedardb:/var/lib/cedardb/data -e CEDAR_PASSWORD=test cedardb/cedardb
 ```
+
 This stores the database in `/opt/cedardb` on your host.
 
 {{< callout type="info" >}}
@@ -61,79 +62,101 @@ In this case, CedarDB ignores the `CEDAR_USER` and `CEDAR_PASSWORD` environment
 the existing credentials to be used.
 {{< /callout >}}
 
-
 {{< callout type="info" >}}
 Ensure the mounted database directory resides on a reasonably fast SSD for best performance.
 {{< /callout >}}
 
 ### Custom credentials
+
 You can configure the initial user and database using environment variables, domain sockets, or secrets.
 
 #### Environment variables
+
 ```shell
 docker run --rm -p 5432:5432 \
   -e CEDAR_USER=test \
   -e CEDAR_PASSWORD=test \
   -e CEDAR_DB=db \
   cedardb/cedardb
 ```
+
 This command creates a superuser `test` with password `test` and a a database named `db`.
 
 Connect like this:
+
 ```shell
 psql -h localhost -U test -d db
 ```
 
 The parameters `CEDAR_USER` and `CEDAR_DB` are optional:
+
 - If `CEDAR_USER` is not set, it defaults to `postgres`.
 - If `CEDAR_DB` is not set, it defaults to the value of `CEDAR_USER`.
 
+#### Docker secrets
 
-#### Domain socket authentication
+CedarDB can also read credentials from files, ideal for secret management:
 
-To avoid passing credentials in the shell  (e.g., because you don't want it to appear in your history), you can run CedarDB in domain socket-only mode:
 ```shell
 docker run --rm -p 5432:5432 \
-  -e CEDAR_DOMAIN_SOCKET_ONLY=yes \
-  --name cedardb \
-  cedardb/cedardb
+  -e CEDAR_USER_FILE=/run/secrets/user_file \
+  -e CEDAR_PASSWORD_FILE=/run/secrets/password_file \
+  -e CEDAR_DB=/run/secrets/db_file cedardb/cedardb
 ```
 
-Then connect from the same host using the domain socket:
-```shell
-docker exec -it cedardb psql -U postgres
-```
-Once connected, you can [manually create users and databases](/docs/references/sqlreference/statements/createrole):
-```sql
-create user {{username}} superuser with password '1234';
-create database {{username}};
+You can manage such files using [Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
+
+### Initialization scripts
+
+CedarDB supports auto-initializing a new database with SQL and shell scripts. Additionally, the docker image accepts `xz` or `gzip` compressed SQL files.
+Files in `/docker-entrypoint-initdb.d/` are executed or sourced during container setup. Supported file extensions are `.sh`, `.sql`, `.sql.xz` and `sql.gz`.
+
+`.sh` files can use the `process_sql` function to run modified SQL statements that need shell pre-processing, e.g. by expanding shell or env variables.
+
+#### Example: Creating an additional user at DB initialization
+
+Initialization files let you create additional [users and databases](/docs/references/sqlreference/statements/createrole) during first-time setup. Provide usernames and passwords via environment variables or Docker secrets.
+
+```shell {filename="users/create-user.sh"}
+#!/bin/bash
+set -e
+
+process_sql <<-EOSQL
+  create role ${NEW_USER} login with password '${NEW_USER_PWD}';
+  create database ${NEW_USER};
+EOSQL
 ```
 
-#### Docker secrets
+Then run:
 
-CedarDB can also read credentials from files, ideal for secret management:
 ```shell
-docker run --rm -p 5432:5432 \
-  -e CEDAR_USER_FILE=/run/secrets/user_file \
-  -e CEDAR_PASSWORD_FILE=/run/secrets/password_file \
-  -e CEDAR_DB=/run/secrets/db_file cedardb/cedardb
+docker run -v ./users/:/docker-entrypoint-initdb.d/ \
+  -p 5432:5432 -e CEDAR_PASSWORD=test \
+  -e NEW_USER=nonroot -e NEW_USER_PWD=1234 \
+  --rm cedardb/cedardb
 ```
-You can manage such files using [Docker secrets](https://docs.docker.com/engine/swarm/secrets/).
 
-### Preloading data
-CedarDB supports auto-initializing a new database with SQL and shell scripts.
-Any file in `/docker-entrypoint-initdb.d/` is executed or sourced during container setup.
+Connect with the new user:
+
+```shell
+# Connect to CedarDB
+psql -h localhost -U nonroot -d nonroot
+# Enter '1234' as password
+```
 
-#### Example: Build a custom image
+#### Example: Preloading data with .sh and .sql files
 
 Create a `movies/` directory with the following files:
 
 ```shell {filename="movies/foo.sh"}
 #!/bin/bash
 set -e
-psql -v ON_ERROR_STOP=1 --username "$CEDAR_USER" --dbname "$CEDAR_DB" <<-EOSQL
-	CREATE TABLE foo(a int);
-	INSERT INTO foo VALUES (7);
+TABLE_NAME=foo
+VALUE=7
+
+process_sql <<-EOSQL
+  CREATE TABLE ${TABLE_NAME}(a int);
+  INSERT INTO ${TABLE_NAME} VALUES (${VALUE});
 EOSQL
 ```
 
@@ -152,19 +175,16 @@ insert into movies values
 (3, 'Das Boot', 1981, 149, 'Drama');
 ```
 
-```Dockerfile {filename="movies/Dockerfile"}
-FROM cedardb/cedardb
-COPY movies.sql foo.sh /docker-entrypoint-initdb.d/
-```
-
-Then build and run:
+Then run:
 
 ```shell
-docker build -t cedardb-movies movies/
-docker run --rm -p 5432:5432 -e CEDAR_PASSWORD=test cedardb-movies
+docker run -v ./movies/:/docker-entrypoint-initdb.d/ \
+  -p 5432:5432 -e CEDAR_PASSWORD=test \
+  --rm cedardb/cedardb
 ```
 
 Connect and inspect the data:
+
 ```shell
 # Connect to CedarDB
 psql -h localhost -U postgres
@@ -195,9 +215,6 @@ postgres= select * from foo;
 
 ```
 
-In addition to plain shell scripts and sql files, the CedarDB docker image also accepts `xz`, `gzip`, or `zstd` compressed sql files.
-A file must have one of the following extensions: `.sql`, `.sql.gz`, `sql.xz`, `sql.zst`, or `.sh`.
-
 {{< callout type="info" >}}
 If you have obtained an enterprise license, refer to the [licensing page](../../licensing) for a step-by-step guide on how to activate it.
 {{< /callout >}}