{ "href": "/post/2019/12/11/atlas-postgresql-and-returning/", "relId": "2019/12/11/atlas-postgresql-and-returning", "title": "Atlas, PostgreSQL, and RETURNING", "author": "pmjones", "created": "2019-12-11 19:53:29 UTC", "updated": [ "2019-12-11 19:53:29 UTC", "2019-12-11 20:02:14 UTC" ], "tags": [ { "href": "/tag/php/", "relId": "php", "title": "PHP", "author": null, "created": null, "updated": [], "markup": "markdown" }, { "href": "/tag/programming/", "relId": "programming", "title": "Programming", "author": null, "created": null, "updated": [], "markup": "markdown" }, { "href": "/tag/atlas/", "relId": "atlas", "title": "Atlas", "author": null, "created": "2020-09-21 14:37:38 UTC", "updated": [ "2020-09-21 14:37:38 UTC", "2023-06-22 02:17:41 UTC" ], "markup": "markdown" } ], "markup": "markdown", "html": "

One of the powerful features of PostgreSQL is its RETURNING clause. For\nexample, if you have a table like this ...

\n
CREATE TABLE articles (\n    article_id SERIAL PRIMARY KEY,\n    title      VARCHAR(255) NOT NULL,\n    -- ...\n    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n);\n
\n

... and you insert a row using Atlas.Query with a RETURNING clause ...

\n
/** @var $insert \\Atlas\\Query\\Insert */\n$insert\n    ->into('articles')\n    ->columns(['title' => 'My Article'])\n    ->returning('created_at');\n\n$pdoStatement = $insert->perform();\n
\n

... then you can fetch the RETURNING column values from the PDOStatement\nresult:

\n
$returning = $pdoStatement->fetch(PDO::FETCH_ASSOC);\nvar_export($returning);\n// ['created_at' => (the postgresql timestamp)]\n
\n

If you have an Atlas.Table data gateway for that table, you can make use of\nRETURNING in your TableEvents classes to populate database-provided values\ninto your Row objects automatically.

\n

To do so, add a RETURNING clause in the modifyInsertRow() method, then\nretrieve the values into the Row in the afterInsertRow() method:

\n
// ...\n\nclass ArticleTableEvents extends TableEvents\n{\n    public function modifyInsertRow(\n        Table $table,\n        Row $row,\n        Insert $insert\n    ) : void\n    {\n        $insert->returning('created_at');\n    }\n\n    public function afterInsertRow(\n        Table $table,\n        Row $row,\n        Insert $insert,\n        PDOStatement $pdoStatement\n    ) : void\n    {\n        $returning = $pdoStatement->fetch(PDO::FETCH_ASSOC);\n        $row->created_at = $returning['created_at'];\n    }\n}\n
\n

Now when a Row gets inserted through the Table data gateway, the\ncreated_at value will be populated automatically.

\n
/** @var $tableLocator \\Atlas\\Table\\TableLocator */\n$articleTable = $tableLocator->get(ArticleTable::CLASS);\n$article = $articlesTable->newRow();\n$article->title = 'bar';\n$articleTable->insertRow($article);\necho $article->created_at; // the postgresql timestamp\n
\n

You can do the same for updates as well, using modifyUpdateRow() and\nafterUpdateRow().

\n

Bonus: becuase it uses both Atlas.Table and Atlas.Query, this functionality is\navailable \"for free\" in Atlas.Orm!

\n" }