You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+13-3Lines changed: 13 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,10 +32,20 @@ The functional tests require a running SQL Server instance. You can easily spin
32
32
make server
33
33
```
34
34
35
-
The default development flow uses the existing ODBC-based path. If you want to develop or test the optional `mssql-python`backend instead, make sure the package is installed in your environment before running tests.
35
+
The default development flow uses the ODBC-based path, but the ODBC driver itself is now an optional dependency. If you want to develop or test that backend, install either the adapter extra or the driver itself before running tests.
36
36
37
37
```shell
38
-
pip install mssql-python
38
+
pip install -U "dbt-sqlserver[pyodbc]"
39
+
# or
40
+
pip install -U pyodbc
41
+
```
42
+
43
+
If you want to develop or test the optional `mssql-python` backend instead, install either the adapter extra or the driver itself before running tests.
44
+
45
+
```shell
46
+
pip install -U "dbt-sqlserver[mssql]"
47
+
# or
48
+
pip install -U mssql-python
39
49
```
40
50
41
51
On Debian/Ubuntu-based environments, `mssql-python` may also require these system libraries:
@@ -77,7 +87,7 @@ make unit
77
87
make functional
78
88
```
79
89
80
-
This remains the documented test procedure for both connection backends. When the `mssql-python` flag is enabled, run the same commands after installing `mssql-python` and setting `SQLSERVER_TEST_USE_MSSQL_PYTHON=True` in `test.env`.
90
+
This remains the documented test procedure for both connection backends. When the `pyodbc` path is enabled, run the same commands after installing `dbt-sqlserver[pyodbc]` or `pyodbc`. When the `mssql-python` flag is enabled, run the same commands after installing`dbt-sqlserver[mssql]` or`mssql-python` and setting `SQLSERVER_TEST_USE_MSSQL_PYTHON=True` in `test.env`.
When this backend is enabled, the adapter does not require the ODBC driver-based connection path for that profile.
61
-
62
-
## Changelog
63
-
64
-
See [the changelog](CHANGELOG.md)
65
-
66
-
## Configuration
67
-
68
-
### Flags
69
-
70
-
-`dbt_sqlserver_use_default_schema_concat`: *(default: `false`)* Controls schema name generation when a [custom schema](https://docs.getdbt.com/docs/build/custom-schemas) is set on a model.
71
-
72
-
-`use_mssql_python`: *(default: `false` in the profile)* Switches the connection backend from the legacy ODBC / `pyodbc` path to the `mssql-python` driver for that target profile.
When `false` (the default), the adapter uses its legacy behaviour: `custom_schema_name` is used **as-is** without being prefixed by `target.schema`.
82
-
When `true`, the adapter delegates to dbt-core's `default__generate_schema_name`, which concatenates `target.schema` + `_` + `custom_schema_name`.
83
-
84
-
**Example usage in `dbt_project.yml`:**
85
-
86
-
```yaml
87
-
vars:
88
-
dbt_sqlserver_use_default_schema_concat: true # Enable standard schema concatenation
89
-
```
90
-
91
-
> **Note:** If you want to permanently customise schema generation and avoid any future deprecation of this flag, override the `sqlserver__generate_schema_name` macro directly in your project.
92
-
93
-
### `mssql-python` feature flag usage
94
-
95
-
Enable the backend per target in your `profiles.yml`:
61
+
Enable it per target in your `profiles.yml`:
96
62
97
63
```yaml
98
64
your_profile:
@@ -108,39 +74,40 @@ your_profile:
108
74
password: your-password
109
75
encrypt: true
110
76
trust_cert: false
111
-
use_mssql_python: true
77
+
use_mssql_python: true# <-- enables this backend
112
78
```
113
79
114
-
#### Notes
80
+
## Changelog
115
81
116
-
- `use_mssql_python: true` is a profile-level feature flag.
117
-
- When enabled, the adapter uses `mssql-python` instead of the legacy `pyodbc` connection path.
118
-
- The legacy ODBC driver setting is only needed for profiles that continue to use the ODBC backend.
119
-
- If you enable `use_mssql_python`, make sure the `mssql-python` package is installed in the environment running dbt.
120
-
- On Debian/Ubuntu-based environments, `mssql-python` also requires `libltdl7`, `libkrb5-3`, and `libgssapi-krb5-2`.
121
-
- This path is intended to fail fast when required dependencies or unsupported settings are missing.
82
+
See [the changelog](CHANGELOG.md)
122
83
123
-
#### Testing
84
+
## Configuration
124
85
125
-
For local development and validation, use the documented adapter workflow from `CONTRIBUTING.md`:
86
+
### `use_mssql_python`
126
87
127
-
```shell
128
-
make dev
129
-
make server
130
-
cp test.env.sample test.env
131
-
make unit
132
-
make functional
133
-
```
88
+
*(default: `false`)* Set to `true` in a profile target to use the `mssql-python` backend instead of `pyodbc`. The adapter fails if the required driver is not installed.
134
89
135
-
To exercise the `mssql-python` backend in tests, configure the profile or environment so that the target under test sets:
90
+
### `dbt_sqlserver_use_default_schema_concat`
136
91
137
-
```yaml
138
-
use_mssql_python: true
139
-
```
92
+
*(default: `false`)* Controls schema name generation when a [custom schema](https://docs.getdbt.com/docs/build/custom-schemas) is set on a model.
If you are testing in the devcontainer, the backend prerequisites are installed automatically. Outside the devcontainer, install `mssql-python` and the system libraries above before running the unit or functional suite.
101
+
When `false`, `custom_schema_name` is used as-is without being prefixed by `target.schema`.
102
+
When `true`, the adapter delegates to dbt-core's `default__generate_schema_name`.
142
103
104
+
```yaml
105
+
# dbt_project.yml
106
+
vars:
107
+
dbt_sqlserver_use_default_schema_concat: true
108
+
```
143
109
110
+
> **Note:** To permanently customise schema generation without a flag dependency, override the `sqlserver__generate_schema_name` macro directly in your project.
144
111
145
112
## Contributing
146
113
@@ -149,7 +116,7 @@ If you are testing in the devcontainer, the backend prerequisites are installed
149
116
[](https://github.com/dbt-msft/dbt-sqlserver/actions/workflows/integration-tests-azure.yml)
150
117
151
118
This adapter is community-maintained.
152
-
You are welcome to contribute by creating issues, opening or reviewing pull requests or helping other users in Slack channel.
119
+
You are welcome to contribute by creating issues, opening or reviewing pull requests, or helping other users in the Slack channel.
153
120
If you're unsure how to get started, check out our [contributing guide](CONTRIBUTING.md).
0 commit comments