> ## Documentation Index
> Fetch the complete documentation index at: https://cs-lua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# db — Объект базы

> SQLite: база — файл в каталоге плагина

# Объект базы

<h2 id="exec">
  db:exec
</h2>

Выполняет запрос, ничего не возвращающий.

```lua theme={null}
db:exec(sql, ...)
```

### Аргументы

| # | имя   | тип    |                  |
| - | ----- | ------ | ---------------- |
| 1 | `sql` | string | SQL              |
| 2 | `...` | any    | значения для `?` |

### Возвращает

| тип      |                        |
| -------- | ---------------------- |
| `number` | сколько строк изменено |

### Пример

```lua theme={null}
db:exec([[
	CREATE TABLE IF NOT EXISTS kills (
		steamid TEXT NOT NULL,
		weapon  TEXT NOT NULL,
		at      INTEGER NOT NULL
	);
	CREATE INDEX IF NOT EXISTS kills_by_player ON kills (steamid);
]])
```

Без параметров принимает несколько запросов через `;` — схему удобно объявлять одним куском. С параметрами запрос должен быть один.

<Note>
  Базы закрываются сами при `lua_reload`, выгрузке плагина и остановке
  сервера. Обращение к закрытой — понятная ошибка, а не работа с
  чужим файлом.
</Note>

<h2 id="query">
  db:query
</h2>

Выполняет запрос и возвращает все строки.

```lua theme={null}
db:query(sql, ...)
```

### Аргументы

| # | имя   | тип    |                  |
| - | ----- | ------ | ---------------- |
| 1 | `sql` | string | SQL              |
| 2 | `...` | any    | значения для `?` |

### Возвращает

| тип     |                                              |
| ------- | -------------------------------------------- |
| `table` | массив строк; пустой, если ничего не нашлось |

Строка — таблица с ключами по именам колонок.

<h2 id="first">
  db:first
</h2>

Выполняет запрос и возвращает первую строку.

```lua theme={null}
db:first(sql, ...)
```

### Аргументы

| # | имя   | тип    |                  |
| - | ----- | ------ | ---------------- |
| 1 | `sql` | string | SQL              |
| 2 | `...` | any    | значения для `?` |

### Возвращает

| тип            |                  |
| -------------- | ---------------- |
| `table \| nil` | строка или `nil` |

### Пример

```lua theme={null}
local r = db:first("SELECT count(*) AS n FROM kills WHERE steamid = ?", id)
print(r.n)
```

<h2 id="prepare">
  db:prepare
</h2>

Разбирает SQL один раз для многократного выполнения.

```lua theme={null}
db:prepare(sql)
```

### Аргументы

| # | имя   | тип    |                   |
| - | ----- | ------ | ----------------- |
| 1 | `sql` | string | ровно один запрос |

### Возвращает

| тип    |                          |
| ------ | ------------------------ |
| `stmt` | подготовленное выражение |

Для разового запроса выигрыша нет. Выражение живёт вместе со своей базой: закрытие базы закрывает и его.

<h2 id="transaction">
  db:transaction
</h2>

Выполняет блок одной транзакцией.

```lua theme={null}
db:transaction(fn)
```

### Аргументы

| # | имя  | тип      |                                 |
| - | ---- | -------- | ------------------------------- |
| 1 | `fn` | function | что выполнить внутри транзакции |

### Возвращает

| тип   |                      |
| ----- | -------------------- |
| `any` | то, что вернула `fn` |

### Пример

```lua theme={null}
db:transaction(function()
	for _, k in ipairs(pending) do
		st:run(k.steamid, k.weapon, k.at)
	end
end)
```

Без неё каждая вставка — отдельная транзакция со своей записью на диск: на 2000 строк разница в 25 раз.

<Warning>
  Ошибка внутри `fn` откатывает транзакцию и уходит наружу как есть.
  Вложенные транзакции запрещены.
</Warning>

<h2 id="last_id">
  db:last\_id
</h2>

Rowid последней вставки.

```lua theme={null}
db:last_id()
```

### Возвращает

| тип      |       |
| -------- | ----- |
| `number` | rowid |

<h2 id="changes">
  db:changes
</h2>

Сколько строк изменил последний запрос.

```lua theme={null}
db:changes()
```

### Возвращает

| тип      |                  |
| -------- | ---------------- |
| `number` | количество строк |

<h2 id="path">
  db:path
</h2>

Путь к файлу базы.

```lua theme={null}
db:path()
```

### Возвращает

| тип      |                 |
| -------- | --------------- |
| `string` | абсолютный путь |

<h2 id="close">
  db:close
</h2>

Закрывает базу.

```lua theme={null}
db:close()
```

### Возвращает

Ничего.

Повторный вызов ошибкой не является: коду уборки не приходится помнить, закрывал он уже или нет.