{"id":13508916,"url":"https://github.com/elixir-ecto/tds","last_synced_at":"2025-05-15T05:07:22.642Z","repository":{"id":26743100,"uuid":"30200797","full_name":"elixir-ecto/tds","owner":"elixir-ecto","description":"TDS Driver for Elixir","archived":false,"fork":false,"pushed_at":"2025-03-10T14:50:33.000Z","size":1268,"stargazers_count":118,"open_issues_count":16,"forks_count":78,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-15T03:55:34.875Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/tds/","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elixir-ecto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-02T18:13:05.000Z","updated_at":"2025-04-30T03:57:51.000Z","dependencies_parsed_at":"2024-01-26T05:06:59.820Z","dependency_job_id":"ac1200a0-deb4-49ca-839f-51832a18555e","html_url":"https://github.com/elixir-ecto/tds","commit_stats":{"total_commits":409,"total_committers":42,"mean_commits":9.738095238095237,"dds":0.6405867970660146,"last_synced_commit":"b2ab0c7ff1e76d577cf0c0fc9849f57d5d44ff5d"},"previous_names":["livehelpnow/tds"],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Ftds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Ftds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Ftds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-ecto%2Ftds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elixir-ecto","download_url":"https://codeload.github.com/elixir-ecto/tds/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254276447,"owners_count":22043867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T02:01:00.423Z","updated_at":"2025-05-15T05:07:17.632Z","avatar_url":"https://github.com/elixir-ecto.png","language":"Elixir","funding_links":[],"categories":["ORM and Datamapping"],"sub_categories":[],"readme":"# Tds - MSSQL Driver for Elixir\n\n[![Hex.pm](https://img.shields.io/hexpm/v/tds.svg)](https://hex.pm/packages/tds)\n![Elixir TDS CI](https://github.com/elixir-ecto/tds/workflows/Elixir%20TDS%20CI/badge.svg)\n\nMSSQL / TDS Database driver for Elixir.\n\n### NOTE:\nSince TDS version 2.0, `tds_ecto` package is deprecated, this version supports `ecto_sql` since version 3.3.4.\n\nPlease check out the issues for a more complete overview. This branch should not be considered stable or ready for production yet.\n\nFor stable versions always use [hex.pm](https://hex.pm/packages/tds) as source for your mix.exs.\n\n## Usage\n\nAdd `:tds` as a dependency in your `mix.exs` file.\n\n```elixir\ndef deps do\n  [\n    {:tds, \"~\u003e 2.3\"}\n  ]\nend\n```\n\nAs of TDS version `\u003e= 1.2`, tds can support windows codepages other than `windows-1252` (latin1).\nIf you need such support you will need to include additional dependency `{:excoding, \"~\u003e 0.1\"}`\nand configure `:tds` app to use `Excoding` module like this:\n\n\n```elixir\nimport Mix.Config\n\nconfig :tds, :text_encoder, Excoding\n```\n\nWhen you are done, run `mix deps.get` in your shell to fetch and compile Tds.\nStart an interactive Elixir shell with `iex -S mix`.\n\n```elixir\niex\u003e {:ok, pid} = Tds.start_link([hostname: \"localhost\", username: \"test_user\", password: \"test_password\", database: \"test_db\", port: 4000])\n{:ok, #PID\u003c0.69.0\u003e}\n\niex\u003e Tds.query!(pid, \"SELECT 'Some Awesome Text' AS MyColumn\", [])\n%Tds.Result{columns: [\"MyColumn\"], rows: [{\"Some Awesome Text\"}], num_rows: 1}}\n\niex\u003e Tds.query!(pid, \"INSERT INTO MyTable (MyColumn) VALUES (@my_value)\",\n...\u003e [%Tds.Parameter{name: \"@my_value\", value: \"My Actual Value\"}])\n%Tds.Result{columns: nil, rows: nil, num_rows: 1}}\n```\n\n## Features\n\n* Automatic decoding and encoding of Elixir values to and from MSSQL's binary format\n* Support of TDS Versions 7.3, 7.4\n\n## Configuration\n\nExample configuration\n\n```elixir\nimport Mix.Config\n\nconfig :your_app, :tds_conn,\n  hostname: \"localhost\",\n  username: \"test_user\",\n  password: \"test_password\",\n  database: \"test_db\",\n  port: 1433\n```\n\nThen using `Application.get_env(:your_app, :tds_conn)` use this as first parameter in `Tds.start_link/1` function.\n\nThere is additional parameter that can be used in configuration and\ncan improve query execution in SQL Server. If you find out that\nyour queries suffer from \"density estimation\" as described [here](https://www.brentozar.com/archive/2018/03/sp_prepare-isnt-good-sp_executesql-performance/)\n\nYou can try switching how tds executes queries as below:\n\n```elixir\nimport Mix.Config\n\nconfig :your_app, :tds_conn,\n  hostname: \"localhost\",\n  username: \"test_user\",\n  password: \"test_password\",\n  database: \"test_db\",\n  port: 1433,\n  execution_mode: :executesql\n```\nThis will skip calling `sp_prepare` and query will be executed using `sp_executesql` instead.\nPlease note that only one execution mode can be set at a time, and SQL Server will probably\nuse single execution plan (since it is NOT estimated by checking data density!).\n\n## SSL / TLS support\n\ntds `\u003e= 2.3.0` supports encrypted connections to the SQL Server.\n\nThe following encryption behaviours are currently supported:\n\n- `:required`: Requires the server to use TLS\n- `:on`: Same as required\n- `:not_supported`: Indicates to the server that encryption is not supported. If server requires encryption, the connection will not be established.\n- `:ssl_opts`: Allow pass options for ssl connection (this options are the same as ssl erlang standart library).\n\nCurrently not supported:\n\n- `:off`: This setting allows the server to upgrade the connection (if server encryption is `:on` or `:required`) and only encrypts the LOGIN packet when the server has encryption set to `:off`.\n- `:client_cert`: This will make the server check the client cerfiticate.\n\nSetting `ssl: true` or `ssl: false` is also allowed. In that case `true` is mapped to `:required` and `false` to `:not_supported`.\n\n```elixir\nconfig :your_app, :tds_conn,\n  hostname: \"localhost\",\n  username: \"test_user\",\n  password: \"test_password\",\n  database: \"test_db\",\n  ssl: :required,\n  port: 1433,\n  execution_mode: :executesql\n\n```\n\n## Connecting to SQL Server Instances\n\nTds supports SQL Server instances by passing `instance: \"instancename\"` to the connection options.\nSince v1.0.16, additional connection parameters are:\n  - `:set_language` - check stored procedure output `exec sp_helplanguage` name column value should be used here\n  - `:set_datefirst` - number in range `1..7`\n  - `:set_dateformat` - atom, one of `:mdy | :dmy | :ymd | :ydm | :myd | :dym`\n  - `:set_deadlock_priority` - atom, one of `:low | :high | :normal | -10..10`\n  - `:set_lock_timeout` - number in milliseconds \u003e 0\n  - `:set_remote_proc_transactions` - atom, one of `:on | :off`\n  - `:set_implicit_transactions` - atom, one of `:on | :off`\n  - `:set_transaction_isolation_level` - atom, one of `:read_uncommitted | :read_committed | :repeatable_read | :snapshot | :serializable`\n  - `:set_allow_snapshot_isolation` - atom, one of `:on | :off`\n  - `:set_cursor_close_on_commit` - atom, one of `:on | :off`\n  - `:set_read_committed_snapshot` - atom, one of `:on | :off`\n\nSet this option to enable snapshot isolation on the database level.\nRequires connecting with a user with appropriate rights.\nMore info [here](https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server).\n\n\n## Federation Authentication\n\nThis Authentication mechanism is not supported.\nThis functionality requires specific environment to be developed.\n\n## Data representation\n\n| TDS               | Elixir                                                                                     |\n| ----------------- | ------------------------------------------------------------------------------------------ |\n| NULL              | nil                                                                                        |\n| bool              | true / false                                                                               |\n| char              | \"é\"                                                                                        |\n| int               | 42                                                                                         |\n| float             | 42.0                                                                                       |\n| text              | \"text\"                                                                                     |\n| binary            | \u003c\u003c42\u003e\u003e                                                                                     |\n| numeric           | #Decimal\u003c42.0\u003e                                                                             |\n| date              | {2013, 10, 12} or %Date{}                                                                  |\n| time              | {0, 37, 14} or {0, 37, 14, 123456} or %Time{}                                              |\n| smalldatetime     | {{2013, 10, 12}, {0, 37, 14}} or {{2013, 10, 12}, {0, 37, 14, 123456}}                     |\n| datetime          | {{2013, 10, 12}, {0, 37, 14}} or {{2013, 10, 12}, {0, 37, 14, 123456}} or %NaiveDateTime{} |\n| datetime2         | {{2013, 10, 12}, {0, 37, 14}} or {{2013, 10, 12}, {0, 37, 14, 123456}} or %NaiveDateTime{} |\n| datetimeoffset(n) | {{2013, 10, 12}, {0, 37, 14}} or {{2013, 10, 12}, {0, 37, 14, 123456}} or %DateTime{}      |\n| uuid              | \u003c\u003c160,238,188,153,156,11,78,248,187,109,107,185,189,56,10,17\u003e\u003e                             |\n\nCurrently unsupported: [User-Defined Types](https://docs.microsoft.com/en-us/sql/relational-databases/clr-integration-database-objects-user-defined-types/working-with-user-defined-types-in-sql-server), XML\n\n### Dates and Times\n\nTds can work with dates and times in either a tuple format or as Elixir calendar types. Calendar types can be enabled in the config with `config :tds, opts: [use_elixir_calendar_types: true]`.\n\n**Tuple forms:**\n\n- Date: `{yr, mth, day}`\n- Time: `{hr, min, sec}` or `{hr, min, sec, fractional_seconds}`\n- DateTime: `{date, time}`\n- DateTimeOffset: `{utc_date, utc_time, offset_mins}`\n\nIn SQL Server, the `fractional_seconds` of a `time`, `datetime2` or `datetimeoffset(n)` column can have a precision of 0-7, where the `microsecond` field of a `%Time{}` or `%DateTime{}` struct can have a precision of 0-6.\n\nNote that the DateTimeOffset tuple expects the date and time in UTC and the offset in minutes. For example, `{{2020, 4, 5}, {5, 30, 59}, 600}` is equal to `'2020-04-05 15:30:59+10:00'`.\n\n### UUIDs\n\n[MSSQL stores UUIDs in mixed-endian\nformat](https://dba.stackexchange.com/a/121878), and these mixed-endian UUIDs\nare returned in [Tds.Result](https://hexdocs.pm/tds/Tds.Result.html).\n\nTo convert a mixed-endian UUID binary to a big-endian string, use\n[Tds.Types.UUID.load/1](https://hexdocs.pm/tds/Tds.Types.UUID.html#load/1)\n\nTo convert a big-endian UUID string to a mixed-endian binary, use\n[Tds.Types.UUID.dump/1](https://hexdocs.pm/tds/Tds.Types.UUID.html#dump/1)\n\n## Contributing\n\nClone and compile Tds with:\n\n```bash\ngit clone https://github.com/elixir-ecto/tds.git\ncd tds\nmix deps.get\n```\n\nYou can test the library with `mix test`. Use `mix credo` for linting and\n`mix dialyzer` for static code analysis. Dialyzer will take a while when you\nuse it for the first time.\n\n### Development SQL Server Setup\n\nThe tests require an SQL Server database to be available on localhost.\nIf you are not using Windows OS you can start sql server instance using Docker.\nOfficial SQL Server Docker image can be found [here](https://hub.docker.com/r/microsoft/mssql-server-linux).\n\nIf you do not have specific requirements on how you would like to start sql server\nin docker, you can use script for this repo.\n\n```bash\n$ ./docker-mssql.sh\n```\n\nIf you prefer to install SQL Server directly on your computer, you can find\ninstallation instructions here:\n\n* [Windows](https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-installation-wizard-setup)\n* [Linux](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup)\n\nMake sure your SQL Server accepts the credentials defined in `test/test_helper.exs`.\n\nYou also will need to have the *sqlcmd* command line tools installed. Setup\ninstructions can be found here:\n\n* [Linux](https://docs.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools)\n* [macOS](https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/install-microsoft-odbc-driver-sql-server-macos)\n\n## Special Thanks\n\nThanks to [ericmj](https://github.com/ericmj), this driver takes a lot of inspiration from postgrex.\n\nAlso thanks to everyone in the Elixir Google group and on the Elixir IRC Channel.\n\n## Copyright and License\n\nCopyright (c) 2015 LiveHelpNow\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-ecto%2Ftds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felixir-ecto%2Ftds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-ecto%2Ftds/lists"}