Ofosos: Creating a Custom Landing Page in Sphinx

Creating a Custom Landing Page in Sphinx

Sample code lives here. When I refer to source code line numbers, you’re supposed to look at the code in this repository. Sample output (courtesy of readthedocs.org) is at https://sphinx-landing-template.readthedocs.io/en/latest/.

By convention the landing page for your Sphinx project is a simple table of contents. Nothing prevents you from adding a custom logo. Can you add a landing page like Jupyter has, with custom HTML and CSS, with full control on how this page is laid out? Yes you can.

I used sphinx-quickstart to create a boilerplate template for my code. I didn’t bother configuring intersphinx or any extensions I didn’t need. I did let Sphinx know that I want to use both .rst and .md suffixes, which is not necessary for this exercise.

I opted to separate source and build directories. I also amended the exclude_patterns config variable by adding ['_build']

The idea here is, that we move the table of contents to a separate file. Then we create a custom index page, by telling Sphinx to render the page index via our template index.html. In index.html we can use the full power of HTML. We will subclass the existing layout.html from the Alabaster theme we’re using. If you desire this, you can go all out and design a customized version of a landing page, that does not inherit from layout.html.

Switching index.rst

If you used sphinx-quickstart, your index.rst contains the table of contents. Rename this file to contents.rst now. Make this change known to Sphinx by changing the property master_doc in conf.py to contents (line 45 in conf.py). Using the Alabaster theme, setting master_doc in conf.py will link the project title on the left top to our table of contents page.

Next we let Sphinx know that we still want to generate the index page, but with a different template. Add the following statement to your conf.py (line 113):

html_additional_pages = {'index': 'index.html'} 

This will prompt Sphinx to render the page index using the template index.html. Since index.html is not a default template, the only way to find this template is in our projects source/_templates/ folder.

Creating index.html

Now create a file named index.html in source/_templates, this will be instantiated by Sphinx to create our index page. Sphinx templating is a topic of it’s own. I’ll describe what I did in this example.

The first line of index.html tells Jinja, the Sphinx template processor, to inherit from the template named layout.html. This gives us much of the basic layout that is provided by Alabaster and leaves us to fill in the title and body of this template.

The seoncd line of index.html sets the title. The underscore notation is used for I18N (Internationalization). This provides for a convenient entry point into translating your project later on.

The main part start in line three. We define the block body here, which supplants the block with the same name from the layout.html template in Alabaster. Double curly braces indicate Python-esque code to Jinja, while {% ... %} indicates directives to it. In both of these constructs we can use underscore notation for I18N. It’s also possible to call functions that have been defined as part of the context of this template. You see the function pathto() being used. It will resolve a relative path in the project’s source directory to a path that your browser understands.

pathto() accepts as arguments the path to a document, if this is an .rst document, don’t use the .rst extension. Instead just write the name of the doc, without extension. You see this used in pathto("contents"), when we refer to the table of contents.

If you want to include images, refer to them like pathto('_static/images/...') in line 8 of index.html. This assumes that you place your images into the folder source/_static/images in your project’s root folder.

Adding custom CSS

Custom CSS can be added by using a conf.py extension. This is a way of adding customization to Sphinx in a per-project manner. Define a conf.py extension by adding a setup(app) function to your conf.py. Sphinx will call it like any other setup(app) method that is bundled in a third party extension.

In line 172 of conf.py we use this extension point to inject a custom stylesheet into the Sphinx build:

def setup(app):     app.add_stylesheet('css/custom.css') 

You could do much more, but this suffices to add a custom CSS file to the output of the HTML processor. This CSS will be available in all of the project, including index.html.


The idea behind this article is to create custom landing pages. These should allow for a large degree of customization, while still tying into the Sphinx workflow. With the ability to use custom HTML and CSS you can ask a design minded person to create your landing page, without them needing to understand reStructured Text. I hope this is helpful for you when creating beautiful landing pages.


