{"id":13711909,"url":"https://github.com/mjoerussell/zdb","last_synced_at":"2025-05-06T21:32:39.311Z","repository":{"id":40290266,"uuid":"364596930","full_name":"mjoerussell/zdb","owner":"mjoerussell","description":"A library for interacting with databases in Zig","archived":false,"fork":false,"pushed_at":"2024-02-15T07:36:41.000Z","size":802,"stargazers_count":24,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-03T23:23:57.862Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjoerussell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-05T14:05:11.000Z","updated_at":"2024-05-29T09:08:53.000Z","dependencies_parsed_at":"2022-08-09T16:18:02.990Z","dependency_job_id":null,"html_url":"https://github.com/mjoerussell/zdb","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjoerussell%2Fzdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjoerussell%2Fzdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjoerussell%2Fzdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjoerussell%2Fzdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjoerussell","download_url":"https://codeload.github.com/mjoerussell/zdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224535572,"owners_count":17327552,"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-02T23:01:12.849Z","updated_at":"2024-11-13T22:30:56.558Z","avatar_url":"https://github.com/mjoerussell.png","language":"Zig","funding_links":[],"categories":["Data \u0026 Science"],"sub_categories":["Database"],"readme":"# zdb\r\n\r\nA library for interacting with databases in Zig. Builds on top of [zig-odbc](https://github.com/mjoerussell/zig-odbc) to provide a higher-level\r\ninteraction between the developer and the DB.\r\n\r\n**Important!: This project is still not fully production-ready. The biggest missing piece as of now is that ODBC operations can only run synchronously.**\r\n\r\n## Using this Library\r\n\r\nTo use zdb, follow these steps:\r\n\r\n### 0. Dependencies\r\n\r\nMake sure you have an ODBC driver and driver manager installed already. On Windows, this should be pre-installed. On other\r\nsystems, a good option is [`unixODBC`](http://www.unixodbc.org).\r\n\r\n### 1. Add to `build.zig.zon`\r\n\r\n```zig\r\n.{\r\n    .name = \"\",\r\n    .version = \"\",\r\n    .dependencies = .{\r\n        .zdb = .{\r\n            .url = \"https://github.com/mjoerussell/zdb/\u003csha\u003e.tar.gz\",\r\n            .hash = \"\u003chash\u003e\",\r\n        }\r\n    }\r\n}\r\n```\r\n\r\n### 2. Add zdb module \u0026 artifact to your project\r\n\r\n```zig\r\n\r\npub fn build(b: *std.build.Builder) void {\r\n    // Create executable \"exe\"\r\n    \r\n    var zdb_dep = b.dependency(\"zdb\", .{\r\n        .target = target,\r\n        .optimize = optimize,\r\n    }); \r\n\r\n    const zdb_module = zdb_dep.module(\"zdb\");\r\n    const zdb_lib = zdb_dep.artifact(\"zdb\");\r\n\r\n    exe.addModule(\"zdb\", zdb_module);\r\n    exe.linkLibrary(zdb_lib);\r\n}\r\n```\r\n\r\n### 3. Usage in Code\r\n\r\nWherever you use zdb, include `const zdb = @import(\"zdb\");`.\r\n\r\n## Current Features\r\n\r\nCurrently this library is in alpha and is limited in scope. The currently available features include:\r\n\r\n### Connect to Database\r\n\r\nIt's easy to connect to a database using a connection string:\r\n\r\n```zig\r\nconst zdb = @import(\"zdb\");\r\nconst Connection = zdb.Connection;\r\n\r\npub fn main() !void {\r\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\r\n    defer _ = gpa.deinit();\r\n\r\n    const allocator = \u0026gpa.allocator;\r\n\r\n    var connection = try Connection.init(.{});\r\n    defer connection.deinit();\r\n\r\n    try connection.connectExtended(\"ODBC;driver=PostgreSQL Unicode(x64);DSN=PostgreSQL35W\");\r\n}\r\n```\r\n\r\nYou can also use a configuration struct to connect:\r\n\r\n```zig  \r\ntry connection.connectWithConfig(allocator, .{ .driver = \"PostgeSQL Unicode(x64)\", .dsn = \"PostgeSQL35W\" });\r\n```\r\n\r\n### Execute Statements\r\n\r\nArbitrary SQL statements can be executed with `Cursor.executeDirect`. Prepared statements can also be created and then executed with `Cursor.prepare` and `Cursor.execute`, respectively.\r\n\r\n```zig\r\n// An example of executing a statement directly\r\n\r\n//.....\r\n\r\nvar cursor = try connection.getCursor(allocator);\r\ndefer cursor.deinit();\r\n\r\nvar result_set = try cursor.executeDirect(allocator, \"select * from example_table\", .{});\r\n\r\n// use results.......\r\n```\r\n\r\nBoth direct executions and prepared executions support statement parameters. `Cursor.executeDirect` and `Cursor.prepare` support passing parameters as a tuple. Prepared statements can be used with multiple sets of parameters by calling `Cursor.bindParameters` in-between executions.\r\n\r\n```zig\r\n// An example of executing a query with parameters\r\n\r\nvar cursor = try connection.getCursor(allocator);\r\ndefer cursor.deinit(allocator);\r\n\r\nvar result_set = try cursor.executeDirect(allocator, \"select * from example_table where value \u003e ?\", .{10});\r\n\r\n// use results.....\r\n```\r\n\r\n### Insert Data\r\n\r\nYou can use `Cursor.executeDirect` and the prepared statement alternative to execute **INSERT** statements just as described in the previous section; however, one often wants to insert multiple values at once. It's also very common to model tables as structs in code, and to want to push entire structs to a table. Because of this zdb has a convenient way to run **INSERT** queries.\r\n\r\nFor a complete example of how this feature can be used please refer to the example [03_create_and_query_table](./examples/src/03_create_and_query_table.zig).\r\n\r\n### ODBC Fallthrough\r\n\r\nIf you want to use this package in it's current state, then it would probably be necessary to use the ODBC bindings directly to\r\nsupplement missing features. You can access the bindings by importing them like this:\r\n\r\n```\r\nconst odbc = @import(\"zdb\").odbc;\r\n```\r\n\r\nPlease see [zig-odbc](https://github.com/mjoerussell/zig-odbc) for more information about these bindings.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjoerussell%2Fzdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjoerussell%2Fzdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjoerussell%2Fzdb/lists"}