{"id":16776349,"url":"https://github.com/morebec/orkestra-postgresql-document-store","last_synced_at":"2026-05-11T02:48:57.733Z","repository":{"id":49499695,"uuid":"359992676","full_name":"Morebec/orkestra-postgresql-document-store","owner":"Morebec","description":"[READ ONLY] Orkestra Component allowing to easily use PostgreSQL as a Document Store","archived":false,"fork":false,"pushed_at":"2023-03-31T18:46:54.000Z","size":36,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"2.x","last_synced_at":"2025-01-23T05:14:15.153Z","etag":null,"topics":["document","document-store","json","jsonb","orkestra","php","postgresql"],"latest_commit_sha":null,"homepage":"","language":"PHP","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/Morebec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2021-04-21T01:01:31.000Z","updated_at":"2022-07-25T15:52:03.000Z","dependencies_parsed_at":"2025-01-23T05:12:03.616Z","dependency_job_id":"c22e5ef1-8f6d-4911-bb79-68e68dda11c7","html_url":"https://github.com/Morebec/orkestra-postgresql-document-store","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Forkestra-postgresql-document-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Forkestra-postgresql-document-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Forkestra-postgresql-document-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Morebec%2Forkestra-postgresql-document-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Morebec","download_url":"https://codeload.github.com/Morebec/orkestra-postgresql-document-store/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243910749,"owners_count":20367545,"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":["document","document-store","json","jsonb","orkestra","php","postgresql"],"created_at":"2024-10-13T07:09:41.574Z","updated_at":"2026-05-11T02:48:57.698Z","avatar_url":"https://github.com/Morebec.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostgreSQLDocumentStore\nImplementation of a Document Store using PostgreSQL's JSONB features.\nIt is based on `doctrine/dbal` for accessing the database internally.\n\n## Installation\n```shell\ncomposer require morebec/orkestra-postgresql-document-store\n```\n\n## Usage\nThe Document Store uses `doctrine/dbal` for accessing the database.\nTherefore, it requires a DBAL Connection as a constructor dependency.\nIt also relies on a `ClockInterface` from the `morebec/orkestra-date-time`component in order to access\nthe current date time.\n\n```php\nuse Doctrine\\DBAL\\Configuration;\nuse Doctrine\\DBAL\\DriverManager;\nuse Morebec\\Orkestra\\DateTime\\SystemClock;\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStore;\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStoreConfiguration;\n\n\n$connection = DriverManager::getConnection([\n    'url' =\u003e '...'\n], new Configuration()); \n\n$config = new PostgreSqlDocumentStoreConfiguration(); \n$clock = new SystemClock();\n$store = new PostgreSqlDocumentStore($connection, $config, $clock);\n```\n\nThe second parameter corresponds to the configuration of the DocumentStore. This configuration class\ncan be used to alter the behaviour of the document store.\n\n\n### Inserting Documents\nTo insert a document in a collection:\n```php\n/** @var Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStore $store */\n$store-\u003einsertDocument('users', 'usr123456789', [\n    'id' =\u003e 'usr123456789',\n    'username' =\u003e 'jane.doe',\n    'fullname' =\u003e 'Jane Doe',\n    'emailAddress' =\u003e 'jane.doe@email.com'\n]);\n```\n\nIf the collection does not exist, it will be created automatically.\n\n### Finding Documents\nFinding elements can be performed using the `findOneDocument` and `findManyDocuments` methods of the\ndocument store. These methods accept either a string representing a PostgreSQL json query or a `Filter`\nwhich is a simple API for a query builder with the document store:\n\n```php\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\Filter\\Filter;\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\Filter\\FilterOperator;\n\n$store-\u003einsertDocument('users', 'usr123456789', [\n    'id' =\u003e 'usr123456789',\n    'username' =\u003e 'jane.doe',\n    'fullname' =\u003e 'Jane Doe',\n    'emailAddress' =\u003e 'jane.doe@email.com',\n    'preferredLanguage' =\u003e 'ENGLISH' \n]);\n\n\n// Finds a document by its ID.\n$store-\u003efindOneDocument('users', Filter::findById('usr123456789'));\n\n// Finds a document by a single field:\n$store-\u003efindOneDocument('users', Filter::findByField('username', FilterOperator::EQUAL(), 'jane.doe'));\n\n// Finds a document by a multiple criteria\n$store-\u003efindOneDocument('users', \n    Filter::where('username', FilterOperator::EQUAL(), 'jane.doe')\n    -\u003eor('preferredLanguage', FilterOperator::IS_NOT(), null)\n);\n\n\n// You can also use strings to have greater control over the query:\n$store-\u003efindOneDocument('users', 'data-\u003e\u003efullname = \\'Jane Doe\\'');\n```\n\u003e If you are using the `Filter` query builder, the values are automatically escaped using prepared statements placeholders.\n\u003e However if you are using a string for a query, the values will not be escaped, and you must make sure that you are not introducing potential loopholes\n\u003e for SQL Injections.\n\n\u003e Internally a column `data` with type `JSONB` is added to every created collection table.\n\u003e This is why if you are doing a string query, you must specify the `data` column.\n\n\u003e For even greater control, the document store exposes a `getConnection` method which returns the `DBAL` connection\n\u003e which you can use to make more complex queries using doctrine's Query Builder or raw connection.\n\n### Updating Documents\nTo update a document, use the `updateDocument` method.\nThis method does not support partial documents, and therefore overwrites the document in the store\nwith the provided one:\n\n```php\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStore;\n\n/** @var $store  PostgreSqlDocumentStore **/\n$store-\u003eupdateDocument('users', 'usr123456789', [\n    'id' =\u003e 'usr123456789',\n    'username' =\u003e 'jane.doe',\n    'fullname' =\u003e 'Jane A. Doe',\n    'emailAddress' =\u003e 'new.jane.doe@email.com',\n    'preferredLanguage' =\u003e 'FRENCH' \n]);\n```\n### Removing Documents\nRemoving a document can be done as follows:\n```php\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStore;\n\n/** @var $store  PostgreSqlDocumentStore **/\n$store-\u003eremoveDocument('users', 'usr123456789');\n```\n\n### Changing table names prefix.\nIn order to have better control over the collection tables it manages,\nthe document store adds a prefix to any table that it creates.\n\nThis prefix can be configured in the document store configuration:\n\n```php\nuse Morebec\\Orkestra\\PostgreSqlDocumentStore\\PostgreSqlDocumentStoreConfiguration;\n\n$config = new PostgreSqlDocumentStoreConfiguration();\n\n$config-\u003ecollectionPrefix = 'you_prefix_';\n```\n\n### Transaction Management\nIf you need to use transactions for your operations, you can do this by accessing the DBAL connection:\n\n```php\n$connection = $store-\u003egetConnection();\n\n$connection-\u003etransactional(static function() use ($store) {\n    $store-\u003einsertDocument('users', 'usr123456789', [\n        'id' =\u003e 'usr123456789',\n        'username' =\u003e 'jane.doe',\n        'fullname' =\u003e 'Jane Doe',\n        'emailAddress' =\u003e 'jane.doe@email.com',\n        'preferredLanguage' =\u003e 'ENGLISH' \n    ]);\n    \n    $store-\u003einsertDocument('users', 'usrABCDEFGHI', [\n        'id' =\u003e 'usrABCDEFGHI',\n        'username' =\u003e 'john.doe',\n        'fullname' =\u003e 'John Doe',\n        'emailAddress' =\u003e 'john.doe@email.com',\n        'preferredLanguage' =\u003e 'SPANISH' \n    ]);\n});\n```\n\n\n## Testing\nTo run the tests execute the following command:\n```shell\nvendor/bin/phpunit tests/\n```\n\nIt is required to have an instance of postgresql running with a password-less role `postgres` and a database named `postgres`.\nTo easily get this setup and running a `docker-compose` configuration file is available at the root of this project.\n\nTo run it simply execute the following command:\n\n```shell\ndocker-compose up -d\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorebec%2Forkestra-postgresql-document-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorebec%2Forkestra-postgresql-document-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorebec%2Forkestra-postgresql-document-store/lists"}