Jupyter landing page https://jupyter.readthedocs.io/en/latest/install.html
sphinx-quickstart https://www.sphinx-doc.org/en/master/usage/quickstart.html
Custom CSS or JavaScript https://docs.readthedocs.io/en/latest/guides/adding-custom-css.html
Sphinx templating https://www.sphinx-doc.org/en/master/templating.html
Jinja templates http://jinja.pocoo.org/

Image credits:

United States Geological Survey (USGS) [Public domain], via Wikimedia Commons

Planet Python

Graham Dumpleton: Running an interactive terminal in the browser

In the last blog post I explained that JupyterHub can be used to spawn instances of applications other than Jupyter notebooks. Because JupyterHub can also handle user authentication, this made it a handy way of spinning up distinct user environments when running workshops. Each attendee of the workshop would be given access to a shell environment running in a separate pod inside of Kubernetes,
Planet Python

Test and Code: 60: 100 Days of Code – Julian Sequeira

Julian Sequeira is Co-Founder of PyBit.es (a blog/platform created to teach and learn Python) and a Python Trainer at Talk Python Training.
He’s also a survivor of the 100DaysOfCode in Python Challenge.

We talk about the 100 days challenge, about learning Python, and about how cool it is to learn within a community.

Special Guest: Julian Sequeira.

Sponsored By:

Support Test & Code


<p>Julian Sequeira is Co-Founder of PyBit.es (a blog/platform created to teach and learn Python) and a Python Trainer at Talk Python Training.<br> He&#39;s also a survivor of the 100DaysOfCode in Python Challenge.</p> <p>We talk about the 100 days challenge, about learning Python, and about how cool it is to learn within a community.</p><p>Special Guest: Julian Sequeira.</p><p>Sponsored By:</p><ul><li><a rel=”nofollow” href=”https://testandcode.com/digitalocean”>DigitalOcean</a>: <a rel=”nofollow” href=”https://testandcode.com/digitalocean”>Get started with a free $ 100 credit </a></li></ul><p><a rel=”payment” href=”https://www.patreon.com/testpodcast”>Support Test &amp; Code</a></p><p>Links:</p><ul><li><a title=”PyBites Blog” rel=”nofollow” href=”https://pybit.es”>PyBites Blog</a></li><li><a title=”PyBites Code Challenges Platform” rel=”nofollow” href=”https://codechalleng.es”>PyBites Code Challenges Platform</a></li><li><a title=”TalkPython + PyBites 100 Days of Code in Python Course” rel=”nofollow” href=”https://talkpython.fm/100days?s=pybites”>TalkPython + PyBites 100 Days of Code in Python Course</a></li><li><a title=”PyBites 100 Days of Code Repo” rel=”nofollow” href=”https://github.com/pybites/100DaysOfCode/blob/master/LOG.md”>PyBites 100 Days of Code Repo</a></li><li><a title=”Pybit.es Slack Community” rel=”nofollow” href=”https://join.slack.com/t/pybites/shared_invite/enQtNDAxODc0MjEyODM2LTNiZjljNTI2NGJiNWI0MTRkNjY4YzQ1ZWU4MmQzNWQyN2Q4ZTQzMTk0NzkyZTRmMThlNmQzYTk5Y2Y5ZDM4NDU”>Pybit.es Slack Community</a></li></ul>
Planet Python

Como Solucionar Problemas no MySQL


O MySQL é um sistema gerenciador de banco de dados relacional open-source, o mais popular de seu tipo no mundo. Como é comum quando se trabalha com qualquer software, tanto os novatos quanto os usuários experientes podem encontrar mensagens de erro confusas ou problemas difíceis de diagnosticar.

Este guia servirá como um recurso de solução de problemas e um ponto de partida à medida que você diagnostica sua configuração do MySQL. Analisaremos alguns dos problemas que muitos usuários do MySQL encontram e forneceremos orientações para solucionar problemas específicos. Também incluiremos links para tutoriais da DigitalOcean e a documentação oficial do MySQL que pode ser útil em certos casos.

