ROWID no SQLite: chave oculta, alias e WITHOUT ROWID

Toda tabela tem uma coluna secreta

Quando você cria uma tabela comum no SQLite, já vem de brinde uma coluna que você nem chegou a declarar:

CREATE TABLE notes (
    title TEXT,
    body  TEXT
);

INSERT INTO notes (title, body) VALUES ('primeiro', 'olá');
INSERT INTO notes (title, body) VALUES ('segundo', 'mundo');

SELECT rowid, title, body FROM notes;

Esse tal de rowid existe de verdade. O SQLite atribui um para cada linha de toda tabela comum, queira você ou não. É um inteiro de 64 bits com sinal, único dentro da tabela, e é justamente a chave que o SQLite usa internamente para localizar as linhas na sua estrutura B-tree. Pense nele como a espinha dorsal da tabela — o índice que mantém tudo o mais organizado.

Você normalmente não vê esse campo porque o SELECT * não o inclui. Para enxergá-lo, é preciso pedir explicitamente pelo nome.

O ROWID tem três apelidos no SQLite

Como o rowid aparece bastante em SQL escrito para outros bancos, o SQLite aceita três nomes diferentes para essa mesma coluna:

CREATE TABLE notes (title TEXT);
INSERT INTO notes VALUES ('a'), ('b'), ('c');

SELECT rowid, oid, _rowid_, title FROM notes;

rowid, oid e _rowid_ apontam todos para a mesma coluna oculta. Se você declarar uma coluna de verdade com algum desses nomes, ela toma o lugar do alias e você perde o atalho — mas é só isso de pegadinha. No dia a dia, use rowid e pronto.

INTEGER PRIMARY KEY é a fórmula mágica

Aqui está o detalhe que pega de jeito quem vem de outros bancos. Quando você declara uma coluna exatamente como INTEGER PRIMARY KEY, ela não é armazenada à parte — ela vira o próprio rowid:

CREATE TABLE users (
    id   INTEGER PRIMARY KEY,
    name TEXT
);

INSERT INTO users (name) VALUES ('Ada'), ('Boris'), ('Rosa');

SELECT rowid, id, name FROM users;

rowid e id são, na prática, a mesma coluna com dois nomes diferentes. Quando você faz um INSERT sem informar o id, o SQLite escolhe automaticamente um inteiro (geralmente o maior rowid atual + 1). É por isso que INTEGER PRIMARY KEY é a forma mais eficiente de criar uma chave primária autoincrementável no SQLite — não há coluna extra nem índice extra, apenas o próprio rowid.

Mas atenção: a grafia exata faz diferença. INT PRIMARY KEY não é a mesma coisa — INT e INTEGER têm comportamentos diferentes aqui:

