Eu acho que um dos componentes mais importantes de um produto, principalmente de tecnologia, é a sua documentação. Uma documentação bem feita, detalhada, nos permite aprender e dominar não apenas ele, mas também os desafios que vão aparecer e como vamos criar as soluções!
E é aqui onde eu aplaudo de pé algo que a Microsoft fez: A doc do SQL Server colaborativa. Há alguns anos, ele mudaram a forma como nós, usuários (seja dev ou DBA) contribuimos para a doc. Antes, você tinha que dar feedbacks em algum sistema ou conhecer gente lá dentro. Agora, qualquer pessoa pode submeter correções que serão revisadas por alguém do time da Microsoft.
A doc do SQL Server (e outros produtos) fica no git, em markdown: https://github.com/MicrosoftDocs/sql-docs Se você não conhece nenhum desses termos, então, eu recomendo que aprenda, se quiser contribuir. Mas não é nada de outro mundo. Você pode contribuir, basicamente editando uma página ou mais páginas e submetendo um Pull Request, que é como você sugere alterações em arquivos nos repositórios git.
Nada melhor do que um usuário que usa muito um produto para ajudá-lo a mantê-lo atualizado e com as instruções, vindas do uso prático, não apenas do que o desenvolvedor espera como funciona. Eu já fiz várias contribuições e a tabela abaixo é um resumo e um pouco de contexto. Quem sabe isso não te motiva fazer também quando encontrar uma inconsistência?
| Assunto | Ano | Descrição |
|---|---|---|
| Impactos do CDC ao atualizar o SQL Server | 2019 | Aqui eu adicionei uma seção nesta página, falando sobre o impacto que o CDC pode causar ao aplicar uma atualização no SQL Server quando as tabelas estão muito grandes. Quando o SQL roda o update, ao iniciar a instância ele reconstruía alguns índices e tabelas do CDC, o que poderia causar uma alta atividade do log e a demora do SQL em ‘Script Upgrade Mode’, estado em que ele entra após iniciar depois que você aplica uma atualização. Basicamente, a proc sp_vupgrade_replication é chamada, que chama a sp_cdc_vupgrade. Você consegue ver o código e vai ver trecho em que drop de índices são feitos e recriados em seguida. |
| Esclarecimento na descrição da coluna os_thread_id | 2019 | No Linux, o SQL funciona um pouco diferente do que no Windows em termos de integração com o SO. Se você pegar a os_thread_id da sys.dm_os_threads e procurar no Process Explorer, por exemplo, você encontra a thread exata. No Linux, você não encontra fácil usando ferramentas como o ps ou procfs. Isso se dá pelo simples fato de que, no Linux, há uma camada de abstração (chamada SQLPAL, explicada nesse post), e o id que você vê lá não é o id direto retornado pelas APIs do SO, como é no Windows. Antes, a documentação dessa DMV não deixava isso claro. |
| Correção do nome do parâmetro de install | 2019 | Aqui foi um simples typo em um exemplo da instalação do SQL Server na linha de comando. Eu mexi bastante com essa doc para criar o script em powershell que instala o SQL |
| Comportamento de Locks com o comando REORGANIZE | 2020 | Esse foi uma contribuição cheia de surpresas. Inicialmente, eu queria adicionar a doc o fato do reorganize causar locks, o que a doc dizia que não fazia. O problema foi o teste que eu fiz: Coloquei o reorganize dentro de uma transação, e isso muda tudo. Eu não sabia disso e não tinha nenhum lugar no doc que avisava. Então, essa ficou a alteração: Se você faz um ALTER… REORGANIZAZE dentro de uma transação, você terá comportamento de locks diferentes do que quando é uma transação explícita. Foi uma boa surpresa esse. |
| Alterado o nome de “servidor” para “instância” para evitar confusão | 2020 | Uma pequena alteração para evitar confusão ao alterar a configuração ‘user connections’: Antes, a doc mencionava que o ‘server’ deveria ser reiniciado. Eu sugeri trocar para ‘SQL Instance’, para não acharem que deveria ser reiniciado o SO inteiro, que é o que normalmente nos referenciamos como ‘server’. |
| Mais informações sobre como os performance counters funcionam | 2020 | Os performance counters do Windows, e, em conjunto com o SQL, sempre foram uma das minhas maiores fontes de monitoramento e apoio para resolver problemas. Isso me levou a querer entendê-los mais a fundo, indo lá no nível do Windows para entender como funcionavam. Descobrir muita coisa nisso, inclusive a relação deles com o WMI e achei muita doc que até ajudou a explicar o porquê alguns valores na sys.dm_os_performance_counters são diferentes do que quando vemos no perfmon do Windows. Então, eu resolvi adicionar um parágrafo complementar fazendo esse link, coisa que antes eu não vinha em lugar nenhuma na doc. Inclusive, eu tenho um curso na plataforma de cursos da Power Tuning, e o capítulo 7 é só sobre isso, caso se interesse, é sé clicar aqui. |
| Adicionar a opção equivalente ao segundos em parâmetro da sp_add_jobsshedule | 2020 | Uma alteração simples: A proc que adiciona um schedule de jobs tem um parâmetro que permite especificar a unidade do schedule. Estava faltando o valor que indica que a unidade era segundos. |
| Reforçar que checks paralelos do comando DBCC CHECKTABLE não estão disponíves em todas as edições | 2021 | Se não me falha a memória, isso foi oriundo de algum caso na Power Tuning. Senti falta na doc específica deste comando mencionar que não é um feature disponível em qualquer edição, como apenas um atalho e facilidade para quem está explorando o comando. |
| Remover trace flag duplicada | 2022 | Uma pequena correção, que apenas corrigiu algum erro de digitação e deixou a trace flag repetida na lista. A doc já foi atualizada, pois não precisa mais. |
| Mencionar que a coluna é em UTC | 2022 | Apenas um reforço que a coluna é no formato UTC na doc da function sys.fn_get_audit_file, que é útil para que não conhece e vai usar a primeira vez. Apesar de poder perceber isso em observações e testes, eu acho que é sempre melhor a confirmação oficial de que realmente aquela coluna vai vir naquele formato. Acho que esse foi o PR que mais demorou pra ser aprovado… 1 ano rs |
| Impacto do TEXTSIZE na sp_executesql e EXEC | 2025 | Esse foi outra grande surpresa que descobri enquanto fazia um projeto na Power Tuning… Eu estava importando alguns dados de um MySQL para um SQL Server, via linked server, e ao levar pra um JOB, comecei a receber erros no formato de umas colunas JSON. Após investigar, descobri que o SQL Agent muda o valor de uma opção chamad TEXTSIZE, e isso afeta o resultado de alguns tipos dados, incluindo quando usar linked server… Basicamente, o JSON que vinha do MySQL estava sendo “cortado”, quando rodava a proc no Job. Bem louco né? Em breve quero escrever um post sobre isso! Eu sugeri adicionar isso na documentação do comando SET TEXTSIZE, mas esse PR não foi aprovado diretamente. Ao invés disso, a Microsft atualizou uma outra documentação que julgou ser mais pertinente: Manage Job Steps | Microsoft Learn. NEsse caso, meu nome nem aparece como colaborador, mas, só o fato de ter provocado um ajuste em alguma parte, já está ótimo e com certeza vai cumprir o mesmo objetivo: ajudar quem procurar um dia pelo mesmo problema |
| Correção da sintaxe no comando ALTER RESOURCE GOVERNOR | 2025 | Aqui foi uma pequena correção na sintaxe que é exibida na página que documenta os comandos, nesse caso o comando é o ALTER RESOURCE GOVERNOR. Antes, a cláusula WITH estava de uma forma que parecia que você poderia fazer um ALTER RESOURCE GOVERNOR RECONFIGURE WITH (…), o que não é verdade… Ou você roda o RECONFIGURE ou você roda o WITH, nunca ambos juntos (e dá erro se tentar) |
Além desses acima, teve pelo menos uma outra issue que abri. Infelizmente, a Microsoft não deixa mais abrir issues, e então você não vai ver: https://github.com/MicrosoftDocs/sql-docs/issues/1817. Esse foi relacionado a um update na doc do WMI. Falei mais sobre ela nesse post.
Você viu como tem desde simples correções, até coisas mais avançadas, que trazem boas descobertas (e até surpresas para o próprio time da MS?). É um ecossistema muito rico e só agrega ao produto!
Se você quiser contribuir, a dica aqui é simples: Se você viu algo que está na doc e quando você foi fazer não foi como o dito, você tem uma oportunidade para ajudar a melhorar. Mas, é muito importante que você faça testes (e em outras versões), consulte colegas mais experientes e tenha certeza de que realmente é algo que não existe, uma inconsistência /ou e não foi documentando em outro lugar. Lembre-se que tudo será revisado por alguém do time, e, se for o caso, pode chegar até próximo ao responsável pela funcionalidade ou o componente referente a doc.
Por isso, quando for abrir o PR, não esqueça de detalhar e fornecer detalhes o suficiente para esclarecer a sua proposta (isto é, não falar de mais, e nem de menos, mas o suficiente)… inclua exemplos e prints que ajudem o time da MS a entender o que você está propondo e conhecer o contexto. Nem sempre sua contribuições serão aceitas, por vários motivos, então, quanto mais claro você for e mais único for o que está propondo, mais chances tem de passar na revisão.
E, se você tiver dúvidas, me procure aqui, ou no Linkedin, que eu posso tentar te guiar e até revisar algo que está propondo antes que você submeta…
Um abraço e obrigado pela leitura!
DBA Team Leader na Power Tuning