Por favor, observe que este guia assume a configuração descrita em Como Instalar o MySQL no Ubuntu 18.04, e os tutoriais vinculados em todo o guia refletem essa configuração. Se seu servidor estiver executando outra distribuição, contudo, você pode encontrar um guia específico para essa distro no Menu de Versão do tutorial, na parte superior dos tutoriais vinculados, quando houver um disponível.

Como Começar com o MySQL

O lugar onde muitos usuários iniciantes do MySQL se deparam com problemas é durante o processo de instalação e configuração. Nosso guia sobre Como Instalar o MySQL no Ubuntu 18.04 fornece instruções sobre como configurar uma instalação básica e pode ser útil para aqueles que são novos no MySQL.

Outra razão pela qual alguns usuários enfrentam problemas é que seu aplicativo requer recursos de banco de dados que estão presentes apenas nas últimas versões, mas a versão do MySQL disponível nos repositórios padrão de algumas distribuições Linux — incluindo o Ubuntu — não é a última versão. Por esta razão, os desenvolvedores MySQL mantém seus próprios repositórios de software, que você pode utilizar para instalar a versão mais recente e mantê-la atualizada. Nosso tutorial “How To Install the Latest MySQL on Ubuntu 18.04” fornece instruções sobre como fazer isso.

Como Acessar os Logs de Erros do MySQL

Muitas vezes, a causa raiz de lentidão, falha ou outro comportamento inesperado no MySQL pode ser determinada pela análise de seus logs de erro. Em sistemas Ubuntu, a localização padrão para o MySQL é em /var/log/mysql/error.log. Em muitos casos, os logs de erros são lidos mais facilmente com o programa less, um utilitário de linha de comando que lhe permite ver arquivos mas não editá-los:

  • sudo less /var/log/mysql/error.log

Se o MySQL não estiver se comportando como esperado, você pode obter mais informações sobre a origem do problema executando este comando e diagnosticando o erro com base no conteúdo do log.

Redefinindo a Senha do Usuário root do MySQL

Se você tiver definido uma senha para o usuário root da sua instalação do MySQL, mas se equeceu dela, você poderia ficar bloqueado para acesso aos seus bancos de dados. Contanto que você tenha acesso ao servidor no qual seu banco de dados está hospedado, contudo, você deverá ser capaz de redefini-la.

Esse processo é diferente de redefinir a senha para um nome de usuário padrão do Linux. Verifique nosso guia How To Reset Your MySQL or MariaDB Root Password para ler e entender esse processo.

Problemas com Consultas

Às vezes, os usuários enfrentam problemas quando começam a realizar consultas nos dados. Em alguns sistemas de banco de dados, incluindo o MySQL, os comandos de consulta devem terminar com um ponto-e-vírgula (;) para que sejam completados, como no seguinte exemplo:

  • SHOW * FROM nome_da_tabela;

Se você não incluir um ponto-e-vírgula no final de sua consulta, o prompt continuará em uma nova linha até que você complete a consulta inserindo um ponto-e-vírgula e pressionando ENTER.

Alguns usuários podem achar que suas consultas estão extremamente lentas. Uma maneira de descobrir qual comando de consulta é a causa de uma lentidão é ativar e visualizar o log de consultas lentas do MySQL. Para fazer isso, abra o seu arquivo mysqld.cnf, que é utilizado para configurar opções para o servidor do MySQL. Este arquivo é normalmente armazenado dentro do diretório /etc/mysql/mysql.conf.d/:

  • sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Percorra o arquivo até ver as seguintes linhas:

 . . . #slow_query_log         = 1 #slow_query_log_file    = /var/log/mysql/mysql-slow.log #long_query_time = 2 #log-queries-not-using-indexes . . . 