CREATE TABLE a (id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE b (id INT PRIMARY KEY, name TEXT);

INSERT INTO a (name) VALUES ('x');
INSERT INTO b (name) VALUES ('y');

SELECT rowid, id, name FROM a;
SELECT rowid, id, name FROM b;

Na tabela a, id e rowid apontam para o mesmo valor. Já na tabela b, id é só uma coluna comum e o rowid continua sendo aquele inteiro oculto, separado. Pior ainda: b.id não é preenchido automaticamente no insert — fica NULL até você atribuir um valor manualmente. Por isso, use sempre INTEGER PRIMARY KEY (escrito por extenso, sem abreviar) quando quiser o comportamento de alias do rowid.

Como obter o ROWID após um INSERT

Depois de um INSERT, é muito comum precisar do rowid que acabou de ser gerado — geralmente para ligar uma linha filha a esse registro. O SQLite oferece a função last_insert_rowid() justamente para isso:

CREATE TABLE posts (
    id    INTEGER PRIMARY KEY,
    title TEXT
);

INSERT INTO posts (title) VALUES ('primeiro');
INSERT INTO posts (title) VALUES ('segundo');

SELECT last_insert_rowid();

A função devolve o rowid do último insert bem-sucedido na conexão atual. Boa parte dos drivers de banco expõe esse mesmo valor como cursor.lastrowid ou algo parecido. A cláusula RETURNING (que veremos mais adiante) é outra forma de recuperá-lo já no próprio insert.

O ROWID não é permanente

O rowid de uma linha é estável enquanto ela existir, mas não serve como identificador vitalício. Um VACUUM pode renumerar os rowids, e se você apagar uma linha aquele número pode acabar sendo reaproveitado em um insert futuro:

CREATE TABLE items (name TEXT);
INSERT INTO items VALUES ('a'), ('b'), ('c');

DELETE FROM items WHERE name = 'c';
INSERT INTO items VALUES ('d');

SELECT rowid, name FROM items;

Repare que a nova linha pode ou não reaproveitar o rowid antigo, dependendo da versão e da situação — o ponto é que você não pode contar com ele permanecer único para sempre. Se você precisa de um identificador que sobreviva a deleções, vacuums e exportações, declare sua própria coluna INTEGER PRIMARY KEY (que fixa o valor naquela linha) e considere a palavra-chave AUTOINCREMENT se você precisar especificamente de valores estritamente crescentes que nunca sejam reutilizados.

Tabelas WITHOUT ROWID no SQLite

Às vezes o rowid é um custo extra que você não quer pagar — geralmente quando sua chave de verdade não é um inteiro. Uma tabela de cidades indexada pelo nome, por exemplo, acaba com duas estruturas: a B-tree do rowid e um índice separado sobre name para garantir a chave primária. O WITHOUT ROWID funde as duas em uma só:

CREATE TABLE cities (
    name       TEXT PRIMARY KEY,
    population INTEGER
) WITHOUT ROWID;

INSERT INTO cities VALUES ('Lisbon', 545000), ('Paris', 2102000);

SELECT * FROM cities WHERE name = 'Lisbon';
-- SELECT rowid FROM cities;   -- erro: nenhuma coluna chamada rowid

Agora a chave de armazenamento real passa a ser name. As buscas por name pulam um nível de indireção e a tabela ocupa menos espaço. Em troca, você abre mão de algumas coisas:

• Não existem rowid, oid nem _rowid_ — essas colunas simplesmente somem.
• last_insert_rowid() não é atualizado em inserções nessa tabela.
• I/O incremental de BLOB e alguns recursos de replicação ficam indisponíveis.
• A tabela precisa ter um PRIMARY KEY declarado.

WITHOUT ROWID é uma otimização pontual, não o padrão. Use quando a chave primária não for inteira e a tabela for grande ou tiver muita escrita. Para tabelas comuns com chave inteira, o layout padrão com rowid já é o ideal.

Modelo mental

Resumindo o essencial:

• Toda tabela comum no SQLite tem uma chave inteira oculta de 64 bits chamada rowid.
• INTEGER PRIMARY KEY (exatamente assim) transforma sua coluna num apelido para o rowid.
• Use last_insert_rowid() para ler o valor que acabou de ser atribuído.
• Rowids podem ser reaproveitados depois de deleções e renumerados pelo VACUUM.
• Tabelas WITHOUT ROWID descartam a chave oculta e usam diretamente a chave primária que você declarou — útil para chaves não inteiras, mas você abre mão de alguns recursos.

Na maior parte do tempo, você nem pensa no rowid. Declara id INTEGER PRIMARY KEY, deixa o SQLite cuidar da numeração e segue a vida. Os detalhes importam quando você está ajustando armazenamento, lendo esquemas já existentes, ou tentando entender por que INT PRIMARY KEY se comporta diferente de INTEGER PRIMARY KEY.

A seguir: NOT NULL e DEFAULT

Agora que a identidade da linha está resolvida, a próxima camada é garantir que as outras colunas guardem valores que façam sentido. As cláusulas NOT NULL e DEFAULT fazem o grosso desse trabalho — e são o tema do próximo capítulo.