{"id":18436063,"url":"https://github.com/codenotary/immudb-py","last_synced_at":"2026-03-14T13:49:00.067Z","repository":{"id":37991725,"uuid":"240278925","full_name":"codenotary/immudb-py","owner":"codenotary","description":"immudb Python SDK","archived":false,"fork":false,"pushed_at":"2025-03-25T14:13:00.000Z","size":566,"stargazers_count":46,"open_issues_count":20,"forks_count":8,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-28T08:13:02.106Z","etag":null,"topics":["cryptographic-verifications","database","immudb","immutability","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","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/codenotary.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-13T14:24:31.000Z","updated_at":"2025-03-26T05:43:00.000Z","dependencies_parsed_at":"2024-06-21T15:21:56.007Z","dependency_job_id":"a3189b60-bc8a-4d56-adf1-2c703afd8aad","html_url":"https://github.com/codenotary/immudb-py","commit_stats":{"total_commits":180,"total_committers":11,"mean_commits":"16.363636363636363","dds":0.6777777777777778,"last_synced_commit":"025885e72101f919b9bdea79af3f8530b6d96410"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenotary","download_url":"https://codeload.github.com/codenotary/immudb-py/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"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":["cryptographic-verifications","database","immudb","immutability","python","python3"],"created_at":"2024-11-06T06:10:13.295Z","updated_at":"2026-03-14T13:48:55.020Z","avatar_url":"https://github.com/codenotary.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# immudb-py [![License](https://img.shields.io/github/license/codenotary/immudb4j)](LICENSE)\n\n[![CI](https://github.com/codenotary/immudb-py/actions/workflows/ci.yml/badge.svg)](https://github.com/codenotary/immudb-py/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/codenotary/immudb-py/badge.svg?branch=master)](https://coveralls.io/github/codenotary/immudb-py?branch=master)[![Slack](https://img.shields.io/badge/join%20slack-%23immutability-brightgreen.svg)](https://slack.vchain.us/)\n[![Discuss at immudb@googlegroups.com](https://img.shields.io/badge/discuss-immudb%40googlegroups.com-blue.svg)](https://groups.google.com/group/immudb)\n\n## Official [immudb] client for Python.\n\n### Try it on the immudb Playground!\n\n[![screenshot](playground.png)](https://play.codenotary.com)\n\n[immudb]: https://immudb.io\n\n## Contents\n\n- [Introduction](#introduction)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Supported Versions](#supported-versions)\n- [Quickstart](#quickstart)\n- [Step by step guide](#step-by-step-guide)\n- [Creating a Client](#creating-a-client)\n\n## Introduction\n\nimmu-py implements a [grpc] immudb client. A minimalist API is exposed for applications while cryptographic\nverifications and state update protocol implementation are fully implemented by this client.\nLatest validated immudb state may be kept in the local filesystem when using default `rootService`,\nplease read [immudb research paper] for details of how immutability is ensured by [immudb].\n\n[grpc]: https://grpc.io/\n[immudb research paper]: https://immudb.io/\n[immudb]: https://immudb.io/\n\n## Prerequisites\n\nimmu-py assumes there is an existing instance of the immudb server up and running. \nRunning `immudb` is quite simple, please refer to the\nfollowing link for downloading and running it: https://immudb.io/docs/quickstart.html\n\nimmudb-py requires python version 3.6 or greater.\nIf you are using 3.6, you'll need dataclasses package; on 3.7+,\ndataclasses is part of the python distribution.\n\n## Installation\n\nYou can install latest version cloning this repository, and then use the make command to install\nprerequisites and the package itself:\n\n```shell\n    make init\n    make install\n```\n\nOr, you can install latest stable version using pip:\n\n```shell\n    pip3 install immudb-py\n```\n\nThen, in you code, import the client library as as follows:\n\n```python\n    from immudb import ImmudbClient\n```\n\n*Note*: immudb-py need `grpcio` module from google. On Alpine linux, you need\n these packages in order to correctly build (and install) grpcio:\n - `linux-headers`\n - `python3-dev`\n - `g++`\n\n## Supported Versions\n\nimmu-py supports the [latest immudb release].\n\n[latest immudb release]: https://github.com/codenotary/immudb/releases/tag/v0.9.0\n\n## Quickstart\n\n[Hello Immutable World!] example can be found in `immudb-client-examples` repo.\n\n[Hello Immutable World!]: https://github.com/codenotary/immudb-client-examples/tree/master/python\n\n## Step by step guide\n\n### Creating a Client\n\nThe following code snippets shows how to create a client.\n\nUsing default configuration:\n\n```python\n    client = ImmudbClient()\n```\n\nSetting `immudb` url and port:\n\n```python\n\n    client = ImmudbClient(\"mycustomurl:someport\")\n    client = ImmudbClient(\"10.105.20.32:8899\")\n```\n\n### User sessions\n\nUse `login` and `logout` methods to initiate and terminate user sessions:\n\n```python\n    client.login(\"usr1\", \"pwd1\");\n\n    // Interact with immudb using logged user\n\n    client.logout();\n```\n### Encoding\n\nPlease note that, in order to provide maximum flexibility, all functions accept byte arrays as parameters.\nTherefore, unicode strings must be properly encoded.\nIt is possible to store structured objects, but they must be serialized (e.g., with pickle or json).\n\n### Creating a database\n\nCreating a new database is quite simple:\n\n```python\n    client.createDatabase(b\"db1\");\n```\n\n### Setting the active database\n\nSpecify the active database with:\n\n```python\n    client.useDatabase(b\"db1\");\n```\nIf not specified, the default databased used is \"defaultdb\".\n\n### Traditional read and write\n\nimmudb provides read and write operations that behave as a traditional\nkey-value store i.e. no cryptographic verification is done. This operations\nmay be used when validations can be post-poned:\n\n```python\n    client.set(b\"k123\", b\"value123\");\n    result = client.get(b\"k123\");\n```\n\n### Verified read and write\n\nimmudb provides built-in cryptographic verification for any entry. The client\nimplements the mathematical validations while the application uses as a traditional\nread or write operation:\n\n```python\n    try:\n        client.verifiedSet(b\"k123\", b\"v123\");\n        results = client.verifiedGet(b\"k123\");\n    Except VerificationException as e:\n        # Do something\n```\n\n### Multi-key read and write\n\nTransactional multi-key read and write operations are supported by immudb and immudb-py.\nAtomic multi-key write (all entries are persisted or none):\n\n```python\n    normal_dictionary = {b\"key1\": b\"value1\", b\"key2\": b\"value2\"}\n    client.setAll(normal_dictionary);\n```\n\nAtomic multi-key read (all entries are retrieved or none):\n\n```python\n    normal_dictionary = {b\"key1\": b\"value1\", b\"key2\": b\"value2\"}\n    results_dictionary = client.getAll(normal_dictionary.keys())\n    # Or manually\n    client.get([b\"key1\", b\"key2\"])\n```\n## User management\nUsers can be added and granted access to databases.\n\n### Adding a user\nThe ```createUser``` functions create a new users and grants the specified permission to a database.\n```python\nuser='newuser'\npassword='Pw1:pasdfoiu'\npermission=immudb.constants.PERMISSION_RW\ndatabase='defaultdb'\n\nclient.createUser(user, password, permission, database)\n```\n\nThe database must exists at the time the user is created. The password must be between 8 and 32 characters in length, and must have at least one upper case letter, a symbol and a digit.\n\nPermission are defined in immudb.constants and are:\n\n- `PERMISSION_SYS_ADMIN`\n- `PERMISSION_ADMIN`\n- `PERMISSION_NONE`\n- `PERMISSION_R`\n- `PERMISSION_RW`\n\n### Changin password\nThe user must must provide both old and new password:\n```python\nnewPassword=\"pW1:a0s98d7gfy\"\nresp=client.changePassword(user, newPassword, oldPassword)\n```\nIt is applied the same password policy of user creation.\n\n### User list\n\nTo get the list of user created on immudb, simply call ```listUsers```:\n```python\nresp=client.listUsers()\nprint(users.userlist.users)\n```\n\n### Closing the client\n\nTo programatically close the connection with immudb server use the `shutdown` operation:\n\n```python\n    client.shutdown();\n```\n\nNote: after shutdown, a new client needs to be created to establish a new connection.\n\n## State persistance\n\nAn important immudb feature is the ability for a client to check every transaction for tampering. In order to \nbe able to do that, it is necessary to persist client state (i.e., save it to disk) so that if some tampering \non the server happens between two runs, it is immediatly detected.\n\nA `RootService` implements just that: it stores immudb client after every transaction, in order to be able to\nuse it afterward to check the server correctness.\n\n### Using the Persistent Root Service\n\nThe default RootService, for simplicity, commits the state to RAM, and so it is unsuitable for real time safe\napplication. To have persistance, the application must instantiate a `PersistentRootService` object, which stores\nits state to disk.\n\nLet's see a simple example that uses state persistance:\n\n```python\nfrom immudb.client import ImmudbClient, PersistentRootService\nclient=ImmudbClient(rs=PersistentRootService())\nclient.login(username=\"immudb\", password=\"immudb\")\nclient.verifiedTxById(42)\nclient.verifiedGet(b\"example\")\n```\n\nIn this example, the Root Service is saved to the disk after every verified transaction. As you can see, it is very\neasy to use. Just create and use the PersistentRootService object in the client initialization.\n\n### Process and threads\n\nPlease keep in mind that the implementation is not thread/process safe. If you are using a multi-process application,\nit is advisable to use a different state file for every instance: just pass the filename as argument to the \nPersistentRootService constructor:\n\n```python\nclient = ImmudbClient(rs=PersistentRootService(\"rootfilename\"))\n```\n\nDefault rootfile is \"~/.immudbRoot\"\n\nIf needed/wanted, it is also easy to extend the default implementation adding synchronization primitives to the get/set methods.\nIn this way, more than one immudb client can share the same PersistentRootService instance without interering each other.\n\n## Cryptographic state signing\n\nTo increase safety, it is possible to generate a private key and use it to sign every verification response. Clients can\nthen use the corresponding public key to check for response correctness.\n\n### Key generation\nYou can use `openssl` to create a private key, and then extract the public key:\n```sh\nopenssl ecparam -name prime256v1 -genkey -noout -out private_signing_key.pem\nopenssl ec -in private_signing_key.pem -pubout -out public_signing_key.pem\n```\n\n### Key usage (server side)\nOn immudb server, use `--signingKey private_signing_key.pem` to activate cryptographic signature.\n\n### Key usage (client/SDK side)\n\nOn immudb python SDK, just pass the public key filename to the ImmudbClient constructor:\n```python\nclient=ImmudbClient(publicKeyFile=\"/certs/public_signing_key.pem\")\n```\nEvery transaction will be then automatically checked. An exception is thrown if the cryptographic check fails.\n\n## Contributing\n\nWe welcome contributions. Feel free to join the team!\n\nTo report bugs or get help, use [GitHub's issues].\n\n[GitHub's issues]: https://github.com/codenotary/immudb-py/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenotary%2Fimmudb-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb-py/lists"}