Essas diretivas comentadas fornecem as opções padrão de configuração do MySQL para o log de consultas lentas. Especificamente, aqui está o que cada uma delas faz:

  • slow-query-log: Definir isso como 1 ativa o log de consultas lentas.

  • slow-query-log-file: Isso define o arquivo onde o MySQL registrará qualquer consulta lenta. Neste caso, ele aponta para o arquivo /var/log/mysql-slow.log.

  • long_query_time: Definindo essa diretiva para 2, configura o MySQL para registrar quaisquer consultas que demorem mais de 2 segundos para serem concluídas.

  • log_queries_not_using_indexes: Isso diz ao MySQL para registrar também quaisquer consultas que executem sem índices para o arquivo /var/log/mysql-slow.log. Essa configuração não é necessária para o log de consultas lentas funcionar, mas pode ser útil para detectar consultas ineficientes.

Descomente cada uma dessas linhas removendo os sinais de cerquilha no início. A seção ficará assim agora:

 . . . slow_query_log = 1 slow_query_log_file = /var/log/mysql-slow.log long_query_time = 2 log_queries_not_using_indexes . . . 

Nota: Se você estiver executando o MySQL 8+, estas linhas comentadas não estarão no arquivo mysqld.cnf por padrão. Nesse caso, adicione as seguintes linhas à parte inferior do arquivo:

 . . . slow_query_log = 1 slow_query_log_file = /var/log/mysql-slow.log long_query_time = 2 log_queries_not_using_indexes 

Depois de habilitar o log de consultas lentas, salve e feche o arquivo. Em seguida, reinicie o serviço MySQL:

  • sudo systemctl restart mysql

Com essas configurações valendo, você pode encontrar comandos de consulta problemáticos visualizando o log de consultas lentas. Você pode fazer isso com o less, assim:

  • sudo less /var/log/mysql_slow.log

Depois de encontrar as consultas que causam a lentidão, você pode verificar nosso guia How To Optimize Queries and Tables in MySQL and MariaDB on a VPS que pode ser útil para otimizá-las.

Além disso, o MySQL inclui o comando EXPLAIN, que fornece informações sobre como o MySQL executa consultas. Esta página da documentação oficial do MySQL fornece dicas sobre como usar o EXPLAIN para destacar consultas ineficientes.

Para obter ajuda na compreensão das estruturas básicas de consulta, consulte nosso tutorial Introduction to MySQL Queries.

Permitindo o Acesso Remoto

Muitos sites e aplicativos começam com o servidor da web e o back-end de banco de dados hospedado na mesma máquina. Com o tempo, no entanto, uma configuração como essa pode se tornar incômoda e difícil de escalar. Uma solução comum é separar essas funções configurando um banco de dados remoto, permitindo que o servidor e o banco de dados cresçam em seu próprio ritmo em suas próprias máquinas. Um dos problemas mais comuns que os usuários enfrentam ao tentar configurar um banco de dados MySQL remoto é que sua instância do MySQL é configurada para escutar apenas conexões locais. Este é o padrão de configuração do MySQL, mas não funcionará para uma configuração de banco de dados remota, já que o MySQL deve ser capaz de escutar por um endereço IP externo onde o servidor possa ser alcançado. Para ativar isso, abra o seu arquivo mysqld.cnf:

  • sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Navegue até a linha que começa com a diretiva bind-address. Será parecido com isto:

 . . . lc-messages-dir = /usr/share/mysql skip-external-locking # # Instead of skip-networking the default is now to listen only on # localhost which is more compatible and is not less secure. bind-address            = . . . 

Por padrão, este valor está definido para, significando que o servidor olhará somente para conexões locais. Você precisará alterar esta diretiva para referenciar um endereço IP externo. Para fins de solução de problemas, você pode definir essa diretiva como um endereço IP curinga, seja *, ::, ou

 . . . lc-messages-dir = /usr/share/mysql skip-external-locking # # Instead of skip-networking the default is now to listen only on # localhost which is more compatible and is not less secure. bind-address            = . . . 

Nota: Se você estiver executando o MySQL 8+, a diretiva bind-address não estará no arquivo mysqld.cnf por padrão. Nesse caso, adicione a seguinte linha destacada à parte inferior do arquivo:

 . . . [mysqld] pid-file        = /var/run/mysqld/mysqld.pid socket          = /var/run/mysqld/mysqld.sock datadir         = /var/lib/mysql log-error       = /var/log/mysql/error.log bind-address            = 

