Merge pull request #2677 from szarnyasg/odbc-nits2

Adjust macOS ODBC page
duckdb · Apr 4, 2024 · 078ec3d · 078ec3d
2 parents d83cda9 + 122edb2
commit 078ec3d
Show file tree

Hide file tree

Showing 7 changed files with 95 additions and 115 deletions.
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,6 +1,6 @@
 GIT
   remote: https://github.com/duckdb/rouge.git
-  revision: f39c4b2b37a909f33709c81e944d1cac85343f02
+  revision: 28137b96594fa26e60e6aaaf533222fcf7d215a7
   branch: duckdb
   specs:
     rouge (3.3823.1)

diff --git a/_data/menu_docs_dev.json b/_data/menu_docs_dev.json
@@ -364,6 +364,10 @@
                 {
                   "page": "macOS Setup",
                   "url": "macos"
+                },
+                {
+                  "page": "Configuration",
+                  "url": "configuration"
                 }
               ]
             }

diff --git a/docs/api/cli/arguments.md b/docs/api/cli/arguments.md
@@ -13,37 +13,37 @@ Fot a list of dot commands available in the CLI shell, see the [Dot Commands pag
 
 | Argument | Description |
 |---|-------|
-| `-append`         | Append the database to the end of the file                           |
-| `-ascii`          | Set [output mode](output-formats) to `ascii`                         |
-| `-bail`           | Stop after hitting an error                                          |
-| `-batch`          | Force batch I/O                                                      |
-| `-box`            | Set [output mode](output-formats) to `box`                           |
-| `-column`         | Set [output mode](output-formats) to `column`                        |
-| `-cmd COMMAND`    | Run `COMMAND` before reading `stdin`                                 |
-| `-c COMMAND`      | Run `COMMAND` and exit                                               |
-| `-csv`            | Set [output mode](output-formats) to `csv`                           |
-| `-echo`           | Print commands before execution                                      |
-| `-init FILENAME`  | Run the script in `FILENAME` upon startup (instead of `~./duckdbrc`) |
-| `-header`         | Turn headers on                                                      |
-| `-help`           | Show this message                                                    |
-| `-html`           | Set [output mode](output-formats) to HTML                            |
-| `-interactive`    | Force interactive I/O                                                |
-| `-json`           | Set [output mode](output-formats) to `json`                          |
-| `-line`           | Set [output mode](output-formats) to `line`                          |
-| `-list`           | Set [output mode](output-formats) to `list`                          |
-| `-markdown`       | Set [output mode](output-formats) to `markdown`                      |
-| `-newline SEP`    | Set output row separator. Default: `\n`                              |
-| `-nofollow`       | Refuse to open symbolic links to database files                      |
-| `-noheader`       | Turn headers off                                                     |
-| `-no-stdin`       | Exit after processing options instead of reading stdin               |
-| `-nullvalue TEXT` | Set text string for `NULL` values. Default: empty string             |
-| `-quote`          | Set [output mode](output-formats) to `quote`                         |
-| `-readonly`       | Open the database read-only                                          |
-| `-s COMMAND`      | Run `COMMAND` and exit                                               |
-| `-separator SEP`  | Set output column separator to SEP. Default: `|`                     |
-| `-stats`          | Print memory stats before each finalize                              |
-| `-table`          | Set [output mode](output-formats) to `table`                         |
-| `-unsigned`       | Allow loading of unsigned extensions                                 |
-| `-version`        | Show DuckDB version                                                  |
+| `-append`         | Append the database to the end of the file                                            |
+| `-ascii`          | Set [output mode](output-formats) to `ascii`                                          |
+| `-bail`           | Stop after hitting an error                                                           |
+| `-batch`          | Force batch I/O                                                                       |
+| `-box`            | Set [output mode](output-formats) to `box`                                            |
+| `-column`         | Set [output mode](output-formats) to `column`                                         |
+| `-cmd COMMAND`    | Run `COMMAND` before reading `stdin`                                                  |
+| `-c COMMAND`      | Run `COMMAND` and exit                                                                |
+| `-csv`            | Set [output mode](output-formats) to `csv`                                            |
+| `-echo`           | Print commands before execution                                                       |
+| `-init FILENAME`  | Run the script in `FILENAME` upon startup (instead of `~./duckdbrc`)                  |
+| `-header`         | Turn headers on                                                                       |
+| `-help`           | Show this message                                                                     |
+| `-html`           | Set [output mode](output-formats) to HTML                                             |
+| `-interactive`    | Force interactive I/O                                                                 |
+| `-json`           | Set [output mode](output-formats) to `json`                                           |
+| `-line`           | Set [output mode](output-formats) to `line`                                           |
+| `-list`           | Set [output mode](output-formats) to `list`                                           |
+| `-markdown`       | Set [output mode](output-formats) to `markdown`                                       |
+| `-newline SEP`    | Set output row separator. Default: `\n`                                               |
+| `-nofollow`       | Refuse to open symbolic links to database files                                       |
+| `-noheader`       | Turn headers off                                                                      |
+| `-no-stdin`       | Exit after processing options instead of reading stdin                                |
+| `-nullvalue TEXT` | Set text string for `NULL` values. Default: empty string                              |
+| `-quote`          | Set [output mode](output-formats) to `quote`                                          |
+| `-readonly`       | Open the database read-only                                                           |
+| `-s COMMAND`      | Run `COMMAND` and exit                                                                |
+| `-separator SEP`  | Set output column separator to SEP. Default: `|`                                      |
+| `-stats`          | Print memory stats before each finalize                                               |
+| `-table`          | Set [output mode](output-formats) to `table`                                          |
+| `-unsigned`       | Allow loading of [unsigned extensions](../../extensions/overview#unsigned-extensions) |
+| `-version`        | Show DuckDB version                                                                   |
 
 <!-- markdownlint-enable MD056 -->
diff --git a/docs/api/odbc/configuration.md b/docs/api/odbc/configuration.md
@@ -0,0 +1,48 @@
+---
+layout: docu
+title: ODBC Configuration
+---
+
+This page documents the files using the ODBC configuration.
+
+## The `odbc.ini` or `.odbc.ini` File
+
+The `.odbc.ini` contains the DSNs for the drivers, which can have specific knobs.
+
+Example of `.odbc.ini` with DuckDB:
+
+```ini
+[DuckDB]
+Driver = DuckDB Driver
+Database = :memory:
+access_mode = read_only
+allow_unsigned_extensions = true
+```
+
+* `[DuckDB]`: between the brackets is a DSN for the DuckDB.
+* `Driver`: Describes the driver's name, as well as where to find the configurations in the `.odbcinst.ini`.
+* `Database`: Describes the database name used by DuckDB, can also be a file path to a `.db` in the system.
+* `access_mode`: The mode in which to connect to the database.
+* `allow_unsigned_extensions`: Allow the use of [unsigned extensions](../../extensions/overview#unsigned-extensions).
+
+## The `.odbcinst.ini` File
+
+The `.odbcinst.ini` contains general configurations for the ODBC installed drivers in the system.
+A driver section starts with the driver name between brackets, and then it follows specific configuration knobs belonging to that driver.
+
+Example of `.odbcinst.ini` with the DuckDB:
+
+```ini
+[ODBC]
+Trace = yes
+TraceFile = /tmp/odbctrace
+
+[DuckDB Driver]
+Driver = /path/to/libduckdb_odbc.dylib
+```
+
+* `[ODBC]`: it is the DM configuration section.
+* `Trace`: it enables the ODBC trace file using the option `yes`.
+* `TraceFile`: the absolute system file path for the ODBC trace file.
+* `[DuckDB Driver]`: the section of the DuckDB installed driver.
+* `Driver`: the absolute system file path of the DuckDB driver. Change to match your configuration.
diff --git a/docs/api/odbc/linux.md b/docs/api/odbc/linux.md
@@ -90,40 +90,4 @@ The ODBC setup on Linux is based on files, the well-known `.odbc.ini` and `.odbc
 These files can be placed at the system `/etc` directory or at the user home directory `/home/⟨user⟩` (shortcut as `~/`).
 The DM prioritizes the user configuration files and then the system files.
 
-### The `.odbc.ini` File
-
-The `.odbc.ini` contains the DSNs for the drivers, which can have specific knobs.
-
-An example of `.odbc.ini` with DuckDB would be:
-
-```ini
-[DuckDB]
-Driver = DuckDB Driver
-Database = :memory:
-```
-
-* `[DuckDB]`: between the brackets is a DSN for the DuckDB.
-* `Driver`: it describes the driver's name, and other configurations will be placed at the `.odbcinst.ini`.
-* `Database`: it describes the database name used by DuckDB, and it can also be a file path to a `.db` in the system.
-
-### The `.odbcinst.ini` File
-
-The `.odbcinst.ini` contains general configurations for the ODBC installed drivers in the system.
-A driver section starts with the driver name between brackets, and then it follows specific configuration knobs belonging to that driver.
-
-An example of `.odbcinst.ini` with the DuckDB driver would be:
-
-```ini
-[ODBC]
-Trace = yes
-TraceFile = /tmp/odbctrace
-
-[DuckDB Driver]
-Driver = /home/⟨user⟩/duckdb_odbc/libduckdb_odbc.so
-```
-
-* `[ODBC]`: it is the DM configuration section.
-* `Trace`: it enables the ODBC trace file using the option `yes`.
-* `TraceFile`: the absolute system file path for the ODBC trace file.
-* `[DuckDB Driver]`: the section of the DuckDB installed driver.
-* `Driver`: the absolute system file path of the DuckDB driver.
+See the [ODBC configuration page](configuration) for details.
diff --git a/docs/api/odbc/macos.md b/docs/api/odbc/macos.md
@@ -15,9 +15,11 @@ brew install unixodbc
 
 ## Step 1: Download ODBC Driver
 
-DuckDB releases the ODBC driver as asset. For macOS, download it from the <a href="https://github.com/duckdb/duckdb/releases/download/v{{ site.currentduckdbversion }}/duckdb_odbc-osx-universal.zip">ODBC macOS asset</a> that contains the following artifacts:
+DuckDB releases the ODBC driver as asset. For macOS, download it from the <a href="https://github.com/duckdb/duckdb/releases/download/v{{ site.currentduckdbversion }}/duckdb_odbc-osx-universal.zip">ODBC macOS asset</a> that contains the `libduckdb_odbc.dylib` artifact, the DuckDB ODBC driver compiled to macOS (with Intel and Apple Silicon support).
 
-`libduckdb_odbc.dylib`: the DuckDB ODBC driver compiled to macOS (with Intel and Apple Silicon support).
+```bash
+wget https://github.com/duckdb/duckdb/releases/download/v{{ site.currentduckdbversion }}/duckdb_odbc-osx-universal.zip
+```
 
 ## Step 2: Extracting ODBC Artifacts
 
@@ -30,7 +32,7 @@ unzip duckdb_odbc-osx-universal.zip -d duckdb_odbc
 
 ## Step 3: Configure the ODBC Driver
 
-There are two ways to configure the ODBC driver, either by initializing the configuration files listed below,
+There are two ways to configure the ODBC driver, either by initializing via the configuration files,
 or by connecting with [`SQLDriverConnect`](https://learn.microsoft.com/en-us/sql/odbc/reference/syntax/sqldriverconnect-function?view=sql-server-ver16).
 A combination of the two is also possible.
 
@@ -39,47 +41,7 @@ Furthermore, the ODBC driver supports all the [configuration options](../../conf
 > If a configuration is set in both the connection string passed to `SQLDriverConnect` and in the `odbc.ini` file,
 > the one passed to `SQLDriverConnect` will take precedence.
 
-### The `odbc.ini` or `.odbc.ini` File
-
-The `.odbc.ini` contains the DSNs for the drivers, which can have specific knobs.
-
-Example of `.odbc.ini` with DuckDB:
-
-```ini
-[DuckDB]
-Driver = DuckDB Driver
-Database=:memory:
-access_mode=read_only
-allow_unsigned_extensions=true
-```
-
-* `[DuckDB]`: between the brackets is a DSN for the DuckDB.
-* `Driver`: Describes the driver's name, as well as where to find the configurations in the `.odbcinst.ini`.
-* `Database`: Describes the database name used by DuckDB, can also be a file path to a `.db` in the system.
-* `access_mode`: The mode in which to connect to the database
-* `allow_unsigned_extensions`: Allow the use of unsigned extensions
-
-### The `.odbcinst.ini` File
-
-The `.odbcinst.ini` contains general configurations for the ODBC installed drivers in the system.
-A driver section starts with the driver name between brackets, and then it follows specific configuration knobs belonging to that driver.
-
-Example of `.odbcinst.ini` with the DuckDB:
-
-```ini
-[ODBC]
-Trace = yes
-TraceFile = /tmp/odbctrace
-
-[DuckDB Driver]
-Driver = /User/⟨user⟩/duckdb_odbc/libduckdb_odbc.dylib
-```
-
-* `[ODBC]`: it is the DM configuration section.
-* `Trace`: it enables the ODBC trace file using the option `yes`.
-* `TraceFile`: the absolute system file path for the ODBC trace file.
-* `[DuckDB Driver]`: the section of the DuckDB installed driver.
-* `Driver`: the absolute system file path of the DuckDB driver.
+See the [ODBC configuration page](configuration) for details.
 
 ## Step 4 (Optional): Test the ODBC Driver
 

diff --git a/docs/api/odbc/windows.md b/docs/api/odbc/windows.md
@@ -9,7 +9,7 @@ For detailed information check out the [Common ODBC Component Files](https://doc
 
 ## Step 1: Download ODBC Driver
 
-DuckDB releases the ODBC driver as asset. For Windows, download it from <a href="https://github.com/duckdb/duckdb/releases/download/v{{ site.currentduckdbversion }}/duckdb_odbc-windows-amd64.zip">Windows Asset</a> that contains the following artifacts:
+DuckDB releases the ODBC driver as asset. For Windows, download it from <a href="https://github.com/duckdb/duckdb/releases/download/v{{ site.currentduckdbversion }}/duckdb_odbc-windows-amd64.zip">Windows Asset (AMD64/x86)</a> that contains the following artifacts:
 
 * `duckdb_odbc.dll`: the DuckDB driver compiled for Windows.
 * `duckdb_odbc_setup.dll`: a setup DLL used by the Windows ODBC Data Source Administrator tool.
@@ -75,6 +75,8 @@ included in DuckDB.
 > If a configuration is set in both the connection string passed to `SQLDriverConnect` and in the `odbc.ini` file,
 > the one passed to `SQLDriverConnect` will take precedence.
 
+See the [ODBC configuration page](configuration) for details.
+
 ### Registry Keys
 
 The ODBC setup on Windows is based on registry keys (see [Registry Entries for ODBC Components