README

PDO wrapper for Phel. Talk to relational databases from Phel without dropping into PHP interop.

Every PDO method has a wrapper, params bind with the right type automatically, rows come back as Phel maps, and transactions nest properly. Tested against SQLite, MySQL and PostgreSQL.

Install

composer require phel-lang/phel-pdo

Requires PHP >=8.4 and phel-lang/phel-lang ^0.41.

Your project needs a phel-config.php, as any Phel project does - that is how Phel finds both your sources and your dependencies' namespaces:

<?php
declare(strict_types=1);
use Phel\Config\PhelConfig;
return PhelConfig::forProject(mainNamespace: 'your-app.main');

Quick start

(require phel.pdo)

(def conn (pdo/connect "sqlite::memory:"))
(pdo/exec conn "create table t1 (id integer primary key autoincrement, name varchar(10))")
(pdo/exec conn "insert into t1 (name) values ('phel'), ('php')")

;; Read - params are bound, never interpolated into the SQL
(pdo/select conn "select * from t1")
;; => [{:id 1, :name "phel"} {:id 2, :name "php"}]

(pdo/select-one conn "select * from t1 where id = ?" [1])
;; => {:id 1, :name "phel"}        ; nil when there are no rows

(pdo/select-value conn "select count(*) from t1")
;; => 2                            ; first column of the first row

;; Named params work everywhere positional ones do
(pdo/select-one conn "select * from t1 where name = :name" {:name "phel"})
;; => {:id 1, :name "phel"}

;; Write from a map
(pdo/insert conn :t1 {:name "lisp"})       ; => "3"  new last-insert-id
(pdo/update conn :t1 {:name "clj"} {:id 3}) ; => 1   affected rows
(pdo/delete conn :t1 {:id 3})               ; => 1   affected rows

;; Transactions - nested blocks get a SAVEPOINT, so a caught failure
;; undoes only that block
(pdo/with-transaction conn
  (pdo/insert conn :t1 {:name "a"})
  (pdo/insert conn :t1 {:name "b"}))

Rows come back as maps keyed by column keyword. pdo/select returns [] when there are no rows; pdo/select-one and pdo/select-value return nil.

Need the statement itself - to stream, to re-execute, to check row-count? pdo/query and pdo/prepare hand it back:

(let [stmt (pdo/prepare conn "select * from t1 where id = :id")]
  (-> stmt (pdo/execute {:id 1}) (pdo/fetch)))
;; => {:id 1, :name "phel"}

With phel-sql

phel-sql is an optional data-driven SQL DSL. It returns [sql params] you feed straight into pdo/prepare + pdo/execute:

(let [[query params] (sql/format {:select [:id :name], :from [:users], :where [:= :id 1]})]
  (-> (pdo/prepare conn query)
      (pdo/execute params)
      (pdo/fetch)))
;; => {:id 1, :name "phel"}

API

All functions live in the phel.pdo namespace.

Connection

Function	Signature	Description
`connect`	`(connect dsn & [username password options])`	Open a connection. Throws `PDOException` on failure. Sets `ERRMODE_EXCEPTION` by default.
`from-connection`	`(from-connection pdo & [options])`	Wrap an already-open `\PDO` (e.g. a framework/DBAL connection) as-is. `{:apply-defaults true}` sets `ERRMODE_EXCEPTION`.
`close`	`(close conn)`	Roll back any open transaction and mark the connection unusable. Idempotent. Never disturbs a `from-connection` handle.
`with-connection`	`(with-connection [name init] & body)`	Bind, run `body`, close on return and on throw. Returns the last body value.
`closed?`	`(closed? conn)`	`true` once `close` has been called.
`exec`	`(exec conn sql)`	Execute SQL, return number of affected rows.
`query`	`(query conn sql & [params options])`	Run SQL, binding `params` (map by name, vector positionally) through a prepared statement. Without params, uses `PDO::query`. `options` takes `{:fetch-mode …}`.
`prepare`	`(prepare conn sql & [options])`	Prepare a statement for later `execute`.
`select`	`(select conn sql & [params options])`	Run SQL and return every row. `options` takes `{:as :maps\|:rows}`, as `fetch-all`.
`select-one`	`(select-one conn sql & [params])`	First row as a map, or `nil`.
`select-value`	`(select-value conn sql & [params not-found])`	First column of the first row — `count(*)`, `max(id)`, an existence check. `not-found` (default `nil`) when there are no rows.
`insert`	`(insert conn table row)`	Insert a non-empty `row` map into `table` via a prepared statement and return the new `last-insert-id` (string). Identifiers must match `[A-Za-z_][A-Za-z0-9_]*`.
`update`	`(update conn table set-map where-map)`	`UPDATE` matched rows, return affected count. Both maps must be non-empty.
`delete`	`(delete conn table where-map)`	`DELETE` matched rows, return affected count. `where-map` must be non-empty.
`insert-many`	`(insert-many conn table rows)`	Insert a seq of same-keyed maps in one multi-`VALUES` statement, return affected count.
`expand-in`	`(expand-in sql params)`	Expand list params into `IN (?, ?, ?)` runs, returning `[sql params]` for `query` / `prepare`.
`quote`	`(quote conn string & [type])`	Quote a string for safe embedding in SQL.
`last-insert-id`	`(last-insert-id conn)`	ID of the last inserted row, as a string (as PDO reports it).
`begin` / `commit` / `rollback`	`(begin conn)` …	Transaction control.
`in-transaction`	`(in-transaction conn)`	`true` if a transaction is active.
`with-transaction`	`(with-transaction conn & body)`	Run `body` in a transaction: commit + return last value, or rollback + re-throw. When already in a transaction, `body` runs in a `SAVEPOINT` so a caught failure undoes only that block.
`with-savepoint`	`(with-savepoint conn f)`	Call `f` inside a `SAVEPOINT`: release + return its value, or roll back to it and re-throw. The primitive behind nested `with-transaction`.
`get-attribute` / `set-attribute`	`(get-attribute handle attr)` / `(set-attribute handle attr value)`	PDO attribute access; `handle` is a connection or a statement.
`get-available-drivers`	`(get-available-drivers)`	Vector of installed PDO drivers (static; no connection needed).
`error-code`	`(error-code handle)`	SQLSTATE string of the last operation; `handle` is a connection or a statement.
`error-info`	`(error-info handle)`	`[sqlstate driver-code driver-message]`; `handle` is a connection or a statement.