Depois de alterar esta linha, salve e feche o arquivo e em seguida, reinicie o serviço MySQL:

  • sudo systemctl restart mysql

Depois disso, tente acessar seu banco de dados remotamente a partir de outra máquina:

  • mysql -u usuário -h ip_servidor_de_banco_de_dados -p

Se você for capaz de acessar seu banco de dados, isso confirma que a diretiva bind-address em seu arquivo de configuração era o problema. Por favor, observe, entretanto, que a configuração de bind-address para0.0.0.0 é insegura, pois permite conexões ao seu servidor a partir de qualquer endereço IP. Por outro lado, se você ainda não conseguir acessar o banco de dados remotamente, algo mais pode estar causando o problema. Em ambos os casos, você pode achar útil seguir nosso guia How To Set Up a Remote Database to Optimize Site Performance with MySQL on Ubuntu 18.04 para definir uma configuração de banco de dados remota mais segura.

O MySQL Pára Inesperadamente ou Falha ao Iniciar

A causa mais comum de falhas no MySQL é que ele parou ou falhou ao iniciar devido a memória insuficiente. Para verificar isso, você precisará revisar o log de erros do MySQL após uma falha.

Primeiro, tente iniciar o servidor MySQL digitando:

  • sudo systemctl start mysql

Em seguida, revise os logs de erro para ver o que está causando o travamento do MySQL. Você pode usar o less para revisar seus logs, uma página por vez:

  • sudo less /var/log/mysql/error.log

Algumas mensagens comuns que indicariam uma quantidade insuficiente de memória são Out of memory ou mmap can't allocate.

Soluções potenciais para uma quantidade inadequada de memória são:

  • Otimização da sua configuração do MySQL. Uma ótima ferramenta open-source para isso é o MySQLtuner. A execução do script MySQLtuner irá gerar um conjunto de ajustes recomendados para o seu arquivo de configuração do MySQL (mysqld.cnf). Observe que quanto mais tempo seu servidor estiver rodando antes de usar o MySQLTuner, mais precisas serão as suas sugestões. Para obter uma estimativa de uso de memória das configurações atuais e as propostas pelo MySQLTimer, use esta Calculadora MySQL.

  • Redução da confiança da sua aplicação web no MySQL para carregamentos de página. Isso geralmente pode ser feito adicionando-se cache estático à sua aplicação. Exemplos disso incluem o Joomla, que tem o cache como um recurso interno que pode ser ativado, e o WP Super Cache, um plugin do WordPress que adiciona esse tipo de funcionalidade.

  • Atualização para um VPS maior. No mínimo, recomendamos um servidor com pelo menos 1 GB de RAM para qualquer servidor que use um banco de dados MySQL, mas o tamanho e o tipo dos dados podem afetar significativamente os requisitos de memória.

Lembre-se de que, embora a atualização do seu servidor seja uma solução em potencial, ela só é recomendável depois que você investigar e pesar todas as outras opções. Um servidor atualizado com mais recursos também vai custar mais dinheiro, então você só deve redimensionar se realmente isso acabar sendo sua melhor opção. Observe também que a documentação do MySQL inclui várias outras sugestões para diagnosticar e prevenir falhas.

Tabelas Corrompidas

Ocasionalmente, as tabelas do MySQL podem ficar corrompidas, o que significa que ocorreu um erro e os dados contidos nelas não podem ser lidos. Tentativas de ler uma tabela corrompida geralmente levam à falha do servidor.

Algumas causas comuns de tabelas corrompidas são:

  • O servidor MySQL parou no meio de uma escrita.

  • Um programa externo modifica uma tabela que está sendo modificada simultaneamente pelo servidor.

  • A máquina foi desligada inesperadamente.

  • O hardware do computador falhou.

  • Há um bug de software em algum lugar no código do MySQL.

Se você suspeitar que uma de suas tabelas foi corrompida, faça um backup do diretório de dados antes de solucionar problemas ou de tentar consertar a tabela. Isso ajudará a minimizar o risco de perda de dados.

