{"id":1827,"date":"2025-05-31T12:05:23","date_gmt":"2025-05-31T15:05:23","guid":{"rendered":"https:\/\/thesqltimes.com\/blog\/?p=1827"},"modified":"2025-05-31T12:05:23","modified_gmt":"2025-05-31T15:05:23","slug":"minhas-contribuicoes-para-a-documentacao-oficial-do-sql-server","status":"publish","type":"post","link":"https:\/\/thesqltimes.com\/blog\/2025\/05\/31\/minhas-contribuicoes-para-a-documentacao-oficial-do-sql-server\/","title":{"rendered":"Minhas contribui\u00e7\u00f5es para a Documenta\u00e7\u00e3o Oficial do SQL Server"},"content":{"rendered":"
\r\n
\r\n \r\n <\/i>\r\n <\/a>\r\n 0 <\/span>\r\n<\/div><\/div>Tempo de Leitura:<\/span> 6<\/span> minutos<\/span><\/span>\n

Eu acho que um dos componentes mais importantes de um produto, principalmente de tecnologia, \u00e9 a sua documenta\u00e7\u00e3o. Uma documenta\u00e7\u00e3o bem feita, detalhada, nos permite aprender e dominar n\u00e3o apenas ele, mas tamb\u00e9m os desafios que v\u00e3o aparecer e como vamos criar as solu\u00e7\u00f5es!<\/p>\n\n\n\n

\"\"<\/a><\/figure>\n\n\n\n

E \u00e9 aqui onde eu aplaudo de p\u00e9 algo que a Microsoft fez: A doc do SQL Server colaborativa. H\u00e1 alguns anos, ele mudaram a forma como n\u00f3s, usu\u00e1rios (seja dev ou DBA) contribuimos para a doc. Antes, voc\u00ea tinha que dar feedbacks em algum sistema ou conhecer gente l\u00e1 dentro. Agora, qualquer pessoa pode submeter corre\u00e7\u00f5es que ser\u00e3o revisadas por algu\u00e9m do time da Microsoft.<\/p>\n\n\n\n

A doc do SQL Server (e outros produtos) fica no git, em markdown: https:\/\/github.com\/MicrosoftDocs\/sql-docs<\/a> Se voc\u00ea n\u00e3o conhece nenhum desses termos, ent\u00e3o, eu recomendo que aprenda, se quiser contribuir. Mas n\u00e3o \u00e9 nada de outro mundo. Voc\u00ea pode contribuir, basicamente editando uma p\u00e1gina ou mais p\u00e1ginas e submetendo um Pull Request, que \u00e9 como voc\u00ea sugere altera\u00e7\u00f5es em arquivos nos reposit\u00f3rios git.<\/p>\n\n\n\n

Nada melhor do que um usu\u00e1rio que usa muito um produto para ajud\u00e1-lo a mant\u00ea-lo atualizado e com as instru\u00e7\u00f5es, vindas do uso pr\u00e1tico, n\u00e3o apenas do que o desenvolvedor espera como funciona. Eu j\u00e1 fiz v\u00e1rias contribui\u00e7\u00f5es<\/a> e a tabela abaixo \u00e9 um resumo e um pouco de contexto. Quem sabe isso n\u00e3o te motiva fazer tamb\u00e9m quando encontrar uma inconsist\u00eancia?<\/p>\n\n\n\n

Assunto<\/th>Ano<\/th>Descri\u00e7\u00e3o<\/th><\/tr><\/thead>
Impactos do CDC ao atualizar o SQL Server<\/a><\/td>2019<\/td>Aqui eu adicionei uma se\u00e7\u00e3o nesta p\u00e1gina<\/a>, falando sobre o impacto que o CDC pode causar ao aplicar uma atualiza\u00e7\u00e3o no SQL Server quando as tabelas est\u00e3o muito grandes. Quando o SQL roda o update, ao iniciar a inst\u00e2ncia ele reconstru\u00eda alguns \u00edndices 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\u00f3s iniciar depois que voc\u00ea aplica uma atualiza\u00e7\u00e3o. Basicamente, a proc sp_vupgrade_replication \u00e9 chamada, que chama a sp_cdc_vupgrade. Voc\u00ea consegue ver o c\u00f3digo e vai ver trecho em que drop de \u00edndices s\u00e3o feitos e recriados em seguida.<\/td><\/tr>
Esclarecimento na descri\u00e7\u00e3o da coluna os_thread_id<\/a><\/td>2019<\/td>No Linux, o SQL funciona um pouco diferente do que no Windows em termos de integra\u00e7\u00e3o com o SO. Se voc\u00ea pegar a os_thread_id da sys.dm_os_threads e procurar no Process Explorer, por exemplo, voc\u00ea encontra a thread exata. No Linux, voc\u00ea n\u00e3o encontra f\u00e1cil usando ferramentas como o ps ou procfs. Isso se d\u00e1 pelo simples fato de que, no Linux, h\u00e1 uma camada de abstra\u00e7\u00e3o (chamada SQLPAL, explicada nesse post<\/a>), e o id que voc\u00ea v\u00ea l\u00e1 n\u00e3o \u00e9 o id direto retornado pelas APIs do SO, como \u00e9 no Windows. Antes, a documenta\u00e7\u00e3o dessa DMV<\/a> n\u00e3o deixava isso claro.<\/td><\/tr>
Corre\u00e7\u00e3o do nome do par\u00e2metro de install<\/a><\/td>2019<\/td>Aqui foi um simples typo em um exemplo da instala\u00e7\u00e3o<\/a> do SQL Server na linha de comando. Eu mexi bastante com essa doc para criar o script em powershell que instala o SQL <\/a><\/td><\/tr>
Comportamento de Locks com o comando REORGANIZE<\/a><\/td>2020<\/td>Esse foi uma contribui\u00e7\u00e3o cheia de surpresas. Inicialmente, eu queria adicionar a doc o fato do reorganize causar locks, o que a doc dizia que n\u00e3o fazia. O problema foi o teste que eu fiz: Coloquei o reorganize dentro de uma transa\u00e7\u00e3o, e isso muda tudo. Eu n\u00e3o sabia disso e n\u00e3o tinha nenhum lugar no doc que avisava. Ent\u00e3o, essa ficou a altera\u00e7\u00e3o<\/a>: Se voc\u00ea faz um ALTER… REORGANIZAZE dentro de uma transa\u00e7\u00e3o, voc\u00ea ter\u00e1 comportamento de locks diferentes do que quando \u00e9 uma transa\u00e7\u00e3o expl\u00edcita. Foi uma boa surpresa esse.<\/td><\/tr>
Alterado o nome de “servidor” para “inst\u00e2ncia” para evitar confus\u00e3o<\/a><\/td>2020<\/td>Uma pequena altera\u00e7\u00e3o para evitar confus\u00e3o ao alterar a configura\u00e7\u00e3o ‘user connections’: Antes, a doc<\/a> mencionava que o ‘server’ deveria ser reiniciado. Eu sugeri trocar para ‘SQL Instance’, para n\u00e3o acharem que deveria ser reiniciado o SO inteiro, que \u00e9 o que normalmente nos referenciamos como ‘server’.<\/td><\/tr>
Mais informa\u00e7\u00f5es sobre como os performance counters funcionam<\/a><\/td>2020<\/td>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\u00ea-los mais a fundo, indo l\u00e1 no n\u00edvel do Windows para entender como funcionavam. Descobrir muita coisa nisso, inclusive a rela\u00e7\u00e3o deles com o WMI e achei muita doc que at\u00e9 ajudou a explicar o porqu\u00ea alguns valores na sys.dm_os_performance_counters s\u00e3o diferentes do que quando vemos no perfmon do Windows. Ent\u00e3o, eu resolvi adicionar um par\u00e1grafo complementar<\/a> fazendo esse link, coisa que antes eu n\u00e3o vinha em lugar nenhuma na doc. Inclusive, eu tenho um curso na plataforma de cursos da Power Tuning, e o cap\u00edtulo 7 \u00e9 s\u00f3 sobre isso, caso se interesse, \u00e9 s\u00e9 clicar aqui.<\/a><\/td><\/tr>
Adicionar a op\u00e7\u00e3o equivalente ao segundos em par\u00e2metro da sp_add_jobsshedule<\/a><\/td>2020<\/td>Uma altera\u00e7\u00e3o simples: A proc que adiciona um schedule de jobs tem um par\u00e2metro<\/a> que permite especificar a unidade do schedule. Estava faltando o valor que indica que a unidade era segundos.<\/td><\/tr>
Refor\u00e7ar que checks paralelos do comando DBCC CHECKTABLE n\u00e3o est\u00e3o dispon\u00edves em todas as edi\u00e7\u00f5es<\/a><\/td>2021<\/td>Se n\u00e3o me falha a mem\u00f3ria, isso foi oriundo de algum caso na Power Tuning. Senti falta na doc espec\u00edfica deste comando<\/a> mencionar que n\u00e3o \u00e9 um feature dispon\u00edvel em qualquer edi\u00e7\u00e3o, como apenas um atalho e facilidade para quem est\u00e1 explorando o comando.<\/td><\/tr>
Remover trace flag duplicada<\/a><\/td>2022<\/td>Uma pequena corre\u00e7\u00e3o, que apenas corrigiu algum erro de digita\u00e7\u00e3o e deixou a trace flag repetida na lista. A doc j\u00e1 foi atualizada<\/a>, pois n\u00e3o precisa mais.<\/td><\/tr>
Mencionar que a coluna \u00e9 em UTC<\/a><\/td>2022<\/td>Apenas um refor\u00e7o que a coluna \u00e9 no formato UTC na doc da function sys.fn_get_audit_file<\/a>, que \u00e9 \u00fatil para que n\u00e3o conhece e vai usar a primeira vez. Apesar de poder perceber isso em observa\u00e7\u00f5es e testes, eu acho que \u00e9 sempre melhor a confirma\u00e7\u00e3o 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<\/td><\/tr>
Impacto do TEXTSIZE na sp_executesql e EXEC<\/a><\/td>2025<\/td>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\u00f3s investigar, descobri que o SQL Agent muda o valor de uma op\u00e7\u00e3o 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\u00e9? Em breve quero escrever um post sobre isso!

Eu sugeri adicionar isso na documenta\u00e7\u00e3o do comando SET TEXTSIZE, mas esse PR n\u00e3o foi aprovado diretamente. Ao inv\u00e9s disso, a Microsft atualizou uma outra documenta\u00e7\u00e3o que julgou ser mais pertinente: Manage Job Steps | Microsoft Learn<\/a>. NEsse caso, meu nome nem aparece como colaborador, mas, s\u00f3 o fato de ter provocado um ajuste em alguma parte, j\u00e1 est\u00e1 \u00f3timo e com certeza vai cumprir o mesmo objetivo: ajudar quem procurar um dia pelo mesmo problema<\/td><\/tr>
Corre\u00e7\u00e3o da sintaxe no comando ALTER RESOURCE GOVERNOR<\/a><\/td>2025<\/td>Aqui foi uma pequena corre\u00e7\u00e3o na sintaxe que \u00e9 exibida na p\u00e1gina que documenta os comandos, nesse caso o comando \u00e9 o ALTER RESOURCE GOVERNOR<\/a>. Antes, a cl\u00e1usula WITH estava de uma forma que parecia que voc\u00ea poderia fazer um ALTER RESOURCE GOVERNOR RECONFIGURE WITH (…), o que n\u00e3o \u00e9 verdade… Ou voc\u00ea roda o RECONFIGURE ou voc\u00ea roda o WITH, nunca ambos juntos (e d\u00e1 erro se tentar)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Al\u00e9m desses acima, teve pelo menos uma outra issue que abri. Infelizmente, a Microsoft n\u00e3o deixa mais abrir issues, e ent\u00e3o voc\u00ea n\u00e3o vai ver: https:\/\/github.com\/MicrosoftDocs\/sql-docs\/issues\/1817<\/a>. Esse foi relacionado a um update na doc do WMI. Falei mais sobre ela nesse post.<\/a><\/p>\n\n\n\n

Voc\u00ea viu como tem desde simples corre\u00e7\u00f5es, at\u00e9 coisas mais avan\u00e7adas, que trazem boas descobertas (e at\u00e9 surpresas para o pr\u00f3prio time da MS?). \u00c9 um ecossistema muito rico e s\u00f3 agrega ao produto! <\/p>\n\n\n\n

Se voc\u00ea quiser contribuir, a dica aqui \u00e9 simples: Se voc\u00ea viu algo que est\u00e1 na doc e quando voc\u00ea foi fazer n\u00e3o foi como o dito, voc\u00ea tem uma oportunidade para ajudar a melhorar. Mas, \u00e9 muito importante que voc\u00ea fa\u00e7a testes (e em outras vers\u00f5es), consulte colegas mais experientes e tenha certeza de que realmente \u00e9 algo que n\u00e3o existe, uma inconsist\u00eancia \/ou e n\u00e3o foi documentando em outro lugar. Lembre-se que tudo ser\u00e1 revisado por algu\u00e9m do time, e, se for o caso, pode chegar at\u00e9 pr\u00f3ximo ao respons\u00e1vel pela funcionalidade ou o componente referente a doc. <\/p>\n\n\n\n

Por isso, quando for abrir o PR, n\u00e3o esque\u00e7a de detalhar e fornecer detalhes o suficiente para esclarecer a sua proposta (isto \u00e9, n\u00e3o 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\u00ea est\u00e1 propondo e conhecer o contexto. Nem sempre sua contribui\u00e7\u00f5es ser\u00e3o aceitas, por v\u00e1rios motivos, ent\u00e3o, quanto mais claro voc\u00ea for e mais \u00fanico for o que est\u00e1 propondo, mais chances tem de passar na revis\u00e3o.<\/p>\n\n\n\n

E, se voc\u00ea tiver d\u00favidas, me procure aqui, ou no Linkedin, que eu posso tentar te guiar e at\u00e9 revisar algo que est\u00e1 propondo antes que voc\u00ea submeta…<\/p>\n\n\n\n

Um abra\u00e7o e obrigado pela leitura!<\/p>\n\n\n\n

<\/p>\n\n\n\n

<\/p>\n","protected":false},"excerpt":{"rendered":"

0 Eu acho que um dos componentes mais importantes de um produto, principalmente de tecnologia, \u00e9 a sua documenta\u00e7\u00e3o. Uma documenta\u00e7\u00e3o bem feita, detalhada, nos permite aprender e dominar n\u00e3o apenas ele, mas tamb\u00e9m os desafios que v\u00e3o aparecer e como vamos criar as solu\u00e7\u00f5es! E \u00e9 aqui onde eu aplaudo de p\u00e9 algo que… Minhas contribui\u00e7\u00f5es para a Documenta\u00e7\u00e3o Oficial do SQL Server<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":1840,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"om_disable_all_campaigns":false,"_exactmetrics_skip_tracking":false,"_exactmetrics_sitenote_active":false,"_exactmetrics_sitenote_note":"","_exactmetrics_sitenote_category":0,"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"neve_meta_sidebar":"","neve_meta_container":"","neve_meta_enable_content_width":"","neve_meta_content_width":0,"neve_meta_title_alignment":"","neve_meta_author_avatar":"","neve_post_elements_order":"","neve_meta_disable_header":"","neve_meta_disable_footer":"","neve_meta_disable_title":"","footnotes":""},"categories":[3,296],"tags":[436,434,408,432,435,402,433,145,387,439,437,438,73,240,111,241],"series":[],"class_list":["post-1827","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-banco-de-dados-2","category-internals","tag-audit","tag-cdc","tag-checkdb","tag-doc","tag-documentacao","tag-github","tag-index","tag-internals","tag-jobs","tag-perfmon","tag-resource-governor","tag-sql-agent","tag-sql-server","tag-sqldocs","tag-tsql","tag-wmi"],"_links":{"self":[{"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/posts\/1827","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/comments?post=1827"}],"version-history":[{"count":13,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/posts\/1827\/revisions"}],"predecessor-version":[{"id":1841,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/posts\/1827\/revisions\/1841"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/media\/1840"}],"wp:attachment":[{"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/media?parent=1827"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/categories?post=1827"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/tags?post=1827"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/thesqltimes.com\/blog\/wp-json\/wp\/v2\/series?post=1827"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}