|
| 1 | +# Working with Microsoft SQL Server databases |
| 2 | + |
| 3 | +This section provides basic information about working with an external [Microsoft SQL Server](https://learn.microsoft.com/en-us/sql/?view=sql-server-ver16) databases. |
| 4 | + |
| 5 | +To work with an external Microsoft SQL Server database, you need to follow these steps: |
| 6 | +1. Create a [secret](../datamodel/secrets.md) containing the password for connecting to the database. |
| 7 | + ```sql |
| 8 | + CREATE OBJECT ms_sql_server_datasource_user_password (TYPE SECRET) WITH (value = "<password>"); |
| 9 | + ``` |
| 10 | +1. Create an [external data source](../datamodel/external_data_source.md) that describes a specific Microsoft SQL Server database. The `LOCATION` parameter contains the network address of the Microsoft SQL Server instance to connect to. The `DATABASE_NAME` specifies the database name (for example, `master`). The `LOGIN` and `PASSWORD_SECRET_NAME` parameters are used for authentication to the external database. You can enable encryption for connections to the external database using the `USE_TLS="TRUE"` parameter. |
| 11 | + ```sql |
| 12 | + CREATE EXTERNAL DATA SOURCE ms_sql_server_datasource WITH ( |
| 13 | + SOURCE_TYPE="Microsoft SQL Server", |
| 14 | + LOCATION="<host>:<port>", |
| 15 | + DATABASE_NAME="<database>", |
| 16 | + AUTH_METHOD="BASIC", |
| 17 | + LOGIN="user", |
| 18 | + PASSWORD_SECRET_NAME="ms_sql_server_datasource_user_password", |
| 19 | + USE_TLS="TRUE" |
| 20 | + ); |
| 21 | + ``` |
| 22 | +1. {% include [!](_includes/connector_deployment.md) %} |
| 23 | +1. [Execute a query](#query) to the database. |
| 24 | + |
| 25 | +## Query syntax { #query } |
| 26 | +The following SQL query format is used to work with Microsoft SQL Server: |
| 27 | + |
| 28 | +```sql |
| 29 | +SELECT * FROM ms_sql_server_datasource.<table_name> |
| 30 | +``` |
| 31 | + |
| 32 | +where: |
| 33 | +- `ms_sql_server_datasource` - the external data source identifier; |
| 34 | +- `<table_name>` - the table name within the external data source. |
| 35 | + |
| 36 | +## Limitations |
| 37 | + |
| 38 | +When working with Microsoft SQL Server clusters, there are a number of limitations: |
| 39 | + |
| 40 | +1. {% include [!](_includes/supported_requests.md) %} |
| 41 | +2. {% include [!](_includes/datetime_limits.md) %} |
| 42 | +3. {% include [!](_includes/predicate_pushdown.md) %} |
| 43 | + |
| 44 | +## Supported data types |
| 45 | + |
| 46 | +In the Microsoft SQL Server database, the optionality of column values (whether the column can contain `NULL` values or not) is not a part of the data type system. The `NOT NULL` constraint for any column of any table is stored within the `IS_NULLABLE` column the [INFORMATION_SCHEMA.COLUMNS](https://learn.microsoft.com/en-us/sql/relational-databases/system-information-schema-views/columns-transact-sql?view=sql-server-ver16) system table, i.e., at the table metadata level. Therefore, all basic Microsoft SQL Server types can contain `NULL` values by default, and in the {{ ydb-full-name }} type system, they should be mapped to [optional](../../yql/reference/types/optional.md). |
| 47 | + |
| 48 | +Below is a correspondence table between Microsoft SQL Server types and {{ ydb-short-name }} types. All other data types, except those listed, are not supported. |
| 49 | + |
| 50 | +| Microsoft SQL Server Data Type | {{ ydb-full-name }} Data Type | Notes | |
| 51 | +|---|----|------| |
| 52 | +|`bit`|`Optional<Bool>`|| |
| 53 | +|`tinyint`|`Optional<Int8>`|| |
| 54 | +|`smallint`|`Optional<Int16>`|| |
| 55 | +|`int`|`Optional<Int32>`|| |
| 56 | +|`bigint`|`Optional<Int64>`|| |
| 57 | +|`real`|`Optional<Float>`|| |
| 58 | +|`float`|`Optional<Double>`|| |
| 59 | +|`date`|`Optional<Date>`|Valid date range from 1970-01-01 to 2105-12-31. Values outside this range return `NULL`.| |
| 60 | +|`smalldatetime`|`Optional<Datetime>`|Valid time range from 1970-01-01 00:00:00 to 2105-12-31 23:59:59. Values outside this range return `NULL`.| |
| 61 | +|`datetime`|`Optional<Timestamp>`|Valid time range from 1970-01-01 00:00:00 to 2105-12-31 23:59:59. Values outside this range return `NULL`.| |
| 62 | +|`datetime2`|`Optional<Timestamp>`|Valid time range from 1970-01-01 00:00:00 to 2105-12-31 23:59:59. Values outside this range return `NULL`.| |
| 63 | +|`binary`|`Optional<String>`|| |
| 64 | +|`varbinary`|`Optional<String>`|| |
| 65 | +|`image`|`Optional<String>`|| |
| 66 | +|`char`|`Optional<Utf8>`|| |
| 67 | +|`varchar`|`Optional<Utf8>`|| |
| 68 | +|`text`|`Optional<Utf8>`|| |
| 69 | +|`nchar`|`Optional<Utf8>`|| |
| 70 | +|`nvarchar`|`Optional<Utf8>`|| |
| 71 | +|`ntext`|`Optional<Utf8>`|| |
0 commit comments