Primeiro, pare o serviço MySQL:

  • sudo systemctl stop mysql

Em seguida, copie todos os seus dados em um novo diretório de backup. Nos sistemas Ubuntu, o diretório de dados padrão é /var/lib/mysql/:

  • cp -r /var/lib/mysql /var/lib/mysql_bkp

Depois de fazer o backup, você está pronto para começar a investigar se a tabela está de fato corrompida. Se a tabela utiliza o mecanismo de armazenamento MyISAM, você pode verificar se ela está corrompida executando um comando CHECK TABLE no prompt do MySQL:

  • CHECK TABLE nome_da_tabela;

Uma mensagem aparecerá na saída desse comando informando se ela está corrompida ou não. Se a tabela MyISAM estiver realmente corrompida, ela geralmente pode ser reparada emitindo um comando REPAIR TABLE:

  • REPAIR TABLE nome_da_tabela;

Supondo que o reparo foi bem sucedido, você verá uma mensagem como a seguinte em sua saída:

+---------------------------------------+--------+----------+----------+ | Table | Op | Msg_type | Msg_text | +---------------------------------------+--------+----------+----------+ | nome_do_banco_de_dados.nome_da_tabela | repair | status | OK | +---------------------------------------+--------+----------+----------+

Se a tabela ainda estiver corrompida, a documentação do MySQL sugere alguns métodos alternativos para reparar tabelas corrompidas.

Por outro lado, se a tabela corrompida usa o mecanismo de armazenamento InnoDB, então o processo para repará-la será diferente. O InnoDB é o mecanismo de armazenamento padrão no MySQL a partir da versão 5.5, e possui operações automatizadas de verificação e reparo de corrupção. O InnoDB verifica páginas corrompidas executando somas de verificação ou checksums em cada página que lê, e se encontrar uma discrepância no checksum, ele irá parar automaticamente o servidor MySQL.

Raramente é necessário reparar tabelas InnoDB, já que o InnoDB possui um mecanismo de recuperação de falhas que pode resolver a maioria dos problemas quando o servidor é reiniciado. No entanto, se você encontrar uma situação onde você precisa reconstruir uma tabela InnoDB corrompida, a documentação do MySQL recomenda o método “Dump and Reload”. Isso envolve recuperar o acesso à tabela corrompida, usando o utilitário mysqldump para criar um backup lógico da tabela, que manterá a estrutura da tabela e os dados dentro dela e, em seguida, recarregar a tabela de volta no banco de dados.

Com isso em mente, tente reiniciar o serviço MySQL para ver se isso permitirá o acesso ao servidor:

  • sudo systemctl restart mysql

Se o servidor permanecer travado ou inacessível, então pode ser útil ativar a opção force_recovery do InnoDB. Você pode fazer isso editando o arquivo mysqld.cnf:

  • sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Na seção [mysqld], adicione a seguinte linha:

 . . . [mysqld] . . . innodb_force_recovery=1 

Salve e feche o arquivo, e então tente reiniciar o serviço MySQL novamente. Se você conseguir acessar com sucesso a tabela corrompida, use o utilitário mysqldump para descarregar os dados da sua tabela para um novo arquivo. Você pode nomear este arquivo como quiser, mas aqui nós o nomearemos como out.sql:

  • mysqldump nome_do_bando_de_dados nome_da_tabela > out.sql

Em seguida, elimine a tabela do banco de dados. Para evitar ter que reabrir o prompt do MySQL, você pode usar a seguinte sintaxe:

  • mysql -u usuário -p --execute="DROP TABLE nome_do_banco_de_dados.nome_da_tabela"

Depois disso, restaure a tabela com o arquivo de dump que você acabou de criar:

  • mysql -u usuário -p < out.sql

Observe que o mecanismo de armazenamento InnoDB geralmente é mais tolerante a falhas do que o antigo mecanismo MyISAM. As tabelas que usam o InnoDB ainda podem ser corrompidas, mas devido a seus recursos de recuperação automática o risco de corrupção da tabela e falhas é decididamente menor.