Statement

Returned by pdo/query and pdo/prepare.

Function	Signature	Description
`execute`	`(execute stmt & [params])`	Run a prepared statement. A map binds by name, a vector positionally; each param's PDO type is inferred. Returns the statement so it threads through `->` / `let`.
`fetch`	`(fetch stmt)`	Next row as a map, or `nil` if exhausted.
`fetch-all`	`(fetch-all stmt & [options])`	Remaining rows. `{:as :maps}` (default) gives maps keyed by column keyword; `{:as :rows}` gives `{:cols […] :rows [[…]]}` — ~5x faster on large result sets.
`fetch-column`	`(fetch-column stmt & [column not-found])`	Single 0-indexed column from the next row, or `not-found` (default `nil`) once exhausted. A SQL `NULL` reads back as `nil`, so pass a distinct `not-found` to tell the two apart.
`fetch-object`	`(fetch-object stmt & [class-name ctor-args])`	Next row as an object (`stdClass` by default, or an instance of `class-name`), or `nil` if exhausted.
`statement-seq`	`(statement-seq stmt)`	Lazy seq of the remaining rows as maps, fetched one at a time.
`bind-value`	`(bind-value stmt column value & [type])`	Bind a value to a placeholder. `type` defaults to the type inferred from the value. Returns the statement.
`bind-param`	`(bind-param stmt column value & [type])`	Bind a parameter, applied at execution time. Same type inference as `bind-value`. Returns the statement.
`column-count`	`(column-count stmt)`	Number of columns in the result set.
`column-names`	`(column-names stmt)`	Result-set column names as a vector of keywords, in select order, or `nil` if the driver can't report them.
`row-count`	`(row-count stmt)`	Rows affected by the last DML.
`column-meta`	`(column-meta stmt column)`	Metadata map for a 0-indexed column, or `nil` if unavailable.
`close-cursor`	`(close-cursor stmt)`	Free the cursor so the statement can be re-executed. Returns the statement.
`set-fetch-mode`	`(set-fetch-mode stmt mode & args)`	Set the statement's default fetch mode (extra args match the mode). Returns the statement.
`next-rowset`	`(next-rowset stmt)`	Advance to the next rowset of a multi-rowset statement; `false` when none remain.
`bind-column`	`(bind-column stmt column target)`	Bind a column (1-based position or name) to an atom, refreshed by `fetch-bound`. Returns a new statement.
`fetch-bound`	`(fetch-bound stmt)`	Fetch the next row, resetting every bound atom. `true` while rows remain, `false` once exhausted.
`debug-dump-params`	`(debug-dump-params stmt)`	Dump prepared statement info as a string.

Note

Unlike PDOStatement::execute() (returns bool), pdo/execute returns the statement itself so it composes with ->.

Note

Every PDO method has a wrapper here. The one that isn't a direct translation is PDOStatement::bindColumn, which binds a PHP variable by reference — Phel has no by-reference locals, so pdo/bind-column binds an atom instead and pdo/fetch-bound refreshes it.

Development

composer install
vendor/bin/phel test

Docs

Deeper docs live in docs/:

Getting started - install, first query, run tests.
Architecture - connection / statement design and conventions.
Recipes - transactions, prepared statements, bind types, phel-sql.
Troubleshooting - common errors and fixes.
Contributing - adding wrappers, commits, PRs, releases.

phel-lang / phel-pdo

Maintainers

Package info

Fund package maintenance!

Statistics

Security