## F.44. pgrowlocks

The `pgrowlocks` module provides a function to show row locking information for a specified table.

By default use is restricted to superusers, members of the `pg_stat_scan_tables` role, and users with `SELECT` permissions on the table.

### F.44.1. Overview

    pgrowlocks(text) returns setof record

The parameter is the name of a table. The result is a set of records, with one row for each locked row within the table. The output columns are shown in Table F.31.

Table F.31. `pgrowlocks` Output Columns

Name | Type | Description
--- | --- | ---
`locked_row` | `tid` | Tuple ID (TID) of locked row
`locker` | `xid` | Transaction ID of locker, or multixact ID if multitransaction
`multi` | `boolean` | True if locker is a multitransaction
`xids` | `xid[]` | Transaction IDs of lockers (more than one if multitransaction)
`lock_type` | `text[]` | Lock mode of lockers (more than one if multitransaction), an array of `Key Share`, `Share`, `For No Key Update`, `No Key Update`, `For Update`, `Update`.
`pids` | `integer[]` | Process IDs of locking backends (more than one if multitransaction)

`pgrowlocks` takes `AccessShareLock` for the target table and reads each row one by one to collect the row locking information. This is not very speedy for a large table. Note that:

1. If the table as a whole is exclusive-locked by someone else, `pgrowlocks` will be blocked.

2. `pgrowlocks` is not guaranteed to produce a self-consistent snapshot. It is possible that a new row lock is taken, or an old lock is freed, during its execution.

`pgrowlocks` does not show the contents of locked rows. If you want to take a look at the row contents at the same time, you could do something like this:

    SELECT * FROM accounts AS a, pgrowlocks('accounts') AS p
      WHERE p.locked_row = a.ctid;

Be aware however that such a query will be very inefficient.

### F.44.2. Sample Output

    test=# SELECT * FROM pgrowlocks('t1');
     locked_row | lock_type | locker | multi |   xids    |     pids
    ------------+-----------+--------+-------+-----------+---------------
          (0,1) | Shared    |     19 | t     | {804,805} | {29066,29068}
          (0,2) | Shared    |     19 | t     | {804,805} | {29066,29068}
          (0,3) | Exclusive |    804 | f     | {804}     | {29066}
          (0,4) | Exclusive |    804 | f     | {804}     | {29066}
    (4 rows)

### F.44.3. Author

Tatsuo Ishii