Erros de Soquete

O MySQL gerencia conexões com o servidor de banco de dados através do uso de um arquivo de soquete, um tipo especial de arquivo que facilita a comunicação entre diferentes processos. O arquivo de soquete do servidor MySQL é chamado mysqld.sock e nos sistemas Ubuntu ele é normalmente armazenado no diretório /var/run/mysqld/. Este arquivo é criado automaticamente pelo serviço MySQL.

Às vezes, alterações no sistema ou na configuração do MySQL podem fazer com que o MySQL não consiga ler o arquivo de soquete, impedindo o acesso aos seus bancos de dados. O erro de soquete mais comum é semelhante ao seguinte:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)

Existem algumas razões pelas quais esse erro pode ocorrer e algumas maneiras possíveis de resolvê-lo.

Uma causa comum desse erro é que o serviço MySQL está parado ou não iniciou, o que significa que não foi possível criar o arquivo de soquete em um primeiro momento. Para descobrir se este é o motivo pelo qual você está vendo este erro, tente iniciar o serviço com systemctl:

  • sudo systemctl start mysql

Em seguida, tente acessar o prompt do MySQL novamente. Se você ainda receber o erro de soquete, verifique novamente o local onde sua instalação do MySQL está procurando pelo arquivo de soquete. Esta informação pode ser encontrada no arquivo mysqld.cnf:

  • sudo nano /etc/mysql/mysql.conf.d/mysql.cnf

Procure o parâmetro socket na seção[mysqld] deste arquivo. Isso parecerá assim:

. . . [mysqld] user = mysql pid-file = /var/run/mysqld/mysqld.pid socket = /var/run/mysqld/mysqld.sock port = 3306 . . .

Feche este arquivo, então certifique-se de que o arquivo mysqld.sock exista executando um comando ls no diretório onde o MySQL espera encontrá-lo:

  • ls -a /var/run/mysqld/

Se o arquivo de soquete existir, você o verá na saída deste comando:

. .. mysqld.pid mysqld.sock mysqld.sock.lock

Se o arquivo não existir, o motivo pode ser que o MySQL está tentando criá-lo, mas não possui permissões adequadas para isso. Você pode garantir que as permissões corretas estão em vigor, alterando a propriedade do diretório para o usuário e grupo mysql:

  • sudo chown mysql:mysql /var/run/mysqld/

Em seguida, certifique-se de que o usuário mysql tenha as permissões apropriadas sobre o diretório. Definindo-as para 755 vai funcionar na maioria dos casos:

  • sudo chmod -R 755 /var/run/mysqld/

Finalmente, reinicie o serviço MySQL para que ele possa tentar criar o arquivo de soquete novamente:

  • sudo systemctl restart mysql

Em seguida, tente acessar o prompt do MySQL mais uma vez. Se você ainda encontrar o erro de soquete, provavelmente há um problema mais profundo com a sua instância do MySQL; nesse caso, você deve revisar o log de erros para ver se ele pode fornecer alguma pista.


O MySQL serve como o backbone de inúmeros aplicativos e sites orientados a dados. Com tantos casos de uso, há também tantas possíveis causas de erros. Da mesma forma, também há muitas maneiras diferentes de resolver tais erros. Neste guia, cobrimos alguns dos erros mais frequentemente encontrados, mas há muitos mais que podem surgir dependendo de como o seu aplicativo funciona com o MySQL.

Se você não conseguiu encontrar uma solução para o seu problema específico, esperamos que este guia lhe tenha dado, pelo menos, algum conhecimento sobre solução de problemas do MySQL e o ajude a encontrar a fonte dos seus erros. Para mais informações, você pode ver a documentação oficial do MySQL, que abrange os tópicos que discutimos aqui, bem como outras estratégias de solução de problemas.

Além disso, se o seu banco de dados MySQL estiver hospedado em um Droplet da DigitalOcean, você pode contatar nossa equipe de Suporte para obter mais assistência.

Por Mark Drake

DigitalOcean Community Tutorials