{"id":13415080,"url":"https://github.com/datastax/csharp-driver","last_synced_at":"2025-05-13T19:08:43.316Z","repository":{"id":6893817,"uuid":"8143458","full_name":"datastax/csharp-driver","owner":"datastax","description":"DataStax C# Driver for Apache Cassandra","archived":false,"fork":false,"pushed_at":"2024-11-22T16:04:04.000Z","size":27100,"stargazers_count":649,"open_issues_count":5,"forks_count":240,"subscribers_count":87,"default_branch":"master","last_synced_at":"2025-04-27T04:58:33.109Z","etag":null,"topics":["cassandra","client","csharp","database","datastax-driver","dotnet","dotnet-core","driver","nosql"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":false,"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/datastax.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2013-02-11T18:15:01.000Z","updated_at":"2025-04-24T11:35:33.000Z","dependencies_parsed_at":"2024-03-13T19:26:10.810Z","dependency_job_id":"78369374-79b7-450f-81e9-a6887004fa32","html_url":"https://github.com/datastax/csharp-driver","commit_stats":{"total_commits":1920,"total_committers":84,"mean_commits":"22.857142857142858","dds":0.6484375,"last_synced_commit":"aa4f36e5c2e01042de82bab42a004bbd9a1c594b"},"previous_names":[],"tags_count":120,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcsharp-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcsharp-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcsharp-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastax%2Fcsharp-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastax","download_url":"https://codeload.github.com/datastax/csharp-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251089620,"owners_count":21534523,"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":["cassandra","client","csharp","database","datastax-driver","dotnet","dotnet-core","driver","nosql"],"created_at":"2024-07-30T21:00:42.931Z","updated_at":"2025-04-27T04:58:40.991Z","avatar_url":"https://github.com/datastax.png","language":"C#","readme":"# DataStax C# Driver for Apache Cassandra\r\n\r\nA modern, [feature-rich][features] and highly tunable C# client library for Apache Cassandra (2.0+) using Cassandra's binary protocol and Cassandra Query Language v3.\r\n\r\nIt also provides additional features for [DataStax Enterprise][dse]:\r\n\r\n- `IAuthenticator` implementations that use the authentication scheme negotiation in the server-side `DseAuthenticator`.\r\n- [DSE graph][dse-graph] integration.\r\n- Serializers for geospatial types which integrate seamlessly with the driver.\r\n\r\nThe driver targets .NET Framework 4.5.2 and .NET Standard 2.0. For more detailed information about platform compatibility, check [this section](#compatibility).\r\n\r\n## Installation\r\n\r\n[Get it on Nuget][nuget]\r\n\r\n```bash\r\nPM\u003e Install-Package CassandraCSharpDriver\r\n```\r\n\r\n[![Build status](https://travis-ci.org/datastax/csharp-driver.svg?branch=master)](https://travis-ci.org/datastax/csharp-driver)\r\n[![Windows Build status](https://ci.appveyor.com/api/projects/status/ri1olv8bl7b7yk7y/branch/master?svg=true)](https://ci.appveyor.com/project/DataStax/csharp-driver/branch/master)\r\n[![Latest stable](https://img.shields.io/nuget/v/CassandraCSharpDriver.svg)](https://www.nuget.org/packages/CassandraCSharpDriver)\r\n\r\n## Features\r\n\r\n- Sync and [Async](#asynchronous-api) API\r\n- Simple, [Prepared](#prepared-statements), and [Batch](#batching-statements) statements\r\n- Asynchronous IO, parallel execution, request pipelining\r\n- Connection pooling\r\n- Auto node discovery\r\n- Automatic reconnection\r\n- Configurable [load balancing][policies] and [retry policies][policies]\r\n- Works with any cluster size\r\n- [Linq2Cql][linq] and Ado.Net support\r\n\r\n## Documentation\r\n\r\n- [Documentation index][docindex]\r\n- [API docs][apidocs]\r\n- [FAQ][faq]\r\n- [Version compatibility matrix][driver-matrix]\r\n- [Developing applications with DataStax drivers][dev-guide]\r\n\r\n## Getting Help\r\n\r\nYou can use the project [Mailing list][mailinglist] or create a ticket on the [Jira issue tracker][jira]. Additionally, you can ask questions on [DataStax Community][community].\r\n\r\n## Upgrading from previous versions or from the DSE C# driver\r\n\r\nIf you are upgrading from previous versions of the driver, [visit the Upgrade Guide][upgrade-guide].\r\n\r\nIf you are upgrading from the [DSE C# driver][dse-driver] (which has been unified with this driver), there's also a section related to this on the [Upgrade Guide][upgrade-guide-dse].\r\n\r\n## Basic Usage\r\n\r\n```csharp\r\n// Configure the builder with your cluster's contact points\r\nvar cluster = Cluster.Builder()\r\n                     .AddContactPoints(\"host1\")\r\n                     .Build();\r\n\r\n// Connect to the nodes using a keyspace\r\nvar session = cluster.Connect(\"sample_keyspace\");\r\n\r\n// Execute a query on a connection synchronously\r\nvar rs = session.Execute(\"SELECT * FROM sample_table\");\r\n\r\n// Iterate through the RowSet\r\nforeach (var row in rs)\r\n{\r\n    var value = row.GetValue\u003cint\u003e(\"sample_int_column\");\r\n\r\n    // Do something with the value\r\n}\r\n```\r\n\r\n**If you are using [DataStax Astra][astra]** you can configure your cluster instance by setting the secure bundle and the user credentials:\r\n\r\n```csharp\r\n// Configure the builder with your cluster's cloud secure connection bundle and credentials\r\nvar cluster = Cluster.Builder()\r\n                     .WithCloudSecureConnectionBundle(\"path/to/secure-connect-DATABASE_NAME.zip\")\r\n                     .WithCredentials(\"user_name\", \"p@ssword1\")\r\n                     .Build();\r\n```\r\n\r\n### Prepared statements\r\n\r\nPrepare your query **once** and bind different parameters to obtain best performance.\r\n\r\n```csharp\r\n// Prepare a statement once\r\nvar ps = session.Prepare(\"UPDATE user_profiles SET birth=? WHERE key=?\");\r\n\r\n// ...bind different parameters every time you need to execute\r\nvar statement = ps.Bind(new DateTime(1942, 11, 27), \"hendrix\");\r\n// Execute the bound statement with the provided parameters\r\nsession.Execute(statement);\r\n```\r\n\r\n### Batching statements\r\n\r\nYou can execute multiple statements (prepared or unprepared) in a batch to update/insert several rows atomically even in different column families.\r\n\r\n```csharp\r\n// Prepare the statements involved in a profile update once\r\nvar profileStmt = session.Prepare(\"UPDATE user_profiles SET email=? WHERE key=?\");\r\nvar userTrackStmt = session.Prepare(\"INSERT INTO user_track (key, text, date) VALUES (?, ?, ?)\");\r\n// ...you should reuse the prepared statement\r\n// Bind the parameters and add the statement to the batch batch\r\nvar batch = new BatchStatement()\r\n  .Add(profileStmt.Bind(emailAddress, \"hendrix\"))\r\n  .Add(userTrackStmt.Bind(\"hendrix\", \"You changed your email\", DateTime.Now));\r\n// Execute the batch\r\nsession.Execute(batch);\r\n```\r\n\r\n### Asynchronous API\r\n\r\nSession allows asynchronous execution of statements (for any type of statement: simple, bound or batch) by exposing the `ExecuteAsync` method.\r\n\r\n```csharp\r\n// Execute a statement asynchronously using await\r\nvar rs = await session.ExecuteAsync(statement);\r\n```\r\n\r\n### Avoid boilerplate mapping code\r\n\r\nThe driver features a built-in [Mapper][mapper] and [Linq][linq] components that can use to avoid boilerplate mapping code between cql rows and your application entities.\r\n\r\n```csharp\r\nUser user = mapper.Single\u003cUser\u003e(\"SELECT name, email FROM users WHERE id = ?\", userId);\r\n```\r\n\r\nSee the [driver components documentation][components] for more information.\r\n\r\n### Automatic pagination of results\r\n\r\nYou can iterate indefinitely over the `RowSet`, having the rows fetched block by block until the rows available on the client side are exhausted.\r\n\r\n```csharp\r\nvar statement = new SimpleStatement(\"SELECT * from large_table\");\r\n// Set the page size, in this case the RowSet will not contain more than 1000 at any time\r\nstatement.SetPageSize(1000);\r\nvar rs = session.Execute(statement);\r\nforeach (var row in rs)\r\n{\r\n  // The enumerator will yield all the rows from Cassandra\r\n  // Retrieving them in the back in blocks of 1000.\r\n}\r\n```\r\n\r\n### User defined types mapping\r\n\r\nYou can map your [Cassandra User Defined Types][udt] to your application entities.\r\n\r\nFor a given udt\r\n\r\n```cql\r\nCREATE TYPE address (\r\n  street text,\r\n  city text,\r\n  zip_code int,\r\n  phones set\u003ctext\u003e\r\n);\r\n```\r\n\r\nFor a given class\r\n\r\n```csharp\r\npublic class Address\r\n{\r\n  public string Street { get; set; }\r\n  public string City { get; set; }\r\n  public int ZipCode { get; set; }\r\n  public IEnumerable\u003cstring\u003e Phones { get; set;}\r\n}\r\n```\r\n\r\nYou can either map the properties by name\r\n\r\n```csharp\r\n// Map the properties by name automatically\r\nsession.UserDefinedTypes.Define(\r\n  UdtMap.For\u003cAddress\u003e()\r\n);\r\n```\r\n\r\nOr you can define the properties manually\r\n\r\n```csharp\r\nsession.UserDefinedTypes.Define(\r\n  UdtMap.For\u003cAddress\u003e()\r\n    .Map(a =\u003e a.Street, \"street\")\r\n    .Map(a =\u003e a.City, \"city\")\r\n    .Map(a =\u003e a.ZipCode, \"zip_code\")\r\n    .Map(a =\u003e a.Phones, \"phones\")\r\n);\r\n```\r\n\r\nYou should **map your [UDT][udt] to your entity once** and you will be able to use that mapping during all your application lifetime.\r\n\r\n```csharp\r\nvar rs = session.Execute(\"SELECT id, name, address FROM users where id = x\");\r\nvar row = rs.First();\r\n// You can retrieve the field as a value of type Address\r\nvar userAddress = row.GetValue\u003cAddress\u003e(\"address\");\r\nConsole.WriteLine(\"user lives on {0} Street\", userAddress.Street);\r\n```\r\n\r\n### Setting cluster and statement execution options\r\n\r\nYou can set the options on how the driver connects to the nodes and the execution options.\r\n\r\n```csharp\r\n// Example at cluster level\r\nvar cluster = Cluster\r\n  .Builder()\r\n  .AddContactPoints(hosts)\r\n  .WithCompression(CompressionType.LZ4)\r\n  .WithLoadBalancingPolicy(new DCAwareRoundRobinPolicy(\"west\"));\r\n\r\n// Example at statement (simple, bound, batch) level\r\nvar statement = new SimpleStatement(query)\r\n  .SetConsistencyLevel(ConsistencyLevel.Quorum)\r\n  .SetRetryPolicy(DowngradingConsistencyRetryPolicy.Instance)\r\n  .SetPageSize(1000);\r\n```\r\n\r\n## Authentication\r\n\r\nIf you are using the `PasswordAuthenticator` which is included in the default distribution of Apache Cassandra, you can use the `Builder.WithCredentials` method or you can explicitly create a `PlainTextAuthProvider` instance.\r\n\r\nFor clients connecting to a DSE cluster secured with `DseAuthenticator`, two authentication providers are included (on the `Cassandra.DataStax.Auth` namespace):\r\n\r\n- `DsePlainTextAuthProvider`: plain-text authentication;\r\n- `DseGssapiAuthProvider`: GSSAPI authentication.\r\n\r\nTo configure a provider, pass it when initializing the cluster:\r\n\r\n```csharp\r\nusing Cassandra;\r\nusing Cassandra.DataStax.Auth;\r\n```\r\n\r\n```csharp\r\nICluster cluster = Cluster.Builder()\r\n    .AddContactPoint(\"127.0.0.1\")\r\n    .WithAuthProvider(new DseGssapiAuthProvider())\r\n    .Build();\r\n```\r\n\r\n## DataStax Graph\r\n\r\n`ISession` has dedicated methods to execute graph queries:\r\n\r\n```csharp\r\nusing Cassandra.DataStax.Graph;\r\n```\r\n\r\n```csharp\r\nsession.ExecuteGraph(\"system.createGraph('demo').ifNotExist().build()\");\r\n\r\nGraphStatement s1 = new SimpleGraphStatement(\"g.addV(label, 'test_vertex')\").SetGraphName(\"demo\");\r\nsession.ExecuteGraph(s1);\r\n\r\nGraphStatement s2 = new SimpleGraphStatement(\"g.V()\").SetGraphName(\"demo\");\r\nGraphResultSet rs = session.ExecuteGraph(s2);\r\n\r\nIVertex vertex = rs.First().To\u003cIVertex\u003e();\r\nConsole.WriteLine(vertex.Label);\r\n```\r\n\r\n### Graph options\r\n\r\nYou can set default graph options when initializing the cluster. They will be used for all graph statements. For example, to avoid repeating `SetGraphName(\"demo\")` on each statement:\r\n\r\n```csharp\r\nICluster cluster = Cluster.Builder()\r\n    .AddContactPoint(\"127.0.0.1\")\r\n    .WithGraphOptions(new GraphOptions().SetName(\"demo\"))\r\n    .Build();\r\n```\r\n\r\nIf an option is set manually on a `GraphStatement`, it always takes precedence; otherwise the default option is used.\r\nThis might be a problem if a default graph name is set, but you explicitly want to execute a statement targeting `system`, for which no graph name must be set. In that situation, use `GraphStatement.SetSystemQuery()`:\r\n\r\n```csharp\r\nGraphStatement s = new SimpleGraphStatement(\"system.createGraph('demo').ifNotExist().build()\")\r\n    .SetSystemQuery();\r\nsession.ExecuteGraph(s);\r\n```\r\n\r\n### Query execution\r\n\r\nAs explained, graph statements can be executed with the session's `ExecuteGraph` method. There is also an asynchronous equivalent called `ExecuteGraphAsync` that returns a `Task` that can be awaited upon.\r\n\r\n### Handling results\r\n\r\nGraph queries return a `GraphResultSet`, which is a sequence of `GraphNode` elements:\r\n\r\n```csharp\r\nGraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement(\"g.V()\"));\r\n\r\n// Iterating as IGraphNode\r\nforeach (IGraphNode r in rs)\r\n{\r\n    Console.WriteLine(r);\r\n}\r\n```\r\n\r\n`IGraphNode` represents a response item returned by the server. Each item can be converted to the expected type:\r\n\r\n```csharp\r\nGraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement(\"g.V()\"));\r\nIVertex vertex = rs.First().To\u003cIVertex\u003e();\r\nConsole.WriteLine(vertex.Label);\r\n```\r\n\r\nAdditionally, you can apply the conversion to all the sequence by using `GraphResultSet.To\u003cT\u003e()` method:\r\n\r\n```csharp\r\nforeach (IVertex vertex in rs.To\u003cIVertex\u003e())\r\n{\r\n    Console.WriteLine(vertex.Label);\r\n}\r\n```\r\n\r\n`GraphNode` provides [implicit conversion operators][implicit] to `string`, `int`, `long` and others in order to improve code readability, allowing the following C# syntax:\r\n\r\n```csharp\r\nvar rs = session.ExecuteGraph(new SimpleGraphStatement(\"g.V().has('name', 'marko').values('location')\"));\r\nforeach (string location in rs)\r\n{\r\n    Console.WriteLine(location);\r\n}\r\n```\r\n\r\n`GraphNode` inherits from [`DynamicObject`][dynamic], allowing you to consume it using the `dynamic` keyword and/or as a dictionary.\r\n\r\n```csharp\r\ndynamic r = session.ExecuteGraph(new SimpleGraphStatement(\"g.V()\")).First();\r\n```\r\n\r\n### Parameters\r\n\r\nGraph query parameters are always named. Parameter bindings are passed as an anonymous type or as a\r\n`IDictionary\u003cstring, object\u003e` alongside the query:\r\n\r\n```csharp\r\nsession.ExecuteGraph(\"g.addV(label, vertexLabel)\", new { vertexLabel = \"test_vertex_2\" });\r\n```\r\n\r\nNote that, unlike in CQL, Gremlin placeholders are not prefixed with \":\".\r\n\r\n### Prepared statements with DSE Graph\r\n\r\nPrepared graph statements are not supported by DSE Graph.\r\n\r\n## Geospatial types\r\n\r\nDSE 5 comes with a set of additional types to represent geospatial data: `PointType`, `LineStringType` and\r\n`PolygonType`:\r\n\r\n```\r\ncqlsh\u003e CREATE TABLE points_of_interest(name text PRIMARY KEY, coords 'PointType');\r\ncqlsh\u003e INSERT INTO points_of_interest (name, coords) VALUES ('Eiffel Tower', 'POINT(48.8582 2.2945)');\r\n```\r\n\r\nThe DSE driver includes C# representations of these types, that can be used directly in queries:\r\n\r\n```csharp\r\nusing Cassandra.Geometry;\r\n```\r\n\r\n```csharp\r\nRow row = session.Execute(\"SELECT coords FROM points_of_interest WHERE name = 'Eiffel Tower'\").First();\r\nPoint coords = row.GetValue\u003cPoint\u003e(\"coords\");\r\n\r\nvar statement = new SimpleStatement(\"INSERT INTO points_of_interest (name, coords) VALUES (?, ?)\",\r\n    \"Washington Monument\",\r\n    new Point(38.8895, 77.0352));\r\nsession.Execute(statement);\r\n```\r\n\r\n## Compatibility\r\n\r\n- Apache Cassandra versions 2.0 and above.\r\n- DataStax Enterprise versions 4.8 and above.\r\n- The driver targets .NET Framework 4.5.2 and .NET Standard 2.0\r\n\r\nHere is a list of platforms and .NET targets that Datastax uses when testing this driver:\r\n\r\n|  Platform             | net462 | net472 | net481 | net6 | net7 | net8  |\r\n|-----------------------|--------|--------|--------|------|------|-------|\r\n| Windows Server 2019³  |  ✓    |  ✓     |  ✓     |  ✓²  |  ✓¹ |  ✓   |\r\n| Ubuntu 18.04          |  -     |  -     |   -    |  ✓   | ✓   | ✓    |\r\n\r\n¹ No tests are run for the `net7` target on the Windows platform but `net7` is still considered fully supported.\r\n\r\n² Only unit tests are ran for the `net6` target on the windows platform but `net6` is still considered fully supported.\r\n\r\n³ Appveyor's `Visual Studio 2022` image is used for these tests.\r\n\r\nMono `6.12.0` is also used to run `net462` tests on `Ubuntu 18.04` but Datastax can't guarantee that the driver fully supports Mono in a production environment. Datastax recommends the modern cross platform .NET platform instead.\r\n\r\nNote: DataStax products do not support big-endian systems.\r\n\r\n## Building and running the tests\r\n\r\nYou can use Visual Studio or msbuild to build the solution.\r\n\r\n[Check the documentation for building the driver from source and running the tests](https://github.com/datastax/csharp-driver/wiki/Building-and-running-tests).\r\n\r\n## License\r\n\r\n© DataStax, Inc.\r\n\r\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at\r\n\r\n\u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e\r\n\r\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\r\n\r\n[astra]: https://www.datastax.com/products/datastax-astra\r\n[apidocs]: https://docs.datastax.com/en/latest-csharp-driver-api/\r\n[docindex]: https://docs.datastax.com/en/developer/csharp-driver/latest/\r\n[features]: https://docs.datastax.com/en/developer/csharp-driver/latest/features/\r\n[faq]: https://docs.datastax.com/en/developer/csharp-driver/latest/faq/\r\n[nuget]: https://nuget.org/packages/CassandraCSharpDriver/\r\n[mailinglist]: https://groups.google.com/a/lists.datastax.com/forum/#!forum/csharp-driver-user\r\n[jira]: https://datastax-oss.atlassian.net/projects/CSHARP/issues\r\n[udt]: https://docs.datastax.com/en/dse/6.0/cql/cql/cql_using/useInsertUDT.html\r\n[poco]: http://en.wikipedia.org/wiki/Plain_Old_CLR_Object\r\n[linq]: https://docs.datastax.com/en/developer/csharp-driver/latest/features/components/linq/\r\n[mapper]: https://docs.datastax.com/en/developer/csharp-driver/latest/features/components/mapper/\r\n[components]: https://docs.datastax.com/en/developer/csharp-driver/latest/features/components/\r\n[policies]: https://docs.datastax.com/en/developer/csharp-driver/latest/features/tuning-policies/\r\n[upgrade-guide]: https://docs.datastax.com/en/developer/csharp-driver/latest/upgrade-guide/\r\n[upgrade-guide-dse]: https://docs.datastax.com/en/developer/csharp-driver/latest/upgrade-guide/upgrade-from-dse-driver/\r\n[dse-driver]: https://docs.datastax.com/en/developer/csharp-driver-dse/latest/\r\n[community]: https://community.datastax.com\r\n[dse]: https://www.datastax.com/products/datastax-enterprise\r\n[implicit]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/implicit\r\n[dynamic]: https://msdn.microsoft.com/en-us/library/dd264736.aspx\r\n[dse-graph]: https://www.datastax.com/products/datastax-enterprise-graph\r\n[dev-guide]: https://docs.datastax.com/en/devapp/doc/devapp/aboutDrivers.html\r\n[driver-matrix]: https://docs.datastax.com/en/driver-matrix/doc/index.html\r\n","funding_links":[],"categories":["Frameworks, Libraries and Tools","Database Drivers","数据库驱动","框架, 库和工具","General"],"sub_categories":["Database Drivers","数据库驱动程序","Integrating with Cassandra"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fcsharp-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastax%2Fcsharp-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastax%2Fcsharp-driver/lists"}